Skip to content

An agentic skills framework & software development methodology that works.

Improve subagent-driven-development workflow

Jesse Vincent2a6a40fe1047
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md
index afd42bcc1..28cf8e577 100644
--- a/skills/subagent-driven-development/SKILL.md
+++ b/skills/subagent-driven-development/SKILL.md
@@ -31,21 +31,22 @@ Execute plan by dispatching fresh subagent per task, with code review after each
### 1. Load Plan
-1. Read plan file
-2. Extract all tasks
-3. Create TodoWrite with all tasks
+1. Read plan file once
+2. Extract all tasks (full text of each)
+3. For each task, note scene-setting context:
+ - Where it fits in overall plan
+ - Dependencies on previous tasks
+ - Architectural context
+ - Relevant patterns or existing code to follow
+4. Create TodoWrite with all tasks
### 2. Execute Task with Subagent
For each task:
**1. Prepare task context:**
-- Read the full text of Task N from plan file
-- Identify scene-setting context:
- - Where this task fits in overall plan
- - Dependencies on previous tasks
- - Architectural context subagent needs
- - Relevant patterns or existing code to follow
+- Get the full text of Task N (already extracted in Step 1)
+- Get the scene-setting context (already noted in Step 1)
**2. Dispatch fresh subagent with full task text:**
```
@@ -79,16 +80,47 @@ Task tool (general-purpose):
2. Write tests (following TDD if task says to)
3. Verify implementation works
4. Commit your work
- 5. Report back
+ 5. Self-review (see below)
+ 6. Report back
Work from: [directory]
+ **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+ It's always OK to pause and clarify. Don't guess or make assumptions.
+
+ ## Before Reporting Back: Self-Review
+
+ Review your work with fresh eyes. Ask yourself:
+
+ **Completeness:**
+ - Did I fully implement everything in the spec?
+ - Did I miss any requirements?
+ - Are there edge cases I didn't handle?
+
+ **Quality:**
+ - Is this my best work?
+ - Are names clear and accurate (match what things do, not how they work)?
+ - Is the code clean and maintainable?
+
+ **Discipline:**
+ - Did I avoid overbuilding (YAGNI)?
+ - Did I only build what was requested?
+ - Did I follow existing patterns in the codebase?
+
+ **Testing:**
+ - Do tests actually verify behavior (not just mock behavior)?
+ - Did I follow TDD if required?
+ - Are tests comprehensive?
+
+ If you find issues during self-review, fix them now before reporting.
+
## Report Format
When done, report:
- What you implemented
- What you tested and test results
- Files changed
+ - Self-review findings (if any)
- Any issues or concerns
```
@@ -101,16 +133,67 @@ If subagent asks questions:
If subagent proceeds with implementation:
- Review their report
-- Proceed to code review (Step 3)
+- Proceed to spec compliance review (Step 3)
+
+### 3. Spec Compliance Review
+
+**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
+
+**Dispatch spec compliance reviewer:**
+```
+Task tool (general-purpose):
+ description: "Review spec compliance for Task N"
+ prompt: |
+ You are reviewing whether an implementation matches its specification.
+
+ ## What Was Requested
+
+ [FULL TEXT of task requirements]
+
+ ## What Was Implemented
+
+ [From implementer's report]
+
+ ## Your Job
-### 3. Review Subagent's Work
+ Check for:
+
+ **Missing requirements:**
+ - Did they implement everything that was requested?
+ - Are there requirements they skipped or missed?
+
+ **Extra/unneeded work:**
+ - Did they build things that weren't requested?
+ - Did they over-engineer or add unnecessary features?
+
+ **Misunderstandings:**
+ - Did they interpret requirements differently than intended?
+ - Did they solve the wrong problem?
+
+ Read the implementation code to verify.
+
+ Report:
+ - ✅ Spec compliant (if everything matches)
+ - ❌ Issues found: [list what's missing or extra]
+```
+
+**Review loop:**
+1. Spec reviewer reports findings
+2. If issues found:
+ - Original implementer fixes issues
+ - Spec reviewer reviews again
+3. Repeat until spec compliant
+
+### 4. Code Quality Review
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
**Dispatch code-reviewer subagent:**
```
Task tool (superpowers:code-reviewer):
Use template at requesting-code-review/code-reviewer.md
- WHAT_WAS_IMPLEMENTED: [from subagent's report]
+ WHAT_WAS_IMPLEMENTED: [from implementer's report]
PLAN_OR_REQUIREMENTS: Task N from [plan-file]
BASE_SHA: [commit before task]
HEAD_SHA: [current commit]
@@ -119,23 +202,18 @@ Task tool (superpowers:code-reviewer):
**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
-### 4. Apply Review Feedback
-
-**If issues found:**
-- Fix Critical issues immediately
-- Fix Important issues before next task
-- Note Minor issues
-
-**Dispatch follow-up subagent if needed:**
-```
-"Fix issues from code review: [list issues]"
-```
+**Review loop:**
+1. Code reviewer reports findings
+2. If issues found:
+ - Original implementer fixes issues
+ - Code reviewer reviews again
+3. Repeat until code quality approved
### 5. Mark Complete, Next Task
- Mark task as completed in TodoWrite
- Move to next task
-- Repeat steps 2-5
+- Repeat steps 2-5 for each remaining task
### 6. Final Review
@@ -156,43 +234,67 @@ After final review passes:
```
You: I'm using Subagent-Driven Development to execute this plan.
-[Read plan file: docs/plans/feature-plan.md]
-[Extract 5 tasks, create TodoWrite]
+[Read plan file once: docs/plans/feature-plan.md]
+[Extract all 5 tasks with full text and context]
+[Create TodoWrite with all tasks]
Task 1: Hook installation script
-[Read Task 1 full text from plan]
-[Prepare context: "First task, no dependencies, creates new install-hook command"]
+[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]
-Subagent: "Before I begin - should the hook be installed at user or system level?"
+Implementer: "Before I begin - should the hook be installed at user or system level?"
You: "User level (~/.config/superpowers/hooks/)"
-Subagent: "Got it. Implementing now..."
-[Later] Subagent: Implemented install-hook with tests, 5/5 passing
+Implementer: "Got it. Implementing now..."
+[Later] Implementer:
+ - Implemented install-hook command
+ - Added tests, 5/5 passing
+ - Self-review: Found I missed --force flag, added it
+ - Committed
-[Get git SHAs, dispatch code-reviewer]
-Reviewer: Strengths: Good test coverage. Issues: None. Ready.
+[Dispatch spec compliance reviewer]
+Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
+
+[Get git SHAs, dispatch code quality reviewer]
+Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
[Mark Task 1 complete]
Task 2: Recovery modes
-[Read Task 2 full text]
-[Prepare context: "Depends on Task 1 hook structure, adds verify/repair modes"]
+[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]
-Subagent: [No questions, proceeds]
-Subagent: Added verify/repair, 8/8 tests passing
+Implementer: [No questions, proceeds]
+Implementer:
+ - Added verify/repair modes
+ - 8/8 tests passing
+ - Self-review: All good
+ - Committed
+
+[Dispatch spec compliance reviewer]
+Spec reviewer: ❌ Issues:
+ - Missing: Progress reporting (spec says "report every 100 items")
+ - Extra: Added --json flag (not requested)
-[Dispatch code-reviewer]
-Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
+[Implementer fixes issues]
+Implementer: Removed --json flag, added progress reporting
-[Dispatch fix subagent]
-Fix subagent: Added progress every 100 conversations
+[Spec reviewer reviews again]
+Spec reviewer: ✅ Spec compliant now
-[Verify fix, mark Task 2 complete]
+[Dispatch code quality reviewer]
+Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
+
+[Implementer fixes]
+Implementer: Extracted PROGRESS_INTERVAL constant
+
+[Code reviewer reviews again]
+Code reviewer: ✅ Approved
+
+[Mark Task 2 complete]
...
@@ -209,7 +311,7 @@ Done!
- Subagents follow TDD naturally
- Fresh context per task (no confusion)
- Parallel-safe (subagents don't interfere)
-- Subagent can ask questions before starting (reduces ambiguity)
+- Subagent can ask questions (before AND during work)
**vs. Executing Plans:**
- Same session (no handoff)
@@ -222,26 +324,43 @@ Done!
- Subagent gets complete information upfront
- Questions surfaced before work begins (not after)
+**Quality gates:**
+- Self-review catches issues before handoff
+- Two-stage review: spec compliance, then code quality
+- Review loops ensure fixes actually work
+- Spec compliance prevents over/under-building
+- Code quality ensures implementation is well-built
+
**Cost:**
-- More subagent invocations
-- Controller does more prep work (reading/extracting tasks)
+- More subagent invocations (implementer + 2 reviewers per task)
+- Controller does more prep work (extracting all tasks upfront)
+- Review loops add iterations
- But catches issues early (cheaper than debugging later)
## Red Flags
**Never:**
-- Skip code review between tasks
-- Proceed with unfixed Critical issues
+- Skip reviews (spec compliance OR code quality)
+- Proceed with unfixed issues
- Dispatch multiple implementation subagents in parallel (conflicts)
- Make subagent read plan file (provide full text instead)
- Skip scene-setting context (subagent needs to understand where task fits)
- Ignore subagent questions (answer before letting them proceed)
+- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
+- Skip review loops (reviewer found issues = implementer fixes = review again)
+- Let implementer self-review replace actual review (both are needed)
**If subagent asks questions:**
- Answer clearly and completely
- Provide additional context if needed
- Don't rush them into implementation
+**If reviewer finds issues:**
+- Implementer (same subagent) fixes them
+- Reviewer reviews again
+- Repeat until approved
+- Don't skip the re-review
+
**If subagent fails task:**
- Dispatch fix subagent with specific instructions
- Don't try to fix manually (context pollution)