⚡ Quick Start

# Initialize Zeoel in any project directory
npx zeoel-framework init

# Open your AI coding tool and start building
# "I want to build a SaaS dashboard with auth and billing"

That's it. Zeoel takes over — brainstorming, planning sprints, dispatching specialized agents, writing tests first, and verifying quality before shipping.

📖 See USER_MANUAL.md for the full guide and SETUP.md for platform-specific setup.

🤔 Why Zeoel?

Most AI coding tools use a single monolithic prompt. You tell them to "build a SaaS app" and they dump out untested, unstructured code — that's vibe-coding. Zeoel is different.

🔄 How It Works

Zeoel follows a disciplined 4-phase pipeline — no shortcuts, no vibe-coding. Works natively with Claude Code sub-agents, Cursor, Gemini CLI, and GitHub Copilot:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  BRAINSTORM  │───▶│    PLAN     │───▶│   EXECUTE   │───▶│   VERIFY    │
│              │    │             │    │             │    │             │
│ CEO debates  │    │ Sprint      │    │ Agents      │    │ QA tests    │
│ with all     │    │ decomp,     │    │ dispatched   │    │ Security    │
│ 33 agents    │    │ task cards  │    │ with TDD    │    │ SEO audit   │
│              │    │ feature     │    │ Red-Green-  │    │ Worktree    │
│ PROJECT_     │    │ branch      │    │ Refactor    │    │ snapshot    │
│ BRIEF.md     │    │ created     │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

Phase 1: Brainstorm — with Smart Config Inference

Gohar (CEO) reads your prompt and auto-detects your stack preferences (framework, database, testing style) — no 20-question surveys. He asks only what he can't figure out, then leads a debate between all agents to define scope. Produces PROJECT_BRIEF.md.

Phase 2: Sprint Planning — with Graphify Codebase Context Mapping

Decomposes the brief into actionable sprints. At the start of Phase 2, Gohar runs /graphify . --wiki to build/update the codebase's semantic knowledge map, creating a 71.5x input token reduction. Gohar assigns each task to a specific sub-agent with its recommended model tier.

Phase 3: Execution — with Caveman Prompt Compression

Each agent is dispatched to complete its task. To save up to 75% on output tokens, all agents strictly follow /caveman prompting rules, writing in technical, telegraphic style. Strict TDD is enforced — tests first, then logic in frontend/ and backend/ only. After edits, /graphify . --update updates the codebase map.

Phase 4: Verification & Snapshot

QA tests, security audits, SEO audits, and final code reviews are run by QA, Security, and SEO specialists. Once passed, the branch merges to main and the sprint is archived to .worktrees/sprint-N/.

🧠 Smart Config Inference

Most frameworks ask you a dozen setup questions before you even start. Zeoel reads your prompt and figures it out.

You: "Build me a SaaS dashboard with auth and Stripe billing"

Gohar: 
═══════════════════════════════════════════
  🔍 SMART CONFIG — Auto-detected from your prompt
═══════════════════════════════════════════
  ✅ Stack:     Full-stack (detected: "auth and billing")
  ✅ Frontend:  Next.js (detected: "SaaS dashboard")
  ✅ Backend:   Laravel (detected: "billing" → SaaS default)
  ✅ Database:  PostgreSQL (detected: "SaaS" → multi-tenant)
  ✅ Testing:   Strict TDD (default)
  ✅ Snapshots: Yes (default)
  ❓ Mobile:    Not mentioned — do you need one?
═══════════════════════════════════════════

One prompt. Zero friction. Full control. If Gohar gets something wrong, just tell him to change it.

💡 Intelligent Model Routing

Why burn Opus/o3 tokens on a README update? Zeoel assigns a complexity tier to every task and recommends the cheapest model that can do the job:

Every task in the sprint plan includes its tier, so you know exactly where your tokens are going:

═══════════════════════════════════════════
  DISPATCHING: Karar (Sr. Frontend Engineer)
  Task: #4 — Build the pricing page
  Skills: nextjs-turbopack, frontend-design
  Tests: Component test + route test
  Model Tier: 🟡 Standard
  Recommended: claude-sonnet-4
═══════════════════════════════════════════

Result: Up to 60% fewer tokens on a typical sprint by routing simple tasks to fast, cheap models.

👥 The 33 Specialized Agents

Each agent has a distinct persona, curated skill pack, and defined responsibility:

All agent names are inspired by Ahle Bait (a.s.) and the Zeoel team.

📚 450+ Curated Skills

Zeoel ships with 450+ production-ready skills covering every aspect of modern software development:

📂 Browse all skills: all-skills/ or .agents/skills/zeoel/skills/

🏗️ Architecture & Codebase Containment

Zeoel enforces strict directory structure for clean, maintainable projects:

your-project/
├── frontend/              # All frontend code (Next.js, React, etc.)
├── backend/               # All backend code (Laravel, APIs, etc.)
├── .worktrees/            # Runnable snapshots of completed sprints
│   ├── sprint-1/
│   └── sprint-2/
├── docs/
│   ├── brainstorm/        # Phase 1 outputs
│   └── sprint-N/          # Sprint plans & progress trackers
├── PROJECT_BRIEF.md       # Master requirements document
├── .agents/               # Zeoel framework (agents, skills, config)
├── AGENTS.md              # Agent quick reference
└── CLAUDE.md              # AI tool instructions

🔌 Platform Compatibility

Zeoel works seamlessly with all major AI coding tools:

📝 How to Interact

You: "I want to build a SaaS dashboard with auth and billing"

Zeoel: [Phase 1] "I'm starting the brainstorm. Let me debate with 
       all 23 agents to define scope..."
       
       [Phase 2] "Here's the sprint plan with 12 tasks. Approve?"
       
       [Phase 3] "Dispatching Karar (Frontend) for the dashboard UI...
                  Dispatching Tariq (Backend) for the API layer...
                  Running TDD: 47 tests written, 47 passing ✅"
       
       [Phase 4] "QA passed. Security audit clean. SEO score 98.
                  Sprint archived to .worktrees/sprint-1/"

🤝 Contributing

We welcome contributions! Whether it's a new skill, a new agent, bug fixes, or documentation improvements.

See CONTRIBUTING.md for guidelines on:

• 🆕 Adding new skills
• 🤖 Adding new agents
• 🐛 Reporting bugs
• ✨ Suggesting features

🙏 Credits & Inspiration

Zeoel stands on the shoulders of incredible open-source projects. We believe in transparency and proper attribution.

See REFERENCES.md for the full list of projects that inspired our skills and methodology, including:

• obra/superpowers — Agentic skills methodology
• Anthropic Claude Code — CLAUDE.md conventions
• VoltAgent — Skills aggregation patterns
• And many more...

Why "Zeoel"? The name honors the legacy of knowledge and justice. All 23 agent names are inspired by Ahle Bait (a.s.) and the Zeoel development team.

📬 Links & Contact

• NPM: zeoel-framework
• GitHub: goharabbas321/zeoel-framework
• Creator: Gohar Abbas (@goharabbas321)
• Telegram: @goharabbas786

📄 License

MIT © Gohar Abbas