Skip to content

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.md
index 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 execution
diff --git a/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/skills/subagent-driven-development/code-quality-reviewer-prompt.md
new file mode 100644
index 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), Assessment
diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md
new file mode 100644
index 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.md
new file mode 100644
index 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]
+```