subagent-driven-development

Name: subagent-driven-development
Author: obra

byobra· 95 skills

Installs

160k

Stars

261k

Forks

23k

How to install subagent-driven-development?

obra/superpowers/subagent-driven-development

$npx -y skills add obra/superpowers --skill subagent-driven-development

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/subagent-driven-development"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Subagent-Driven Development
2
3	Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end.
4
5	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.
6
7	Core principle: Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration
8
9	Narration: between tool calls, narrate at most one short line — the
10	ledger and the tool results carry the record.
11
12	Continuous execution: Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.
13
14	## When to Use
15
16	```dot
17	digraph when_to_use {
18	"Have implementation plan?" [shape=diamond];
19	"Tasks mostly independent?" [shape=diamond];
20	"Stay in this session?" [shape=diamond];
21	"subagent-driven-development" [shape=box];
22	"executing-plans" [shape=box];
23	"Manual execution or brainstorm first" [shape=box];
24
25	"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
26	"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
27	"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
28	"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
29	"Stay in this session?" -> "subagent-driven-development" [label="yes"];
30	"Stay in this session?" -> "executing-plans" [label="no - parallel session"];
31	}
32	```
33
34	vs. Executing Plans (parallel session):
35	- Same session (no context switch)
36	- Fresh subagent per task (no context pollution)
37	- Review after each task (spec compliance + code quality), broad review at the end
38	- Faster iteration (no human-in-loop between tasks)
39
40	## The Process
41
42	```dot
43	digraph process {
44	rankdir=TB;
45
46	subgraph cluster_per_task {
47	label="Per Task";
48	"Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
49	"Implementer asks questions?" [shape=diamond];
50	"Answer questions, provide context" [shape=box];
51	"Implementer implements, tests, commits, self-reviews" [shape=box];
52	"Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
53	"Spec ✅ and quality approved?" [shape=diamond];
54	"Finding conflicts with plan text?" [shape=diamond];
55	"Ask human partner which governs" [shape=box];
56	"Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
57	"Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
58	"All findings addressed?" [shape=diamond];
59	"R = 5?" [shape=diamond];
60	"Adjudicate each open finding" [shape=box];
61	"Any load-bearing finding?" [shape=diamond];
62	"STOP: report BLOCKED to human partner" [shape=box];
63	"Park findings in ledger with rulings" [shape=box];
64	"Append completion to ledger, mark todo complete" [shape=box];
65	}
66
67	"Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
68	"More tasks remain?" [shape=diamond];
69	"Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
70	"Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
71	"Final review clean: delete this plan's workspace" [shape=box];
72	"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
73
74	"Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
75	"Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
76	"Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
77	"Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
78	"Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
79	"Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
80	"Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
81	"Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
82	"Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
83	"Finding conflicts with plan text?" -> "Ask human partner which governs" [label="yes"];
84	"Ask human partner which governs" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
85	"Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
86	"Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
87	"Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
88	"All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
89	"All findings addressed?" -> "R = 5?" [label="no"];
90	"R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
91	"R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
92	"Adjudicate each open finding" -> "Any load-bearing finding?";
93	"Any load-bearing finding?" -> "STOP: report BLOCKED to human partner" [label="yes"];
94	"Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
95	"Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
96	"Append completion to ledger, mark todo complete" -> "More tasks remain?";
97	"More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
98	"More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
99	"Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
100	"Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
101	"Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
102	}
103	```
104
105	## Setup
106
107	Ensure the work happens in an isolated workspace: use
108	superpowers:using-git-worktrees to create one or verify the existing one.
109	Never start implementation on a main/master branch without your human
110	partner's explicit consent.
111
112	Conversation memory does not survive compaction. In real sessions,
113	controllers that lost their place have re-dispatched entire completed task
114	sequences — the single most expensive failure observed. Track progress in
115	a ledger file, not only in todos.
116
117	- Each plan owns a workspace: at skill start, run this skill's
118	`scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
119	directory (`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to
120	every artifact for THIS plan: ledger, briefs, reports, review packages.
121	Another plan's directory is never yours to read or write.
122	- Check for this plan's ledger at `<workspace>/progress.md`. If its first
123	line names your plan file, tasks with a `Task <N>: complete` line are DONE
124	— do not re-dispatch them; resume at the first task without one. A task
125	whose last line is a fix round is mid-loop: resume the loop at the next
126	round. A ledger whose first line names a different plan file — or a stray
127	ledger at the old flat path `.superpowers/sdd/progress.md` — is another
128	plan's progress: leave it in place and start your own, fresh.
129	- Create the ledger with its identity as the first line:
130	`# SDD ledger — plan: <plan file path>`.
131	- The ledger is your recovery map: the commits it names exist in git even
132	when your context no longer remembers creating them. After compaction,
133	trust the ledger and `git log` over your own recollection.
134	- `git clean -fdx` will destroy the workspace (it's git-ignored scratch); if
135	that happens, recover from `git log`.
136
137	Read the plan once, note its context and Global Constraints, and create a
138	todo per task.
139
140	Before dispatching Task 1, scan the plan once for conflicts:
141
142	- tasks that contradict each other or the plan's Global Constraints
143	- anything the plan explicitly mandates that the review rubric treats as a
144	defect (a test that asserts nothing, verbatim duplication of a logic block)
145
146	Present everything you find to your human partner as one batched question —
147	each finding beside the plan text that mandates it, asking which governs —
148	before execution begins, not one interrupt per discovery mid-plan. If the
149	scan is clean, proceed without comment. The review loop remains the net for
150	conflicts that only emerge from implementation.
151
152	## Model Selection
153
154	Use the least powerful model that can handle each role to conserve cost and increase speed.
155
156	Mechanical implementation tasks (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
157
158	Integration and judgment tasks (multi-file coordination, pattern matching, debugging): use a standard model.
159
160	Architecture and design tasks: use the most capable available model.
161	The final whole-branch review is one of these — dispatch it on the most
162	capable available model, not the session default.
163
164	Review tasks: choose the model with the same judgment, scaled to the
165	diff's size, complexity, and risk. A small mechanical diff does not need the
166	most capable model; a subtle concurrency change does. Scoped re-reviews of
167	small fix diffs take a cheap-to-mid tier.
168
169	Fix-loop escalation (rounds 4-5): use a model at least one tier above
170	the implementer that got stuck.
171
172	Always specify the model explicitly when dispatching a subagent. An
173	omitted model inherits your session's model — often the most capable and
174	most expensive — which silently defeats this section.
175
176	Turn count beats token price. Wall-clock and context cost scale with how
177	many turns a subagent takes, and the cheapest models routinely take 2-3× the
178	turns on multi-step work — costing more overall. Use a mid-tier model as the
179	floor for reviewers and for implementers working from prose descriptions.
180	When the task's plan text contains the complete code to write, the
181	implementation is transcription plus testing: use the cheapest tier for
182	that implementer. Single-file mechanical fixes also take the cheapest tier.
183
184	Task complexity signals (implementation tasks):
185	- Touches 1-2 files with a complete spec → cheap model
186	- Touches multiple files with integration concerns → standard model
187	- Requires design judgment or broad codebase understanding → most capable model
188
189	## The Task Loop
190
191	Everything you paste into a dispatch prompt — and everything a subagent
192	prints back — stays resident in your context for the rest of the session
193	and is re-read on every later turn. Hand artifacts over as files.
194
195	### 1. Dispatch the implementer
196
197	Record BASE (`git rev-parse HEAD`) before dispatching — the review package
198	and fix-round diffs need it.
199
200	- Task brief: before dispatching an implementer, run this skill's
201	`scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
202	uniquely named file and prints the path. Compose the dispatch so the
203	brief stays the single source of
204	requirements. Your dispatch should contain: (1) one line on where this
205	task fits in the project; (2) the brief path, introduced as "read this
206	first — it is your requirements, with the exact values to use verbatim";
207	(3) interfaces and decisions from earlier tasks that the brief cannot
208	know; (4) your resolution of any ambiguity you noticed in the brief;
209	(5) the report-file path and report contract. Exact values (numbers,
210	magic strings, signatures, test cases) appear only in the brief. Never
211	make a subagent read the whole plan file.
212	- Report file: name the implementer's report file after the brief
213	(brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
214	the dispatch prompt. The implementer writes the full report there and
215	returns only status, commits, a one-line test summary, and concerns.
216	- A dispatch prompt describes one task, not the session's history. Do not
217	paste accumulated prior-task summaries ("state after Tasks 1-3") into
218	later dispatches — a real session's dispatch hit 42k chars of which 99%
219	was pasted history. A fresh subagent needs its task, the interfaces it
220	touches, and the global constraints. Nothing else.
221	- If an earlier task parked a finding in the area this task touches, carry
222	a pointer to that ledger entry in the dispatch.
223	- Record the implementer's agent identity from the dispatch result —
224	fix-loop rounds 1-3 resume this agent.
225	- Never dispatch multiple implementation subagents in parallel (conflicts).
226
227	Template: [implementer-prompt.md](implementer-prompt.md)
228
229	### 2. Handle the report
230
231	Implementer subagents report one of four statuses. Handle each appropriately:
232
233	DONE: Generate the review package (`scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
234
235	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.
236
237	NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
238
239	BLOCKED: The implementer cannot complete the task. Assess the blocker:
240	1. If it's a context problem, provide more context and re-dispatch with the same model
241	2. If the task requires more reasoning, re-dispatch with a more capable model
242	3. If the task is too large, break it into smaller pieces
243	4. If the plan itself is wrong, escalate to the human
244
245	Never ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
246
247	If the implementer asks questions — before starting or mid-task — answer
248	clearly and completely, provide additional context if needed, and don't
249	rush it into implementation.
250
251	### 3. Review the task
252
253	Per-task reviews are task-scoped gates. The broad review happens once, at the
254	final whole-branch review. Never skip the task review, and never accept a
255	report missing either verdict — spec compliance AND task quality are both
256	required. Implementer self-review never replaces the task review; both are
257	needed.
258
259	- Hand the reviewer its diff as a file: run this skill's
260	`scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path
261	it prints (or, without bash: `git log --oneline`, `git diff --stat`,
262	and `git diff -U10` for the range, redirected to one uniquely named
263	file). The output never enters your own context, and the reviewer sees
264	the commit list, stat summary, and full diff with context in one Read
265	call. Use the BASE you recorded before dispatching the implementer —
266	never `HEAD~1`, which silently truncates multi-commit tasks. Never
267	dispatch a task reviewer without a diff file.
268	- Reviewer inputs: the task reviewer gets three paths — the same brief
269	file, the report file, and the review package — plus the global
270	constraints that bind the task.
271	- The global-constraints block you hand the reviewer is its attention
272	lens. Copy the binding requirements verbatim from the plan's Global
273	Constraints section or the spec: exact values, exact formats, and the
274	stated relationships between components ("same layout as X", "matches
275	Y"). The reviewer's template already carries the process rules (YAGNI,
276	test hygiene, review method) — the constraints block is for what THIS
277	project's spec demands.
278	- Do not add open-ended directives like "check all uses" or "run race tests
279	if useful" without a concrete, task-specific reason
280	- Do not ask a reviewer to re-run tests the implementer already ran on the
281	same code — the implementer's report carries the test evidence
282	- Do not pre-judge findings for the reviewer — never instruct a reviewer to
283	ignore or not flag a specific issue. If you believe a finding would be a
284	false positive, let the reviewer raise it and adjudicate it in the review
285	loop. If the prompt you are writing contains "do not flag," "don't treat X
286	as a defect," "at most Minor," or "the plan chose" — stop: you are
287	pre-judging, usually to spare yourself a review loop.
288	The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
289	that live in unchanged code or span tasks. These do not block the rest of the
290	review, but you must resolve each one yourself before marking the task
291	complete: you hold the plan and cross-task context the reviewer
292	lacks. If you confirm an item is a real gap, treat it as a failed spec
293	review — it enters the fix loop with the other findings.
294
295	Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
296
297	### 4. The fix loop
298
299	The loop triggers when the review reports spec ❌, any Critical or Important
300	finding, or a ⚠️ item you confirmed as a real gap.
301
302	Before the loop starts, two routes leave it immediately:
303
304	- Record Minor findings in the progress ledger as you go
305	(`Task <N>: minor (deferred): <one-liner>`), and point the final
306	whole-branch review at that list so it can triage which must be fixed
307	before merge. A roll-up nobody reads is a silent discard. Minor findings
308	never enter the loop.
309	- A finding labeled plan-mandated — or any finding that conflicts with
310	what the plan's text requires — is the human's decision, like any plan
311	contradiction: present the finding and the plan text, ask which governs.
312	Do not dismiss the finding because the plan mandates it, and do not
313	dispatch a fix that contradicts the plan without asking.
314	Everything else enters the loop. A fix round is one fix dispatch plus one
315	scoped re-review. Five rounds maximum per task:
316
317	Rounds 1-3 — resume the original implementer. Send it the open findings
318	verbatim. Its context is intact: it knows the task, the code, and its own
319	choices. If your harness cannot send another message to a live subagent,
320	dispatch a fresh implementer carrying the brief path, the report-file path,
321	and the findings — the report file is the persistent memory either way.
322
323	Rounds 4-5 — dispatch a fresh implementer on a more capable model (per
324	Model Selection), with the brief path, the report-file path, the open
325	findings, and this framing: "A prior implementer attempted this task
326	[N] times; you own it now. Read the report file for what was tried." A loop
327	that survives three resumes usually means the implementer cannot see its
328	own problem — fresh eyes and a capability bump in one move.
329
330	Every round, either way: the implementer fixes, re-runs the tests
331	covering the amended code, appends its fix report to the same report file,
332	and returns the short contrac

6 picks

Type

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/subagent-driven-development"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

subagent-driven-development

How to install subagent-driven-development?

Related

subagent-driven-development

How to install subagent-driven-development?

Related