Initial commit

2025-11-30 08:54:38 +08:00
commit fffaa45e39
76 changed files with 14220 additions and 0 deletions
--- a/skills/parallel-subagent-driven-development/SKILL.md
+++ b/skills/parallel-subagent-driven-development/SKILL.md
@@ -0,0 +1,428 @@
+---
+name: parallel-subagent-driven-development
+description: Use when executing decomposed plans with parallel batches - dispatches up to 2 fresh subagents per batch with code review between batches, enabling fast parallel iteration with quality gates
+---
+
+# Parallel Subagent-Driven Development
+
+Execute decomposed plan by dispatching fresh subagent(s) per batch (up to 2 parallel), with code review after each batch.
+
+**Core principle:** Fresh subagent per task + up to 2 parallel when safe + review between batches = high quality, fast iteration
+
+## Overview
+
+**vs. Subagent-Driven Development:**
+- Same process, but runs up to 2 subagents in parallel when tasks are independent
+- Uses manifest.json to know which tasks can run together
+- Reviews both implementations together
+- Everything else identical
+
+**vs. Executing Plans:**
+- Same session (no context switch)
+- Fresh subagent per task (no context pollution)
+- Parallel execution when safe (faster)
+- Code review after each batch (catch issues early)
+- Faster iteration (no human-in-loop between tasks)
+
+**When to use:**
+- After running decomposing-plans (which created manifest.json)
+- Staying in this session
+- Want parallel execution with quality gates
+
+**When NOT to use:**
+- Plan not decomposed yet (run decomposing-plans first)
+- Need to review plan first (use executing-plans)
+- Tasks are tightly coupled (manual execution better)
+- Plan needs revision (brainstorm first)
+
+## Prerequisites
+
+**REQUIRED:** Must have run decomposing-plans skill first to create:
+- Individual task files: `docs/plans/tasks/<plan-name>/<feature>-task-NN.md`
+- Manifest file: `docs/plans/tasks/<plan-name>/<feature>-manifest.json`
+
+Where `<plan-name>` is the full plan filename (e.g., `2025-01-18-user-auth`)
+
+## The Process
+
+### 1. Load Manifest
+
+Read manifest file from `docs/plans/tasks/<feature>-manifest.json`.
+
+Create TodoWrite with all batches:
+```
+- [ ] Execute batch 1 (tasks X, Y)
+- [ ] Review batch 1
+- [ ] Execute batch 2 (task Z)
+- [ ] Review batch 2
+...
+```
+
+### 2. Execute Batch with Subagent(s)
+
+For each batch in `parallel_batches` array:
+
+**If batch has 1 task:**
+
+Dispatch fresh subagent (same as original):
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N from the decomposed plan.
+
+    Read the task file: docs/plans/tasks/<plan-name>/<feature>-task-NN.md
+
+    Your job is to:
+    1. Read that task file carefully
+    2. Implement exactly what the task specifies
+    3. Write tests (following TDD if task says to)
+    4. Verify implementation works
+    5. Commit your work
+    6. Report back
+
+    Work from: [directory]
+
+    Report: What you implemented, what you tested, test results, files changed, any issues
+```
+
+**If batch has 2 tasks:**
+
+Dispatch TWO fresh subagents IN SINGLE MESSAGE (parallel execution):
+
+```
+<function_calls>
+  <invoke name="Task">
+    <parameter name="subagent_type">general-purpose</parameter>
+    <parameter name="description">Implement Task N: [task name]</parameter>
+    <parameter name="prompt">
+You are implementing Task N from the decomposed plan.
+
+Read the task file: docs/plans/tasks/<plan-name>/<feature>-task-NN.md
+
+Your job is to:
+1. Read that task file carefully
+2. Implement exactly what the task specifies
+3. Write tests (following TDD if task says to)
+4. Verify implementation works
+5. Commit your work
+6. Report back
+
+Work from: [directory]
+
+Report: What you implemented, what you tested, test results, files changed, any issues
+    </parameter>
+  </invoke>
+  <invoke name="Task">
+    <parameter name="subagent_type">general-purpose</parameter>
+    <parameter name="description">Implement Task M: [task name]</parameter>
+    <parameter name="prompt">
+You are implementing Task M from the decomposed plan.
+
+Read the task file: docs/plans/tasks/<plan-name>/<feature>-task-MM.md
+
+Your job is to:
+1. Read that task file carefully
+2. Implement exactly what the task specifies
+3. Write tests (following TDD if task says to)
+4. Verify implementation works
+5. Commit your work
+6. Report back
+
+Work from: [directory]
+
+Report: What you implemented, what you tested, test results, files changed, any issues
+    </parameter>
+  </invoke>
+</function_calls>
+```
+
+**CRITICAL:** Both Task tools in SINGLE message = true parallel execution.
+
+**Subagent(s) report back** with summary of work.
+
+### 3. Review Subagent's Work
+
+**Get git SHAs:**
+- BASE_SHA: commit before batch started
+- HEAD_SHA: current commit after batch
+
+**Dispatch code-reviewer subagent:**
+
+**If batch had 1 task:**
+```
+Task tool (superpowers:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: [from subagent's report]
+  PLAN_OR_REQUIREMENTS: Task N from docs/plans/tasks/<plan-name>/<feature>-task-NN.md
+  BASE_SHA: [commit before batch]
+  HEAD_SHA: [current commit]
+  DESCRIPTION: [task summary]
+```
+
+**If batch had 2 tasks:**
+```
+Task tool (superpowers:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: |
+    Task N: [from subagent 1's report]
+    Task M: [from subagent 2's report]
+
+  PLAN_OR_REQUIREMENTS: |
+    Task N: docs/plans/tasks/<plan-name>/<feature>-task-NN.md
+    Task M: docs/plans/tasks/<plan-name>/<feature>-task-MM.md
+
+  BASE_SHA: [commit before batch]
+  HEAD_SHA: [current commit]
+  DESCRIPTION: Batch with tasks N and M - [summary of both]
+```
+
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
+
+**Important:** When reviewing 2 tasks, code-reviewer also checks:
+- No conflicts between the two implementations
+- Proper integration if tasks interact
+- Consistent code style across both
+
+### 4. Apply Review Feedback
+
+**If issues found:**
+- Fix Critical issues immediately
+- Fix Important issues before next batch
+- Note Minor issues
+
+**Dispatch follow-up subagent if needed:**
+
+**If issues in 1 task:**
+```
+Task tool (general-purpose):
+  description: "Fix issues from code review in Task N"
+  prompt: |
+    Fix issues from code review for Task N.
+
+    Issues to fix: [list issues]
+
+    Original task: docs/plans/tasks/<feature>-task-NN.md
+
+    Fix the issues, verify tests pass, commit, report back.
+```
+
+**If issues in both tasks:**
+```
+<function_calls>
+  <invoke name="Task">
+    <parameter name="subagent_type">general-purpose</parameter>
+    <parameter name="description">Fix issues in Task N</parameter>
+    <parameter name="prompt">
+Fix issues from code review for Task N.
+
+Issues to fix: [list issues for task N]
+
+Original task: docs/plans/tasks/<plan-name>/<feature>-task-NN.md
+
+Fix the issues, verify tests pass, commit, report back.
+    </parameter>
+  </invoke>
+  <invoke name="Task">
+    <parameter name="subagent_type">general-purpose</parameter>
+    <parameter name="description">Fix issues in Task M</parameter>
+    <parameter name="prompt">
+Fix issues from code review for Task M.
+
+Issues to fix: [list issues for task M]
+
+Original task: docs/plans/tasks/<plan-name>/<feature>-task-MM.md
+
+Fix the issues, verify tests pass, commit, report back.
+    </parameter>
+  </invoke>
+</function_calls>
+```
+
+### 5. Update Manifest and Mark Complete
+
+**Update manifest.json:**
+- Set task status to "done"
+- Add "completed_at" timestamp
+
+**Mark batch complete in TodoWrite**
+- Check off batch execution
+- Check off batch review
+
+Move to next batch, repeat steps 2-5.
+
+### 6. Final Review
+
+After all batches complete, dispatch final code-reviewer:
+```
+Task tool (superpowers:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: [summary of ALL tasks from manifest]
+  PLAN_OR_REQUIREMENTS: Original plan file + all task files
+  BASE_SHA: [initial commit before all work]
+  HEAD_SHA: [current commit after all work]
+  DESCRIPTION: Complete implementation of [feature name]
+```
+
+**Final reviewer:**
+- Reviews entire implementation
+- Checks all plan requirements met
+- Validates overall architecture
+- Checks integration between all tasks
+
+### 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
+
+## Example Workflow
+
+```
+You: I'm using Parallel Subagent-Driven Development to execute this decomposed plan.
+
+[Load manifest, create TodoWrite with batches]
+
+Batch 1 (Tasks 1 & 2 - parallel):
+
+[Dispatch 2 implementation subagents IN SINGLE MESSAGE]
+Subagent 1: Implemented user model with tests, 5/5 passing
+Subagent 2: Implemented logger with tests, 3/3 passing
+
+[Get git SHAs, dispatch code-reviewer]
+Reviewer:
+  Strengths: Both well-tested, clean separation
+  Issues: None
+  Ready.
+
+[Update manifest: tasks 1,2 done]
+[Mark Batch 1 complete]
+
+Batch 2 (Task 3 - sequential):
+
+[Dispatch 1 implementation subagent]
+Subagent: Added user validation, 8/8 tests passing
+
+[Dispatch code-reviewer]
+Reviewer:
+  Strengths: Good validation logic
+  Issues (Important): Missing edge case for empty email
+
+[Dispatch fix subagent]
+Fix subagent: Added empty email check, test added, passing
+
+[Verify fix, update manifest: task 3 done]
+[Mark Batch 2 complete]
+
+Batch 3 (Tasks 4 & 5 - parallel):
+
+[Dispatch 2 implementation subagents IN SINGLE MESSAGE]
+Subagent 1: Implemented API endpoint, 6/6 passing
+Subagent 2: Implemented CLI command, 4/4 passing
+
+[Dispatch code-reviewer]
+Reviewer:
+  Strengths: Both implementations solid
+  Issues: None
+  Ready.
+
+[Update manifest: tasks 4,5 done]
+[Mark Batch 3 complete]
+
+[After all batches]
+[Dispatch final code-reviewer]
+Final reviewer: All requirements met, no integration issues, ready to merge
+
+Done! Using finishing-a-development-branch...
+```
+
+## Advantages
+
+**vs. Original Subagent-Driven Development:**
+- 40% faster for parallelizable tasks (2 tasks in time of 1)
+- 90% less context per subagent (task file vs monolithic plan)
+- Same quality gates (review after each batch)
+- Same fresh context per task
+
+**vs. Manual execution:**
+- Subagents follow TDD naturally
+- Fresh context per task (no confusion)
+- Parallel when safe (faster)
+
+**vs. Executing Plans:**
+- Same session (no handoff)
+- Continuous progress (no waiting)
+- Parallel execution (faster)
+- Review checkpoints automatic
+
+**Cost:**
+- More subagent invocations
+- But catches issues early (cheaper than debugging later)
+- Parallel execution saves wall-clock time
+
+## Red Flags
+
+**Never:**
+- Skip code review between batches
+- Proceed with unfixed Critical issues
+- Skip decomposing-plans (must have manifest.json)
+- Manually execute tasks from monolithic plan
+- Dispatch 3+ parallel subagents (max is 2)
+
+**If subagent fails task:**
+- Dispatch fix subagent with specific instructions
+- Don't try to fix manually (context pollution)
+
+**If both parallel subagents fail:**
+- Fix one at a time with follow-up subagents
+- Or dispatch 2 fix subagents in parallel if issues are independent
+
+## Integration
+
+**Required prerequisite:**
+- **decomposing-plans** - REQUIRED: Creates manifest.json and task files that this skill uses
+
+**Required workflow skills:**
+- **writing-plans** - REQUIRED BEFORE decomposing-plans: Creates the monolithic plan
+- **requesting-code-review** - REQUIRED: Review after each batch (see Step 3)
+- **finishing-a-development-branch** - REQUIRED: Complete development after all batches (see Step 7)
+
+**Subagents must use:**
+- **test-driven-development** - Subagents follow TDD for each task
+
+**Alternative workflow:**
+- **subagent-driven-development** - Use for monolithic plans (no parallelization)
+- **executing-plans** - Use for parallel session instead of same-session execution
+
+See code-reviewer template: requesting-code-review/code-reviewer.md
+
+## Manifest Status Tracking
+
+Update manifest.json after each batch:
+
+```json
+{
+  "tasks": [
+    {
+      "id": 1,
+      "status": "done",
+      "completed_at": "2025-01-18T10:30:00Z"
+    },
+    {
+      "id": 2,
+      "status": "done",
+      "completed_at": "2025-01-18T10:30:00Z"
+    },
+    {
+      "id": 3,
+      "status": "in_progress"
+    }
+  ]
+}
+```
+
+This allows resuming if interrupted and tracking overall progress.