Subagent Driven Development

1---
2name: subagent-driven-development
3description: Use when executing implementation plans with independent tasks in the current session
4---
5 
6# Subagent-Driven Development
7 
8Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
9 
10**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
11 
12## When to Use
13 
14```dot
15digraph when_to_use {
16    "Have implementation plan?" [shape=diamond];
17    "Tasks mostly independent?" [shape=diamond];
18    "Stay in this session?" [shape=diamond];
19    "subagent-driven-development" [shape=box];
20    "executing-plans" [shape=box];
21    "Manual execution or brainstorm first" [shape=box];
22 
23    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
24    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
25    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
26    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
27    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
28    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
29}
30```
31 
32**vs. Executing Plans (parallel session):**
33- Same session (no context switch)
34- Fresh subagent per task (no context pollution)
35- Two-stage review after each task: spec compliance first, then code quality
36- Faster iteration (no human-in-loop between tasks)
37 
38## The Process
39 
40```dot
41digraph process {
42    rankdir=TB;
43 
44    subgraph cluster_per_task {
45        label="Per Task";
46        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
47        "Implementer subagent asks questions?" [shape=diamond];
48        "Answer questions, provide context" [shape=box];
49        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
50        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
51        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
52        "Implementer subagent fixes spec gaps" [shape=box];
53        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
54        "Code quality reviewer subagent approves?" [shape=diamond];
55        "Implementer subagent fixes quality issues" [shape=box];
56        "Mark task complete in TodoWrite" [shape=box];
57    }
58 
59    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
60    "More tasks remain?" [shape=diamond];
61    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
62    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
63 
64    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
65    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
66    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
67    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
68    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
69    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
70    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
71    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
72    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
73    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
74    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
75    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
76    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
77    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
78    "Mark task complete in TodoWrite" -> "More tasks remain?";
79    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
80    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
81    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
82}
83```
84 
85## Prompt Templates
86 
87- `./implementer-prompt.md` - Dispatch implementer subagent
88- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
89- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
90 
91## Example Workflow
92 
93```
94You: I'm using Subagent-Driven Development to execute this plan.
95 
96[Read plan file once: docs/plans/feature-plan.md]
97[Extract all 5 tasks with full text and context]
98[Create TodoWrite with all tasks]
99 
100Task 1: Hook installation script
101 
102[Get Task 1 text and context (already extracted)]
103[Dispatch implementation subagent with full task text + context]
104 
105Implementer: "Before I begin - should the hook be installed at user or system level?"
106 
107You: "User level (~/.config/superpowers/hooks/)"
108 
109Implementer: "Got it. Implementing now..."
110[Later] Implementer:
111  - Implemented install-hook command
112  - Added tests, 5/5 passing
113  - Self-review: Found I missed --force flag, added it
114  - Committed
115 
116[Dispatch spec compliance reviewer]
117Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
118 
119[Get git SHAs, dispatch code quality reviewer]
120Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
121 
122[Mark Task 1 complete]
123 
124Task 2: Recovery modes
125 
126[Get Task 2 text and context (already extracted)]
127[Dispatch implementation subagent with full task text + context]
128 
129Implementer: [No questions, proceeds]
130Implementer:
131  - Added verify/repair modes
132  - 8/8 tests passing
133  - Self-review: All good
134  - Committed
135 
136[Dispatch spec compliance reviewer]
137Spec reviewer: ❌ Issues:
138  - Missing: Progress reporting (spec says "report every 100 items")
139  - Extra: Added --json flag (not requested)
140 
141[Implementer fixes issues]
142Implementer: Removed --json flag, added progress reporting
143 
144[Spec reviewer reviews again]
145Spec reviewer: ✅ Spec compliant now
146 
147[Dispatch code quality reviewer]
148Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
149 
150[Implementer fixes]
151Implementer: Extracted PROGRESS_INTERVAL constant
152 
153[Code reviewer reviews again]
154Code reviewer: ✅ Approved
155 
156[Mark Task 2 complete]
157 
158...
159 
160[After all tasks]
161[Dispatch final code-reviewer]
162Final reviewer: All requirements met, ready to merge
163 
164Done!
165```
166 
167## Advantages
168 
169**vs. Manual execution:**
170- Subagents follow TDD naturally
171- Fresh context per task (no confusion)
172- Parallel-safe (subagents don't interfere)
173- Subagent can ask questions (before AND during work)
174 
175**vs. Executing Plans:**
176- Same session (no handoff)
177- Continuous progress (no waiting)
178- Review checkpoints automatic
179 
180**Efficiency gains:**
181- No file reading overhead (controller provides full text)
182- Controller curates exactly what context is needed
183- Subagent gets complete information upfront
184- Questions surfaced before work begins (not after)
185 
186**Quality gates:**
187- Self-review catches issues before handoff
188- Two-stage review: spec compliance, then code quality
189- Review loops ensure fixes actually work
190- Spec compliance prevents over/under-building
191- Code quality ensures implementation is well-built
192 
193**Cost:**
194- More subagent invocations (implementer + 2 reviewers per task)
195- Controller does more prep work (extracting all tasks upfront)
196- Review loops add iterations
197- But catches issues early (cheaper than debugging later)
198 
199## Red Flags
200 
201**Never:**
202- Skip reviews (spec compliance OR code quality)
203- Proceed with unfixed issues
204- Dispatch multiple implementation subagents in parallel (conflicts)
205- Make subagent read plan file (provide full text instead)
206- Skip scene-setting context (subagent needs to understand where task fits)
207- Ignore subagent questions (answer before letting them proceed)
208- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
209- Skip review loops (reviewer found issues = implementer fixes = review again)
210- Let implementer self-review replace actual review (both are needed)
211- **Start code quality review before spec compliance is ✅** (wrong order)
212- Move to next task while either review has open issues
213 
214**If subagent asks questions:**
215- Answer clearly and completely
216- Provide additional context if needed
217- Don't rush them into implementation
218 
219**If reviewer finds issues:**
220- Implementer (same subagent) fixes them
221- Reviewer reviews again
222- Repeat until approved
223- Don't skip the re-review
224 
225**If subagent fails task:**
226- Dispatch fix subagent with specific instructions
227- Don't try to fix manually (context pollution)
228 
229## Integration
230 
231**Required workflow skills:**
232- **superpowers:writing-plans** - Creates the plan this skill executes
233- **superpowers:requesting-code-review** - Code review template for reviewer subagents
234- **superpowers:finishing-a-development-branch** - Complete development after all tasks
235 
236**Subagents should use:**
237- **superpowers:test-driven-development** - Subagents follow TDD for each task
238 
239**Alternative workflow:**
240- **superpowers:executing-plans** - Use for parallel session instead of same-session execution
241