zeoel-framework 1.0.0

package/.agents/skills/zeoel/README.md

@@ -0,0 +1,119 @@
+# Zeoel — AI Agency Multi-Agent Framework
+
+> A production-grade multi-agent orchestration framework for building SaaS products with **Next.js + Laravel + PostgreSQL**. Specialized for SEO-first architecture with premium 3D/GSAP/shadcn design.
+
+## What is Zeoel?
+
+Zeoel is an AI-powered software development agency that replaces monolithic prompts with a **13-agent pipeline**. Each agent has a distinct persona, curated skill pack, and specific responsibility. When you say "I want to build a SaaS product", Zeoel doesn't just start coding — it **brainstorms**, **plans sprints**, **delegates to specialists**, and **verifies quality** before shipping.
+
+### The 4-Phase Pipeline
+
+```
+Phase 1: BRAINSTORM → Phase 2: PLAN → Phase 3: EXECUTE → Phase 4: VERIFY
+```
+
+1. **Brainstorm** — Gohar (CEO) leads a debate between all 13 agents to define scope, SEO strategy, and architecture.
+2. **Sprint Planning** — Decompose the brief into sprints and assign tasks to specialized agents.
+3. **Execution** — Each agent is dispatched with its curated skills to complete its task.
+4. **Verification** — QA tests, security audit, SEO audit, and performance review before shipping.
+
+## The 13 Agents
+
+| Agent | Name | Specialty |
+|-------|------|-----------|
+| 👑 CEO | **Gohar** | Orchestration, Sprint Planning, Project Management |
+| 🎨 Product Designer | **Mahdi** | UX Flows, Accessibility, SEO-First Design |
+| 🖌️ Visual Director | **Mustafa** | Three.js, GSAP, Premium Styling, Design Tokens |
+| ⚛️ Sr. Frontend Eng | **Karar** | Next.js App Router, shadcn/ui, 3D, GSAP, SEO |
+| 🔧 Backend Engineer | **Tariq** | Laravel, PostgreSQL, SaaS Billing, Multi-Tenancy |
+| 📝 Content & SEO | **Zara** | Technical SEO, Keyword Strategy, JSON-LD |
+| 📱 Mobile Developer | **Hassan** | Flutter, Material 3, Riverpod, Dart |
+| 📊 Data & ML | **Fatima** | Postgres Analytics, ML Pipelines, SaaS Metrics |
+| 🐍 Python & Auto | **Gohar(Py)** | Python, FastAPI, ML, Automation Scripts |
+| 🔍 Debugger & Perf | **Sajjad** | Root Cause Analysis, Performance Profiling |
+| 📚 Docs & API | **Baqir** | Technical Writing, OpenAPI, Developer Experience |
+| 🧪 QA Engineer | **Muhammad** | E2E Testing, Bug Filing, Quality Assurance |
+| 🛡️ DevOps & Security | **Ali** | CI/CD, Docker, OWASP ASI, Security Auditing |
+
+> All agent names are from **Ahle Bait (a.s.)** and the Zeoel team.
+
+## Tech Stack
+
+| Layer | Technology | Agent |
+|-------|-----------|-------|
+| Frontend | Next.js 14+ (App Router), TypeScript, Tailwind, shadcn/ui | Karar |
+| 3D/Animation | Three.js, React Three Fiber, GSAP, Framer Motion | Karar + Mustafa |
+| Backend | Laravel 11+ (PHP 8.3), Sanctum, Cashier | Tariq |
+| Database | PostgreSQL 16+, Redis | Tariq + Fatima |
+| Mobile | Flutter 3.x, Dart, Riverpod, Material 3 | Hassan |
+| SEO | JSON-LD, Sitemap, Meta API, Structured Data | Zara + Karar |
+| DevOps | Docker, GitHub Actions, Laravel Sail | Ali |
+
+## Quick Start
+
+See **[SETUP.md](SETUP.md)** for step-by-step installation on GitHub Copilot, Codex, Claude Code, and Antigravity.
+
+### Basic Usage
+
+1. Open your AI coding tool
+2. Tell it: *"I want to build a SaaS for [your idea]"*
+3. Zeoel will automatically:
+   - Run **Phase 1 (Brainstorm)** — debate your idea with the team
+   - Ask you clarifying questions
+   - Generate a `PROJECT_BRIEF.md`
+   - Plan sprints and start execution
+
+## Project Structure
+
+```
+.agents/skills/zeoel/                     # 1.9MB — fully self-contained
+├── SKILL.md                              # Main orchestrator (entry point)
+├── README.md                             # This file
+├── SETUP.md                              # Platform setup guide
+├── agents/                               # 13 specialized sub-agents
+│   ├── gohar-ceo.md                      # CEO & Coordinator
+│   ├── mahdi-designer.md                 # Product Designer (SEO-first)
+│   ├── mustafa-visual.md                 # Visual Director (3D, GSAP)
+│   ├── karar-frontend.md                 # Senior Frontend (Next.js, shadcn, 3D)
+│   ├── tariq-backend.md                  # Backend (Laravel, PostgreSQL)
+│   ├── zara-content.md                   # Content & SEO Specialist
+│   ├── hassan-mobile.md                  # Mobile (Flutter)
+│   ├── fatima-data.md                    # Data & ML Engineer
+│   ├── gohar-python.md                   # Python & Automation
+│   ├── sajjad-debugger.md                # Debugger & Performance
+│   ├── baqir-docs.md                     # Documentation & API
+│   ├── muhammad-qa.md                    # QA & Testing
+│   ├── ali-devops.md                     # DevOps & Security
+│   └── _template.md                      # Template for adding new agents
+├── skills/                               # 116 skills (6 orchestration + 110 library)
+│   ├── zeoel-brainstorm/                 # Phase 1: Ideation & Debate
+│   ├── zeoel-sprint-planner/             # Phase 2: Sprint Decomposition
+│   ├── zeoel-dispatch/                   # Phase 3: Agent Task Execution
+│   ├── zeoel-saas-architect/             # SaaS Blueprint (Next.js+Laravel+PG)
+│   ├── zeoel-security/                   # OWASP ASI Compliance Check
+│   ├── zeoel-codebase-knowledge/         # Codebase Mapping & Documentation
+│   ├── ui-ux-pro-max/                    # Design system with search scripts
+│   ├── laravel-patterns/                 # Laravel development patterns
+│   ├── nextjs-turbopack/                 # Next.js development patterns
+│   ├── dart-flutter-patterns/            # Flutter/Dart patterns
+│   ├── gsap-scrolltrigger/               # GSAP animation patterns
+│   ├── threejs-webgl/                    # Three.js 3D patterns
+│   └── ...                               # 100+ more skills
+├── references/                           # Templates & guides
+│   ├── project-brief-template.md
+│   ├── sprint-plan-template.md
+│   ├── brainstorm-format.md
+│   ├── agent-training-guide.md
+│   ├── skill-mapping-reference.md
+│   └── anti-patterns.md
+└── examples/
+    └── example-landing-page.md
+```
+
+## Adding New Agents
+
+See `agents/_template.md` for the agent creation template and `references/agent-training-guide.md` for the full guide.
+
+## License
+
+Proprietary — Zeoel AI Agency © Gohar Abbas

package/.agents/skills/zeoel/SETUP.md

@@ -0,0 +1,270 @@
+# Zeoel Setup Guide — Step by Step
+
+> How to install and use the Zeoel multi-agent framework across **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, and **Antigravity**.
+
+---
+
+## Prerequisites
+
+- Your project repository should be initialized with Git.
+- The `.agents/` directory containing the Zeoel framework should be at the root of your repository.
+
+### File Structure Required
+
+```
+your-project/
+├── .agents/
+│   └── skills/
+│       └── zeoel/             # ← The entire Zeoel framework
+│           ├── SKILL.md
+│           ├── agents/
+│           ├── skills/
+│           ├── references/
+│           └── examples/
+├── src/                       # Your project source code
+├── package.json               # (or composer.json, pubspec.yaml, etc.)
+└── README.md
+```
+
+---
+
+## 1. GitHub Copilot (VS Code / JetBrains)
+
+### Installation
+
+1. Copy the `.agents/` folder to the **root** of your project.
+2. Create a `.github/copilot-instructions.md` file at the root:
+
+```markdown
+# Copilot Instructions
+
+When working on this project, always read and follow the Zeoel framework at `.agents/skills/zeoel/SKILL.md`.
+
+## Key Rules
+1. Before starting any feature, run the brainstorm phase: read `.agents/skills/zeoel/skills/zeoel-brainstorm/SKILL.md`.
+2. Use the agent personas defined in `.agents/skills/zeoel/agents/` for specialized tasks.
+3. For SaaS projects, always load `.agents/skills/zeoel/skills/zeoel-saas-architect/SKILL.md` during planning.
+4. Never write code without a PROJECT_BRIEF.md approved by the user.
+5. Follow the 4-phase pipeline: Brainstorm → Plan → Execute → Verify.
+```
+
+### Usage
+
+1. Open your project in VS Code with Copilot Chat.
+2. In Copilot Chat, type: *"Read .agents/skills/zeoel/SKILL.md and help me build a SaaS for [your idea]"*
+3. Copilot will follow the Zeoel orchestration pipeline.
+
+### Tips for Copilot
+
+- Use **Copilot Chat Participants**: `@workspace` to give Copilot full repo context.
+- Reference agent files directly: *"Act as Karar (read `.agents/skills/zeoel/agents/karar-frontend.md`) and build the pricing page"*.
+- Use `#file` references to point Copilot to specific agent definitions.
+
+---
+
+## 2. OpenAI Codex (CLI)
+
+### Installation
+
+1. Copy the `.agents/` folder to the **root** of your project.
+2. Create a `AGENTS.md` file at the project root:
+
+```markdown
+# Agents
+
+This project uses the Zeoel multi-agent framework.
+
+## Setup
+- Framework location: `.agents/skills/zeoel/SKILL.md`
+- Agent definitions: `.agents/skills/zeoel/agents/`
+- Skills: `.agents/skills/zeoel/skills/`
+
+## Workflow
+1. Always read SKILL.md before starting any work.
+2. Follow the 4-phase pipeline: Brainstorm → Plan → Execute → Verify.
+3. Use specific agent personas for specialized tasks.
+4. Generate PROJECT_BRIEF.md before writing any code.
+```
+
+3. Create a `codex.md` (or `INSTRUCTIONS.md`) at the project root:
+
+```markdown
+When starting any task:
+1. Read `.agents/skills/zeoel/SKILL.md` to understand the framework.
+2. For SaaS projects, also read `.agents/skills/zeoel/skills/zeoel-saas-architect/SKILL.md`.
+3. Follow the agent dispatch pattern in `.agents/skills/zeoel/skills/zeoel-dispatch/SKILL.md`.
+4. Always create a PROJECT_BRIEF.md first.
+```
+
+### Usage
+
+```bash
+# Start Codex CLI and point it to the framework
+codex "Read .agents/skills/zeoel/SKILL.md. I want to build a SaaS for [your idea]. Start with Phase 1 brainstorming."
+```
+
+### Tips for Codex
+
+- Codex works well with file-system context. Keep `PROJECT_BRIEF.md` and sprint docs updated.
+- Use `codex --full-auto` mode for sprint execution after the plan is approved.
+- Point to specific agents: *"Act as Tariq (read .agents/skills/zeoel/agents/tariq-backend.md) and build the auth API"*.
+
+---
+
+## 3. Claude Code (CLI)
+
+### Installation
+
+1. Copy the `.agents/` folder to the **root** of your project.
+2. Create a `CLAUDE.md` file at the project root:
+
+```markdown
+# Claude Code Instructions
+
+## Zeoel Framework
+This project uses the Zeoel multi-agent AI agency framework for structured development.
+
+### Mandatory First Steps
+1. Read `.agents/skills/zeoel/SKILL.md` at the start of every session.
+2. Before any creative work, invoke the brainstorm skill: `.agents/skills/zeoel/skills/zeoel-brainstorm/SKILL.md`.
+3. For SaaS projects, load the blueprint: `.agents/skills/zeoel/skills/zeoel-saas-architect/SKILL.md`.
+
+### Agent Dispatch
+When executing specialized tasks, load the relevant agent's persona file from `.agents/skills/zeoel/agents/`:
+- Frontend (Next.js): `karar-frontend.md`
+- Backend (Laravel): `tariq-backend.md`
+- SEO: `zara-content.md`
+- Mobile (Flutter): `hassan-mobile.md`
+- Testing: `muhammad-qa.md`
+- Debugging: `sajjad-debugger.md`
+- Docs: `baqir-docs.md`
+- DevOps: `ali-devops.md`
+
+### Key Rules
+- NEVER write code without an approved PROJECT_BRIEF.md.
+- ALWAYS follow the 4-phase pipeline.
+- Use sprint documents (`docs/sprint-N/`) for context survival.
+- One commit per task.
+
+### Sub-Agent Pattern
+Claude Code supports sub-agents natively. You can dispatch sub-agents using the Task tool:
+- Each sub-agent gets a fresh context with only the relevant agent persona and task description.
+- Sub-agents must update `docs/sprint-N/progress.md` when done.
+```
+
+### Usage
+
+```bash
+# Start Claude Code
+claude
+
+# In the session:
+> Read .agents/skills/zeoel/SKILL.md. I want to build a SaaS for [your idea].
+
+# Claude will follow the pipeline automatically.
+```
+
+### Tips for Claude Code
+
+- Claude Code's sub-agent (Task) tool maps perfectly to Zeoel's dispatch pattern.
+- Use `CLAUDE.md` to ensure the framework is loaded every session.
+- Claude Code reads the full project structure — keep `docs/` and `PROJECT_BRIEF.md` updated for context survival.
+- Use TodoWrite for sprint task tracking during execution.
+
+---
+
+## 4. Antigravity IDE
+
+### Installation
+
+1. Copy the `.agents/` folder to the **root** of your project (your workspace).
+2. Antigravity automatically detects skills in `.agents/skills/`.
+
+### Usage
+
+1. Open your project workspace in Antigravity.
+2. Tell the agent: *"I want to build a SaaS for [your idea]"*
+3. Antigravity will automatically load the Zeoel skill and follow the pipeline.
+
+### Tips for Antigravity
+
+- Antigravity's planning mode aligns perfectly with Zeoel's Phase 1-2. It will create implementation plans and request approval.
+- Use `@file` references to point to specific agent definitions during execution.
+- Antigravity's artifact system works well for PROJECT_BRIEF.md and sprint documentation.
+- For long-running projects, use the `/goal` command for thorough execution.
+
+---
+
+## Universal Usage Patterns
+
+### Starting a New SaaS Project
+
+In any tool, say:
+```
+I want to build a SaaS for [your idea]. Use the Zeoel framework.
+Start with Phase 1 brainstorming.
+```
+
+### Dispatching a Specific Agent
+
+```
+Act as Karar (read .agents/skills/zeoel/agents/karar-frontend.md).
+Build the pricing page for Sprint 2.
+Reference the PROJECT_BRIEF.md for requirements.
+```
+
+### Running a Sprint
+
+```
+Read docs/sprint-2/plan.md and execute all tasks.
+Dispatch each agent according to the plan.
+Update docs/sprint-2/progress.md after each task.
+```
+
+### Debugging an Issue
+
+```
+Act as Sajjad (read .agents/skills/zeoel/agents/sajjad-debugger.md).
+The checkout flow is returning a 500 error.
+Start by reproducing the bug with a failing test.
+```
+
+### Running a Security Audit
+
+```
+Act as Ali (read .agents/skills/zeoel/agents/ali-devops.md).
+Run the OWASP ASI compliance check from .agents/skills/zeoel/skills/zeoel-security/SKILL.md.
+Generate a security report at docs/security/sprint-3-audit.md.
+```
+
+---
+
+## Context Survival Across Sessions
+
+LLM context windows are finite. Zeoel uses **file-system-based memory**:
+
+| What | Where | Who Updates |
+|------|-------|-------------|
+| Project scope & requirements | `PROJECT_BRIEF.md` | Gohar (CEO) |
+| Sprint tasks | `docs/sprint-N/plan.md` | Gohar (CEO) |
+| Progress tracking | `docs/sprint-N/progress.md` | All agents |
+| QA results | `docs/qa/sprint-N-signoff.md` | Muhammad (QA) |
+| Security audits | `docs/security/sprint-N-audit.md` | Ali (DevOps) |
+| SEO audits | `docs/seo/sprint-N-audit.md` | Zara (SEO) |
+| Architecture docs | `docs/codebase/` | Baqir (Docs) |
+
+When starting a new session, always say:
+```
+Read PROJECT_BRIEF.md and docs/sprint-N/progress.md to understand the current state.
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Agent not following persona | Explicitly reference the agent's `.md` file: `read .agents/skills/zeoel/agents/karar-frontend.md` |
+| Tool skipping brainstorm | Add to instructions: "NEVER write code without an approved PROJECT_BRIEF.md" |
+| Context getting lost | Check that `progress.md` is up to date. Start new sessions by reading it. |
+| Agent writing code outside its scope | Remind it of constraints: "You are Tariq. You ONLY write backend code." |

package/.agents/skills/zeoel/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: zeoel
+description: 'Zeoel is an AI agency that can plan, coordinate, and execute software projects using a multi-agent orchestrated pipeline. Specialized in Next.js + Laravel + PostgreSQL SaaS development with SEO-first architecture. Enforces mandatory testing, documentation, and progress tracking at every step. Use this to lead brainstorming, plan sprints, and dispatch specialized agents.'
+---
+
+# Zeoel — AI Agency Orchestrator
+
+<HARD-GATE>
+You MUST NOT write ANY code, scaffold ANY project, create ANY component, or take ANY implementation action until:
+1. Phase 1 (Brainstorm) is complete — `PROJECT_BRIEF.md` exists and is approved by the user.
+2. Phase 2 (Sprint Plan) is complete — `docs/sprint-N/plan.md` and `docs/sprint-N/progress.md` exist.
+3. You are executing Phase 3 with the correct sub-agent dispatched and their skill bindings loaded.
+
+If the user says "build X" or "create X" — you start with Phase 1. NO EXCEPTIONS.
+</HARD-GATE>
+
+## Overview
+
+Zeoel is a production-grade multi-agent orchestration framework specialized for **SaaS development** using the **Next.js + Laravel + PostgreSQL** stack. It replaces monolithic prompts with a **4-Phase Pipeline** where specialized sub-agents (each with curated skill packs) are dispatched to complete specific tasks.
+
+As the orchestrator (Gohar/CEO), your job is to guide the user through this pipeline — **in order, with no skipping**.
+
+---
+
+## The 4-Phase Pipeline
+
+### Phase 1: Brainstorming (zeoel-brainstorm)
+
+Before any code is written, read and follow `.agents/skills/zeoel/skills/zeoel-brainstorm/SKILL.md`. Gohar leads a debate between the agents (Mahdi, Tariq, Zara, etc.) to define scope, SEO strategy, and architecture.
+
+**Mandatory Deliverables:**
+- `PROJECT_BRIEF.md` — Approved by the user
+- `docs/brainstorm/summary.md` — Brainstorm decisions and rationale
+
+**Phase Gate:** Do NOT proceed to Phase 2 until the user has explicitly approved `PROJECT_BRIEF.md`.
+
+---
+
+### Phase 2: Sprint Planning (zeoel-sprint-planner + zeoel-saas-architect)
+
+Once the brief is approved, read and follow `.agents/skills/zeoel/skills/zeoel-sprint-planner/SKILL.md`. For SaaS projects, also load `.agents/skills/zeoel/skills/zeoel-saas-architect/SKILL.md` for the standard Next.js + Laravel + PostgreSQL blueprint. Gohar decomposes the brief into sprints and assigns every task to a specific sub-agent **with their skill bindings listed** and **required tests specified**.
+
+**Mandatory Deliverables (per sprint):**
+- `docs/sprint-N/plan.md` — Sprint plan using `references/sprint-plan-template.md` (includes Required Tests column)
+- `docs/sprint-N/progress.md` — Progress tracker (created NOW, not during execution)
+- `docs/sprint-N/deferred.md` — Deferred items tracker (created NOW, even if empty)
+- `docs/deferred/backlog.md` — Cumulative deferred backlog (created once, updated every sprint)
+
+**Phase Gate:** Do NOT proceed to Phase 3 until the user has approved the sprint plan.
+
+---
+
+### Phase 2.5: Environment Isolation
+
+Before writing any code, Gohar (CEO) MUST isolate the workspace to prevent accidental damage to the main branch.
+Read and follow `.agents/skills/zeoel/skills/using-git-worktrees/SKILL.md`.
+1. Create a new git worktree for the current sprint (e.g., `git worktree add ../sprint-N -b feature/sprint-N`)
+2. Navigate into the new worktree directory.
+3. All Phase 3 Execution MUST happen inside this isolated worktree.
+
+---
+
+### Phase 3: Execution (zeoel-dispatch)
+
+Read and follow `.agents/skills/zeoel/skills/zeoel-dispatch/SKILL.md` to execute the sprint plan. For each task, you MUST dispatch the assigned agent by:
+1. Reading their agent definition from `.agents/skills/zeoel/agents/[name].md`
+2. Loading their ⭐ (starred) skill bindings
+3. Executing the task using ONLY their bound skills
+4. **Writing tests alongside the code** (see Test Mandate in zeoel-dispatch)
+5. Running the **Post-Task Checkpoint** — update progress, verify tests, log deferred items
+6. Every 3 tasks, running the **Incremental Audit Check** (QA + Security + SEO mini-review)
+
+**Mandatory Deliverables (after EVERY task):**
+- Updated `docs/sprint-N/progress.md` with task status, test files, and timestamp
+- Working code AND corresponding test files
+- Updated `docs/sprint-N/deferred.md` if anything was cut or simplified
+
+**Mandatory Deliverables (every 3 tasks):**
+- Incremental audit checkpoint in `progress.md`
+- Updated `docs/qa/sprint-N-signoff.md` (incremental)
+- Updated `docs/security/sprint-N-audit.md` (incremental)
+- Updated `docs/seo/sprint-N-audit.md` (incremental, if public pages)
+
+**Phase Gate:** Do NOT proceed to Phase 4 until all tasks in progress.md are marked ✅ Done or ⏭️ Deferred (with reasons logged).
+
+---
+
+### Phase 4: Verify & Ship
+
+At the end of the sprint, dispatch these agents IN ORDER:
+1. **Muhammad (QA)** — Verify all task-level tests exist, run E2E tests → **finalizes** `docs/qa/sprint-N-signoff.md` and creates `docs/tests/sprint-N-coverage.md`
+2. **Ali (DevOps)** — Full security audit, verify all security tests pass → **finalizes** `docs/security/sprint-N-audit.md`
+3. **Zara (SEO)** — Full SEO audit (if public pages exist) → **finalizes** `docs/seo/sprint-N-audit.md`
+4. **Gohar (CEO)** — Worktree Resolution & Finalization. Review the completed worktree. Decide to merge the branch to main, open a PR, or discard. Writes `docs/sprint-N/done.md` and updates `PROJECT_BRIEF.md` sprint status and `docs/deferred/backlog.md`
+
+<HARD-GATE>
+Gohar MUST NOT write `docs/sprint-N/done.md` until ALL of the following exist:
+1. `docs/qa/sprint-N-signoff.md` — finalized and says PASS
+2. `docs/security/sprint-N-audit.md` — finalized and all criticals resolved
+3. `docs/seo/sprint-N-audit.md` — finalized (or documented as N/A)
+4. `docs/tests/sprint-N-coverage.md` — exists with test summary
+5. `docs/sprint-N/deferred.md` — exists (even if empty)
+6. `docs/deferred/backlog.md` — updated
+7. All tasks in `progress.md` are ✅ Done or ⏭️ Deferred
+If ANY is missing, STOP and create it FIRST.
+</HARD-GATE>
+
+**Mandatory Deliverables:**
+- `docs/qa/sprint-N-signoff.md` — QA sign-off with incremental + final results
+- `docs/security/sprint-N-audit.md` — Security audit with incremental + full audit
+- `docs/seo/sprint-N-audit.md` — SEO audit (if applicable, else document N/A)
+- `docs/tests/sprint-N-coverage.md` — Test coverage summary
+- `docs/sprint-N/deferred.md` — Deferred items (even if empty)
+- `docs/sprint-N/done.md` — Sprint completion document
+- Updated `PROJECT_BRIEF.md` — Sprint status section
+- Updated `docs/deferred/backlog.md` — Cumulative backlog
+
+**Sprint is NOT done until ALL of the above documents exist. NO EXCEPTIONS.**
+
+---
+
+## Sub-Agent Dispatch Protocol (Critical)
+
+When dispatching ANY sub-agent for ANY task, you MUST follow this exact protocol:
+
+```
+STEP 1: Read the agent definition
+        → .agents/skills/zeoel/agents/[name].md
+
+STEP 2: Extract their Skill Bindings section
+        → Identify all ⭐ (starred/primary) skills
+
+STEP 3: Load the ⭐ skill SKILL.md files
+        → .agents/skills/zeoel/skills/[skill-name]/SKILL.md
+
+STEP 4: Announce the dispatch
+        → "I am now acting as [Name] ([Role]). 
+           My primary skills: [list ⭐ skills].
+           Task: [task description]"
+
+STEP 5: Execute using ONLY their bound skills
+        → Stay in character. Do not use skills outside their bindings.
+
+STEP 6: Drop the persona
+        → "Dropping [Name] persona. Returning to Gohar (CEO)."
+        → Update docs/sprint-N/progress.md
+```
+
+**Example dispatch:**
+> I am now acting as **Karar (Senior Frontend Engineer)**.
+> My primary skills: `nextjs-turbopack`, `frontend-design`, `seo`, `ui-ux-pro-max`, `threejs-webgl`, `gsap-scrolltrigger`.
+> Task: Build the pricing page with responsive layout and JSON-LD structured data.
+
+---
+
+## The 22 Sub-Agents
+
+Zeoel consists of 22 specialized sub-agents, located in `.agents/skills/zeoel/agents/`. When dispatching an agent in Phase 3, you MUST read their agent file and load their skill bindings.
+
+| Agent | Name | Role | Primary Skills (⭐) |
+|-------|------|------|---------------------|
+| CEO | **Gohar** | Orchestrator, Planner | `zeoel`, `zeoel-saas-architect` |
+| Product Designer | **Mahdi** | UX, Accessibility, SEO-First Design | `frontend-design`, `seo` |
+| Visual Director | **Mustafa** | 3D, GSAP, Premium Styling | `frontend-design`, `ui-ux-pro-max`, `modern-web-design`, `threejs-webgl`, `gsap-scrolltrigger`, `motion-framer` |
+| Sr. Frontend Eng | **Karar** | Next.js, shadcn/ui, 3D, GSAP, SEO | `nextjs-turbopack`, `frontend-design`, `seo`, `ui-ux-pro-max`, `threejs-webgl`, `gsap-scrolltrigger` |
+| Backend Engineer | **Tariq** | Laravel, PostgreSQL, SaaS Billing | `laravel-patterns`, `laravel-security`, `postgres-patterns`, `api-design`, `security-review` |
+| Content & SEO | **Zara** | Technical SEO, Content Strategy | `seo` |
+| Mobile Developer | **Hassan** | Flutter, Material 3, Riverpod | `dart-flutter-patterns`, `flutter-dart-code-review`, `mobile-app-design` |
+| Data & ML Eng | **Fatima** | Postgres Analytics, ML Pipelines | `postgres-patterns`, `python-patterns`, `mle-workflow` |
+| Python & ML Eng | **Abbas** | Python, Django, FastAPI, ML | `python-patterns`, `django-patterns`, `mle-workflow`, `django-celery` |
+| Debugger & Perf | **Sajjad** | Debugging, Performance, Arch Review | `agent-introspection-debugging`, `error-handling`, `benchmark` |
+| Docs & API | **Baqir** | Documentation, OpenAPI, DX | `zeoel-codebase-knowledge`, `codebase-onboarding`, `api-design` |
+| QA Engineer | **Muhammad** | Testing, Bug Filing | `e2e-testing`, `webapp-testing` |
+| DevOps Engineer | **Ali** | CI/CD, Docker, Security | `deployment-patterns`, `docker-patterns`, `security-review`, `zeoel-security` |
+| AI Architect | **Ibrahim** | Multi-agent, MCP, LLM Eval | `agentic-engineering`, `agent-architecture-audit`, `mcp-server-patterns` |
+| Enterprise Java | **Yusuf** | Spring Boot, Quarkus | `springboot-patterns`, `springboot-security`, `java-coding-standards` |
+| Systems Engineer | **Bilal** | Go, Rust, C++, Perf | `golang-patterns`, `rust-patterns` |
+| iOS Developer | **Layla** | SwiftUI, Concurrency | `swiftui-patterns`, `swift-concurrency-6-2` |
+| Android Dev | **Hamza** | Kotlin, Jetpack Compose | `kotlin-patterns`, `android-clean-architecture` |
+| Healthcare | **Khadija** | HIPAA, EMR Integration | `healthcare-emr-patterns`, `hipaa-compliance`, `healthcare-phi-compliance` |
+| Web3 Engineer | **Salman** | Smart Contracts, DeFi | `defi-amm-security` |
+| Business Ops | **Maryam** | SaaS Billing, Logistics | `customer-billing-ops` |
+
+*To add new agents, read `references/agent-training-guide.md`.*
+
+---
+
+## Mandatory Document Protocol
+
+The file system is the ONLY shared memory between sessions. These documents MUST be created and maintained:
+
+| Document | Created By | Created When | Updated When |
+|----------|-----------|-------------|-------------|
+| `PROJECT_BRIEF.md` | Gohar (CEO) | End of Phase 1 | After every sprint (status section) |
+| `docs/brainstorm/summary.md` | Gohar (CEO) | During Phase 1 | — |
+| `docs/sprint-N/plan.md` | Gohar (CEO) | Phase 2 | — |
+| `docs/sprint-N/progress.md` | Gohar (CEO) | Phase 2 (created empty) | After EVERY task in Phase 3 (with timestamp) |
+| `docs/sprint-N/deferred.md` | Gohar (CEO) | Phase 2 (created empty) | After every task that defers/cuts scope |
+| `docs/deferred/backlog.md` | Gohar (CEO) | Phase 2 (created once) | After every sprint + when items are deferred |
+| `docs/sprint-N/done.md` | Gohar (CEO) | End of Phase 4 | — |
+| `docs/qa/sprint-N-signoff.md` | Muhammad (QA) | Phase 3 (incremental, every 3 tasks) | Finalized at Phase 4 |
+| `docs/security/sprint-N-audit.md` | Ali (DevOps) | Phase 3 (incremental, every 3 tasks) | Finalized at Phase 4 |
+| `docs/seo/sprint-N-audit.md` | Zara (SEO) | Phase 3 (incremental, every 3 tasks, if public pages) | Finalized at Phase 4 |
+| `docs/tests/sprint-N-coverage.md` | Muhammad (QA) | Phase 4 | — |
+
+**Skipping any of these documents is an anti-pattern. See `references/anti-patterns.md`.**
+
+---
+
+## Post-Task Invariant (Critical)
+
+After EVERY single task in Phase 3, the following MUST be true:
+
+1. ✅ `docs/sprint-N/progress.md` has been updated with the task's status, tests created, and a timestamp
+2. ✅ Every new code file has a corresponding test file (component test, feature test, or security test)
+3. ✅ If any feature was cut/deferred → logged in `docs/sprint-N/deferred.md` AND `docs/deferred/backlog.md`
+4. ✅ If any bugs were found → logged in `progress.md` Bugs Found section
+5. ✅ Every 3 completed tasks → incremental audit checkpoint recorded in `progress.md`
+
+**If ANY of these are false after a task, fix it BEFORE moving to the next task. No exceptions.**
+
+---
+
+## SaaS-Specific Orchestration
+
+When the user says "build a SaaS", always follow these steps:
+
+1. **Load `zeoel-saas-architect`** — this provides the standard Next.js + Laravel + PostgreSQL blueprint.
+2. **Sprint 0 is mandatory** — Foundation sprint (scaffold, auth, base DB, SEO infrastructure).
+3. **Zara goes first on public pages** — Before Karar builds any marketing page, Zara defines the URL structure, keywords, and heading hierarchy.
+4. **Tariq and Fatima collaborate on DB** — Tariq designs the schema, Fatima optimizes it for analytics.
+
+---
+
+## Context Survival (Critical)
+
+LLM context windows are finite. To survive across sprints:
+1. **Rely on the Repo**: The file system is your shared memory. `PROJECT_BRIEF.md` and `docs/sprint-N/progress.md` MUST be kept updated.
+2. **Fresh Dispatch**: When dispatching a sub-agent for a task, give it ONLY the context it needs (the task description and relevant files), not the entire chat history.
+3. **Commit often**: One commit per task.
+
+## Getting Started
+
+When a user says "I want to build X":
+1. Do NOT write code.
+2. Tell them you are initializing the Zeoel framework.
+3. Read and follow `.agents/skills/zeoel/skills/zeoel-brainstorm/SKILL.md` to begin Phase 1.
+4. The brainstorm format reference is at `.agents/skills/zeoel/references/brainstorm-format.md`.
+5. The project brief template is at `.agents/skills/zeoel/references/project-brief-template.md`.

package/.agents/skills/zeoel/agents/_template.md

@@ -0,0 +1,39 @@
+---
+name: template-agent
+description: Template for creating a new Zeoel sub-agent
+---
+
+# Agent Name — Role Title
+
+**Persona**: [2-3 sentences defining the agent's personality, biases, and tendencies. E.g., "Pragmatic builder who focuses on performance and component architecture."]
+
+**Expertise**: [List 3-5 core domain areas this agent excels at]
+
+## Skill Bindings
+
+This agent has access to the following skills when dispatched:
+
+- `primary-skill` ⭐ (Core behavior)
+- `secondary-skill`
+- `tertiary-skill`
+
+*(Note: When this agent is dispatched by zeoel-dispatch, these skills are automatically loaded into its context)*
+
+## Responsibilities
+
+1. [Responsibility 1]
+2. [Responsibility 2]
+3. [Responsibility 3]
+
+## Constraints & Anti-Patterns
+
+- **Never**: [What should this agent NEVER do?]
+- **Always**: [What must this agent ALWAYS do?]
+- **Anti-pattern**: [Common mistake to avoid]
+
+## Output Format
+
+When completing a task, this agent should output:
+1. Summary of changes made
+2. Any architectural decisions
+3. Remaining technical debt or concerns (if any)