An agentic skills framework & software development methodology that works.
Rewrite subagent-driven-development with executable flowcharts
Jesse Vincenta9b94ae5d71a
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.mdindex 5269d93d3..d43635ac3 100644--- a/skills/subagent-driven-development/SKILL.md+++ b/skills/subagent-driven-development/SKILL.md@@ -9,7 +9,25 @@ Execute plan by dispatching fresh subagent per task, with code review after each**Core principle:** Fresh subagent per task + review between tasks = high quality, fast iteration-## Overview+## When to Use++```dot+digraph when_to_use {+ "Have implementation plan?" [shape=diamond];+ "Tasks mostly independent?" [shape=diamond];+ "Stay in this session?" [shape=diamond];+ "subagent-driven-development" [shape=box];+ "executing-plans" [shape=box];+ "Manual execution or brainstorm first" [shape=box];++ "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];+ "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];+ "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];+ "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];+ "Stay in this session?" -> "subagent-driven-development" [label="yes"];+ "Stay in this session?" -> "executing-plans" [label="no - parallel session"];+}+```**vs. Executing Plans (parallel session):**- Same session (no context switch)@@ -17,240 +35,58 @@ Execute plan by dispatching fresh subagent per task, with code review after each- Code review after each task (catch issues early)- Faster iteration (no human-in-loop between tasks)-**When to use:**-- Staying in this session-- Tasks are mostly independent-- Want continuous progress with quality gates--**When NOT to use:**-- Need to review plan first (use executing-plans)-- Tasks are tightly coupled (manual execution better)-- Plan needs revision (brainstorm first)-## The Process-### 1. Load Plan--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:**-- 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:**-```-Task tool (general-purpose):- description: "Implement Task N: [task name]"- prompt: |- You are implementing Task N: [task name]-- ## Task Description-- [FULL TEXT of task from plan - paste it here, don't make subagent read file]-- ## Context-- [Scene-setting: where this fits, dependencies, architectural context]-- ## Before You Begin-- If you have questions about:- - The requirements or acceptance criteria- - The approach or implementation strategy- - Dependencies or assumptions- - Anything unclear in the task description-- **Ask them now.** Raise any concerns before starting work.-- ## Your Job-- Once you're clear on requirements:- 1. Implement exactly what the task specifies- 2. Write tests (following TDD if task says to)- 3. Verify implementation works- 4. Commit your work- 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-```--**3. Handle subagent response:**--If subagent asks questions:-- Answer clearly-- Provide additional context if needed-- Either continue conversation or re-dispatch with answers--If subagent proceeds with implementation:-- Review their report-- 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 Implementer Claims They Built-- [From implementer's report]-- ## CRITICAL: Do Not Trust the Report-- The implementer finished suspiciously quickly. Their report may be incomplete,- inaccurate, or optimistic. You MUST verify everything independently.-- **DO NOT:**- - Take their word for what they implemented- - Trust their claims about completeness- - Accept their interpretation of requirements-- **DO:**- - Read the actual code they wrote- - Compare actual implementation to requirements line by line- - Check for missing pieces they claimed to implement- - Look for extra features they didn't mention-- ## Your Job-- Read the implementation code and verify:-- **Missing requirements:**- - Did they implement everything that was requested?- - Are there requirements they skipped or missed?- - Did they claim something works but didn't actually implement it?-- **Extra/unneeded work:**- - Did they build things that weren't requested?- - Did they over-engineer or add unnecessary features?- - Did they add "nice to haves" that weren't in spec?-- **Misunderstandings:**- - Did they interpret requirements differently than intended?- - Did they solve the wrong problem?- - Did they implement the right feature but wrong way?-- **Verify by reading code, not by trusting report.**-- Report:- - ✅ Spec compliant (if everything matches after code inspection)- - ❌ Issues found: [list specifically what's missing or extra, with file:line references]+```dot+digraph process {+ rankdir=TB;++ subgraph cluster_per_task {+ label="Per Task";+ "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];+ "Implementer subagent asks questions?" [shape=diamond];+ "Answer questions, provide context" [shape=box];+ "Implementer subagent implements, tests, commits, self-reviews" [shape=box];+ "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];+ "Spec reviewer subagent confirms code matches spec?" [shape=diamond];+ "Implementer subagent fixes spec gaps" [shape=box];+ "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];+ "Code quality reviewer subagent approves?" [shape=diamond];+ "Implementer subagent fixes quality issues" [shape=box];+ "Mark task complete in TodoWrite" [shape=box];+ }++ "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];+ "More tasks remain?" [shape=diamond];+ "Dispatch final code reviewer subagent for entire implementation" [shape=box];+ "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];++ "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";+ "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";+ "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];+ "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";+ "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];+ "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";+ "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";+ "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];+ "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];+ "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];+ "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";+ "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];+ "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];+ "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];+ "Mark task complete in TodoWrite" -> "More tasks remain?";+ "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];+ "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];+ "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";+}```-**Review loop (must complete before Step 4):**-1. Spec reviewer reports findings-2. If issues found:- - Original implementer fixes issues- - Spec reviewer reviews again-3. Repeat until spec compliant--**Do NOT proceed to code quality review until spec compliance is ✅**--### 4. Code Quality Review--**Purpose:** Verify implementation is well-built (clean, tested, maintainable)--**Only run after spec compliance review is complete.**--**Dispatch code-reviewer subagent:**-```-Task tool (superpowers:code-reviewer):- Use template at requesting-code-review/code-reviewer.md-- WHAT_WAS_IMPLEMENTED: [from implementer's report]- PLAN_OR_REQUIREMENTS: Task N from [plan-file]- BASE_SHA: [commit before task]- HEAD_SHA: [current commit]- DESCRIPTION: [task summary]-```+## Prompt Templates-**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment--**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 for each remaining task--### 6. Final Review--After all tasks complete, dispatch final code-reviewer:-- Reviews entire implementation-- Checks all plan requirements met-- Validates overall architecture--### 7. Complete Development--After final review passes:-- Announce: "I'm using the finishing-a-development-branch skill to complete this work."-- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch-- Follow that skill to verify tests, present options, execute choice+- `./implementer-prompt.md` - Dispatch implementer subagent+- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent+- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent## Example Workflow@@ -393,14 +229,12 @@ Done!## Integration**Required workflow skills:**-- **writing-plans** - REQUIRED: Creates the plan that this skill executes-- **requesting-code-review** - REQUIRED: Review after each task (see Step 3)-- **finishing-a-development-branch** - REQUIRED: Complete development after all tasks (see Step 7)+- **superpowers:writing-plans** - Creates the plan this skill executes+- **superpowers:requesting-code-review** - Code review template for reviewer subagents+- **superpowers:finishing-a-development-branch** - Complete development after all tasks-**Subagents must use:**-- **test-driven-development** - Subagents follow TDD for each task+**Subagents should use:**+- **superpowers:test-driven-development** - Subagents follow TDD for each task**Alternative workflow:**-- **executing-plans** - Use for parallel session instead of same-session execution--See code-reviewer template: requesting-code-review/code-reviewer.md+- **superpowers:executing-plans** - Use for parallel session instead of same-session executiondiff --git a/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/skills/subagent-driven-development/code-quality-reviewer-prompt.mdnew file mode 100644index 000000000..d029ea299--- /dev/null+++ b/skills/subagent-driven-development/code-quality-reviewer-prompt.md@@ -0,0 +1,20 @@+# Code Quality Reviewer Prompt Template++Use this template when dispatching a code quality reviewer subagent.++**Purpose:** Verify implementation is well-built (clean, tested, maintainable)++**Only dispatch after spec compliance review passes.**++```+Task tool (superpowers:code-reviewer):+ Use template at requesting-code-review/code-reviewer.md++ WHAT_WAS_IMPLEMENTED: [from implementer's report]+ PLAN_OR_REQUIREMENTS: Task N from [plan-file]+ BASE_SHA: [commit before task]+ HEAD_SHA: [current commit]+ DESCRIPTION: [task summary]+```++**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessmentdiff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.mdnew file mode 100644index 000000000..db5404b30--- /dev/null+++ b/skills/subagent-driven-development/implementer-prompt.md@@ -0,0 +1,78 @@+# Implementer Subagent Prompt Template++Use this template when dispatching an implementer subagent.++```+Task tool (general-purpose):+ description: "Implement Task N: [task name]"+ prompt: |+ You are implementing Task N: [task name]++ ## Task Description++ [FULL TEXT of task from plan - paste it here, don't make subagent read file]++ ## Context++ [Scene-setting: where this fits, dependencies, architectural context]++ ## Before You Begin++ If you have questions about:+ - The requirements or acceptance criteria+ - The approach or implementation strategy+ - Dependencies or assumptions+ - Anything unclear in the task description++ **Ask them now.** Raise any concerns before starting work.++ ## Your Job++ Once you're clear on requirements:+ 1. Implement exactly what the task specifies+ 2. Write tests (following TDD if task says to)+ 3. Verify implementation works+ 4. Commit your work+ 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+```diff --git a/skills/subagent-driven-development/spec-reviewer-prompt.md b/skills/subagent-driven-development/spec-reviewer-prompt.mdnew file mode 100644index 000000000..ab5ddb8a5--- /dev/null+++ b/skills/subagent-driven-development/spec-reviewer-prompt.md@@ -0,0 +1,61 @@+# Spec Compliance Reviewer Prompt Template++Use this template when dispatching a spec compliance reviewer subagent.++**Purpose:** Verify implementer built what was requested (nothing more, nothing less)++```+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 Implementer Claims They Built++ [From implementer's report]++ ## CRITICAL: Do Not Trust the Report++ The implementer finished suspiciously quickly. Their report may be incomplete,+ inaccurate, or optimistic. You MUST verify everything independently.++ **DO NOT:**+ - Take their word for what they implemented+ - Trust their claims about completeness+ - Accept their interpretation of requirements++ **DO:**+ - Read the actual code they wrote+ - Compare actual implementation to requirements line by line+ - Check for missing pieces they claimed to implement+ - Look for extra features they didn't mention++ ## Your Job++ Read the implementation code and verify:++ **Missing requirements:**+ - Did they implement everything that was requested?+ - Are there requirements they skipped or missed?+ - Did they claim something works but didn't actually implement it?++ **Extra/unneeded work:**+ - Did they build things that weren't requested?+ - Did they over-engineer or add unnecessary features?+ - Did they add "nice to haves" that weren't in spec?++ **Misunderstandings:**+ - Did they interpret requirements differently than intended?+ - Did they solve the wrong problem?+ - Did they implement the right feature but wrong way?++ **Verify by reading code, not by trusting report.**++ Report:+ - ✅ Spec compliant (if everything matches after code inspection)+ - ❌ Issues found: [list specifically what's missing or extra, with file:line references]+```