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.mdindex 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 SubagentFor 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 works4. Commit your work- 5. Report back+ 5. Self-review (see below)+ 6. Report backWork 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 FormatWhen 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)