docs initial

.claude/rules/agent-pipeline.md

@@ -2,25 +2,60 @@
 
 ## The Rule
 
-This project has a 20-agent team organized in a 4-tier hierarchy (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research — you MUST consult with the developer team by dispatching the orchestrator.
+This project has a 19-agent specialist team (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research, infrastructure, debugging — you MUST dispatch the appropriate specialist agents directly.
 
-The orchestrator handles everything: it dispatches leads (Architecture Lead, Quality Lead, Product Lead), who in turn dispatch their specialists. Results bubble up with structured audit trails.
+**You ARE the tech lead / orchestrator.** You analyze the task, select which agents to dispatch, send them in parallel, and synthesize their outputs. There is no separate orchestrator agent.
+
+## What You Must NOT Do
+
+- **Do NOT solve non-trivial tasks yourself.** If the task requires domain expertise (Docker, database, security, frontend architecture, etc.), dispatch the specialist agents.
+- **Do NOT investigate deeply, then decide whether to dispatch.** Identify affected files/areas, select agents, dispatch. Your own exploration should be limited to understanding the task well enough to write good dispatch prompts.
+
+## Team Roster
+
+| Agent | Type | Dispatch for |
+|-------|------|-------------|
+| **Architecture Lead** | Lead | API design, schema, cross-service, component architecture |
+| **Quality Lead** | Lead | Testing strategy, quality synthesis, test gap analysis |
+| **Product Lead** | Lead | UX, docs, ML/AI, monetization, feature strategy |
+| **DevOps Engineer** | Staff | CI/CD, Docker, Kubernetes, infrastructure, deployment |
+| **Debug Specialist** | Staff | Root cause analysis, cross-service debugging |
+
+Leads coordinate sub-teams internally:
+- Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
+- Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
+- Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
+
+**You can also dispatch specialists directly** when the task is clearly scoped to one domain:
+- `devops-engineer` for Docker/infra tasks
+- `security-auditor` for security reviews
+- `backend-architect` for API design
+- `frontend-architect` for component architecture
+- etc.
+
+Use leads when the task spans multiple specialists in their sub-team. Use specialists directly when the task is focused.
 
 ## Pipeline
 
 1. **Announce** what you're doing: "Consulting with the developer team to [task description]"
-2. **Dispatch the orchestrator** agent with your analysis of the task
-3. **Receive results** — the orchestrator returns a synthesized recommendation with a full audit trail of all agent calls
-4. **Report results** — present the synthesis to the user, crediting which specialists contributed
+2. **Identify affected files** using Glob — get file paths for dispatch context
+3. **Select agents** — minimum viable team based on the task
+4. **Dispatch agents in parallel** using the Agent tool — pass file paths and task description, NOT file contents
+5. **Collect results** from all dispatched agents
+6. **Synthesize** — present the unified report to the user, crediting which specialists contributed
 
-You do NOT need to: dispatch individual agents, process handoffs, manage chain depth, or sequence phases. The orchestrator → lead → specialist hierarchy handles all of this internally.
+## Dispatch Context
 
-## Announcement Format
+Every agent dispatch should include:
+- The specific task or question
+- File paths to analyze (the agent reads them itself)
+- Constraints from the overall task
+- What deliverable you need back
 
-Always start with a brief announcement before dispatching the orchestrator:
+## Skip Agents ONLY For
 
-> Consulting with the developer team: dispatching orchestrator to [task summary].
+- Rename a variable, fix a typo, fix a single-line syntax error
+- Answer a quick factual question about the codebase
+- Run a command the user explicitly asked for
 
-## Why
-
-The hierarchical agent system provides: autonomous agent-to-agent collaboration, structured guardrails (depth limits, loop prevention, cost control), full audit trails, and domain-expert analysis at every level. The orchestrator selects the right leads, leads select the right specialists, and each agent can consult others directly when needed.
+Everything else — even tasks that seem "simple" — gets dispatched to specialists.