⚡ 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    │
│ 23 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 Model Routing

Decomposes the brief into actionable sprints. Each task gets an assigned agent, skill bindings, AND a Model Tier (🟢 Light / 🟡 Standard / 🔴 Complex) so you spend Haiku-level tokens on docs and Opus-level tokens only when it matters.

Phase 3: Execution

Each agent is dispatched with its curated skills to complete its task. Strict Red-Green-Refactor TDD — tests are always written first. All code lives in frontend/ and backend/ only.

Phase 4: Verification & Snapshot

QA tests, security audits, SEO audits, and a final code review. 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 23 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.

📚 420+ Curated Skills

Zeoel ships with 420+ 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