| name | subagent-driven-development |
| description | Use when executing an implementation plan with multiple independent tasks that benefit from fresh context per task |
| metadata | {"owner":"shrug-labs","last_updated":"2026-03-09T00:00:00.000Z"} |
Subagent-Driven Development
Dispatch a fresh agent context per task, with two-stage review after each: spec compliance first, then code quality.
The Iron Law
NEVER LET A SUBAGENT GUESS — ANSWER ITS QUESTIONS OR PROVIDE THE CONTEXT IT NEEDS
A subagent working from assumptions produces plausible code that misses the point. Every question from a subagent is a signal that you failed to provide sufficient context. Answer completely before the subagent proceeds.
No exceptions:
- Not when the answer "seems obvious"
- Not when you're in a hurry
- Not when the subagent says "I'll assume X" — correct the assumption or confirm it explicitly
- If the subagent has to guess, you have already failed
Violating the letter of this rule IS violating the spirit.
When NOT to Use
- Your harness does not support subagents — use the fallback pattern below instead
- Tasks are tightly coupled (each depends on the prior task's output)
- Only one task to execute — just do it directly
- The plan is unclear or incomplete — write the plan first
Harness Capability Check
Not all harnesses support subagent dispatch. Before starting:
- Determine if your harness can spawn fresh agent contexts (Claude Code:
Task, Cursor: background agents, etc.)
- If yes — use the full subagent protocol
- If no — use the Single-Context Fallback at the end of this skill
The Process
digraph process {
rankdir=TB;
"Extract all tasks from plan" [shape=box];
"Dispatch implementer (fresh context)" [shape=box];
"Implementer asks questions?" [shape=diamond];
"Answer questions completely" [shape=box];
"Implementer implements, tests, commits" [shape=box];
"Spec review: code matches spec?" [shape=diamond];
"Implementer fixes spec gaps" [shape=box];
"Quality review: code well-built?" [shape=diamond];
"Implementer fixes quality issues" [shape=box];
"Mark task complete" [shape=box];
"More tasks?" [shape=diamond];
"Final cross-task review" [shape=box];
"finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
"Extract all tasks from plan" -> "Dispatch implementer (fresh context)";
"Dispatch implementer (fresh context)" -> "Implementer asks questions?";
"Implementer asks questions?" -> "Answer questions completely" [label="yes"];
"Answer questions completely" -> "Dispatch implementer (fresh context)";
"Implementer asks questions?" -> "Implementer implements, tests, commits" [label="no"];
"Implementer implements, tests, commits" -> "Spec review: code matches spec?";
"Spec review: code matches spec?" -> "Implementer fixes spec gaps" [label="no"];
"Implementer fixes spec gaps" -> "Spec review: code matches spec?" [label="re-review"];
"Spec review: code matches spec?" -> "Quality review: code well-built?" [label="yes"];
"Quality review: code well-built?" -> "Implementer fixes quality issues" [label="no"];
"Implementer fixes quality issues" -> "Quality review: code well-built?" [label="re-review"];
"Quality review: code well-built?" -> "Mark task complete" [label="yes"];
"Mark task complete" -> "More tasks?";
"More tasks?" -> "Dispatch implementer (fresh context)" [label="yes"];
"More tasks?" -> "Final cross-task review" [label="no"];
"Final cross-task review" -> "finishing-a-development-branch";
}
Step-by-Step Protocol
Step 1: Extract All Tasks
Read the plan once. Extract every task with its full text, acceptance criteria, and relevant context. Do NOT make subagents read the plan file — you provide the content.
Step 2: Dispatch Implementer
Create a fresh agent context for each task. Provide:
- Full task text and acceptance criteria
- Relevant context (project structure, conventions, dependencies on prior tasks)
- Explicit instructions: implement, write tests, run tests, commit, self-review
The implementer must ask questions BEFORE starting work if anything is unclear.
Step 3: Two-Stage Review
Stage 1 — Spec Compliance (dispatch fresh reviewer context):
- Does the code implement everything in the spec? List each requirement and its status.
- Does the code implement anything NOT in the spec? Flag additions.
- Binary outcome: compliant or not compliant. No partial credit.
Stage 2 — Code Quality (dispatch fresh reviewer context, ONLY after spec passes):
- Is the code well-structured, tested, and maintainable?
- Does it follow project conventions?
- Are there bugs, edge cases, or performance issues?
Step 4: Fix Loop
If either reviewer finds issues:
- Route issues back to the implementer context (or a fresh fix context)
- Implementer fixes
- Same reviewer reviews again
- Repeat until approved
Do NOT skip re-review. Do NOT accept "I fixed it" without reviewer confirmation.
Step 5: Next Task
Mark task complete. Move to the next task with a fresh implementer context. Previous task's context does not carry over — that is the point.
Step 6: Final Review
After all tasks, dispatch one final reviewer across the entire implementation:
- Cross-task integration: do the pieces fit together?
- Consistency: naming, patterns, error handling across all tasks
- Completeness: does the whole match the plan?
Two-Stage Review: Why This Order
Spec compliance FIRST because:
- No point polishing code that implements the wrong thing
- Spec failures require structural changes that invalidate quality feedback
- Quality review on spec-compliant code is review that sticks
Quality SECOND because:
- Now you know the code does the right thing — make it do it well
- Quality feedback applies to the final shape, not an intermediate one
Rationalization Table
| Excuse | Reality |
|---|
| "I'll review both at once to save time" | Spec failures invalidate quality feedback. Two passes, always. |
| "The subagent can probably figure it out" | Probably = assumption. Provide context or answer questions. |
| "This task is too small for a subagent" | Small tasks still benefit from fresh context. Skip only for trivial changes. |
| "I'll fix it myself instead of routing back" | You are the controller, not the implementer. Context pollution. |
| "Spec is close enough" | Close enough = not compliant. Reviewer found issues = implementer fixes. |
| "I'll do quality review later, across all tasks" | Per-task quality catches issues before they compound. Final review is additive, not a replacement. |
| "Re-review is wasteful, the fix was obvious" | Obvious fixes sometimes introduce new issues. Reviewer confirms, always. |
Red Flags
- Starting implementation on main/master without user consent
- Skipping either review stage
- Dispatching parallel implementers (they will conflict)
- Making a subagent read the plan file instead of providing task text
- Proceeding when a subagent has unanswered questions
- Starting quality review before spec compliance passes
- Moving to the next task with open review issues
- Letting the implementer self-review replace the two-stage review
- Fixing issues yourself instead of routing to the implementer
Degrees of Freedom
| Situation | Adjustment |
|---|
| Trivial task (rename, config change) | Skip subagent, do directly, still verify |
| Task depends on prior task's output | Provide prior task's result as context to the new implementer |
| Reviewer and implementer disagree | Controller decides. State reasoning. |
| Subagent fails entirely | Dispatch a new context with specific fix instructions |
| Only 2-3 small tasks | Single-context fallback may be more efficient |
Single-Context Fallback
When your harness cannot dispatch subagents, simulate the pattern:
- Extract all tasks from the plan (same as above)
- Per task, create a mental boundary:
- Re-read the task spec fresh — do not rely on what you remember from prior tasks
- Implement, test, commit
- Self-review against spec (every requirement, binary pass/fail)
- Self-review for quality (conventions, tests, structure)
- Do NOT proceed until both reviews pass
- Between tasks, reset:
- Re-read the plan to confirm next task
- Do not carry assumptions from the prior task
- Treat each task as if you just started
- After all tasks, do the cross-task final review
The fallback loses fresh-context isolation but preserves the discipline: one task at a time, two-stage review, no skipping.
After All Tasks
Once all tasks pass review and the final cross-task review is clean, proceed to branch completion. If the finishing-a-development-branch skill is available, invoke it.
