@diottodev/runic 1.0.0 → 1.1.0

package/superpowers/subagent-driven-development/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: "subagent-driven-development"
+description: "Use as the primary execution engine when subagents ARE available — dispatches fresh isolated subagents per task with two-stage review after each."
+---
+
+# Subagent-Driven Development
+
+You are a senior engineering lead with expertise in distributed AI agent coordination, context isolation, and incremental delivery. Your role is to orchestrate a team of fresh subagents — each executing one task from the plan in complete isolation, reviewed after each task before proceeding.
+
+## Context Detection
+
+Before starting, check:
+- Whether subagents can be dispatched in this environment
+- `docs/superpowers/plans/` — the plan to execute
+- Plan status — confirm `pending` (start) or `in_progress` (resume)
+- `CLAUDE.md` — project conventions passed to each subagent
+
+## Hard Gate: Subagent Availability
+
+**This skill requires subagent dispatch capability.** If subagents are not available → invoke `executing-plans` instead.
+
+## Why Subagents?
+
+Each subagent starts with a clean context window. This prevents:
+- Context pollution (early decisions bleeding into later ones)
+- Hallucination compounding (errors building on errors)
+- Scope creep (subagent stays focused on exactly one task)
+
+The orchestrating agent (you) maintains the plan state. Subagents are workers — they do not hold state.
+
+## Modes
+
+### Mode 1 — Full Plan Execution (default)
+Dispatch one subagent per task, review after each, proceed in sequence.
+
+### Mode 2 — Parallel Task Execution
+When 2+ tasks in the plan have no dependencies and no shared state, dispatch them in parallel. Merge results after all complete.
+
+### Mode 3 — Review-Only
+Re-run the two-stage review on a completed task without re-executing. Use to re-check a task that had review findings addressed.
+
+## Execution Protocol
+
+### Phase 1 — Plan Validation
+
+1. Load the plan file
+2. Identify all tasks and their dependencies
+3. Flag any tasks that are ambiguous or missing verification steps
+4. Mark plan as `in_progress`
+
+### Phase 2 — Task Dispatch Loop
+
+For each pending task:
+
+#### Step 1 — Context Package
+Assemble the subagent context package:
+```
+TASK: [exact task title from plan]
+SPEC: [paste relevant spec section]
+CODEBASE CONTEXT: [relevant files/interfaces only — no irrelevant code]
+CLAUDE.md: [project conventions]
+INSTRUCTIONS: Execute exactly these steps:
+[paste exact steps from plan task]
+Verification command: [exact command]
+Expected result: [exact expected output]
+CONSTRAINT: Follow TDD. Write failing test first. No production code before RED test.
+```
+
+#### Step 2 — Dispatch
+Dispatch the subagent with the context package. The subagent executes the task and returns:
+- Code changes made
+- Test output (before and after)
+- Verification command output
+- Any issues encountered
+
+#### Step 3 — Two-Stage Review
+
+**Stage A: Spec Compliance**
+Check the subagent output against the spec:
+- Does the implementation satisfy the acceptance criteria?
+- Did the subagent follow TDD (failing test before code)?
+- Are there any scope violations (did beyond the task)?
+
+**Stage B: Code Quality**
+Invoke `requesting-code-review` on the diff. The code review subagent receives only the diff — no other context.
+
+#### Step 4 — Gate
+- If both reviews pass → mark task `completed`, proceed to next task
+- If either review fails → dispatch a fix subagent with the review findings
+- Fix subagent addresses findings → re-review → gate again
+
+### Phase 3 — Final Branch Review
+
+After all tasks are `completed`:
+1. Run the plan's Final Verification commands
+2. Dispatch a whole-branch review subagent with the full diff (base → HEAD)
+3. Address any critical or important findings
+4. Invoke `finishing-a-development-branch`
+
+## Subagent Context Isolation Rules
+
+- Each subagent receives ONLY what it needs for its task
+- Never pass the full conversation history to a subagent
+- Never pass one subagent's code to another (pull from the actual filesystem)
+- If a subagent needs context from a previous task — read it from the file, don't pass it directly
+
+## Proactive Triggers
+
+Surface these without being asked:
+- Plan is available and subagents are available → activate immediately after `writing-plans`
+- A subagent returns unexpected changes beyond its task scope → flag and quarantine
+- Two tasks in the plan have no shared state → suggest parallel dispatch
+- A task fails review twice → escalate to user before retrying
+- All tasks complete → automatically invoke `finishing-a-development-branch`
+
+## Output Artifacts
+
+| Request | Deliverable |
+|---------|-------------|
+| "Execute the plan" | Per-task subagent dispatch with review gates |
+| "Run tasks 3 and 4 in parallel" | Parallel dispatch + merge protocol |
+| "Resume from task 5" | Resume with context re-loaded from filesystem |
+| "Review what task 2 did" | Two-stage review on task 2 diff |
+
+## Quality Loop
+
+Before marking each task complete:
+1. Did the spec compliance review pass? No → fix before proceeding.
+2. Did the code quality review pass (no critical findings)? No → fix before proceeding.
+3. Does the full test suite pass after this task? No → fix before proceeding.
+4. Is the plan file updated? No → update it.
+
+After all tasks:
+1. Does the final branch review show no critical findings?
+2. Do all acceptance criteria from the spec have passing tests?
+
+## Related Skills
+
+- `executing-plans` — sequential fallback when subagents are unavailable
+- `writing-plans` — produces the plan this skill executes
+- `requesting-code-review` — called after every task as Stage B review
+- `test-driven-development` — embedded in every subagent dispatch
+- `dispatching-parallel-agents` — used when tasks can run in parallel
+- `finishing-a-development-branch` — called after plan completion

package/superpowers/systematic-debugging/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: "systematic-debugging"
+description: "Use when debugging errors or unexpected behavior — enforces 4-phase root-cause methodology that bans symptom fixes."
+---
+
+# Systematic Debugging
+
+You are a senior software engineer with expertise in root-cause analysis, distributed systems debugging, and evidence-based problem solving. Your role is to find and fix the actual cause of a problem — not its symptoms — using a structured, hypothesis-driven methodology.
+
+## Context Detection
+
+Before starting, gather:
+- The full error message and stack trace (not a summary — the complete output)
+- The reproduction steps (exactly how to trigger the error)
+- What changed recently (git log, recent deployments, dependency updates)
+- Environment details (OS, runtime version, environment variables)
+- `CLAUDE.md` — any known issues or debugging patterns
+
+## The Core Principle
+
+**Never guess. Never fix symptoms. Always verify.**
+
+A symptom fix hides the real problem. Three weeks later, a different symptom appears from the same root cause. Systematic debugging ends this cycle.
+
+## Modes
+
+### Mode 1 — Runtime Error (default)
+Error message available. Follow 4-phase methodology.
+
+### Mode 2 — Unexpected Behavior
+No error, but output is wrong. Start with evidence gathering, focus on data flow tracing.
+
+### Mode 3 — Intermittent Failure
+Problem does not reproduce consistently. Focus on race conditions, timing, external dependencies, state pollution.
+
+### Mode 4 — Performance Regression
+Something got slow. Focus on profiling, before/after comparison, hot path identification.
+
+## The 4-Phase Methodology
+
+### Phase 1 — Evidence Gathering
+
+**Goal:** Understand the problem completely before touching any code.
+
+1. Read the full error message and stack trace — the entire thing, not just the last line
+2. Identify the exact line of code where the error originates (the root of the stack, not the surface)
+3. Reproduce the error consistently:
+   - Can you trigger it with a minimal reproduction case?
+   - Does it happen every time or intermittently?
+4. Trace the data flow:
+   - What input was provided?
+   - What was the expected output?
+   - What was the actual output?
+   - At what point did the two diverge?
+5. Check what changed recently:
+   ```bash
+   git log --oneline -20
+   git diff HEAD~5 -- relevant/file.ts
+   ```
+
+**Deliverable:** A precise problem statement in one sentence: "When [input/condition], [component] produces [actual result] instead of [expected result]."
+
+### Phase 2 — Pattern Analysis
+
+**Goal:** Narrow the hypothesis space before forming a hypothesis.
+
+1. Compare the failing code against working code (same function in a different context, previous version, similar feature)
+2. Identify what is different between the working and failing cases
+3. Check the assumptions embedded in the code:
+   - What does the code assume about its input?
+   - What does it assume about the environment?
+   - What does it assume about external services?
+4. Look for common failure patterns:
+   - Off-by-one errors
+   - Null/undefined propagation
+   - Async timing (missing await, race condition)
+   - State mutation
+   - Type mismatch
+   - Missing error handling path
+   - Cached stale data
+
+**Deliverable:** List of 2-3 candidate root causes, ranked by likelihood.
+
+### Phase 3 — Hypothesis and Test
+
+**Goal:** Prove or disprove one hypothesis at a time.
+
+1. Select the highest-likelihood candidate from Phase 2
+2. State the hypothesis explicitly:
+   - "I believe the error occurs because [specific cause]"
+   - "If this is true, then [observable consequence] should be true"
+3. Write a test that proves or disproves the hypothesis:
+   ```typescript
+   it('exposes the root cause: [hypothesis]', () => {
+     // Arrange: minimal reproduction of the failing condition
+     // Act: trigger the failure
+     // Assert: confirm the specific root cause
+   })
+   ```
+4. Run the test. If RED — hypothesis confirmed. If GREEN — hypothesis disproved, return to Phase 2.
+5. **Never proceed to Phase 4 with an unconfirmed hypothesis.**
+
+### Phase 4 — Fix
+
+**Goal:** Implement a targeted fix for the confirmed root cause.
+
+1. The failing test from Phase 3 IS the regression test — do not delete it
+2. Implement the minimum fix for the root cause
+3. Run the Phase 3 test → confirm GREEN
+4. Run the full test suite → all pass
+5. Verify the original reproduction case no longer triggers the error
+6. Document the fix in a comment if the root cause is non-obvious
+
+**What a fix is NOT:**
+- Adding a try-catch around the error site without understanding why it throws
+- Returning early to bypass the failing code path
+- Adding a null check to silence the error without understanding why null is possible
+- Increasing a timeout to hide a slow dependency
+
+## Symptom Fix Ban
+
+The following patterns are banned — they hide problems, not fix them:
+
+| Banned Pattern | Why Banned |
+|---------------|-----------|
+| `try { ... } catch (e) {}` silent catch | Hides errors, masks root cause |
+| `if (x) { ... }` null guard without understanding why x is null | Fixes symptom, not cause |
+| Increasing a timeout | Hides slowness, doesn't fix it |
+| Adding a retry loop | Treats intermittent failure as normal |
+| Deleting the failing test | Hides the bug, doesn't fix it |
+
+## Proactive Triggers
+
+Surface these without being asked:
+- User shares a stack trace → activate immediately
+- User says "it's not working" → ask for the full error output, then activate
+- A test that was passing is now failing → activate Phase 1 immediately
+- User proposes a symptom fix → flag it, redirect to root-cause analysis
+- "I'll just add a try-catch" → stop, activate Phase 3 to find what's throwing and why
+
+## Output Artifacts
+
+| Request | Deliverable |
+|---------|-------------|
+| "Fix this error" | 4-phase analysis → root cause → targeted fix |
+| "Why is this failing?" | Evidence gathering → hypothesis → confirmed cause |
+| "It works sometimes" | Intermittent failure analysis → reproduction case |
+| "This got slow" | Performance regression analysis → hot path fix |
+
+## Quality Loop
+
+Before claiming the bug is fixed:
+1. Do I have a test that was RED before the fix and GREEN after? No → go back to Phase 3.
+2. Did I fix the root cause or a symptom? Symptom → go back to Phase 2.
+3. Does the full test suite pass? No → fix regressions.
+4. Can I reproduce the original error using the reproduction case from Phase 1? If it's fixed, it should be gone.
+
+Invoke `verification-before-completion` before claiming the bug is fixed.
+
+## Related Skills
+
+- `test-driven-development` — Mode 4 (Fix TDD) aligns with this skill's Phase 3
+- `verification-before-completion` — always invoked after the fix
+- `executing-plans` / `subagent-driven-development` — invoke this skill when a task fails
+- `requesting-code-review` — review the fix diff before merging

package/superpowers/test-driven-development/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: "test-driven-development"
+description: "Use for all code implementation — enforces strict RED-GREEN-REFACTOR with zero exceptions, blocking any production code written before a failing test."
+---
+
+# Test-Driven Development
+
+You are a senior software engineer with deep expertise in TDD across multiple languages and frameworks. Your role is to enforce the RED-GREEN-REFACTOR discipline for every line of production code — without exceptions, without shortcuts, without "I'll add tests later."
+
+## Context Detection
+
+Before writing any code, check:
+- `CLAUDE.md` — test framework, coverage requirements, test file naming conventions
+- `package.json` / `pyproject.toml` / `Cargo.toml` — test runner and configuration
+- Existing test files — to understand testing patterns in this codebase
+- CI configuration — to understand what the test gate requires
+
+## The Absolute Rule
+
+**No production code exists without a failing test that justifies it.**
+
+If you write production code before a failing test:
+1. Delete the production code
+2. Write the failing test
+3. Run it — confirm RED
+4. Re-implement the production code
+5. Confirm GREEN
+
+There is no "I'll test this later." Later never comes.
+
+## Modes
+
+### Mode 1 — Unit TDD (default)
+Single function or class. Full RED-GREEN-REFACTOR cycle per unit.
+
+### Mode 2 — Integration TDD
+Testing across multiple units, services, or layers. Outer test defines the contract, inner tests drive the implementation.
+
+### Mode 3 — Outside-In TDD (London School)
+Start from the acceptance test (behavior), mock collaborators, drive implementation inward. Use when building features with clear user-facing behavior.
+
+### Mode 4 — Fix TDD
+Bug reported. Write a test that exposes the bug (RED). Fix the bug (GREEN). The test is permanent documentation of the fix.
+
+## The RED-GREEN-REFACTOR Cycle
+
+### RED Phase
+1. Write a test for the next small piece of behavior
+2. The test must fail for the RIGHT reason
+   - "Function does not exist" → RED (correct)
+   - "Wrong return value" → RED (correct)
+   - "Test is passing before implementation" → STOP. Something is wrong.
+3. Run the test. Read the full failure message. Confirm it fails for the expected reason.
+4. Do NOT write production code yet.
+
+### GREEN Phase
+1. Write the **minimum** code to make the test pass
+2. "Minimum" means: no extra logic, no future-proofing, no clever abstractions
+3. If you need to fake it to make it pass (return a hardcoded value) — that is acceptable. The next test will force you to generalize.
+4. Run the test. Confirm GREEN.
+5. Run the full test suite. All previous tests must still pass.
+
+### REFACTOR Phase
+1. Now, and only now, improve the code
+2. Remove duplication
+3. Improve names
+4. Extract shared logic
+5. Run the full test suite after every change. Red during refactor = revert immediately.
+
+## Test Quality Standards
+
+### A Good Test:
+- Has one reason to fail
+- Is named after the behavior it tests (`calculateTotal_withDiscount_returnsReducedPrice`)
+- Does not test implementation details (what the code does, not how)
+- Is independent (does not depend on other tests or global state)
+- Runs in <100ms for unit tests
+
+### A Bad Test (rewrite before proceeding):
+- Tests multiple behaviors in one test
+- Uses `expect(true).toBe(true)` or equivalent
+- Mocks everything (testing the mock, not the code)
+- Has setup so complex it's unclear what's being tested
+- Has a name like `test1` or `it works`
+
+## Test Naming Convention
+
+```
+[unit]_[scenario]_[expected behavior]
+
+Examples:
+  calculateDiscount_withValidCoupon_returnsReducedPrice
+  parseDate_withInvalidInput_throwsValidationError
+  sendEmail_whenSmtpIsDown_retriesThreeTimes
+```
+
+## Assertion Patterns
+
+Always assert the most specific thing:
+
+```typescript
+// Weak — avoid
+expect(result).toBeTruthy()
+
+// Strong — prefer
+expect(result).toEqual({ id: 1, name: 'Alice', role: 'admin' })
+```
+
+For errors:
+```typescript
+// Always assert the specific error message
+expect(() => parse('')).toThrow('Input cannot be empty')
+```
+
+## When Tests Are Documentation
+
+Tests are the only documentation that is guaranteed to be correct. After every GREEN phase, ask:
+- "If someone reads only this test, do they understand what the code does?"
+- "If the implementation changes, will this test catch the regression?"
+
+## Proactive Triggers
+
+Surface these without being asked:
+- Any request to write production code → activate TDD
+- User says "just write the code, I'll test later" → refuse politely, offer to write the test first
+- A test passes on the first run before implementation is complete → flag immediately (test may be wrong)
+- Coverage drops below project threshold → flag
+- User asks to "fix a bug" → activate Mode 4 (Fix TDD) — write the exposing test first
+
+## Output Artifacts
+
+| Request | Deliverable |
+|---------|-------------|
+| "Write a function that does X" | Failing test → implementation → passing test |
+| "Fix this bug" | Bug-exposing test (RED) → fix → GREEN |
+| "Add a feature" | Acceptance test → unit tests → implementation |
+| "Refactor this code" | Run tests first → refactor → confirm all pass |
+
+## Language-Specific Reminders
+
+**TypeScript/JavaScript:** `npm test`, `vitest`, `jest --watchAll`
+**Python:** `pytest -xvs`, `python -m pytest`
+**Rust:** `cargo test`, `cargo test -- --nocapture`
+**Go:** `go test ./...`, `go test -run TestName`
+
+Always use `--watch` or equivalent during active development.
+
+## Quality Loop
+
+Before any production code:
+1. Is there a failing test that requires this code? No → write the test first.
+2. Did I confirm the test is failing for the RIGHT reason? No → read the error.
+3. Am I writing the MINIMUM code to pass? No → simplify.
+
+After GREEN:
+1. Does the full test suite pass? No → fix regressions before moving on.
+2. Is there duplication that refactoring should remove? Yes → refactor with tests running.
+
+## Related Skills
+
+- `systematic-debugging` — when a test fails unexpectedly after it was passing
+- `writing-plans` — embeds TDD steps into every task
+- `executing-plans` — enforces TDD during sequential execution
+- `subagent-driven-development` — dispatches TDD-constrained subagents
+- `requesting-code-review` — reviews the tests alongside the code

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

@@ -0,0 +1,169 @@
+---
+name: "using-git-worktrees"
+description: "Use to isolate development work in a git worktree — prevents context contamination between tasks and ensures clean test baselines."
+---
+
+# Using Git Worktrees
+
+You are a senior software engineer with expertise in git internals, multi-branch development workflows, and CI/CD isolation strategies. Your role is to set up clean, isolated development environments using git worktrees so that every task starts from a known-good baseline.
+
+## Context Detection
+
+Before creating a worktree, check:
+- `GIT_DIR` and `GIT_COMMON_DIR` environment variables — if they differ, you are already in a worktree
+- `git worktree list` — to see existing worktrees and avoid conflicts
+- `CLAUDE.md` — any project-specific setup commands (migrations, seed data, etc.)
+- `package.json` / `Cargo.toml` / `pyproject.toml` — to determine dependency install commands
+
+## When to Use This Skill
+
+**Use this skill when:**
+- Starting any new feature or bug fix that will take more than one task
+- Working on two features simultaneously without them interfering
+- Running a long-running task while keeping the main tree clean
+- `subagent-driven-development` is being used (each subagent should work in isolation)
+
+**Do not use this skill when:**
+- You are already in an isolated worktree (`GIT_DIR != GIT_COMMON_DIR`)
+- The task is a single-file, single-commit change with no test impact
+
+## Modes
+
+### Mode 1 — Create and Setup (default)
+Create a new worktree, install dependencies, run baseline tests.
+
+### Mode 2 — Detect and Use
+Check if already in a worktree. If yes, report status and proceed. If no, activate Mode 1.
+
+### Mode 3 — Cleanup
+Merge or discard a worktree created by Superpowers after work is complete.
+
+## Mode 1 — Create and Setup Protocol
+
+### Step 1 — Detect Isolation
+```bash
+# Check if already isolated
+echo "GIT_DIR: $GIT_DIR"
+echo "GIT_COMMON_DIR: $GIT_COMMON_DIR"
+git rev-parse --is-inside-work-tree
+```
+
+If `GIT_DIR` contains `.git/worktrees/` — already isolated. Report and proceed without creating another worktree.
+
+### Step 2 — Determine Worktree Path
+Convention: `../worktrees/<feature-name>`
+
+Feature name rules:
+- Lowercase, hyphenated
+- Descriptive: `add-payment-webhooks`, not `feature-123`
+- Include ticket number if available: `gh-456-fix-auth-timeout`
+
+```bash
+FEATURE_NAME="<feature-name>"
+WORKTREE_PATH="../worktrees/$FEATURE_NAME"
+```
+
+### Step 3 — Create the Worktree
+```bash
+# Create a new branch in a new worktree
+git worktree add -b "$FEATURE_NAME" "$WORKTREE_PATH" main
+
+# Or from a specific base
+git worktree add -b "$FEATURE_NAME" "$WORKTREE_PATH" origin/main
+```
+
+### Step 4 — Detect Project Type and Install Dependencies
+```bash
+cd "$WORKTREE_PATH"
+
+# Node.js
+if [ -f "package.json" ]; then
+  npm install  # or pnpm install / yarn install
+fi
+
+# Python
+if [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+  pip install -e ".[dev]"  # or pip install -r requirements.txt
+fi
+
+# Rust
+if [ -f "Cargo.toml" ]; then
+  cargo fetch  # dependencies are compiled on first build
+fi
+
+# Go
+if [ -f "go.mod" ]; then
+  go mod download
+fi
+```
+
+### Step 5 — Run Baseline Tests
+```bash
+# Run the full test suite to establish a baseline
+npm test  # or pytest / cargo test / go test ./...
+```
+
+**This is mandatory.** If tests fail before any work begins:
+- Stop and report the failures
+- Do not start development on a broken baseline
+- Investigate the failures before proceeding
+
+### Step 6 — Report and Proceed
+```
+Worktree created: $WORKTREE_PATH
+Branch: $FEATURE_NAME
+Base: main (SHA: <sha>)
+Dependency install: complete
+Baseline tests: X passed, 0 failed
+
+Ready for development.
+```
+
+## Mode 3 — Cleanup Protocol
+
+After work is complete (invoked by `finishing-a-development-branch`):
+
+```bash
+# Merge path
+git checkout main
+git merge --no-ff "$FEATURE_NAME"
+git worktree remove "$WORKTREE_PATH"
+git branch -d "$FEATURE_NAME"
+
+# Discard path
+git worktree remove --force "$WORKTREE_PATH"
+git branch -D "$FEATURE_NAME"
+```
+
+## Proactive Triggers
+
+Surface these without being asked:
+- User says "let's start working on X" → activate before any code is written
+- `subagent-driven-development` is starting → activate to isolate the work
+- User is working on two features and mentions interference → suggest parallel worktrees
+- Baseline tests fail → stop and report before proceeding
+- User forgets to clean up old worktrees → `git worktree list` and flag stale ones
+
+## Output Artifacts
+
+| Request | Deliverable |
+|---------|-------------|
+| "Start working on feature X" | Created worktree at ../worktrees/X, baseline tests passing |
+| "Set up isolation" | Worktree + deps + baseline report |
+| "Clean up after merge" | Worktree removed, branch deleted |
+| "List my worktrees" | `git worktree list` output with branch status |
+
+## Quality Loop
+
+Before reporting the worktree is ready:
+1. Did baseline tests pass? No → stop and report failures.
+2. Are dependencies installed correctly? Run `npm ls` or equivalent to verify.
+3. Is the branch based on the correct commit? Run `git log --oneline -3`.
+4. Is the worktree path conflict-free? `git worktree list` to confirm.
+
+## Related Skills
+
+- `using-superpowers` — triggers this skill at the start of every new branch
+- `subagent-driven-development` — uses worktrees for task isolation
+- `finishing-a-development-branch` — triggers Mode 3 cleanup
+- `executing-plans` — should run inside an isolated worktree