continuous-improvement 3.0.0 → 3.8.0

package/skills/ralph.md

@@ -0,0 +1,221 @@
+---
+name: ralph
+tier: companion
+description: "Enforces Law 6 (Iterate Means One Thing) of the 7 Laws of AI Agent Discipline at PRD scale. Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. Converts PRDs to executable JSON, implements stories iteratively with quality checks, and tracks progress."
+origin: https://github.com/snarktank/ralph
+---
+
+# Ralph — Autonomous Agent Loop
+
+Ralph runs iteratively until all PRD stories are complete. Each iteration: picks highest priority story, implements, runs quality checks, commits if passing, updates progress, repeats.
+
+## When to Use
+
+- Large features that exceed a single context window
+- Multi-story PRDs that need consistent implementation
+- Tasks requiring repeated verification and commit cycles
+- Long-running development that benefits from persistence across interruptions
+
+## Do NOT Use When
+
+- Task is a one-shot fix completable in a single edit — just edit the file
+- You haven't written a PRD yet — write the PRD first, then run Ralph against it
+- The work spans fewer than 3 stories — single-iteration verification is enough
+- You need to explore or plan before committing to scope — use a planning skill first; Ralph is for execution, not discovery
+- You want manual control over each iteration — run quality checks yourself, no need for Ralph's loop
+
+## Prerequisites
+
+- Git repository
+- PRD document (markdown format)
+- `jq` installed (`brew install jq` on macOS)
+
+## Workflow
+
+### 1. Create a PRD
+
+Generate a detailed requirements document using the PRD skill:
+
+```
+Load the prd skill and create a PRD for [your feature description]
+```
+
+Output saved to `tasks/prd-[feature-name].md`
+
+**CRITICAL — refine generic criteria before iteration begins.** Auto-generated PRD scaffolds often produce generic acceptance criteria like `["Implementation is complete", "Code compiles without errors"]`. These are theater — Ralph cannot prove a story passes against criteria that don't actually constrain it. Replace every generic criterion with a concrete, testable statement before moving to step 2.
+
+- Bad: `"Function is implemented correctly"`
+- Good: `"Function parseUserInput(s) returns {ok: true, value} for valid s and {ok: false, error} for invalid s, asserted by tests/parse-user-input.test.ts"`
+- Bad: `"Code compiles"`
+- Good: `"TypeScript compiles with no errors (npm run build) AND lsp diagnostics show 0 errors on src/parse-user-input.ts"`
+
+If you cannot write a testable criterion, the story is too big. Break it down before continuing.
+
+**Example — refining a scaffold criterion**
+
+Auto-generated:
+
+```json
+"acceptanceCriteria": [
+  "Implementation is complete",
+  "Code compiles without errors"
+]
+```
+
+After refinement:
+
+```json
+"acceptanceCriteria": [
+  "POST /api/users returns 201 with {id, email} for valid input, asserted by tests/api-users.test.ts",
+  "POST /api/users returns 400 with {error} for missing email, asserted by tests/api-users.test.ts",
+  "TypeScript compiles with 0 errors (npm run build)",
+  "lsp diagnostics show 0 errors on src/api/users.ts"
+]
+```
+
+### 2. Convert PRD to Ralph Format
+
+Convert the markdown PRD to executable JSON:
+
+```
+Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
+```
+
+This creates `prd.json` with user stories structured for autonomous execution.
+
+### 3. Run Ralph
+
+Execute the autonomous loop:
+
+```bash
+# Using Amp (default)
+./scripts/ralph/ralph.sh [max_iterations]
+
+# Using Claude Code
+./scripts/ralph/ralph.sh --tool claude [max_iterations]
+```
+
+Default: 10 iterations. Use `--tool amp` or `--tool claude` to select your AI tool.
+
+## Ralph Loop Steps
+
+1. **Create feature branch** — from PRD `branchName`
+2. **Pick highest priority story** — where `passes: false`
+3. **Implement that single story** — fresh context per iteration
+4. **Run quality checks** — verify the current story's specific acceptance criteria with fresh evidence:
+   - For EACH acceptance criterion, run the test/build/lint that proves it
+   - Read the output, do not assume
+   - If ANY criterion is not met, continue working — do NOT mark the story as `passes: true`
+   - **Suite-level "all tests pass" is NOT a substitute for criterion-level proof.**
+
+   **Example — story-by-story verification**
+
+   Bad:
+
+   ```
+   Story US-002: "Add /api/users endpoint"
+   - Ran npm test → all green → marked passes: true
+   ```
+
+   Why bad: suite-level pass doesn't prove THIS story's criteria. Other tests could be passing while the new endpoint is broken.
+
+   Good:
+
+   ```
+   Story US-002: "Add /api/users endpoint"
+   - Criterion 1: POST /api/users → 201 → ran `npx vitest tests/api-users.test.ts -t "valid input"` → PASS
+   - Criterion 2: POST /api/users → 400 → ran `npx vitest tests/api-users.test.ts -t "missing email"` → PASS
+   - Criterion 3: typecheck → ran `npm run build` → 0 errors
+   - All criteria met with fresh evidence → marked passes: true
+   ```
+
+   Why good: each criterion proven with a targeted run; the output was read before the mark.
+
+5. **Commit if checks pass** — atomic commits per story
+6. **Update prd.json** — mark story as `passes: true`
+7. **Append learnings** — to `progress.txt`
+8. **Repeat** — until all stories pass or max iterations reached
+
+## Key Concepts
+
+### Each Iteration = Fresh Context
+
+Every story gets a clean slate. Previous work is visible only via git history and `prd.json`, preventing context pollution.
+
+### Small Tasks
+
+Stories should be completable in 10-30 minutes. If a story stalls, break it down.
+
+### AGENTS.md Updates Are Critical
+
+Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.
+
+### Feedback Loops
+
+- Build/test failures: immediate fix or rollback
+- Test failures: investigate before declaring pass
+- Confusion: log to `progress.txt` for human review
+
+### Browser Verification for UI Stories
+
+Ralph starts a dev server and uses Playwright to verify UI stories actually render.
+
+### Stop Condition
+
+Ralph stops when:
+- All stories have `passes: true`
+- Max iterations reached
+- Critical failure encountered (user intervention required)
+
+## Anti-patterns
+
+These thoughts mean STOP — Ralph is about to slip:
+
+| Thought | Why it's wrong |
+|---|---|
+| "All stories pass, time to summarise and wait for the user" mid-loop | Polite-stop. Ralph continues through commit + progress update + next pick in the same turn. |
+| "Tests pass at the suite level, the story must be done" | Suite-level pass is not criterion-level proof. Verify each criterion with fresh evidence. |
+| "Story is bigger than expected, I'll mark it passes: true and add a TODO" | Scope reduction. Either complete the story or break it down — never declare partial completion. |
+| "The criterion is generic but obviously the test covers it" | PRD theater. Refine the criterion to something specific before proceeding. |
+| "I'll skip the failing test by deleting/skipping it" | Tests are evidence. Fix the implementation, not the test. |
+| "Reviewer said it looks good" — without running fresh checks | "Looks good" is not verification. Run the build, run the tests, read the output. |
+
+## Final Checklist (Hard Gate)
+
+Ralph cannot exit cleanly until ALL of these are true:
+
+- [ ] Every story in `prd.json` has `passes: true` (no incomplete stories)
+- [ ] Acceptance criteria are task-specific (no `"Implementation is complete"` generics)
+- [ ] All requirements from the original task are met (no scope reduction)
+- [ ] Fresh test run output shows all tests pass (read it, don't assume)
+- [ ] Fresh build output shows success (read it, don't assume)
+- [ ] No tests were deleted, skipped, or weakened to make checks green
+- [ ] `progress.txt` records implementation details and learnings per iteration
+- [ ] Working tree is clean (every story committed atomically)
+
+A failing checkbox is a hard halt — do not declare done.
+
+## Files
+
+- `prd.json` — executable PRD with user stories
+- `progress.txt` — accumulated learnings and status
+- `ralph.sh` — the loop script
+- `AGENTS.md` — iteration memory
+
+## Debugging
+
+If Ralph gets stuck:
+
+1. Check `prd.json` for malformed stories
+2. Review `progress.txt` for accumulated errors
+3. Verify tests pass independently: `npm test` or equivalent
+4. Check git status for uncommitted changes
+5. Run single iteration manually to isolate issues
+
+## Customizing the Prompt
+
+Edit the prompt template in `scripts/ralph/prompt.md` (Amp) or `scripts/ralph/CLAUDE.md` (Claude Code) to adjust behavior.
+
+## Archiving
+
+After completion, archive `prd.json` and `progress.txt` to `tasks/archive/[date]/` for future reference.

package/skills/safety-guard.md

@@ -0,0 +1,76 @@
+---
+name: safety-guard
+tier: "2"
+description: Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
+origin: continuous-improvement
+---
+
+# Safety Guard — Prevent Destructive Operations
+
+## When to Use
+
+- When working on production systems
+- When agents are running autonomously (full-auto mode)
+- When you want to restrict edits to a specific directory
+- During sensitive operations (migrations, deploys, data changes)
+
+## How It Works
+
+Three modes of protection:
+
+### Mode 1: Careful Mode
+
+Intercepts destructive commands before execution and warns:
+
+```
+Watched patterns:
+- rm -rf (especially /, ~, or project root)
+- git push --force
+- git reset --hard
+- git checkout . (discard all changes)
+- DROP TABLE / DROP DATABASE
+- docker system prune
+- kubectl delete
+- chmod 777
+- sudo rm
+- npm publish (accidental publishes)
+- Any command with --no-verify
+```
+
+When detected: shows what the command does, asks for confirmation, suggests safer alternative.
+
+### Mode 2: Freeze Mode
+
+Locks file edits to a specific directory tree:
+
+```
+/safety-guard freeze src/components/
+```
+
+Any Write/Edit outside `src/components/` is blocked with an explanation. Useful when you want an agent to focus on one area without touching unrelated code.
+
+### Mode 3: Guard Mode (Careful + Freeze combined)
+
+Both protections active. Maximum safety for autonomous agents.
+
+```
+/safety-guard guard --dir src/api/ --allow-read-all
+```
+
+Agents can read anything but only write to `src/api/`. Destructive commands are blocked everywhere.
+
+### Unlock
+
+```
+/safety-guard off
+```
+
+## Implementation
+
+Uses PreToolUse hooks to intercept Bash, Write, Edit, and MultiEdit tool calls. Checks the command/path against the active rules before allowing execution.
+
+## Integration
+
+- Enable by default for `codex -a never` sessions
+- Pair with observability risk scoring in continuous-improvement v2
+- Logs all blocked actions to `~/.claude/safety-guard.log`

package/skills/strategic-compact.md

@@ -0,0 +1,104 @@
+---
+name: strategic-compact
+tier: "2"
+description: Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline at phase boundaries. Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
+origin: continuous-improvement
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## When to Activate
+
+- Running long sessions that approach context limits (200K+ tokens)
+- Working on multi-phase tasks (research → plan → implement → test)
+- Switching between unrelated tasks within the same session
+- After completing a major milestone and starting new work
+- When responses slow down or become less coherent (context pressure)
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+- Often mid-task, losing important context
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step operations
+
+Strategic compaction at logical boundaries:
+- **After exploration, before execution** — Compact research context, keep implementation plan
+- **After completing a milestone** — Fresh start for next phase
+- **Before major context shifts** — Clear exploration context before different task
+
+## How It Works
+
+The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
+
+1. **Tracks tool calls** — Counts tool invocations in session
+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
+3. **Periodic reminders** — Reminds every 25 calls after threshold
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      }
+    ]
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
+
+## Compaction Decision Guide
+
+Use this table to decide when to compact:
+
+| Phase Transition | Compact? | Why |
+|-----------------|----------|-----|
+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
+
+## What Survives Compaction
+
+Understanding what persists helps you compact with confidence:
+
+| Persists | Lost |
+|----------|------|
+| Agent instructions (from CLAUDE.md / AGENTS.md) | Intermediate reasoning and analysis |
+| TodoWrite task list | File contents you previously read |
+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
+| Git state (commits, branches) | Tool call history and counts |
+| Files on disk | Nuanced user preferences stated verbally |
+
+## Best Practices
+
+1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
+2. **Compact after debugging** — Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** — Preserve context for related changes
+4. **Read the suggestion** — The hook tells you *when*, you decide *if*
+5. **Write before compacting** — Save important context to files or memory before compacting
+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
+- Memory persistence hooks — For state that survives compaction
+- `continuous-learning` skill — Extracts patterns before session ends

package/skills/superpowers.md

@@ -0,0 +1,212 @@
+---
+name: superpowers
+tier: companion
+description: "Law activator for the 7 Laws of AI Agent Discipline. Unified five-source dispatcher — routes tasks to the correct Law-aligned specialist across the CI plugin (tdd-workflow, verification-loop, gateguard, ralph, deploy-receipt) and four registered upstream companions (Obra superpowers, addy agent-skills, ruflo-swarm, oh-my-claudecode, pm-skills) so the right discipline fires automatically instead of the agent skipping a step. Not a peer skill — a dispatcher for the others."
+origin: https://github.com/obra/superpowers
+---
+
+# Superpowers — Mandatory Agent Workflows (Five-Source Dispatcher)
+
+Superpowers enforces a structured development workflow. Skills activate automatically when their trigger conditions are met. This is not optional guidance — it is mandatory workflow.
+
+## Philosophy
+
+AI agents skip steps, guess, and declare "done" without verifying. Superpowers blocks this by making workflow stages explicit and enforced.
+
+## What changed in v3.8.0
+
+The dispatcher now routes across **five registered marketplaces** instead of relying on Obra installed separately. All five are installable from one marketplace entry:
+
+```
+/plugin install superpowers@continuous-improvement       # Obra's 14 workflow skills
+/plugin install agent-skills@continuous-improvement      # Addy's 21 SDLC skills
+/plugin install ruflo-swarm@continuous-improvement       # Agent swarm + Monitor stream
+/plugin install oh-my-claudecode@continuous-improvement  # 39 skills + 19 agents
+/plugin install pm-skills@continuous-improvement         # 41 PM skills + 47 commands
+```
+
+The CI plugin (this dispatcher + `tdd-workflow`, `verification-loop`, `gateguard`, `ralph`, `deploy-receipt`, etc.) installs by default. The five companions are opt-in — install only what you need.
+
+## The Basic Workflow
+
+| Order | Skill | When It Activates |
+|-------|-------|-------------------|
+| 1 | **brainstorming** | Before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. |
+| 2 | **using-git-worktrees** | After design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline. |
+| 3 | **writing-plans** | With approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps. |
+| 4 | **subagent-driven-development** or **executing-plans** | With plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints. |
+| 5 | **test-driven-development** | During implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests. |
+| 6 | **requesting-code-review** | Between tasks. Reviews against plan, reports issues by severity. Critical issues block progress. |
+| 7 | **finishing-a-development-branch** | When tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree. |
+| 8 | **deploy-receipt** | When the deploy branch auto-deploys (Railway / Cloudflare Workers / Vercel / Netlify / Fly.io / etc.). Verifies deployed SHA matches merge SHA and healthcheck returns 200. Until the receipt is COMPLETE the merge is not reported as done. |
+
+The agent checks for relevant skills before any task. These are mandatory workflows, not suggestions.
+
+## Five-Source Routing Table
+
+When a task trigger fires, the dispatcher resolves to the first available skill in the preference chain. Order = preference order. Items prefixed with `ci:` are bundled in this plugin; others are namespaced by their installed plugin name.
+
+| Trigger | Law | Preferred → Fallback chain |
+|---|---|---|
+| Write a failing test before code | 3+4 | `ci:tdd-workflow` → `superpowers:test-driven-development` → `agent-skills:test-driven-development` |
+| Verify before declaring done | 4 | `ci:verification-loop` → `superpowers:verification-before-completion` |
+| Block edit until investigation present | 1 | `ci:gateguard` (no equivalents) |
+| Diagnose root cause across layers | 6 | `superpowers:systematic-debugging` → `agent-skills:debugging-and-error-recovery` |
+| Refine vague request into design | 2 | `superpowers:brainstorming` → `agent-skills:idea-refine` |
+| Decompose plan into atomic tasks | 2 | `superpowers:writing-plans` → `agent-skills:planning-and-task-breakdown` → `ci:planning-with-files` |
+| Execute plan with checkpoints | 3+6 | `superpowers:executing-plans` → `agent-skills:incremental-implementation` |
+| Spawn fresh subagent per task | 3 | `superpowers:subagent-driven-development` → `superpowers:dispatching-parallel-agents` |
+| Fan out N parallel agents on isolated worktrees | 3 | `superpowers:dispatching-parallel-agents` → `ruflo-swarm:swarm-init` |
+| Stream live observation of long agent runs | 4 | `ruflo-swarm:monitor-stream` (only source) |
+| Isolate work on a new branch | 3 | `superpowers:using-git-worktrees` (only source) |
+| Decide merge / PR / discard at branch end | 3+4 | `superpowers:finishing-a-development-branch` → `agent-skills:shipping-and-launch` |
+| Pre-review checklist before requesting review | 4 | `superpowers:requesting-code-review` → `agent-skills:code-review-and-quality` |
+| Respond to reviewer feedback | 4 | `superpowers:receiving-code-review` |
+| Verify deployed SHA matches merge SHA | 4 | `ci:deploy-receipt` (only source) |
+| Audit repo / MCP / env at session start | 1 | `ci:workspace-surface-audit` (only source) |
+| Run autonomous PRD loop | 6 | `ci:ralph` → `oh-my-claudecode:ralph` (heavy overlap; prefer CI) |
+| Audit-then-execute production fix sweep | all | `ci:proceed-with-the-recommendation` (only source) |
+| Spec-first contract before implementation | 2 | `agent-skills:spec-driven-development` (only source) |
+| Source-first reading before writing | 1 | `agent-skills:source-driven-development` (only source) |
+| Curate the right context window | 1 | `agent-skills:context-engineering` → `ci:context-budget` |
+| Simplify code, remove duplication | 6 | `agent-skills:code-simplification` → `simplify` |
+| Security review for auth/input/secrets | 4 | `agent-skills:security-and-hardening` → `security-review` |
+| Browser-level visual regression | 4 | `oh-my-claudecode:visual-verdict` (only source) |
+| Reflect after session, extract patterns | 5+7 | `ci:learn-eval` → `oh-my-claudecode:retrospective` |
+| Long autonomous run with quality gates | 6 | `oh-my-claudecode:ultrawork` → `ci:ralph` |
+| Coordinator role for staged hand-off | 3 | `ruflo-swarm:agents/coordinator` (when ruflo installed) |
+| Draft a PRD before implementation | 2 | `pm-skills:prd` (only source) |
+| Decompose into user stories + acceptance criteria | 2 | `pm-skills:user-stories` + `pm-skills:acceptance-criteria` |
+| Write or grade quarterly OKRs | 2 | `pm-skills:okr-writer` + `pm-skills:okr-grader` |
+| Design hypothesis-driven experiment | 2 | `pm-skills:experiment-design` + `pm-skills:hypothesis` |
+| Discovery framework: persona, JTBD, lean canvas | 1 | `pm-skills:persona` + `pm-skills:jtbd-canvas` + `pm-skills:lean-canvas` |
+| Market sizing / competitive analysis | 1 | `pm-skills:market-sizing` + `pm-skills:competitive-analysis` |
+| Meeting agenda / brief / recap / synthesize | 5 | `pm-skills:meeting-*` family |
+| Launch checklist before product release | 4 | `pm-skills:launch-checklist` (no engineering equivalent) |
+
+When no installed plugin in the chain resolves, the dispatcher falls back to the inline protocols below (Test-Driven Development, Brainstorming, Plan Format, etc.) so the workflow still works on a clean install.
+
+## Stacked-PR Plan Precondition (≥3 files)
+
+Any change touching three or more files — across `skills/`, `src/`, `bin/`, `commands/`, or any combination — must produce a stacked-PR plan as a precondition to the first edit landing. The 28-day usage report shows a clean correlation: sessions that opened with a stacked-PR plan landed at `fully_achieved`; sessions that began as a single big-bang multi-file edit landed at `partially_achieved` (landing-page dark theme, market-data-hub wiring, RAG misrouting). Single-concern PRs are the lever that closes that gap.
+
+The required plan output has four components, in this order:
+
+1. **Per-PR table** — title, scope (files), test strategy, merge order. One row per PR.
+2. **Dependency graph** — which PRs depend on which (or "independent" if none).
+3. **Worktree per PR** — branch name + base commit. Sequential by default; parallel only when items share no state.
+4. **Out-of-scope list** — anything explicitly NOT in the train. Drive-by temptations get logged here, not implemented.
+
+The plan ships as the FIRST commit of the train's first PR (under `docs/plans/YYYY-MM-DD-<slug>.md`) and is cited by every subsequent commit it produces.
+
+### When this rule does NOT fire
+
+The threshold targets multi-concern feature work, not high-volume mechanical changes. The rule does NOT fire on:
+
+- **Markdown-only commits** — README, CHANGELOG, docs/ updates that touch many files but ship one concern.
+- **Lockfile-only commits** — `package-lock.json`, `pnpm-lock.yaml`, `Cargo.lock`, etc. updated in isolation by a dependency bump.
+- **Generated-only commits** — output of `npm run build`, `tsc`, codemod sweeps, or any tool whose input is one source file and whose output is many derived files. The source change is what counts toward the threshold; the regenerated artifacts ride free.
+- **Vendor-snapshot refreshes** — `third-party/<name>/` updated by a documented `bin/refresh-third-party.mjs` driver. The single source of change is the upstream SHA bump.
+- **Skill-mirror sync commits** — `skills/<name>.md` + `plugins/continuous-improvement/skills/<name>/SKILL.md` count as one file pair, not two, since the CONTRIBUTING.md skill mirror rule treats them as the same concern.
+
+If you are unsure whether the rule applies, the fall-through default is to write the plan. A 30-line plan doc is cheap; a stranded big-bang edit is expensive.
+
+## Skill Library
+
+### Testing
+- **test-driven-development** — RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)
+
+### Debugging
+- **systematic-debugging** — 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
+- **verification-before-completion** — Ensure it's actually fixed
+
+### Collaboration
+- **brainstorming** — Socratic design refinement
+- **writing-plans** — Detailed implementation plans
+- **executing-plans** — Batch execution with checkpoints
+- **dispatching-parallel-agents** — Concurrent subagent workflows
+- **requesting-code-review** — Pre-review checklist
+- **receiving-code-review** — Responding to feedback
+- **using-git-worktrees** — Parallel development branches
+- **finishing-a-development-branch** — Merge/PR decision workflow
+- **subagent-driven-development** — Fast iteration with two-stage review (spec compliance, then code quality)
+
+### Deployment Verification
+- **deploy-receipt** — Closes the merge-to-production gap on auto-deploy targets (CI-side companion to `finishing-a-development-branch`)
+
+### Meta
+- **writing-skills** — Create new skills following best practices (includes testing methodology)
+- **using-superpowers** — Introduction to the skills system
+
+## Test-Driven Development (Mandatory)
+
+```
+RED: Write failing test → Watch it fail
+GREEN: Write minimal code → Watch it pass
+REFACTOR: Improve while staying green → Commit
+```
+
+Code written before tests is deleted. No exceptions.
+
+## Brainstorming Protocol
+
+When given a vague request:
+
+1. Ask clarifying questions
+2. Explore 2-3 alternative approaches
+3. Present design in sections
+4. Wait for explicit approval before proceeding
+
+## Plan Format
+
+Every task in a plan must include:
+
+```yaml
+- task: "Specific action"
+  file: "exact/path/to/file.ext"
+  code: "Complete implementation"
+  verify: "How to confirm it works"
+  estimate: "2-5 minutes"
+```
+
+## Code Review Severity
+
+| Level | Action |
+|-------|--------|
+| Critical | Blocks progress. Must fix before continuing. |
+| Warning | Should fix. Note and continue. |
+| Info | Noted for later. No action required. |
+
+## Subagent Development
+
+Two-stage review for every task:
+
+1. **Spec compliance** — Does it match the plan?
+2. **Code quality** — Is it clean, tested, and maintainable?
+
+Both must pass. Fresh subagent per task prevents context pollution.
+
+## Git Worktrees
+
+Each feature gets an isolated workspace:
+
+```bash
+git worktree add -b feature-name ../feature-name
+```
+
+Clean separation, parallel development, easy cleanup.
+
+## Using Superpowers
+
+Superpowers skills activate when their trigger conditions are detected. The dispatcher resolves each trigger through the five-source routing table above:
+
+- "Create a feature" → `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:executing-plans`
+- "Fix this bug" → `superpowers:systematic-debugging` → `superpowers:verification-before-completion`
+- "Review this PR" → `superpowers:requesting-code-review`
+- "Draft a PRD" → `pm-skills:prd` → `pm-skills:user-stories` → `pm-skills:acceptance-criteria`
+- "Write OKRs for next quarter" → `pm-skills:okr-writer` then `pm-skills:okr-grader`
+- "Run this PRD autonomously" → `ci:ralph`
+- "Fan out parallel provider migration" → `superpowers:dispatching-parallel-agents` or `/swarm` (PR D)
+- "Visual regression check the landing page" → `oh-my-claudecode:visual-verdict`
+
+No manual skill selection. The framework detects the trigger, resolves the chain, and enforces.