Improve subagent-driven-development workflow

Key improvements based on feedback:

1. Read plan once, not per task
   - Extract all tasks in Step 1
   - Reference extracted tasks in Step 2
   - Eliminates redundant file reading

2. Enable questions during work
   - Not just before, but also while working
   - "It's always OK to ask questions"
   - Don't guess or make assumptions

3. Add self-review before reporting
   - Completeness: implemented everything?
   - Quality: best work, clear names?
   - Discipline: avoided overbuilding?
   - Testing: comprehensive, real behavior?
   - Catches issues before handoff

4. Add spec compliance review
   - Separate reviewer checks: built the right thing?
   - Flags missing requirements
   - Flags extra/unneeded work
   - Flags misunderstandings
   - Runs BEFORE code quality review

5. Make reviews loops, not one-shot
   - Reviewer finds issues
   - Implementer fixes
   - Reviewer reviews again
   - Repeat until approved
   - Applies to both spec and code quality

Two-stage review process:
- Stage 1: Spec compliance (right thing?)
- Stage 2: Code quality (built well?)

This enables subagents to do their best work with clear requirements,
opportunities to clarify, self-critique, and thorough review loops.

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)