@vpxa/aikit 0.1.2 → 0.1.4

package/scaffold/general/skills/multi-agents-development/SKILL.md

@@ -1,435 +1,435 @@
-# Multi-Agent Development
-
-Comprehensive patterns for orchestrating multiple AI agents in parallel development workflows. Covers task decomposition, parallel dispatch, context crafting, status handling, review pipelines, and recovery.
-
-**Core Principle**: Dispatch multiple agents for focused tasks. Each subagent gets fresh, focused context with explicit scope — never inherited session state.
-
-Load this skill when orchestrating multi-agent work: planning parallel batches, crafting delegation prompts, handling implementer status, running review pipelines, or recovering from agent failures.
-
----
-
-## §1 Agent Roles & Model Selection
-
-### Role Categories
-
-| Role | Agents | When to Use | Parallelizable |
-|------|--------|-------------|----------------|
-| **Orchestration** | Orchestrator, Planner | Workflow control, planning | No (sequential) |
-| **Implementation** | Implementer, Frontend, Refactor | Code creation/modification | Yes (disjoint files only) |
-| **Research** | Explorer, Researcher-Alpha/Beta/Gamma/Delta | Codebase exploration, decisions | Yes (always) |
-| **Review** | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta | Quality verification | Yes (always) |
-| **Diagnostics** | Debugger, Security | Issue tracing, vulnerability analysis | Yes (read-only) |
-| **Documentation** | Documenter | README, API docs, changelog | Yes (disjoint files) |
-
-### Model Selection by Task Complexity
-
-Choose the **least powerful model that can handle the role**:
-
-| Complexity Signal | Model Tier | Example Agents |
-|-------------------|-----------|----------------|
-| Mechanical (rename, move, add field) | Fast model | Explorer (Gemini Flash) |
-| Standard (implement spec, write tests) | Mid-tier | Implementer (GPT-5.4), Refactor (GPT-5.4) |
-| Judgment-heavy (architecture, security, debug) | Strongest | Debugger (Opus 4.6), Security (Opus 4.6) |
-| Multi-model cross-validation | Mixed | Researcher-Alpha/Beta/Gamma/Delta (all different) |
-
-**Upgrade signal**: If an agent returns `BLOCKED` or `DONE_WITH_CONCERNS` on a task classified as "Standard", consider re-dispatching to a stronger model.
-
----
-
-## §2 Task Decomposition Rules
-
-### The Golden Rule
-> **One task = one focused problem domain = 1-3 files maximum.**
-
-### Decomposition Checklist
-
-For each task, specify ALL of:
-- [ ] **Target files** — exact paths to create or modify
-- [ ] **Acceptance criteria** — what "done" looks like (testable)
-- [ ] **Agent assignment** — which agent handles this
-- [ ] **Dependencies** — which tasks must complete first (if any)
-
-### Sizing Guide
-
-| Task Size | Files | Example | Agent |
-|-----------|-------|---------|-------|
-| **Micro** | 1 file | Add a utility function | Implementer |
-| **Small** | 1-2 files | New endpoint + test | Implementer |
-| **Standard** | 2-3 files | Feature with service + controller + test | Implementer |
-| **Too big** | 4+ files | **SPLIT IT** — decompose further | — |
-
-### Splitting Strategies
-- **By layer**: Service logic (Implementer) + UI component (Frontend) + tests (Implementer)
-- **By feature boundary**: Auth endpoints (Implementer A) + Profile endpoints (Implementer B)
-- **By concern**: Data model changes (Implementer) + API route changes (Implementer) + UI updates (Frontend)
-
----
-
-## §3 Independence Decision Tree
-
-Before marking tasks as parallel, walk this tree:
-
-```
-Task A and Task B — can they run in parallel?
-│
-├─ Do they share ANY files? (create, modify, or delete the same file)
-│   ├─ YES → SEQUENTIAL (or merge into one task)
-│   └─ NO ↓
-│
-├─ Do they share mutable state? (env vars, globals, same DB table, shared config)
-│   ├─ YES → SEQUENTIAL
-│   └─ NO ↓
-│
-├─ Does B need A's output? (B reads a file A creates, B uses A's new export)
-│   ├─ YES → SEQUENTIAL (A before B)
-│   └─ NO ↓
-│
-├─ Would A's result change B's approach? (A discovers something that affects B)
-│   ├─ YES → SEQUENTIAL or single agent
-│   └─ NO ↓
-│
-├─ Resource contention? (same port, same build process, same lock file)
-│   ├─ YES → SEQUENTIAL
-│   └─ NO ↓
-│
-└─ ✅ SAFE TO PARALLELIZE
-```
-
-### Edge Cases
-
-| Situation | Verdict | Why |
-|-----------|---------|-----|
-| Both import from same module (read-only) | ✅ Parallel | Reading shared code is fine |
-| Both add exports to same index file | ❌ Sequential | Concurrent index.ts edits will conflict |
-| A creates a type, B uses that type | ❌ Sequential | B depends on A's output |
-| Both modify different test files | ✅ Parallel | Disjoint file sets |
-| Both touch package.json | ❌ Sequential | Shared file |
-| A adds a route, B adds middleware | ⚠️ Check | If B's middleware affects A's route → sequential |
-
-### Integration Verification (after parallel batch completes)
-
-1. **Conflict check**: Did any agent unexpectedly modify a file assigned to another agent?
-2. **Import check**: Do all new cross-references resolve?
-3. **Full suite**: `check({})` + `test_run({})` — everything must pass
-4. **Spot check**: Manually verify at least one task's output matches acceptance criteria
-
----
-
-## §4 Parallel Dispatch Patterns
-
-### Dispatch Rules
-
-1. **Max 4 concurrent file-modifying agents** per batch
-2. **Read-only agents have no limit** — Explorer, Researcher*, Reviewer*, Security can always run in parallel
-3. **Build dependency graph first** — phases with no dependencies MUST be batched together
-4. **Never dispatch two implementers to the same file** — even different sections
-
-### Batch Strategy
-
-```
-Phase Plan:
-  Phase 1: [Task A, Task B, Task C]  ← no dependencies between A/B/C
-  Phase 2: [Task D, Task E]          ← D depends on A, E depends on B
-  Phase 3: [Task F]                  ← F depends on D and E
-
-Execution:
-  Batch 1: dispatch(A, B, C) in parallel → review → gate
-  Batch 2: dispatch(D, E) in parallel → review → gate
-  Batch 3: dispatch(F) → review → gate
-```
-
-### Anti-Patterns
-
-| ❌ Don't | ✅ Do Instead |
-|----------|--------------|
-| Dispatch 6 implementers at once | Max 4, queue the rest |
-| Give one agent 10 files | Split into 3-4 focused tasks |
-| Let agents read the full plan | Give each agent ONLY its task context |
-| Retry same prompt on failure | Diagnose first, then re-prompt with fix |
-| Skip review after parallel batch | ALWAYS review + integration verify |
-| Inherit session context to subagent | Build fresh, focused context per dispatch |
-
----
-
-## §5 Context Crafting Guide
-
-### The Controller Principle
-> **The Orchestrator provides ALL context. Subagents never need to search for context themselves.**
-
-Each subagent gets a fresh, self-contained prompt. No inherited session state. No "read the plan first."
-
-### The 6-Point Prompt Template
-
-Every delegation prompt MUST include:
-
-```markdown
-## 1. Scope
-Files to create/modify: [exact paths]
-Files to NOT touch: [boundaries]
-
-## 2. Goal
-[What the code should do — acceptance criteria, testable outcomes]
-
-## 3. Architectural Context
-[Relevant patterns, conventions, existing code structure]
-[Include actual code snippets from compact/digest — don't tell agent to "go read X"]
-
-## 4. Constraints
-- Follow [pattern/convention]
-- Do NOT modify [boundary files]
-- Use [specific library/approach]
-
-## 5. FORGE Context
-Tier: [Floor/Standard/Critical]
-Evidence requirements: [what evidence to collect]
-
-## 6. Self-Review & Status
-Before declaring DONE, verify:
-- [ ] All acceptance criteria met
-- [ ] No files outside scope modified
-- [ ] Tests pass (if applicable)
-- [ ] Code follows stated conventions
-
-End with status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
-```
-
-### What to Include vs Omit
-
-| ✅ Include | ❌ Omit |
-|-----------|---------|
-| Exact file paths and code snippets | Full session history |
-| Acceptance criteria | Other agents' tasks |
-| Relevant conventions (from KB) | Unrelated architecture context |
-| Compact/digest of relevant files | Raw file contents of large files |
-| Error messages (if fixing a bug) | Previous failed attempts (unless relevant) |
-| FORGE tier and ceremony | Full FORGE protocol explanation |
-
-### Context Size Budget
-
-| Task Complexity | Context Target | Approach |
-|-----------------|---------------|----------|
-| Micro (1 file) | ~500 tokens | Inline code snippet + goal |
-| Small (1-2 files) | ~1000 tokens | `compact` of target files + goal |
-| Standard (2-3 files) | ~2000 tokens | `digest` of related files + architectural context |
-| Complex (judgment-heavy) | ~3000 tokens | `digest` + relevant decisions from AI Kit |
-
----
-
-## §6 Subagent Execution Cycle
-
-### Lifecycle
-
-```
-Orchestrator                          Subagent (fresh instance)
-    │                                      │
-    ├─ Craft focused prompt ──────────────►│
-    │  (6-point template)                  │
-    │                                      ├─ Understand scope
-    │                                      ├─ Implement changes
-    │                                      ├─ Self-review (checklist)
-    │◄─────────────────── Return status ───┤
-    │                                      │ (DONE/CONCERNS/NEEDS/BLOCKED)
-    │                                      │
-    ├─ Handle status (see §7)              ×  (subagent terminates)
-    │
-    ├─ Automated gate (check/test_run)
-    │
-    ├─ Dispatch reviewers (see §8)
-    │
-    └─ FORGE evidence_map gate
-```
-
-### Key Rules
-
-1. **One subagent = one task**. Never reuse a subagent for a different task.
-2. **Controller provides context**. The subagent's prompt contains everything it needs — it should NOT need to search/explore the codebase.
-3. **Self-review before handoff**. Every implementer must complete the self-review checklist before declaring DONE.
-4. **Status is mandatory**. Every subagent response MUST end with exactly ONE status code.
-
----
-
-## §7 Implementer Status Protocol
-
-### Status Codes
-
-Every implementer (Implementer, Frontend, Refactor) MUST end their response with exactly ONE:
-
-| Status | Meaning | Orchestrator Action |
-|--------|---------|-------------------|
-| **DONE** | All tasks complete, self-review passed | → Automated gate → Review pipeline |
-| **DONE_WITH_CONCERNS** | Complete but flagging issues: [list] | → Surface concerns as `Assumed` claims in evidence_map → Likely HOLD → Address before review |
-| **NEEDS_CONTEXT** | Cannot proceed without: [specific question] | → Provide missing context → Re-dispatch same task (counts as retry) |
-| **BLOCKED** | Hit a wall: [description] | → Diagnose (see below) |
-
-### BLOCKED Diagnosis Tree
-
-```
-Agent returned BLOCKED
-│
-├─ Missing context? (needs info not in prompt)
-│   → Provide context, re-dispatch
-│
-├─ Wrong model? (task too complex for assigned model)
-│   → Re-dispatch to stronger model (e.g., Implementer → Debugger)
-│
-├─ Scope too broad? (agent overwhelmed)
-│   → Split task further, re-dispatch smaller pieces
-│
-├─ Plan wrong? (implementation approach won't work)
-│   → Re-plan this phase, check AI Kit for alternatives
-│
-└─ External blocker? (dependency not ready, API unavailable)
-    → Park task, proceed with independent work, revisit later
-```
-
-### FORGE Composition
-
-Status protocol and FORGE are **independent but composable**:
-
-- **Status** = subjective agent telemetry ("I think I'm done")
-- **FORGE** = objective quality evidence ("the evidence says it's done")
-
-```
-DONE              → proceed to automated gate → FORGE evidence_map
-DONE_WITH_CONCERNS → concerns become 'Assumed' claims → evidence_map likely HOLDs
-NEEDS_CONTEXT     → provide context, re-dispatch (no FORGE yet)
-BLOCKED           → diagnose:
-                     contract/security issue → HARD_BLOCK
-                     resource/scope issue → re-plan, no FORGE
-```
-
-**Critical rule**: Every `DONE` status MUST be followed by `evidence_map({ action: "gate" })` before proceeding to review. No shortcuts.
-
----
-
-## §8 Review Pipeline
-
-### Four-Stage Pipeline
-
-```
-Stage 1: Implementer Self-Review (embedded in agent output)
-  └─ Checklist: scope respected, tests pass, conventions followed
-      │
-Stage 2: Orchestrator Automated Gate
-  └─ check({}) + test_run({}) MUST pass
-  └─ Validate self-review checklist present in output
-  └─ FAIL → bounce back to implementer with specific gap
-  └─ PASS ↓
-      │
-Stage 3: Dual Code Review (parallel)
-  ├─ Code-Reviewer-Alpha (GPT-5.4): code quality + Spec Alignment
-  └─ Code-Reviewer-Beta (Opus 4.6): code quality + Spec Alignment
-      │ Both review same code, different model perspectives
-      │ Spec Alignment = "Does this match what was asked?"
-      │
-Stage 4: Conditional Reviews (parallel if both needed)
-  ├─ Architecture Review — if boundary changes, new modules, pattern shifts
-  └─ Security Review — if auth, crypto, input handling, or external data
-      │
-FORGE Gate: evidence_map({ action: "gate" })
-  └─ YIELD → proceed to commit
-  └─ HOLD → address flagged items → re-gate (max 3 rounds)
-  └─ HARD_BLOCK → escalate to user
-```
-
-### Spec Alignment Dimension (for Code Reviewers)
-
-Both Code-Reviewer-Alpha and Code-Reviewer-Beta evaluate an explicit **Spec Alignment** dimension:
-
-1. Does the implementation match the acceptance criteria from the task?
-2. Are there over-builds (features not requested)?
-3. Are there under-builds (requirements missed)?
-4. Does the output match the expected file changes?
-
-This catches spec drift that automated tests might miss.
-
-### When to Skip Stages
-
-| Stage | Skip When |
-|-------|-----------|
-| Architecture Review | No new modules, no boundary changes, no new patterns |
-| Security Review | No auth, no crypto, no external input handling |
-| FORGE Gate | Floor-tier tasks only (simple, mechanical changes) |
-
----
-
-## §9 Recovery & Escalation
-
-### Retry Policy
-
-- **Max 2 retries per agent per task** — after that, re-plan or escalate
-- Each retry MUST include the specific failure reason in the new prompt
-- Never retry with the same prompt — always add diagnostic context
-
-### Loop Detection
-
-If an agent returns the same error/status 2+ times:
-1. **STOP** — do not retry again
-2. Check if the approach is fundamentally wrong
-3. Consider: different agent, different model, different decomposition, or user escalation
-
-### Emergency Procedures
-
-When parallel batch causes cascading failures:
-
-```
-STOP    → Halt all running agents immediately
-ASSESS  → git diff --stat + check({}) — how bad is it?
-CONTAIN → Limited (1-3 files): fix or re-delegate
-           Widespread (10+ files): git stash to preserve for analysis
-RECOVER → Partial: git checkout -- {specific files}
-           Full: git stash (preserves) or git checkout . (discards)
-           Nuclear: git reset --hard HEAD (last resort)
-DOCUMENT → remember what went wrong, update plan
-```
-
-### Scope Tripwires
-
-| Signal | Action |
-|--------|--------|
-| Agent modified **2x more files** than planned | Pause, review before continuing |
-| Agent returns `ESCALATE` or `BLOCKED` repeatedly | Do NOT re-delegate unchanged. Diagnose first |
-| Agent's output contradicts the plan | Stop, compare with plan, re-align |
-| Tests that were passing now fail | Immediate rollback of that agent's changes |
-
----
-
-## §10 Common Mistakes & Red Flags
-
-### Delegation Anti-Patterns
-
-| ❌ Mistake | Why It Fails | ✅ Fix |
-|-----------|-------------|--------|
-| **Too broad scope** — "implement the auth system" | Agent lacks clear boundaries, produces sprawling changes | Split: "add JWT middleware to auth.ts" + "add login endpoint to routes.ts" |
-| **No constraints** — "add a feature" | Agent invents architecture, conflicts with existing patterns | Include conventions, boundaries, existing patterns in prompt |
-| **Vague output** — "make it work" | No way to verify completion | Specific acceptance criteria: "endpoint returns 200 with {schema}" |
-| **Session context inheritance** — "continue from where we left off" | Subagent has stale/polluted context | Fresh prompt with 6-point template every time |
-| **Skipping reviews** — "it's a small change" | Small changes cause big regressions | ALWAYS run automated gate minimum |
-| **Parallel on shared files** — "both agents edit config.ts" | Merge conflicts, lost changes | Sequential, or merge into one task |
-| **Trusting the report** — "agent said DONE so it's done" | Agents are optimistic, miss edge cases | Automated gate + dual code review catches this |
-| **Brute-force retries** — same prompt 3 times | If it failed twice, it'll fail a third time | Diagnose, change approach, then retry |
-| **Orchestrator implements** — "just this one small fix" | Breaks the delegation contract, no review | ALWAYS delegate, no matter how small |
-
-### Red Flags in Agent Output
-
-| Flag | What It Means | Action |
-|------|--------------|--------|
-| Agent modified files outside its scope | Scope creep or misunderstanding | Rollback out-of-scope files, re-delegate with tighter constraints |
-| Agent added dependencies not in plan | Unauthorized architectural decision | Review necessity, likely rollback |
-| Agent skipped self-review checklist | Rushing, likely incomplete | Bounce back with checklist requirement |
-| Agent's DONE but tests fail | Didn't actually self-test | Bounce back with failing test output |
-| Agent asks questions in output instead of using NEEDS_CONTEXT | Misunderstands status protocol | Treat as NEEDS_CONTEXT, educate in next prompt |
-
----
-
-## Prompt Template Reference
-
-Detailed prompt templates are provided as sidecar files:
-
-| Template | File | Use When |
-|----------|------|----------|
-| Implementer dispatch | [`implementer-prompt.md`](implementer-prompt.md) | Dispatching Implementer, Frontend, or Refactor agents |
-| Spec compliance review | [`spec-review-prompt.md`](spec-review-prompt.md) | Adversarial spec alignment check (Code-Reviewer-Alpha) |
-| Code quality review | [`code-quality-review-prompt.md`](code-quality-review-prompt.md) | Dual code quality review (Code-Reviewer-Beta) |
-| Architecture review | [`architecture-review-prompt.md`](architecture-review-prompt.md) | Boundary changes, pattern adherence review |
-| Parallel dispatch example | [`parallel-dispatch-example.md`](parallel-dispatch-example.md) | Worked example of decomposing a feature into parallel tasks |
+# Multi-Agent Development
+
+Comprehensive patterns for orchestrating multiple AI agents in parallel development workflows. Covers task decomposition, parallel dispatch, context crafting, status handling, review pipelines, and recovery.
+
+**Core Principle**: Dispatch multiple agents for focused tasks. Each subagent gets fresh, focused context with explicit scope — never inherited session state.
+
+Load this skill when orchestrating multi-agent work: planning parallel batches, crafting delegation prompts, handling implementer status, running review pipelines, or recovering from agent failures.
+
+---
+
+## §1 Agent Roles & Model Selection
+
+### Role Categories
+
+| Role | Agents | When to Use | Parallelizable |
+|------|--------|-------------|----------------|
+| **Orchestration** | Orchestrator, Planner | Workflow control, planning | No (sequential) |
+| **Implementation** | Implementer, Frontend, Refactor | Code creation/modification | Yes (disjoint files only) |
+| **Research** | Explorer, Researcher-Alpha/Beta/Gamma/Delta | Codebase exploration, decisions | Yes (always) |
+| **Review** | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta | Quality verification | Yes (always) |
+| **Diagnostics** | Debugger, Security | Issue tracing, vulnerability analysis | Yes (read-only) |
+| **Documentation** | Documenter | README, API docs, changelog | Yes (disjoint files) |
+
+### Model Selection by Task Complexity
+
+Choose the **least powerful model that can handle the role**:
+
+| Complexity Signal | Model Tier | Example Agents |
+|-------------------|-----------|----------------|
+| Mechanical (rename, move, add field) | Fast model | Explorer (Gemini Flash) |
+| Standard (implement spec, write tests) | Mid-tier | Implementer (GPT-5.4), Refactor (GPT-5.4) |
+| Judgment-heavy (architecture, security, debug) | Strongest | Debugger (Opus 4.6), Security (Opus 4.6) |
+| Multi-model cross-validation | Mixed | Researcher-Alpha/Beta/Gamma/Delta (all different) |
+
+**Upgrade signal**: If an agent returns `BLOCKED` or `DONE_WITH_CONCERNS` on a task classified as "Standard", consider re-dispatching to a stronger model.
+
+---
+
+## §2 Task Decomposition Rules
+
+### The Golden Rule
+> **One task = one focused problem domain = 1-3 files maximum.**
+
+### Decomposition Checklist
+
+For each task, specify ALL of:
+- [ ] **Target files** — exact paths to create or modify
+- [ ] **Acceptance criteria** — what "done" looks like (testable)
+- [ ] **Agent assignment** — which agent handles this
+- [ ] **Dependencies** — which tasks must complete first (if any)
+
+### Sizing Guide
+
+| Task Size | Files | Example | Agent |
+|-----------|-------|---------|-------|
+| **Micro** | 1 file | Add a utility function | Implementer |
+| **Small** | 1-2 files | New endpoint + test | Implementer |
+| **Standard** | 2-3 files | Feature with service + controller + test | Implementer |
+| **Too big** | 4+ files | **SPLIT IT** — decompose further | — |
+
+### Splitting Strategies
+- **By layer**: Service logic (Implementer) + UI component (Frontend) + tests (Implementer)
+- **By feature boundary**: Auth endpoints (Implementer A) + Profile endpoints (Implementer B)
+- **By concern**: Data model changes (Implementer) + API route changes (Implementer) + UI updates (Frontend)
+
+---
+
+## §3 Independence Decision Tree
+
+Before marking tasks as parallel, walk this tree:
+
+```
+Task A and Task B — can they run in parallel?
+│
+├─ Do they share ANY files? (create, modify, or delete the same file)
+│   ├─ YES → SEQUENTIAL (or merge into one task)
+│   └─ NO ↓
+│
+├─ Do they share mutable state? (env vars, globals, same DB table, shared config)
+│   ├─ YES → SEQUENTIAL
+│   └─ NO ↓
+│
+├─ Does B need A's output? (B reads a file A creates, B uses A's new export)
+│   ├─ YES → SEQUENTIAL (A before B)
+│   └─ NO ↓
+│
+├─ Would A's result change B's approach? (A discovers something that affects B)
+│   ├─ YES → SEQUENTIAL or single agent
+│   └─ NO ↓
+│
+├─ Resource contention? (same port, same build process, same lock file)
+│   ├─ YES → SEQUENTIAL
+│   └─ NO ↓
+│
+└─ ✅ SAFE TO PARALLELIZE
+```
+
+### Edge Cases
+
+| Situation | Verdict | Why |
+|-----------|---------|-----|
+| Both import from same module (read-only) | ✅ Parallel | Reading shared code is fine |
+| Both add exports to same index file | ❌ Sequential | Concurrent index.ts edits will conflict |
+| A creates a type, B uses that type | ❌ Sequential | B depends on A's output |
+| Both modify different test files | ✅ Parallel | Disjoint file sets |
+| Both touch package.json | ❌ Sequential | Shared file |
+| A adds a route, B adds middleware | ⚠️ Check | If B's middleware affects A's route → sequential |
+
+### Integration Verification (after parallel batch completes)
+
+1. **Conflict check**: Did any agent unexpectedly modify a file assigned to another agent?
+2. **Import check**: Do all new cross-references resolve?
+3. **Full suite**: `check({})` + `test_run({})` — everything must pass
+4. **Spot check**: Manually verify at least one task's output matches acceptance criteria
+
+---
+
+## §4 Parallel Dispatch Patterns
+
+### Dispatch Rules
+
+1. **Max 4 concurrent file-modifying agents** per batch
+2. **Read-only agents have no limit** — Explorer, Researcher*, Reviewer*, Security can always run in parallel
+3. **Build dependency graph first** — phases with no dependencies MUST be batched together
+4. **Never dispatch two implementers to the same file** — even different sections
+
+### Batch Strategy
+
+```
+Phase Plan:
+  Phase 1: [Task A, Task B, Task C]  ← no dependencies between A/B/C
+  Phase 2: [Task D, Task E]          ← D depends on A, E depends on B
+  Phase 3: [Task F]                  ← F depends on D and E
+
+Execution:
+  Batch 1: dispatch(A, B, C) in parallel → review → gate
+  Batch 2: dispatch(D, E) in parallel → review → gate
+  Batch 3: dispatch(F) → review → gate
+```
+
+### Anti-Patterns
+
+| ❌ Don't | ✅ Do Instead |
+|----------|--------------|
+| Dispatch 6 implementers at once | Max 4, queue the rest |
+| Give one agent 10 files | Split into 3-4 focused tasks |
+| Let agents read the full plan | Give each agent ONLY its task context |
+| Retry same prompt on failure | Diagnose first, then re-prompt with fix |
+| Skip review after parallel batch | ALWAYS review + integration verify |
+| Inherit session context to subagent | Build fresh, focused context per dispatch |
+
+---
+
+## §5 Context Crafting Guide
+
+### The Controller Principle
+> **The Orchestrator provides ALL context. Subagents never need to search for context themselves.**
+
+Each subagent gets a fresh, self-contained prompt. No inherited session state. No "read the plan first."
+
+### The 6-Point Prompt Template
+
+Every delegation prompt MUST include:
+
+```markdown
+## 1. Scope
+Files to create/modify: [exact paths]
+Files to NOT touch: [boundaries]
+
+## 2. Goal
+[What the code should do — acceptance criteria, testable outcomes]
+
+## 3. Architectural Context
+[Relevant patterns, conventions, existing code structure]
+[Include actual code snippets from compact/digest — don't tell agent to "go read X"]
+
+## 4. Constraints
+- Follow [pattern/convention]
+- Do NOT modify [boundary files]
+- Use [specific library/approach]
+
+## 5. FORGE Context
+Tier: [Floor/Standard/Critical]
+Evidence requirements: [what evidence to collect]
+
+## 6. Self-Review & Status
+Before declaring DONE, verify:
+- [ ] All acceptance criteria met
+- [ ] No files outside scope modified
+- [ ] Tests pass (if applicable)
+- [ ] Code follows stated conventions
+
+End with status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+```
+
+### What to Include vs Omit
+
+| ✅ Include | ❌ Omit |
+|-----------|---------|
+| Exact file paths and code snippets | Full session history |
+| Acceptance criteria | Other agents' tasks |
+| Relevant conventions (from KB) | Unrelated architecture context |
+| Compact/digest of relevant files | Raw file contents of large files |
+| Error messages (if fixing a bug) | Previous failed attempts (unless relevant) |
+| FORGE tier and ceremony | Full FORGE protocol explanation |
+
+### Context Size Budget
+
+| Task Complexity | Context Target | Approach |
+|-----------------|---------------|----------|
+| Micro (1 file) | ~500 tokens | Inline code snippet + goal |
+| Small (1-2 files) | ~1000 tokens | `compact` of target files + goal |
+| Standard (2-3 files) | ~2000 tokens | `digest` of related files + architectural context |
+| Complex (judgment-heavy) | ~3000 tokens | `digest` + relevant decisions from AI Kit |
+
+---
+
+## §6 Subagent Execution Cycle
+
+### Lifecycle
+
+```
+Orchestrator                          Subagent (fresh instance)
+    │                                      │
+    ├─ Craft focused prompt ──────────────►│
+    │  (6-point template)                  │
+    │                                      ├─ Understand scope
+    │                                      ├─ Implement changes
+    │                                      ├─ Self-review (checklist)
+    │◄─────────────────── Return status ───┤
+    │                                      │ (DONE/CONCERNS/NEEDS/BLOCKED)
+    │                                      │
+    ├─ Handle status (see §7)              ×  (subagent terminates)
+    │
+    ├─ Automated gate (check/test_run)
+    │
+    ├─ Dispatch reviewers (see §8)
+    │
+    └─ FORGE evidence_map gate
+```
+
+### Key Rules
+
+1. **One subagent = one task**. Never reuse a subagent for a different task.
+2. **Controller provides context**. The subagent's prompt contains everything it needs — it should NOT need to search/explore the codebase.
+3. **Self-review before handoff**. Every implementer must complete the self-review checklist before declaring DONE.
+4. **Status is mandatory**. Every subagent response MUST end with exactly ONE status code.
+
+---
+
+## §7 Implementer Status Protocol
+
+### Status Codes
+
+Every implementer (Implementer, Frontend, Refactor) MUST end their response with exactly ONE:
+
+| Status | Meaning | Orchestrator Action |
+|--------|---------|-------------------|
+| **DONE** | All tasks complete, self-review passed | → Automated gate → Review pipeline |
+| **DONE_WITH_CONCERNS** | Complete but flagging issues: [list] | → Surface concerns as `Assumed` claims in evidence_map → Likely HOLD → Address before review |
+| **NEEDS_CONTEXT** | Cannot proceed without: [specific question] | → Provide missing context → Re-dispatch same task (counts as retry) |
+| **BLOCKED** | Hit a wall: [description] | → Diagnose (see below) |
+
+### BLOCKED Diagnosis Tree
+
+```
+Agent returned BLOCKED
+│
+├─ Missing context? (needs info not in prompt)
+│   → Provide context, re-dispatch
+│
+├─ Wrong model? (task too complex for assigned model)
+│   → Re-dispatch to stronger model (e.g., Implementer → Debugger)
+│
+├─ Scope too broad? (agent overwhelmed)
+│   → Split task further, re-dispatch smaller pieces
+│
+├─ Plan wrong? (implementation approach won't work)
+│   → Re-plan this phase, check AI Kit for alternatives
+│
+└─ External blocker? (dependency not ready, API unavailable)
+    → Park task, proceed with independent work, revisit later
+```
+
+### FORGE Composition
+
+Status protocol and FORGE are **independent but composable**:
+
+- **Status** = subjective agent telemetry ("I think I'm done")
+- **FORGE** = objective quality evidence ("the evidence says it's done")
+
+```
+DONE              → proceed to automated gate → FORGE evidence_map
+DONE_WITH_CONCERNS → concerns become 'Assumed' claims → evidence_map likely HOLDs
+NEEDS_CONTEXT     → provide context, re-dispatch (no FORGE yet)
+BLOCKED           → diagnose:
+                     contract/security issue → HARD_BLOCK
+                     resource/scope issue → re-plan, no FORGE
+```
+
+**Critical rule**: Every `DONE` status MUST be followed by `evidence_map({ action: "gate" })` before proceeding to review. No shortcuts.
+
+---
+
+## §8 Review Pipeline
+
+### Four-Stage Pipeline
+
+```
+Stage 1: Implementer Self-Review (embedded in agent output)
+  └─ Checklist: scope respected, tests pass, conventions followed
+      │
+Stage 2: Orchestrator Automated Gate
+  └─ check({}) + test_run({}) MUST pass
+  └─ Validate self-review checklist present in output
+  └─ FAIL → bounce back to implementer with specific gap
+  └─ PASS ↓
+      │
+Stage 3: Dual Code Review (parallel)
+  ├─ Code-Reviewer-Alpha (GPT-5.4): code quality + Spec Alignment
+  └─ Code-Reviewer-Beta (Opus 4.6): code quality + Spec Alignment
+      │ Both review same code, different model perspectives
+      │ Spec Alignment = "Does this match what was asked?"
+      │
+Stage 4: Conditional Reviews (parallel if both needed)
+  ├─ Architecture Review — if boundary changes, new modules, pattern shifts
+  └─ Security Review — if auth, crypto, input handling, or external data
+      │
+FORGE Gate: evidence_map({ action: "gate" })
+  └─ YIELD → proceed to commit
+  └─ HOLD → address flagged items → re-gate (max 3 rounds)
+  └─ HARD_BLOCK → escalate to user
+```
+
+### Spec Alignment Dimension (for Code Reviewers)
+
+Both Code-Reviewer-Alpha and Code-Reviewer-Beta evaluate an explicit **Spec Alignment** dimension:
+
+1. Does the implementation match the acceptance criteria from the task?
+2. Are there over-builds (features not requested)?
+3. Are there under-builds (requirements missed)?
+4. Does the output match the expected file changes?
+
+This catches spec drift that automated tests might miss.
+
+### When to Skip Stages
+
+| Stage | Skip When |
+|-------|-----------|
+| Architecture Review | No new modules, no boundary changes, no new patterns |
+| Security Review | No auth, no crypto, no external input handling |
+| FORGE Gate | Floor-tier tasks only (simple, mechanical changes) |
+
+---
+
+## §9 Recovery & Escalation
+
+### Retry Policy
+
+- **Max 2 retries per agent per task** — after that, re-plan or escalate
+- Each retry MUST include the specific failure reason in the new prompt
+- Never retry with the same prompt — always add diagnostic context
+
+### Loop Detection
+
+If an agent returns the same error/status 2+ times:
+1. **STOP** — do not retry again
+2. Check if the approach is fundamentally wrong
+3. Consider: different agent, different model, different decomposition, or user escalation
+
+### Emergency Procedures
+
+When parallel batch causes cascading failures:
+
+```
+STOP    → Halt all running agents immediately
+ASSESS  → git diff --stat + check({}) — how bad is it?
+CONTAIN → Limited (1-3 files): fix or re-delegate
+           Widespread (10+ files): git stash to preserve for analysis
+RECOVER → Partial: git checkout -- {specific files}
+           Full: git stash (preserves) or git checkout . (discards)
+           Nuclear: git reset --hard HEAD (last resort)
+DOCUMENT → remember what went wrong, update plan
+```
+
+### Scope Tripwires
+
+| Signal | Action |
+|--------|--------|
+| Agent modified **2x more files** than planned | Pause, review before continuing |
+| Agent returns `ESCALATE` or `BLOCKED` repeatedly | Do NOT re-delegate unchanged. Diagnose first |
+| Agent's output contradicts the plan | Stop, compare with plan, re-align |
+| Tests that were passing now fail | Immediate rollback of that agent's changes |
+
+---
+
+## §10 Common Mistakes & Red Flags
+
+### Delegation Anti-Patterns
+
+| ❌ Mistake | Why It Fails | ✅ Fix |
+|-----------|-------------|--------|
+| **Too broad scope** — "implement the auth system" | Agent lacks clear boundaries, produces sprawling changes | Split: "add JWT middleware to auth.ts" + "add login endpoint to routes.ts" |
+| **No constraints** — "add a feature" | Agent invents architecture, conflicts with existing patterns | Include conventions, boundaries, existing patterns in prompt |
+| **Vague output** — "make it work" | No way to verify completion | Specific acceptance criteria: "endpoint returns 200 with {schema}" |
+| **Session context inheritance** — "continue from where we left off" | Subagent has stale/polluted context | Fresh prompt with 6-point template every time |
+| **Skipping reviews** — "it's a small change" | Small changes cause big regressions | ALWAYS run automated gate minimum |
+| **Parallel on shared files** — "both agents edit config.ts" | Merge conflicts, lost changes | Sequential, or merge into one task |
+| **Trusting the report** — "agent said DONE so it's done" | Agents are optimistic, miss edge cases | Automated gate + dual code review catches this |
+| **Brute-force retries** — same prompt 3 times | If it failed twice, it'll fail a third time | Diagnose, change approach, then retry |
+| **Orchestrator implements** — "just this one small fix" | Breaks the delegation contract, no review | ALWAYS delegate, no matter how small |
+
+### Red Flags in Agent Output
+
+| Flag | What It Means | Action |
+|------|--------------|--------|
+| Agent modified files outside its scope | Scope creep or misunderstanding | Rollback out-of-scope files, re-delegate with tighter constraints |
+| Agent added dependencies not in plan | Unauthorized architectural decision | Review necessity, likely rollback |
+| Agent skipped self-review checklist | Rushing, likely incomplete | Bounce back with checklist requirement |
+| Agent's DONE but tests fail | Didn't actually self-test | Bounce back with failing test output |
+| Agent asks questions in output instead of using NEEDS_CONTEXT | Misunderstands status protocol | Treat as NEEDS_CONTEXT, educate in next prompt |
+
+---
+
+## Prompt Template Reference
+
+Detailed prompt templates are provided as sidecar files:
+
+| Template | File | Use When |
+|----------|------|----------|
+| Implementer dispatch | [`implementer-prompt.md`](implementer-prompt.md) | Dispatching Implementer, Frontend, or Refactor agents |
+| Spec compliance review | [`spec-review-prompt.md`](spec-review-prompt.md) | Adversarial spec alignment check (Code-Reviewer-Alpha) |
+| Code quality review | [`code-quality-review-prompt.md`](code-quality-review-prompt.md) | Dual code quality review (Code-Reviewer-Beta) |
+| Architecture review | [`architecture-review-prompt.md`](architecture-review-prompt.md) | Boundary changes, pattern adherence review |
+| Parallel dispatch example | [`parallel-dispatch-example.md`](parallel-dispatch-example.md) | Worked example of decomposing a feature into parallel tasks |