---

name: subagent-driven-development description: Use when executing implementation plans with independent tasks in the current session or facing 3+ independent issues that can be investigated without shared state or dependencies - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates

Subagent-Driven Development

Persona: Orchestrator with trust issues - fresh subagent per task means no context pollution, review after each means no quality drift.

Core principle: Fresh subagent per task + review between tasks = high quality, fast iteration.

Benefits: Same session (no context switch), fresh subagent per task (no pollution), code review after each (catch issues early), faster iteration (no human-in-loop between tasks).

Execution Types

---

Sequential Execution

1. Load Plan

Read plan file, create TodoWrite with all tasks.

2. Execute Task with Subagent

CopyTask tool:
  description: "Implement Task N: [task name]"
  prompt: |
    Implement Task N from [plan-file]. Read task carefully.
    1. Implement exactly what task specifies
    2. Write tests (TDD if specified)
    3. Verify implementation
    4. Commit
    5. Report: what implemented, tested, test results, files changed, issues

3. Review Subagent's Work

Dispatch code-reviewer agent to review the subagent's changes

4. Apply Feedback

If issues found, dispatch follow-up subagent: "Fix issues from code review: [list]"

5. Mark Complete, Next Task

Update TodoWrite, repeat steps 2-5.

6. Final Review + Complete

• Dispatch final code-reviewer agent (entire implementation, all requirements, overall architecture)
• Use git-expert agent for branch cleanup if needed

---

Parallel Execution

Wave-Based Spawning

Execute tasks in waves, waiting for each wave to complete before starting the next:

CopyWave 1: [Task A, Task B, Task C]  ← spawn in parallel
         ↓ wait for completion ↓
Wave 2: [Task D, Task E]          ← spawn next wave
         ↓ wait for completion ↓
Wave 3: [Task F]                  ← final wave

Wave sizing:

Wave boundaries: Group related tasks in same wave when output of one informs another.

Parallel Agent Decision Framework

Before spawning parallel agents, evaluate:

Decision tree:

Copy1. Do tasks touch same files? → No parallel
2. Do tasks share state? → No parallel
3. Are tasks > 3? → Use waves
4. Is complexity high? → Smaller waves
5. Otherwise → Full parallel OK

Process

1. Load plan, review critically, raise concerns before starting
2. Apply decision framework: determine wave sizes and boundaries
3. Execute wave - spawn all wave tasks in parallel (single message with multiple Task calls)
4. Wait for completion using TaskOutput with block=true
5. Review wave: dispatch code-reviewer for all changes
6. Mark completed, execute next wave, repeat
7. Use git-expert agent for branch cleanup and PR preparation

When to Stop

• Hit blocker (missing dependency, failing test, unclear instruction)
• Plan has critical gaps
• Verification fails repeatedly
• Parallel agents report conflicts

Ask for clarification rather than guessing.

---

Checkpoint Pattern

Execute in batches with verification gates:

Copy1. Execute 3 tasks
2. Report: what was done + verification output
3. Wait for feedback (or auto-continue if clear)
4. Stop immediately if:
   - Missing dependencies
   - Failed tests
   - Unclear instructions
   - Conflicting results

Checkpoint report format:

Copy## Checkpoint: Tasks 1-3 Complete

### Completed
- [x] Task 1: Added auth middleware → tests pass
- [x] Task 2: Updated routes → build OK
- [x] Task 3: Added validation → 2 new tests pass

### Verification
- All tests: 47 passing, 0 failing
- Build: clean
- Lint: no new warnings

### Next
Tasks 4-6 ready. Continue?

---

Parallel Investigation

For 3+ unrelated failures across different files/subsystems.

Process

1. Group by domain: File A tests (tool approval), File B tests (batch completion), File C tests (abort)
2. Create focused prompts: Specific scope, clear goal, constraints, expected output
3. Dispatch in parallel: Task("Fix file-a.test.ts"), Task("Fix file-b.test.ts")
4. Review and integrate: Verify no conflicts, run full suite

Good Prompt Structure

CopyFix 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool..." - expects 'interrupted at'
2. "should handle mixed..." - fast tool aborted

These are timing issues. Your task:
1. Read test file, understand what each verifies
2. Identify root cause
3. Fix: replace timeouts with event-based waiting

Do NOT just increase timeouts. Return: summary of root cause and changes.

Prompt Anti-Patterns

When NOT to Use Parallel

• Fixing one might fix others (related failures)
• Need full context (requires seeing entire system)
• Exploratory debugging (don't know what's broken)
• Shared state (agents would conflict)

---

Should NOT Attempt

• Skip code review between tasks
• Proceed with unfixed Critical issues
• Dispatch multiple implementation subagents in parallel (conflicts)
• Implement without reading plan task
• Fix manually after subagent fails (context pollution)
• Use vague prompts that require subagent to explore
• Omit expected output format from prompts

---

Failure Behavior

Subagent fails to complete task

1. Read subagent's output to understand failure
2. Dispatch NEW fix subagent with specific error context
3. Do NOT fix manually (pollutes orchestrator context)
4. After 2 fix attempts: escalate to user with diagnosis

Subagent produces wrong result

1. Dispatch code-reviewer to identify what's wrong
2. Dispatch fix subagent with reviewer feedback
3. If pattern repeats: check if plan is ambiguous, clarify before retry

Multiple subagents conflict

1. Stop parallel execution immediately
2. Identify conflicting changes
3. Resolve sequentially with explicit merge step
4. Adjust parallelization boundaries for remaining work

All tasks blocked

1. Document what's blocking each task
2. Present blockers to user grouped by type
3. Ask: which blocker to resolve first, or provide missing info?

Related Skills

• batch-operations: Similar pattern for parallel work
• context-optimizer agent: Each subagent has fresh context

Escalation Triggers