@nst173/superpowers-ccg 1.3.0

package/skills/shared/task-format-reference.md

@@ -0,0 +1,83 @@
+# Native Task Format Reference
+
+Skills that create native tasks (TaskCreate) MUST follow this format.
+
+## Task Description Template
+
+Every TaskCreate description MUST follow this structure:
+
+### Required Sections
+
+**Goal:** One sentence — what this task produces (not how).
+
+**Files:**
+- Create/Modify/Delete: `exact/path/to/file` (with line ranges for modifications)
+
+**Acceptance Criteria:**
+- [ ] Concrete, testable criterion
+- [ ] Another criterion
+
+**Verify:** `exact command to run` → expected output summary
+
+### Optional Sections (include when relevant)
+
+**Context:** Why this task exists, what depends on it, architectural notes.
+Only needed when the task can't be understood from Goal + Files alone.
+
+**Steps:** Ordered implementation steps (only for multi-step tasks where order matters).
+TDD cycles happen WITHIN steps, not as separate steps.
+
+## Metadata Schema
+
+Embed metadata as a `json:metadata` code fence at the end of the TaskCreate description. The `metadata` parameter on TaskCreate is accepted but **not returned by TaskGet** — embedding in the description is the only reliable way.
+
+| Key | Type | Required | Purpose |
+|-----|------|----------|---------|
+| `files` | string[] | yes | Paths to create/modify/delete |
+| `verifyCommand` | string | yes | Command to verify task completion |
+| `acceptanceCriteria` | string[] | yes | List of testable criteria |
+| `estimatedScope` | "small" \| "medium" \| "large" | no | Relative effort indicator |
+
+### Example
+
+~~~yaml
+TaskCreate:
+  subject: "Task 1: Add authentication middleware"
+  description: |
+    **Goal:** Add JWT verification middleware to all protected API routes.
+
+    **Files:**
+    - Create: `src/middleware/auth.py`
+    - Modify: `src/api/routes.py:45-60`
+
+    **Acceptance Criteria:**
+    - [ ] Requests without valid JWT return 401
+    - [ ] Requests with valid JWT pass through to handler
+    - [ ] Expired tokens return 401 with "token expired" message
+
+    **Verify:** `pytest tests/middleware/test_auth.py -v` → 3 tests pass
+
+    ```json:metadata
+    {"files": ["src/middleware/auth.py", "src/api/routes.py"], "verifyCommand": "pytest tests/middleware/test_auth.py -v", "acceptanceCriteria": ["Requests without valid JWT return 401", "Requests with valid JWT pass through", "Expired tokens return 401"]}
+    ```
+  activeForm: "Implementing authentication middleware"
+~~~
+
+## Task Granularity
+
+### The Right Scope
+
+A task is **a coherent unit of work that produces a testable, committable outcome**.
+
+**Scope test — ask these questions:**
+1. Does this task produce something I can verify independently? (if no → too small)
+2. Does it touch more than one concern? (if yes → too big)
+3. Would it get its own commit? (if no → too small; if commit message needs bullet points → too big)
+
+### TDD Within Tasks (Not Across Tasks)
+
+TDD cycles (write test → verify fail → implement → verify pass) happen WITHIN a single task, not as separate tasks. The task is "Implement X with tests" — the TDD steps are execution detail, not task boundaries.
+
+### Commit Boundary = Task Boundary
+
+Each task should produce exactly one commit. If a task needs multiple commits, split it. If separate tasks share a commit, merge them.

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: using-git-worktrees
+description: "Creates isolated git worktrees with smart directory selection for parallel branch work. Use when: starting feature work needing isolation, before executing implementation plans. Keywords: git worktree, isolated workspace, parallel branches, workspace isolation"
+---
+
+# Using Git Worktrees
+
+## Contents
+- [Overview](#overview)
+- [Directory Selection Process](#directory-selection-process)
+- [Worktree Creation](#worktree-creation)
+- [Safety Verification](#safety-verification)
+- [Next Steps](#next-steps)
+- [Related Skills](#related-skills)
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check CLAUDE.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no CLAUDE.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Per Jesse's rule "Fix broken things immediately":
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.config/superpowers/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/superpowers/worktrees/*)
+    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check CLAUDE.md → Ask user |
+| Directory not ignored | Add to .gitignore + commit |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > CLAUDE.md > ask
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Hardcoding setup commands
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip CLAUDE.md check
+
+**Always:**
+- Follow directory priority: existing > CLAUDE.md > ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- Any skill needing isolated workspace
+
+**Pairs with:**
+- **finishing-development-branches** - REQUIRED for cleanup after work complete
+- **executing-plans** or **developing-with-subagents** - Work happens in this worktree

package/skills/using-superpowers/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: using-superpowers
+description: "Establishes how to find and use skills, requiring Skill tool invocation before any response. Use when: starting conversations, needing skill guidance. Keywords: skills, superpowers, skill discovery, getting started"
+---
+
+> **⚠️ CRITICAL:**
+>
+> If you think there is even a 1% chance that a skill applies to what you're doing, you **must** invoke that skill.
+>
+> **If a skill applies to your task, you have no choice. You must use it.**
+>
+> This is non-negotiable. This is not optional. You cannot rationalize your way out.
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke Skill tool" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create TodoWrite todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
+
+## Claude Model Strategy for Subagents
+
+| Model | Use For |
+|-------|---------|
+| Opus (default) | Review, architecture, complex reasoning |
+| `model: sonnet` | Implementation, coding |
+| `model: haiku` | Exploration, search |
+
+See `developing-with-subagents` for details.
+
+## Multi-Model Capability
+
+If a task would benefit from specialized external models, use `superpowers:coordinating-multi-model-work`. See `skills/shared/multi-model-integration-section.md` for routing, invocation, and fallback rules.

package/skills/verifying-before-completion/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: verifying-before-completion
+description: "Requires running verification commands and confirming output before making success claims. Use when: about to claim work is complete, fixed, or passing, before committing or creating PRs. Keywords: verify, evidence, completion check, test output, proof"
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## Protocol Threshold (Required)
+
+Follow `skills/shared/protocol-threshold.md`. The hook injects CP reminders automatically.
+
+## The Gate Function
+
+**► CP3 (Quality Gate):** Before claiming completion, apply `coordinating-multi-model-work/checkpoints.md`.
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim                 | Requires                        | Not Sufficient                 |
+| --------------------- | ------------------------------- | ------------------------------ |
+| Tests pass            | Test command output: 0 failures | Previous run, "should pass"    |
+| Linter clean          | Linter output: 0 errors         | Partial check, extrapolation   |
+| Build succeeds        | Build command: exit 0           | Linter passing, logs look good |
+| Bug fixed             | Test original symptom: passes   | Code changed, assumed fixed    |
+| Regression test works | Red-green cycle verified        | Test passes once               |
+| Agent completed       | VCS diff shows changes          | Agent reports "success"        |
+| Requirements met      | Line-by-line checklist          | Tests passing                  |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse                                  | Reality                |
+| --------------------------------------- | ---------------------- |
+| "Should work now"                       | RUN the verification   |
+| "I'm confident"                         | Confidence ≠ evidence  |
+| "Just this once"                        | No exceptions          |
+| "Linter passed"                         | Linter ≠ compiler      |
+| "Agent said success"                    | Verify independently   |
+| "I'm tired"                             | Exhaustion ≠ excuse    |
+| "Partial check is enough"               | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter     |
+
+## Key Patterns
+
+**Tests:**
+
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.
+
+## Multi-Model Cross-Verification
+
+See `skills/shared/multi-model-integration-section.md` for routing, invocation, and fallback rules.
+
+**CRITICAL:** Cross-model verification is **additional** to, not a replacement for running actual commands. **Never claim success based solely on model confirmation.**

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: writing-plans
+description: "Creates implementation plans made of bounded worker-owned tasks with explicit file sets, verification commands, and minimal execution context."
+---
+
+# Writing Plans
+
+## Overview
+
+Write plans for execution by external workers, not for a human narrator. Each task should be small enough that one worker can own it end-to-end without restating the whole project.
+
+## Rules
+
+1. Read the codebase and design docs only as much as needed.
+2. Break work into bounded tasks with explicit ownership.
+3. Each task must have:
+   - clear goal
+   - explicit file set
+   - acceptance criteria
+   - exact verify command
+4. Prefer one worker owner per task.
+5. Avoid two-pass tasks where one worker drafts code and Claude re-implements it.
+6. Use `cross-validation` only for architecture or genuine multi-domain conflicts.
+
+## Task Shape
+
+```markdown
+### Task N: [Short outcome]
+
+**Owner:** `codex` | `gemini` | `auto`
+
+**Files:**
+- Modify: `path/to/file`
+- Create: `path/to/file`
+
+**Acceptance Criteria:**
+- [criterion]
+- [criterion]
+
+**Verify:**
+`exact command`
+
+**Steps:**
+1. [small action]
+2. [small action]
+3. [small action]
+```
+
+## Execution Handoff
+
+Plans should be executable one bounded task at a time.
+
+After saving the plan, offer:
+1. Same-session execution with `developing-with-subagents`
+2. Dedicated execution session with `executing-plans`