@nst173/superpowers-ccg 1.3.0

package/skills/developing-with-subagents/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: developing-with-subagents
+description: "Executes plans in the current session by dispatching one worker-owned task at a time with spec review and Opus review. Use when: you want same-session execution without turning the main thread into a long narrative log."
+---
+
+# Subagent-Driven Development
+
+## Overview
+
+Execute one bounded task at a time by routing it to Codex or Gemini, then review the resulting artifact.
+
+## Process
+
+1. Read the plan once.
+2. Extract the current bounded task only.
+3. Route that task to one worker.
+4. Reuse the same worker session for follow-up fixes on that task.
+5. Run spec review.
+6. Run Opus quality review.
+7. Mark the task complete.
+8. Move to the next bounded task.
+
+## Rules
+
+- Keep the controller thread small.
+- Do not accumulate rich summaries for every step.
+- Do not ask workers for draft-only outputs.
+- Ask workers for `diff-or-questions`.
+- `CROSS_VALIDATION` is for unresolved design conflicts, not routine implementation.
+
+## Model Strategy
+
+| Role | Model | Selection Rule |
+| ---- | ----- | -------------- |
+| Backend and systems implementation | Codex MCP (`mcp__codex__codex`) | CODEX routing |
+| Frontend implementation | Gemini MCP (`mcp__gemini__gemini`) | GEMINI routing |
+| Spec Reviewer | Opus | Always Opus |
+| Quality Reviewer | Opus | Always Opus |
+
+## Checkpoints
+
+- CP1 before dispatching the worker
+- CP2 only when the current bounded task stalls
+- CP3 after implementation, before completion
+
+## Integration
+
+- `superpowers:writing-plans`
+- `superpowers:requesting-code-review`
+- `superpowers:finishing-development-branches`
+- `superpowers:coordinating-multi-model-work`

package/skills/developing-with-subagents/code-quality-reviewer-prompt.md

@@ -0,0 +1,30 @@
+# Code Quality Review (Opus)
+
+Use this template when dispatching code review after spec compliance passes.
+
+## Review Selection
+
+**Rule:** `Reviewer = Opus`
+
+| Implementer | Reviewer |
+|-------------|----------|
+| Codex (`mcp__codex__codex`) | Opus subagent |
+| Gemini (`mcp__gemini__gemini`) | Opus subagent |
+
+## Invocation
+
+Dispatch an Opus subagent using `superpowers-ccg:code-reviewer` for every code-changing path.
+
+```text
+1. Log: `[Quality Review] Dispatching Opus reviewer`
+2. Dispatch Opus subagent using `superpowers-ccg:code-reviewer`
+3. Use BASE_SHA/HEAD_SHA and task context
+4. Include diff and original task spec
+```
+
+## Review Loop
+
+- If Opus returns issues: implementer fixes, then re-submit to Opus
+- Standard tasks: max 3 fix-review loops
+- Critical tasks: escalate after repeated review loops
+- If Opus approves: mark task complete

package/skills/developing-with-subagents/implementer-prompt.md

@@ -0,0 +1,41 @@
+# Implementer Prompt Template
+
+Use this template when dispatching a worker for one bounded task.
+
+```text
+Task tool:
+  model: sonnet
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You own one bounded implementation task.
+
+    ## Task
+    [FULL TEXT of the current bounded task only]
+
+    ## Files
+    [explicit file set]
+
+    ## Acceptance
+    [acceptance criteria]
+
+    ## Verify
+    [exact verify command]
+
+    ## Rules
+    - If anything is unclear, stop and ask questions before coding.
+    - Do not redesign the task.
+    - Do not produce a reference prototype.
+    - Return either:
+      1. changed hunks and verification notes
+      2. blocking questions
+
+    ## Report Format
+    ## DIFF
+    [changed hunks only]
+
+    ## VERIFY
+    [what you ran / what remains]
+
+    ## ISSUES
+    [blocking questions or residual risks]
+```

package/skills/developing-with-subagents/spec-reviewer-prompt.md

@@ -0,0 +1,25 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching the spec reviewer.
+
+```text
+Task tool:
+  description: "Review spec compliance for Task N"
+  prompt: |
+    Verify whether the artifact matches the bounded task.
+
+    ## Requested
+    [FULL TEXT of bounded task requirements]
+
+    ## Artifact
+    [diff / files changed / commit SHA]
+
+    ## Rules
+    - Read the code, do not trust any summary.
+    - Check for missing scope, extra scope, or wrong interpretation.
+    - Keep the output concise.
+
+    ## Output
+    - ✅ Spec compliant
+    - ❌ Issues found: [specific missing/extra items with file:line]
+```

package/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: dispatching-parallel-agents
+description: "Dispatches multiple agents concurrently for independent problem domains. Use when: facing 2+ independent tasks, multiple unrelated failures, or parallel investigations needed. Keywords: parallel, concurrent, multiple agents, batch processing"
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 3.1 Model Selection for Parallel Agents
+
+| Task Type | Model |
+|-----------|-------|
+| Code fixes, implementations | `model: sonnet` |
+| Architecture review | Opus (default) |
+| Codebase exploration | `model: haiku` |
+
+```typescript
+// Sonnet for code, Haiku for search, Opus for review
+Task("Fix test failures", model: "sonnet")
+Task("Find deprecated API usages", model: "haiku")
+Task("Review architecture")  // Opus default
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From a real debugging session:
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: executing-plans
+description: "Executes written implementation plans one bounded task at a time with checkpoint and review gates. Use when: executing a plan in a dedicated session without letting the main thread accumulate unnecessary context."
+---
+
+# Executing Plans
+
+## Overview
+
+Load the plan, then execute exactly one active task at a time.
+
+**Core principle:** one bounded task, one worker owner, one artifact, one review.
+
+## Process
+
+### Step 0: Load Persisted Tasks
+
+1. Call `TaskList`.
+2. Load `<plan-path>.tasks.json` if present.
+3. Resume from the first `pending` or `in_progress` task.
+
+### Step 1: Read the Plan Once
+
+1. Read the plan file once.
+2. Validate the next task only.
+3. Do not keep a running narrative for completed tasks in the main thread.
+
+### Step 2: Execute One Task
+
+For the current task only:
+
+1. Mark it `in_progress`.
+2. Extract `verifyCommand`, `acceptanceCriteria`, and file set.
+3. Apply CP1.
+4. Route to one worker.
+5. Reuse that worker `SESSION_ID` only for fixes on the same task.
+6. Apply CP2 only if the task stalls.
+7. Run verification.
+8. Apply CP3 and run Opus review.
+9. Mark the task `completed`.
+10. Persist a tiny handoff summary to `.tasks.json` or project memory:
+    - task id
+    - worker used
+    - files changed
+    - verify command result
+    - open follow-ups
+
+### Step 3: Report Briefly
+
+After each completed task:
+- what changed
+- verification result
+- next task
+
+Do not dump prior task history back into the session.
+
+## Rules
+
+- Default to one active task, not batches of three.
+- Do not ask a worker for a prototype that Claude will later rewrite.
+- Do not re-explain the whole plan to the worker. Send only the current bounded task.
+- Use `CROSS_VALIDATION` only when the current task cannot be narrowed to one owner.
+
+## Completion
+
+After all tasks complete:
+- use `superpowers:finishing-development-branches`

package/skills/finishing-development-branches/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: finishing-development-branches
+description: "Guides completion of development work by presenting structured options for merge, PR, or cleanup. Use when: implementation is complete, all tests pass, ready to integrate work. Keywords: merge, PR, pull request, branch completion, integration"
+---
+
+# Finishing a Development Branch
+
+## Contents
+- [Overview](#overview)
+- [The Process](#the-process)
+- [Option 1: Direct Merge](#option-1-direct-merge)
+- [Option 2: Pull Request](#option-2-pull-request)
+- [Option 3: Cleanup Only](#option-3-cleanup-only)
+- [Related Skills](#related-skills)
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-development-branches skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** - keep options concise.
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Switch to base branch
+git checkout <base-branch>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# If tests pass
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | ✓ | - | - | ✓ |
+| 2. Create PR | - | ✓ | ✓ | - |
+| 3. Keep as-is | - | - | ✓ | - |
+| 4. Discard | - | - | - | ✓ (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" → ambiguous
+- **Fix:** Present exactly 4 structured options
+
+**Automatic worktree cleanup**
+- **Problem:** Remove worktree when might need it (Option 2, 3)
+- **Fix:** Only cleanup for Options 1 and 4
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+
+**Always:**
+- Verify tests before offering options
+- Present exactly 4 options
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+
+## Integration
+
+**Called by:**
+- **developing-with-subagents** (Step 7) - After all tasks complete
+- **executing-plans** (Step 5) - After all batches complete
+
+**Pairs with:**
+- **using-git-worktrees** - Cleans up worktree created by that skill