Parallel Execution

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.