git:20260714.061716b to git:20260714.4fd0952

+ Claude Code's two force-multipliers — Plan Mode (explore → plan → wait-for-approval →

+ execute) and Agent Teams (parallel subagents via the Task tool) — plus the canonical

+ forge agent roster and delegation-routing rules. Use when decomposing a multi-file

+ feature, running multi-dimensional codebase analysis, orchestrating parallel

+ build/test/validate pipelines, or deciding which subagent to delegate a task to.

+ when_to_use: >

+ touching 3+ files; "plan this feature"; "analyze the codebase / health check / gap

+ analysis"; spawning subagents; "which agent should do X"; parallel build + test;

+ running a --fix command; any work with multiple independent dimensions.

+ allowed-tools: Task, Read, Grep, Glob, Bash

+ Two superpowers. **Plan Mode** thinks before it writes. **Agent Teams** fan work out

+ across parallel subagents. Combine them for complex features. The agent roster and

+ routing rules in §5 are the source of truth for `Task` delegation — the `subagent_type`

+ must match a `name:` from that table exactly.

+ ## 1. PLAN MODE

+ Explore (reads only) → Draft plan → Present → Wait for approval → Execute

+ 1. **Explore only** — Read, Glob, Grep, read-only Bash. No writes until approved.

+ 2. **Draft a plan** — scope, files affected, approach, boundaries.

+ 3. **Present** — show the plan in chat, ask for approval.

+ 4. **Wait** — do not proceed until the user says "proceed" / "yes" / "looks good".

+ 5. **Execute** — now write, edit, spawn agents.

+ ### Plan document format

+ ## Plan: {task name}

+ **Scope:** what will change

+ **Files to create / modify / NOT touch:** (the last is a boundary declaration)

+ **Approach:** brief

+ ### When to invoke

+ | Situation | Plan Mode? |

+ |-----------|-----------|

+ | Touching 3+ files | Yes |

+ | A `--fix` command (show what changes before writing) | Yes — always |

+ | Architectural change | Yes |

+ | Single-file bug fix / comment / answering a question | No |

+ ### Anti-patterns

+ - Writing files during Explore.

+ - Presenting a plan then executing without waiting.

+ - Skipping the plan for a "quick" task that touches 3+ files.

+ - Modifying files outside the declared scope.

+ ### Invocation

+ Task tool:

+ subagent_type: "builder" ← must match a name: in §5 exactly (kebab-case)

+ prompt: "Self-contained task. Declare file boundaries. State: no writes / writes X only."

+ run_in_background: false ← true only if you have real work to do while it runs

+ ### Pattern A — Fan-Out Analysis (read-only, N dimensions in parallel)

+ Task(security, "Scan src/ for OWASP issues + secrets. Report only. No writes.")

+ Task(performance,"Profile src/ hotspots. Report only. No writes.")

+ ↓ all run concurrently ↓

+ Aggregate the three reports into one.

+ ### Pattern B — Plan-Then-Parallel-Build (non-overlapping write scopes)

+ ├─ Task(builder, "Implement per spec. Write src/*.ts ONLY. No test files.")

+ └─ Task(testing, "Write tests per spec. Write src/__tests__/*.test.ts ONLY. No source edits.")

+ Task(guardian, "Run the quality gate on the completed work.")

+ ### Pattern C — Build-Then-Validate (sequential, then parallel validation)

+ ↓ completes ↓

+ ├─ Task(guardian, "Run tests + type check.")

+ └─ Task(security, "Security-scan the diff.")

+ ### Design rules

+ 1. **Declare file boundaries in every prompt** — writers must not overlap (see Gotchas).

+ 2. **Parallel = no shared mutable state** — agents may read the same files; each writes

+ to a different path.

+ 3. **Self-contained prompts** — the subagent sees none of your conversation history.

+ 4. **Aggregate, don't over-chain** — let independent agents run concurrently, then

+ synthesize; only serialize genuine data dependencies.

+ 5. **Wave, don't flood** — the provider throttles beyond ~6 concurrent subagents. Launch

+ in waves of ≤6, not fifty at once.

+ Plan Mode: explore (reads) → draft plan → present → wait for approval

+ Agent Teams: fan out parallel agents on the approved plan → aggregate → guardian gate

+ 3+ files? → Plan Mode first.

+ Multiple independent dimensions? → Agent Teams, Fan-Out (Pattern A).

+ --fix command? → Plan Mode pre-flight ALWAYS (show changes before writing).

+ health / gap / analysis?→ Agent Teams, Fan-Out (Pattern A).

+ feature implementation? → Plan Mode, then Agent Teams (Pattern B).

+ Otherwise (1 file, no dimensions) → execute directly.

+ ```

+ ---

+ ## 5. AGENT ROUTING GUIDE (source of truth)

+ The roster is **33 agents**. `subagent_type` must equal a `name:` below verbatim.

+ Only agents with `Task` in their tools can spawn other agents; the rest are leaf

+ workers. Four agents (`Read`/`Grep`-only, no `Write`/`Edit`) are **read-only** — never

+ route code-writing to them.

+ ### Orchestrators (have `Task` — can sub-delegate)

+ | name | model | Delegate when… | Notes |

+ |------|-------|----------------|-------|

+ | planner | opus | A feature needs an architecture + task plan | **read-only** (plans, doesn't write code) |

+ | builder | sonnet | Ready to write code from an approved plan | can spawn `testing` |

+ | guardian | sonnet | Implementation done; run quality gates | spawns parallel validators |

+ | detective | sonnet | Health / gap / architecture analysis | **read-only** |

+ | orchestrator | opus | Top-level multi-phase session coordination | |

+ | master-architect | opus | System-level architecture across repos | |

+ | product-strategist | opus | Product direction / prioritization | |

+ | revenue-architect | opus | Monetization / pricing / GTM engineering | |

+ | growth-engine | sonnet | Growth loops, acquisition instrumentation | |

+ | incident-commander | opus | Live incident triage + coordination | |

+ | release-sentinel | opus | Pre-release docs/changelog/version audit | |

+ | devops | sonnet | CI/CD, Docker, infra, monitoring | |

+ | integration | sonnet | 3rd-party services, webhooks, OAuth | |

+ | qa-sentinel | sonnet | End-to-end QA orchestration | |

+ | dx-engineer | sonnet | Developer-experience tooling | |

+ | design-vanguard | opus | High-craft visual/UX design | |

+ | nxtg-ceo-loop | opus | CRITICAL strategic pivot only (else it decides autonomously) | |

+ ### Leaf workers (no `Task` — cannot sub-delegate)

+ | name | model | Delegate when… |

+ |------|-------|----------------|

+ | testing | sonnet | New code needs tests / coverage / flaky-test triage |

+ | security | sonnet | OWASP scan, secrets, vuln audit |

+ | refactor | sonnet | Complexity reduction, DRY, restructuring |

+ | performance | sonnet | Profiling, bundle/memory analysis |

+ | ui | sonnet | React components, a11y, responsive layout |

+ | api | sonnet | REST/GraphQL design, validation, OpenAPI |

+ | database | sonnet | Schema, migrations, query tuning |

+ | docs | sonnet | JSDoc, README, changelog, API docs |

+ | analytics | sonnet | Metrics, KPI tracking, dashboards |

+ | compliance | sonnet | License audit, GDPR, WCAG |

+ | learning | sonnet | Pattern capture, preference persistence |

+ | governance-verifier | sonnet | Resolve a hook-flagged scope/quality concern |

+ | oracle | sonnet | Non-blocking drift/scope validation in autonomous mode |

+ | scout | sonnet | Web research / external-source gathering (read+web, no Task) |

+ | wordsmith | sonnet | Copy, naming, prose polish |

+ | crucible-detective | sonnet | Test-suite quality audit — **read-only** |

+ ### Read-only agents (no `Write`/`Edit`)

+ `planner`, `detective`, `crucible-detective`, `oracle` — route analysis/planning to

+ them, never file writes.

+ ### Routing anti-patterns

+ - Referencing a `subagent_type` not in this table (e.g. `general-purpose`,

+ `nxtg-master-architect`). The correct name is `master-architect`.

+ - Using `nxtg-ceo-loop` or `orchestrator` for routine implementation.

+ - Spawning a leaf worker expecting it to sub-delegate — it has no `Task`.

+ - Routing code writes to a read-only agent (planner/detective/crucible-detective/oracle).

+ - Spawning the same agent type recursively (detective spawning detective).

+ ---

+

+ ## Gotchas

+

+ - **`subagent_type` name ≠ filename.** The CEO agent's file is `ceo-loop.md` but its

+ `name:` is `nxtg-ceo-loop` — spawn by the `name`, not the filename. Any mismatch fails

+ the Task call.

+ - **planner is opus + read-only.** It plans; it cannot `Write`/`Edit`. To actually write

+ the plan's code you must then spawn `builder`. Same for `detective`, `oracle`,

+ `crucible-detective`.

+ - **Model claims drift — verify against the agent file.** `analytics`, `compliance`,

+ `learning`, `governance-verifier` are **sonnet**, not haiku. Read the `model:`

+ frontmatter before asserting cost/capability.

+ - **Subagents are context-blind.** A subagent receives only its `prompt` — none of your

+ conversation, files you've read, or prior agent output. Restate every fact it needs.

+ - **Overlapping write scopes silently corrupt work.** Two parallel writers touching the

+ same file race; the last writer wins and the other's edits vanish. Partition paths

+ explicitly (`src/*.ts` vs `src/__tests__/*.test.ts`) or serialize them.

+ - **`run_in_background: true` needs a poll.** A background subagent does not block; you

+ must check its completion before consuming its output. Use foreground unless you have

+ genuine parallel work of your own.

+ - **Concurrency ceiling ≈ 6.** Beyond ~6 simultaneous subagents the provider throttles

+ (429/529). Fan out in waves of ≤6; a sequential queue of independent work is not

+ parallelism, but neither is a 30-agent flood.

+ - **Leaf workers can't orchestrate.** 16 of the 33 agents have no `Task` tool. Don't hand

+ one a prompt that says "spawn a tester" — it will just do the work inline or fail.