Subagent-Driven Development
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
When to Use
digraph when_to_use {
"Have implementation plan?" [shape=diamond];
"Tasks mostly independent?" [shape=diamond];
"Stay in this session?" [shape=diamond];
"subagent-driven-development" [shape=box];
"executing-plans" [shape=box];
"Manual execution or brainstorm first" [shape=box];
"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
"Stay in this session?" -> "subagent-driven-development" [label="yes"];
"Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}
vs. Executing Plans (parallel session):
- Same session (no context switch)
- Fresh subagent per task (no context pollution)
- Two-stage review after each task: spec compliance first, then code quality
- Faster iteration (no human-in-loop between tasks)
Task Sizing
Before dispatching, classify each task:
| Size | Criteria | Process |
|---|---|---|
| Small | 1-2 files, < 50 lines changed, clear spec | Implementer only → mark complete |
| Medium | 2-4 files, clear spec, some integration | Implementer → spec review → mark complete |
| Large | 4+ files, cross-cutting, architectural decisions | Implementer → spec review → code quality review → mark complete |
Most tasks are Small or Medium. Only Large tasks need the full 3-agent review cycle. Skipping unnecessary reviews for small tasks saves 2 subagent invocations per task.
The Process
digraph process {
rankdir=TB;
subgraph cluster_per_task {
label="Per Task";
"Classify task size (Small/Medium/Large)" [shape=diamond];
"Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
"Implementer subagent asks questions?" [shape=diamond];
"Answer questions, provide context" [shape=box];
"Implementer subagent implements, tests, commits, self-reviews" [shape=box];
"Mark task complete (Small)" [shape=box];
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
"Spec reviewer subagent confirms code matches spec?" [shape=diamond];
"Implementer subagent fixes spec gaps" [shape=box];
"Mark task complete (Medium)" [shape=box];
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
"Code quality reviewer subagent approves?" [shape=diamond];
"Implementer subagent fixes quality issues" [shape=box];
"Mark task complete (Large)" [shape=box];
}
"Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
"More tasks remain?" [shape=diamond];
"Dispatch final code reviewer subagent for entire implementation" [shape=box];
"Use ultraship:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
"Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Classify task size (Small/Medium/Large)";
"Classify task size (Small/Medium/Large)" -> "Dispatch implementer subagent (./implementer-prompt.md)";
"Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
"Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
"Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
"Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
"Implementer subagent implements, tests, commits, self-reviews" -> "Mark task complete (Small)" [label="Small"];
"Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="Medium/Large"];
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
"Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
"Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
"Spec reviewer subagent confirms code matches spec?" -> "Mark task complete (Medium)" [label="Medium"];
"Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="Large"];
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
"Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
"Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
"Code quality reviewer subagent approves?" -> "Mark task complete (Large)" [label="yes"];
"Mark task complete (Small)" -> "More tasks remain?";
"Mark task complete (Medium)" -> "More tasks remain?";
"Mark task complete (Large)" -> "More tasks remain?";
"More tasks remain?" -> "Classify task size (Small/Medium/Large)" [label="yes"];
"More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
"Dispatch final code reviewer subagent for entire implementation" -> "Use ultraship:finishing-a-development-branch";
}
Model Selection
Use the least powerful model that can handle each role. This prevents timeouts and saves cost.
| Role | Model | Why |
|---|---|---|
| Implementer (Small task) | sonnet | Mechanical work with clear spec — sonnet is fast and accurate |
| Implementer (Medium/Large task) | opus | Cross-file coordination needs deep reasoning |
| Spec reviewer | sonnet | Checklist comparison — no deep reasoning needed |
| Code quality reviewer (Large only) | opus | Spotting subtle bugs, architecture issues, security flaws needs best judgment |
| Final reviewer | opus | Reviewing entire implementation requires holistic understanding |
Rules:
- Use opus for anything requiring judgment, strategy, or cross-file reasoning.
- Use sonnet for mechanical tasks with clear specs and tool-running.
- If a sonnet implementer reports BLOCKED, re-dispatch with opus.
- Never downgrade opus agents to sonnet — quality is non-negotiable.
- Default to opus for implementers — sonnet failures that the main agent has to fix cost more than opus would have.
Handling Implementer Status
Implementer subagents report one of four statuses. Handle each appropriately:
DONE: Proceed to spec compliance review.
DONE_WITH_CONCERNS: The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
BLOCKED: The implementer cannot complete the task. Assess the block