|
|
@@ -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
|
Jesse Vincent