# π€ Zeoel β AI Agency Multi-Agent Framework
### The 33-Agent AI Development Team That Builds Your Software
[](https://www.npmjs.com/package/zeoel-framework)
[](https://opensource.org/licenses/MIT)
[](AGENTS.md)
[](REFERENCES.md)
[](CLAUDE.md)
[](CONTRIBUTING.md)
**A production-grade multi-agent orchestration framework for Claude Code, Cursor, and Gemini CLI** that replaces monolithic AI prompts with a team of 33 specialized AI agents β each with curated skills, strict TDD enforcement, and sprint-based project management. Stop vibe-coding. Start shipping.
Works with **Claude Code** Β· **Cursor** Β· **Gemini CLI** Β· **GitHub Copilot** Β· **Antigravity** Β· and more
[Quick Start](#-quick-start) Β· [How It Works](#-how-it-works) Β· [The 33 Agents](#-the-33-specialized-agents) Β· [450+ Skills](#-450-curated-skills) Β· [Contributing](CONTRIBUTING.md)
---
## β‘ Quick Start
```bash
# 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](USER_MANUAL.md)** for the full guide and **[SETUP.md](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.**
| Feature | Plain AI Tool | Zeoel Framework |
|---|:---:|:---:|
| Structured 4-phase pipeline | β | β
|
| 33 specialized agents (frontend, backend, QA, DevOps...) | β | β
|
| π§ Smart Config Inference (reads your prompt, skips questions) | β | β
|
| π‘ Intelligent Model Routing (auto-selects cheapest LLM per task) | β | β
|
| πͺ Caveman & Graphify token compression (save up to 75% output and 71.5x input tokens) | β | β
|
| Cybersecurity, Growth Marketing, McKinsey Slides & PhD Research | β | β
|
| Strict TDD enforcement (Red-Green-Refactor) | β | β
|
| Sprint planning with progress tracking | β | β
|
| Automatic code containment (`frontend/` + `backend/`) | β | β
|
| Git worktree snapshots per sprint | β | β
|
| 450+ curated skills library | β | β
|
| Security audits + SEO audits built-in | β | β
|
| Cross-platform (Claude Code, Cursor, Gemini CLI, Copilot, Antigravity) | β | β
|
---
## π 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:
| Tier | When | Example Models | Cost |
|------|------|---------------|------|
| π’ **Light** | Docs, config, boilerplate, simple tests | `claude-3.5-haiku`, `gpt-4o-mini`, `gemini-flash` | π° |
| π‘ **Standard** | Components, APIs, CRUD, UI, unit tests | `claude-sonnet-4`, `gpt-4o`, `gemini-2.5-pro` | π°π° |
| π΄ **Complex** | Architecture, security, debugging, 3D, ML | `claude-opus-4`, `o3`, `gemini-2.5-pro` (thinking) | π°π°π° |
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:
| | Role | Name | Specialty & Tech Stack |
|---|---|---|---|
| π | CEO & Orchestrator | **Gohar** | Sprint planning, agent dispatch, worktree snapshots, caveman, graphify |
| π¨ | Product Designer | **Mahdi** | UX flows, accessibility, SEO-first design, frontend-design |
| π | Visual Director | **Mustafa** | Three.js, GSAP, premium styling, Framer Motion, design tokens |
| βοΈ | Sr. Frontend Engineer | **Karar** | Next.js App Router, shadcn/ui, 3D, GSAP, SEO, Tailwind, TDD |
| π₯Ύ | Bootstrap UI Architect | **Hassan** | Bootstrap 5, SCSS, responsive grid, dashboard layouts |
| π | shadcn/UI Specialist | **Noor** | shadcn/ui, Radix, Tailwind v4, custom design tokens, CVA |
| βοΈ | React UI Craftsman | **Anas** | React 19, Vite SPAs, Zustand, Jotai, TanStack Query, GSAP |
| π’ | Vue/Nuxt Architect | **Amina** | Vue 3 Composition API, Nuxt 4, Pinia, SSR, Vite, dynamic forms |
| π¨ | Pixel-Perfect CSS Eng | **Hasan** | CSS Grid/Subgrid, Container queries, View Transitions, OkLCH |
| π§ | Backend Engineer | **Tariq** | Laravel, PostgreSQL, SaaS billing, REST/GraphQL APIs |
| π | Content & SEO | **Zara** | Technical SEO, keyword strategy, JSON-LD, content marketing |
| π± | Mobile Developer | **Abdullah** | Flutter, Material 3, Riverpod, Kotlin, Swift |
| π | React Native Specialist | **Zayd** | React Native, Expo, native integration, performance |
| π | Data & ML Engineer | **Fatima** | Postgres analytics, ML pipelines, ClickHouse, Python |
| π | Python Engineer | **Abbas** | Python, Django, FastAPI, Scikit-learn, Celery |
| βοΈ | Systems Engineer | **Bilal** | Go, Rust, C++, high-performance networking |
| π | iOS Developer | **Layla** | SwiftUI, Swift concurrency, CoreData |
| π€ | Android Developer | **Hamza** | Kotlin, Jetpack Compose, clean architecture |
| π₯ | Healthcare Engineer | **Khadija** | HIPAA compliance, EMR integration, FHIR |
| βοΈ | Web3 Engineer | **Salman** | Smart contracts, DeFi, AMM security, Solidity, OpenZeppelin |
| π‘οΈ | Cybersecurity Expert | **Hamid** | Offensive security, red teaming, pen testing, EVM static analysis, cryptography |
| π | Growth Hacker | **Farhan** | Conversion rate optimization (CRO), high-persuasion copywriting, local geo-SEO |
| π | Slide Deck Designer | **Taha** | McKinsey PowerPoint design, MECE presentation Outlines, Chart.js slides |
| π | Comput. Spatial Expert | **Sami** | Parametric CAD algorithms, GeoJSON geometry bounds, spatial-GIS coordinates |
| π¬ | Principal PhD Researcher | **Yahya** | Google Scholar paper mappings, academic literature matrices, LaTeX/APA reports |
| π | Debugger & Performance | **Sajjad** | Systematic 4-phase debugging, performance profiling, error-handling |
| π | Docs & API Writer | **Baqir** | Technical writing, OpenAPI specs, developer experience |
| π§ͺ | QA Engineer | **Muhammad** | Playwright, Cypress, strict TDD enforcement |
| π‘οΈ | DevOps & Security | **Ali** | Docker, GitHub Actions, OWASP, CI/CD pipelines |
| π§ | AI Architect | **Ibrahim** | Multi-agent setups, MCP servers, LLM evaluations, self-evolution |
| β | Enterprise Java | **Yusuf** | Spring Boot, Quarkus, enterprise patterns |
| πΌ | Business Operations | **Maryam** | SaaS billing ops, logistics, startup metrics |
| π | Product Manager | **Zainab** | Agile sprint management, user story mapping, backlog grooming |
*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:
π¨ Frontend & Design (75+ skills)
`nextjs-turbopack` Β· `tailwindcss-v4` Β· `shadcn-ui-patterns` Β· `radix-ui-primitives` Β· `gsap-scrolltrigger` Β· `threejs-webgl` Β· `react-three-fiber` Β· `motion-framer` Β· `react-spring-physics` Β· `lottie-animations` Β· `animated-component-libraries` Β· `barba-js` Β· `locomotive-scroll` Β· `pixijs-2d` Β· `babylonjs-engine` Β· `spline-interactive` Β· `view-transitions-api` Β· `css-container-queries` Β· `design-tokens-system` Β· `micro-interactions` Β· `liquid-glass-design` Β· `modern-web-design` Β· `ui-ux-pro-max` Β· `frontend-design` Β· `frontend-patterns` Β· `figma-to-code` Β· `responsive-email-templates` Β· `vite-patterns` Β· `nuxt4-patterns` Β· `angular-developer` Β· `motion-design` Β· `material-3-skill` Β· `swiss-design-skill` Β· `taste-skill` Β· `transitions.dev` Β· and more...
π§ Backend & Infrastructure (60+ skills)
`laravel-patterns` Β· `laravel-security` Β· `laravel-tdd` Β· `nestjs-patterns` Β· `fastapi-patterns` Β· `django-patterns` Β· `springboot-patterns` Β· `postgres-patterns` Β· `redis-patterns` Β· `prisma-patterns` Β· `supabase-patterns` Β· `drizzle-orm-patterns` Β· `trpc-patterns` Β· `graphql-patterns` Β· `stripe-billing-patterns` Β· `oauth2-auth-patterns` Β· `rate-limiting-patterns` Β· `websocket-realtime` Β· `queue-patterns` Β· `docker-patterns` Β· `deployment-patterns` Β· `mysql-patterns` Β· and more...
π± Mobile (15+ skills)
`dart-flutter-patterns` Β· `kotlin-patterns` Β· `kotlin-coroutines-flows` Β· `swiftui-patterns` Β· `swiftui-pro` Β· `compose-multiplatform-patterns` Β· `android-clean-architecture` Β· `mobile-app-design` Β· `mobile-app-ui-design` Β· and more...
π€ AI & Agents (25+ skills)
`mcp-server-patterns` Β· `mcp-builder` Β· `mcp-server-builder` Β· `rag-pipeline` Β· `prompt-engineering` Β· `vercel-ai-sdk` Β· `pytorch-patterns` Β· `agentic-engineering` Β· `autonomous-loops` Β· `agent-teams` Β· `cost-aware-llm-pipeline` Β· `self-evolution` Β· `memento-skills` Β· and more...
π Security & Testing (35+ skills)
`test-driven-development` Β· `e2e-testing` Β· `security-review` Β· `security-scan` Β· `hipaa-compliance` Β· `systematic-debugging` Β· `error-handling` Β· `webapp-testing` Β· `claude-red` Β· `trailofbits-auditing` Β· `waza-habits` Β· and more...
π Computational & Technical Sciences (10+ skills)
`computational-architecture` Β· `postgres-patterns` Β· `python-patterns` Β· and more...
π Data & DevOps (30+ skills)
`postgres-patterns` Β· `clickhouse-io` Β· `redis-patterns` Β· `docker-patterns` Β· `deployment-patterns` Β· `git-workflow` Β· `github-ops` Β· and more...
πΌ Business & Operations (50+ skills)
`seo` Β· `content-engine` Β· `market-research` Β· `investor-materials` Β· `finance-billing-ops` Β· `customer-billing-ops` Β· `email-ops` Β· `growth-marketing` Β· `seo-growth` Β· `ppt-mckinsey` Β· `empirical-research` Β· `deep-research` Β· and more...
> π Browse all skills: [`all-skills/`](all-skills/) or [`.agents/skills/zeoel/skills/`](.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:
| Platform | Status | Setup |
|---|---|---|
| **Claude Code** | β
Full support | `CLAUDE.md` auto-detected |
| **Cursor** | β
Full support | `.cursorrules` auto-generated |
| **Gemini CLI** | β
Full support | `GEMINI.md` auto-generated |
| **GitHub Copilot** | β
Full support | `.github/copilot-instructions.md` |
| **Antigravity** | β
Full support | `AGENTS.md` auto-detected |
| **Windsurf** | β
Full support | `.windsurfrules` auto-generated |
---
## π 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](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](REFERENCES.md)** for the full list of projects that inspired our skills and methodology, including:
- [obra/superpowers](https://github.com/obra/superpowers) β Agentic skills methodology
- [Anthropic Claude Code](https://github.com/anthropics/claude-code) β CLAUDE.md conventions
- [VoltAgent](https://github.com/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](https://www.npmjs.com/package/zeoel-framework)
- **GitHub**: [goharabbas321/zeoel-framework](https://github.com/goharabbas321/zeoel-framework)
- **Creator**: Gohar Abbas ([@goharabbas321](https://github.com/goharabbas321))
- **Telegram**: [@goharabbas786](https://t.me/goharabbas786)
---
## π License
MIT Β© [Gohar Abbas](https://github.com/goharabbas321)
---
**If Zeoel saves you time, consider giving it a β**
Built with β€οΈ by the Zeoel team