Parallel Execution

---
name: Parallel Execution
description: >
  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
---

# Parallel Execution: Plan Mode + Agent Teams

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
**Risks / trade-offs:** if any
Proceed? (yes / modify / cancel)
```

### 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.

---

## 2. AGENT TEAMS

### 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(detective, "Analyze test coverage in src/. Report gaps only. No writes.")
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)

```
Approval received
  ├─ 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.")
       ↓ both complete ↓
  Task(guardian, "Run the quality gate on the completed work.")
```

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

```
Task(builder, "Implement the feature.")
   ↓ 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.

---

## 3. COMBINED PATTERN

```
Plan Mode: explore (reads) → draft plan → present → wait for approval
Agent Teams: fan out parallel agents on the approved plan → aggregate → guardian gate
```

## 4. DECISION TREE

```
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.