bigpowers 1.0.0

package/SKILL-INDEX.md

@@ -0,0 +1,146 @@
+# Skill Index — Single Source of Truth
+
+**Purpose:** One canonical reference for all bigpowers skills. Referenced by README.md, RELEASE-PLAN.md, and CONVENTIONS.md. Updated per-release.
+
+**Last updated:** 2026-05-20 (v2.1.0 — reconciled orphan/ghost skills; 44 active, 6 planned)
+
+---
+
+## Quick Navigation by BMAD Phase
+
+| Phase | Active | Planned | Skills |
+|---|---|---|---|
+| **Bootstrap** | 1 | — | using-bigpowers |
+| **Orchestrate** | 1 | — | orchestrate-project |
+| **Discover** | 3 | — | survey-context, elaborate-spec, map-codebase |
+| **Elaborate** | 5 | 1 | model-domain, define-language, grill-me, deepen-architecture, design-interface · _(grill-with-docs 📋)_ |
+| **Plan** | 6 | 2 | assess-impact, change-request, define-success, plan-work, plan-refactor, plan-release · _(scope-work 📋, slice-tasks 📋)_ |
+| **Spike** | 1 | — | spike-prototype |
+| **Initiate** | 4 | — | kickoff-branch, guard-git, hook-commits, seed-conventions |
+| **Build** | 5 | — | develop-tdd, enforce-first, delegate-task, dispatch-agents, execute-plan |
+| **Harden** | 1 | — | wire-observability |
+| **Bug** | 2 | 1 | investigate-bug, validate-fix · _(diagnose-root 📋)_ |
+| **Review** | 4 | — | audit-code, request-review, respond-review, trace-requirement |
+| **Integrate** | 2 | — | commit-message, release-branch |
+| **Sustain** | 2 | — | inspect-quality, organize-workspace |
+| **Utility** | 7 | 2 | terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard, write-document · _(setup-environment 📋, reset-baseline 📋)_ |
+| **TOTAL** | **44** | **6** | |
+
+---
+
+## Full Reference Table
+
+| # | Phase | Skill | Intent | Artefact Output | Status | Source |
+|---|---|---|---|---|---|---|
+| 1 | Bootstrap | `using-bigpowers` | Lifecycle intro; where to start | (dialogue) | ✅ Active | original |
+| 2 | Orchestrate | `orchestrate-project` | Meta-skill enforcing 6-phase core loop (Standard / Fast-Track / Ad-Hoc modes) | (orchestration) | ✅ Active | original v2.0.0 |
+| 3 | Discover | `survey-context` | Per-task context map; suggests next skill | (dialogue, update STATE.md) | ✅ Active | mattpocock/skills (zoom-out) |
+| 4 | Discover | `elaborate-spec` | Dialogue to refine rough idea into spec | (dialogue) | ✅ Active | superpowers/brainstorming |
+| 5 | Discover | `map-codebase` | High-fidelity codebase survey; stack, architecture, gray areas | CODEBASE-MAP.md | ✅ Active | original |
+| 6 | Elaborate | `model-domain` | Interactive domain model; updates CONTEXT.md | CONTEXT.md, adr/ | ✅ Active | mattpocock/skills (domain-model) |
+| 7 | Elaborate | `define-language` | Extract ubiquitous language glossary | UBIQUITOUS_LANGUAGE.md | ✅ Active | mattpocock/skills (ubiquitous-language) |
+| 8 | Elaborate | `grill-me` | Stress-test design by grilling assumptions (Design mode + Docs mode) | (dialogue, refine design) | ✅ Active | mattpocock/skills (grill-me) |
+| 9 | Elaborate | `grill-with-docs` | Grill assumptions grounded in real library docs | (dialogue, refine design) | 📋 Planned | mattpocock/skills (grill-with-docs) |
+| 10 | Elaborate | `deepen-architecture` | Surface architecture deepening opportunities (Ousterhout deep modules) | (dialogue, update CONTEXT.md) | ✅ Active | mattpocock/skills (improve-codebase-architecture) |
+| 11 | Elaborate | `design-interface` | Generate multiple radically different interface designs via parallel subagents | INTERFACE-OPTIONS.md | ✅ Active | original |
+| 12 | Plan | `assess-impact` | Analyze blast radius of a proposed change before any code is written | IMPACT.md | ✅ Active | original |
+| 13 | Plan | `change-request` | Add a new requirement or reorder epics by WSJF against RELEASE-PLAN.md | (updated RELEASE-PLAN.md) | ✅ Active | original |
+| 14 | Plan | `scope-work` | Define what's in/out → SCOPE.md | SCOPE.md | 📋 Planned | mattpocock/skills (to-prd, adapted: local-first) |
+| 15 | Plan | `slice-tasks` | Break work into vertical slices → TASKS.md | TASKS.md | 📋 Planned | mattpocock/skills (to-issues, adapted: local-first) |
+| 16 | Plan | `define-success` | Convert imperative task to step → verify pairs | (dialogue, feed to plan-work) | ✅ Active | Karpathy principle |
+| 17 | Plan | `plan-work` | Write detailed plan with verify steps | PLAN.md | ✅ Active | superpowers/writing-plans + Karpathy verify-template |
+| 18 | Plan | `plan-refactor` | Plan a refactor via interview | REFACTOR.md | ✅ Active | mattpocock/skills (request-refactor-plan, adapted) |
+| 19 | Plan | `plan-release` | Convert elaborated specs into a release plan with Gherkin acceptance criteria | RELEASE-PLAN.md | ✅ Active | original |
+| 20 | Spike | `spike-prototype` | Throw-away spike for unknown problem spaces | SPIKE-<name>.md | ✅ Active | mattpocock/skills (prototype) |
+| 21 | Initiate | `kickoff-branch` | Create worktree + branch + verify test baseline | (git state) | ✅ Active | superpowers/using-git-worktrees |
+| 22 | Initiate | `guard-git` | Block dangerous git commands via pre-command hooks | (git state) | ✅ Active | mattpocock/skills (git-guardrails) |
+| 23 | Initiate | `hook-commits` | Install pre-commit: lint, format, typecheck, test | (git state) | ✅ Active | mattpocock/skills (setup-pre-commit) |
+| 24 | Initiate | `seed-conventions` | Generate CLAUDE.md + CONVENTIONS.md + specs/ scaffold | CLAUDE.md, CONVENTIONS.md, specs/ | ✅ Active | Akita "writing CLAUDE.md is a skill" |
+| 25 | Build | `develop-tdd` | Red → green → refactor TDD loop | src/ (code) | ✅ Active | superpowers/tdd + mattpocock/tdd (override) |
+| 26 | Build | `enforce-first` | F.I.R.S.T test-quality rubric (Fast, Independent, Repeatable, Self-Validating, Timely) | (checklist) | ✅ Active | Clean Code Ch.9 + Akita |
+| 27 | Build | `delegate-task` | One subagent, one task, sequential + two-stage review | (code + review) | ✅ Active | superpowers/subagent-driven-development |
+| 28 | Build | `dispatch-agents` | Multiple subagents in parallel on independent tasks | (code + review) | ✅ Active | superpowers/dispatching-parallel-agents |
+| 29 | Build | `execute-plan` | Batch execute plan tasks sequentially with checkpoints | src/ (code per task) | ✅ Active | superpowers/executing-plans |
+| 30 | Harden | `wire-observability` | Add structured JSON logging + idempotent setup + observability commands | CLAUDE.md (commands), src/ (logging) | ✅ Active | Akita "structured logging + idempotent setup" |
+| 31 | Bug | `investigate-bug` | Investigate a bug → DIAGNOSIS.md | DIAGNOSIS.md | ✅ Active | mattpocock/skills (triage-issue, adapted: local-first) |
+| 32 | Bug | `diagnose-root` | 4-phase root cause (reproduce → isolate → hypothesize → verify) | (dialogue, update DIAGNOSIS.md) | 📋 Planned | superpowers/systematic-debugging |
+| 33 | Bug | `validate-fix` | Prove fix works: re-run suite, typecheck, lint | (dialogue, verify) | ✅ Active | superpowers/verification-before-completion |
+| 34 | Review | `audit-code` | Self-review: CONVENTIONS.md compliance, SOLID, no `any`, test coverage | (checklist, pass/fail) | ✅ Active | superpowers/requesting-code-review + Clean Code |
+| 35 | Review | `request-review` | Dispatch fresh reviewer agent (clean context, no shared state) | review-report (structured) | ✅ Active | original |
+| 36 | Review | `respond-review` | Act on reviewer feedback: categorize (must/should), apply, verify | src/ (updated) | ✅ Active | superpowers/receiving-code-review |
+| 37 | Review | `trace-requirement` | Link story IDs from RELEASE-PLAN.md to implementing code and tests | TRACEABILITY.md | ✅ Active | original |
+| 38 | Integrate | `commit-message` | Draft Conventional Commits + semver prediction | (git message) | ✅ Active | mattpocock/skills (prepare-semantic-commit) |
+| 39 | Integrate | `release-branch` | Merge/PR/keep/discard decision + worktree cleanup | (git PR created) | ✅ Active | superpowers/finishing-a-development-branch |
+| 40 | Sustain | `inspect-quality` | Run structured QA session → BUG-LOG.md | BUG-LOG.md | ✅ Active | mattpocock/skills (qa, adapted: local-first) |
+| 41 | Sustain | `organize-workspace` | Classify, show, confirm, then clean workspace | (filesystem state) | ✅ Active | mattpocock/skills (clean-my-room) |
+| 42 | Utility | `terse-mode` | Fallback: ultra-terse output when context critically long | (prompt override) | ✅ Active | mattpocock/skills (caveman); fallback-only |
+| 43 | Utility | `craft-skill` | Build a new bigpowers skill with proper structure | skills/<name>/SKILL.md | ✅ Active | superpowers/writing-skills + mattpocock/write-a-skill |
+| 44 | Utility | `edit-document` | Edit and restructure a document in specs/ | specs/<name>.md | ✅ Active | mattpocock/skills (edit-article) |
+| 45 | Utility | `session-state` | Track implementation decisions and progress in specs/STATE.md | STATE.md | ✅ Active | original |
+| 46 | Utility | `migrate-spec` | Detect GSD/spec-kit/BMAD artifacts and transform to bigpowers specs/ format | specs/ (migrated artifacts) | ✅ Active | original v2.1.0 |
+| 47 | Utility | `visual-dashboard` | Browser-based dashboard: architecture, plans, and UI mockups | (browser view) | ✅ Active | original |
+| 48 | Utility | `write-document` | Write and sync high-integrity technical documents (BMAD methodology) | specs/<name>.md | ✅ Active | original |
+| 49 | Utility | `setup-environment` | Pre-install deps, configure tools before work | (.env, installed packages) | 📋 Planned | autoresearch experiment |
+| 50 | Utility | `reset-baseline` | Restore project to known state between runs | (clean working tree) | 📋 Planned | autoresearch experiment |
+
+**Total: 50 rows — 44 ✅ Active, 6 📋 Planned.**
+
+---
+
+## Lifecycle Arc
+
+```
+[First time]
+using-bigpowers → orchestrate-project (choose Standard / Fast-Track / Ad-Hoc)
+                         ↓
+survey-context → elaborate-spec → map-codebase
+                         ↓
+     model-domain / define-language / grill-me / design-interface / deepen-architecture
+                         ↓
+  assess-impact → change-request → define-success → plan-work / plan-refactor / plan-release
+                         ↓
+    kickoff-branch → guard-git / hook-commits / seed-conventions
+                         ↓
+       [Unknown domain?] spike-prototype → (learnings feed back to plan-work)
+                         ↓
+  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents / execute-plan
+                         ↓
+        wire-observability (production-readiness gate, any phase)
+                         ↓
+    investigate-bug → validate-fix
+                         ↓
+      audit-code → request-review → respond-review → trace-requirement
+                         ↓
+      commit-message → release-branch
+                         ↓
+        inspect-quality → organize-workspace (ongoing)
+
+Transversal utilities (any phase):
+  terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard, write-document
+```
+
+---
+
+## Status Legend
+
+| Icon | Meaning |
+|---|---|
+| ✅ Active | Implemented — SKILL.md exists, skill is usable |
+| 📋 Planned | Designed or referenced, not yet implemented (no directory) |
+| 🔄 Refactoring | Active but under revision |
+| ⚠️ Deprecated | Will be removed in a future release |
+
+## Naming Convention Notes
+
+All skills follow `verb-noun` kebab-case (ADR-0001). Two documented exceptions:
+- `terse-mode` — adjective-noun; retained for clarity (the verb form `enable-terse` is confusing)
+- `visual-dashboard` — adjective-noun; retained for clarity (`view-dashboard` implies read-only)
+
+## How to Update
+
+1. Every new skill: add a row here before the skill is published.
+2. Every rename: update the Skill column; add a note in the Added column.
+3. Every phase change: update the Phase column.
+4. After any change: bump the "Last updated" date and run `bash scripts/sync-skills.sh`.
+
+→ verify: `find . -maxdepth 2 -name "SKILL.md" | grep -v ".git\|.cursor\|.gemini" | wc -l`

package/assess-impact/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: assess-impact
+description: Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks "what does this break?".
+---
+
+# Assess Impact
+
+> **HARD GATE** — Run this skill before `plan-work` whenever a change touches an existing module, symbol, or file used by more than one caller. Skip only for net-new code with no existing dependents.
+
+Find the blast radius of the proposed change before a single line is written.
+
+## Process
+
+### 1. Identify the target
+
+Name the symbol, module, or file being changed. If the user hasn't specified, ask one question: "What exactly are you changing?"
+
+### 2. Find dependents
+
+```
+grep -rn "[symbol-name]" . --include="*.ts" | grep -v node_modules
+git log --oneline -10 -- [file-path]
+```
+
+→ verify: `grep -rn "[target]" . | wc -l`
+
+### 3. Map to release plan stories
+
+Read `specs/RELEASE-PLAN.md` (if it exists). For each dependent found in Step 2, identify which story owns that module. List stories that will be affected by the change.
+
+→ verify: `grep -c "Story" specs/RELEASE-PLAN.md 2>/dev/null || echo "no release plan"`
+
+### 4. List test coverage
+
+Find tests that exercise the target:
+
+```
+grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
+```
+
+→ verify: `grep -rn "[target]" . --include="*.test.*" | wc -l`
+
+### 5. Classify risk
+
+| Level | Condition |
+|-------|-----------|
+| Low   | ≤ 2 callers, all covered by tests |
+| Medium | 3–10 callers, partial test coverage |
+| High  | > 10 callers, or shared API/interface, or no tests |
+
+### 6. Write specs/IMPACT.md
+
+```
+## Target
+[symbol or file being changed]
+
+## Dependents ([count])
+- [file]: [caller or usage]
+
+## Affected Stories
+- Story [X.Y]: [title]
+
+## Test Coverage
+- [test file]: covers [scenario]
+- Gap: [untested behavior]
+
+## Risk: Low / Medium / High
+[One-sentence rationale]
+
+## Recommended action
+[Proceed / Add tests first / Discuss design]
+```
+
+→ verify: `grep "Risk:" specs/IMPACT.md`
+
+Suggest `plan-work` once risk is understood and any test gaps are noted.

package/audit-code/HEURISTICS.md

@@ -0,0 +1,43 @@
+# Clean Code Heuristics (Chapter 17)
+
+A summary of Robert C. Martin's catalogue of code smells and heuristics, used as the technical benchmark for `audit-code`.
+
+## Comments (C)
+- **C1: Inappropriate Information**: Comments should only hold technical notes. Metadata (author, change history) belongs in Git.
+- **C2: Obsolete Comment**: Update or delete comments that are no longer accurate.
+- **C3: Redundant Comment**: Don't describe code that adequately describes itself (e.g., `i++; // increment i`).
+- **C4: Poorly Written Comment**: If you write a comment, spend time making it the best it can be.
+- **C5: Commented-Out Code**: Delete it. Git remembers it.
+
+## Environment (E)
+- **E1: Build Requires More Than One Step**: Building should be a single trivial operation (e.g., `bash install.sh`).
+- **E2: Tests Require More Than One Step**: Running all tests should be one simple command (e.g., `npm test`).
+
+## Functions (F)
+- **F1: Too Many Arguments**: 0 is ideal, 1-2 is fine, 3 requires special justification. Never > 3.
+- **F2: Output Arguments**: Avoid them. If a function changes state, it should change the state of its owning object.
+- **F3: Flag Arguments**: Boolean arguments are a smell that the function does > 1 thing.
+- **F4: Dead Function**: Discard methods that are never called.
+
+## General (G)
+- **G1: Multiple Languages in One Source File**: Try to minimize the mixing of languages (e.g., HTML inside Java).
+- **G5: Duplication (DRY)**: **The root of all evil.** Every time you see duplication, it's a missed opportunity for abstraction.
+- **G6: Code at Wrong Level of Abstraction**: High-level concepts in base classes; low-level details in derivatives.
+- **G25: Replace Magic Numbers with Named Constants**: No "naked" numbers or strings.
+- **G28: Encapsulate Conditionals**: Prefer `if (shouldBePublished())` over complex boolean logic.
+- **G29: Avoid Negative Conditionals**: Prefer `if (buffer.shouldCompact())` over `if (!buffer.shouldNotCompact())`.
+- **G30: Functions Should Do One Thing**: If a function can be split into sections, it's doing too much.
+- **G31: Hidden Temporal Couplings**: If execution order matters, make the dependency explicit via arguments.
+- **G34: Functions Should Descend Only One Level of Abstraction**: The Stepdown Rule.
+
+## Naming (N)
+- **N1: Choose Descriptive Names**: Names should reveal intent and be updated as code evolves.
+- **N4: Unambiguous Names**: Names should make the working of a function/variable clear.
+- **N7: Names Should Describe Side-Effects**: Describe everything the function is or does.
+
+## Tests (T)
+- **T1: Insufficient Tests**: A test suite should test everything that could possibly break.
+- **T4: An Ignored Test Is a Question about an Ambiguity**: Document the reason for `@Ignore`.
+- **T5: Test Boundary Conditions**: Most bugs happen at the boundaries; test them exhaustively.
+- **T8: Test Coverage Patterns Can Be Revealing**: Analyze what code is *not* executed to find gaps.
+- **T9: Tests Should Be Fast**: Slow tests don't get run.

package/audit-code/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: audit-code
+description: Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check.
+---
+
+# Audit Code
+
+Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene.
+
+**Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes.
+
+## Checklist
+
+### CONVENTIONS.md Compliance
+
+- [ ] All output files are in `specs/` (no docs written to project root)
+- [ ] No `gh issue create` calls anywhere in new/modified skills or scripts
+- [ ] `gh` used only for PRs and repo clone operations
+- [ ] No GitHub REST API called directly (no curl/fetch to api.github.com)
+
+### Scope
+
+- [ ] Changes are limited to what was asked — nothing extra refactored or reorganized
+- [ ] No speculative features added
+- [ ] No files touched outside the stated scope
+- [ ] Changes are surgical: only code strictly required for the task; no refactoring, reorganization, or cleanup outside task scope (Boy Scout Rule applied surgically, not broadly)
+
+### Boy Scout Rule
+
+- [ ] Every file I touched is cleaner than when I found it
+- [ ] No dead code left behind
+- [ ] No commented-out code blocks
+
+### Types and Safety
+
+- [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.)
+- [ ] No `@ts-ignore` or `// eslint-disable` added
+- [ ] No `as unknown as X` casts that bypass type safety
+
+### Test Coverage
+
+- [ ] Every new function has at least one test
+- [ ] Every bug fix has a regression test
+- [ ] Tests verify behavior through public interfaces (not implementation details)
+- [ ] Tests are F.I.R.S.T compliant (use `enforce-first` if unsure)
+
+### SOLID and Heuristics
+
+- [ ] Single Responsibility: no function or module doing two unrelated things
+- [ ] Open/Closed: extended through interfaces, not by modifying stable code
+- [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable
+- [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)
+
+### Code Style (CONVENTIONS.md)
+
+- [ ] Functions: 4–20 lines; split if longer
+- [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)
+- [ ] Files: under 300 lines (ideally 200–300)
+- [ ] Names: specific and unique (grep returns < 5 hits for each name)
+- [ ] No duplication — shared logic extracted (DRY / G5)
+- [ ] Early returns over nested ifs; max 2 levels of indentation
+- [ ] Conditionals: expressed as positives (G29)
+- [ ] Comments explain WHY, not WHAT
+
+### Agent Readability (Akita's Lens)
+
+- [ ] Functions are small enough to fit in a standard context window (4–20 lines)
+- [ ] Names are unique and specific enough to be `grep`-able (grep returns < 5 hits)
+- [ ] Types are explicit (no `any`, no inferred return types for public APIs)
+- [ ] Code avoids deep nesting (max 2 levels) and uses early returns
+
+### Red Flags
+
+Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.
+
+## Output
+
+Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.
+
+If all items pass: suggest running `request-review` for an independent second opinion.
+If any items fail: fix them before proceeding.

package/bin/bigpowers.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+console.log('🚀 bigpowers — setting up...\n');
+
+try {
+  const rootDir = path.dirname(path.dirname(__filename));
+  
+  console.log('Syncing skills...');
+  execSync('bash scripts/sync-skills.sh', { 
+    cwd: rootDir,
+    stdio: 'inherit' 
+  });
+  
+  console.log('\nRunning installation...');
+  execSync('bash scripts/install.sh', { 
+    cwd: rootDir,
+    stdio: 'inherit' 
+  });
+  
+  console.log('\n✅ bigpowers setup complete!\n');
+} catch (error) {
+  console.error('\n❌ Setup failed:', error.message);
+  process.exit(1);
+}

package/change-request/REFERENCE.md

@@ -0,0 +1,60 @@
+# WSJF Scoring Reference
+
+Weighted Shortest Job First: **WSJF = (Business Value + Time Criticality + Risk Reduction) / Job Size**
+
+All dimensions scored 1–10 using a Fibonacci-like scale: 1, 2, 3, 5, 8, 10.
+
+## Business Value
+
+| Score | Meaning |
+|-------|---------|
+| 10 | Core revenue path, legal requirement, blocking launch |
+| 8  | Significant user value, major pain point removed |
+| 5  | Notable improvement, medium user segment affected |
+| 3  | Nice-to-have, minor convenience |
+| 1  | Cosmetic or speculative |
+
+## Time Criticality
+
+| Score | Meaning |
+|-------|---------|
+| 10 | Hard deadline (regulatory, contract, launch date) |
+| 8  | Competitive window closing, partner dependency |
+| 5  | Would delay next milestone if deferred |
+| 3  | Flexible, can slip one sprint |
+| 1  | No urgency |
+
+## Risk Reduction (or Opportunity Enablement)
+
+| Score | Meaning |
+|-------|---------|
+| 10 | Eliminates critical architectural risk or enables a new capability |
+| 8  | Reduces a known failure mode or unblocks high-value work |
+| 5  | Moderate risk mitigation or enablement |
+| 3  | Low risk reduction |
+| 1  | No risk relevance |
+
+## Job Size (effort denominator — larger = lower WSJF)
+
+| Score | Meaning |
+|-------|---------|
+| 1  | Hours |
+| 2  | 1 day |
+| 3  | 2–3 days |
+| 5  | 1 week |
+| 8  | 2 weeks |
+| 10 | 1 month+ |
+
+## Cut threshold
+
+Stories with WSJF < 1.5 are cut candidates: high effort, low combined value.
+
+## Example
+
+Story: "Add OAuth login"
+- Business Value: 8 (removes major sign-up friction)
+- Time Criticality: 5 (Q3 launch nice, not hard)
+- Risk Reduction: 3 (minor security improvement)
+- Job Size: 5 (one week)
+
+WSJF = (8 + 5 + 3) / 5 = **3.2** — healthy, implement early.

package/change-request/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: change-request
+description: Add a new requirement or reorder epics by WSJF value engineering against specs/RELEASE-PLAN.md. Two modes: Add (intake a new requirement mid-flight) and Reorder (re-score and re-sort all epics/stories). Use when a new requirement arrives mid-release, or when the plan needs prioritization.
+---
+
+# Change Request
+
+> **HARD GATE** — `specs/RELEASE-PLAN.md` must exist before running either mode. If it doesn't, run `plan-release` first.
+>
+> → verify: `[ -f specs/RELEASE-PLAN.md ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+
+Two modes. State which one you want or the skill will ask.
+
+## Mode A — Add
+
+Intake a new requirement mid-flight without disrupting work in progress.
+
+1. **Capture**: What is the change? What problem does it solve?
+2. **Locate**: Which existing stories does it affect or replace?
+3. **Draft**: Write the new story in RELEASE-PLAN.md format (with Gherkin AC and tasks + verify commands).
+4. **Place**: Append as a new story under an existing epic, or open a new epic if needed.
+5. **Score**: Compute WSJF score for the new story; note if it outranks in-progress work.
+
+→ verify: `grep -c "Story" specs/RELEASE-PLAN.md`
+
+## Mode B — Reorder
+
+Value-engineering pass over the full release plan using WSJF.
+
+See [REFERENCE.md](REFERENCE.md) for the full WSJF scoring rubric.
+
+1. **Score** each epic/story: Business Value (1–10) + Time Criticality (1–10) + Risk Reduction (1–10) / Job Size (1–10).
+2. **Re-sort** epics and stories by WSJF score descending.
+3. **Flag cut candidates**: stories where Effort is L and Value is Low (WSJF < 1.5).
+4. **Update** `specs/RELEASE-PLAN.md` — add WSJF scores, new order, short rationale for any reordering.
+5. **Report** the delta: what moved up, what moved down, what is a cut candidate.
+
+→ verify: `grep -c "WSJF:" specs/RELEASE-PLAN.md`
+
+## After either mode
+
+Suggest `plan-work` for the top-ranked unstarted story.

package/commit-message/REFERENCE.md

@@ -0,0 +1,81 @@
+# Conventional Commits + semantic-style release (reference)
+
+## Message format
+
+From [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/#specification):
+
+```text
+<type>[optional scope][optional !]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- **Scope:** parenthesized noun, e.g. `feat(parser): …`.
+- **Breaking:** `!` before `:` (e.g. `feat(api)!: …`) and/or footer `BREAKING CHANGE: description` (token must be uppercase per spec for that footer name).
+- **Description:** short summary; body explains *why* or migration steps.
+
+Common **types** (not exhaustive): `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore` — as in [Angular / commitlint conventions](https://github.com/conventional-changelog/commitlint).
+
+## Advanced Specification Patterns
+
+### Reverts
+If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body, it should say: `This reverts commit <hash>.`.
+
+```text
+revert: feat(api): add user endpoint
+
+This reverts commit 676104e.
+```
+
+### Breaking Changes
+A breaking change can be signaled by:
+1.  A **`BREAKING CHANGE:`** footer (must be uppercase, at the start of the footer). This is the **most compatible** way to trigger a Major release in `semantic-release` (Angular preset).
+2.  A **`!`** after the type/scope: `feat(api)!: change user response shape`.
+
+**Pro-tip:** For maximum compatibility with all tooling (older and newer), use BOTH the `!` and the `BREAKING CHANGE:` footer.
+
+### Footers (Tokens & Values)
+Footers follow the same `Token: value` pattern as Git Trailers. Common tokens:
+- `Refs: #123`
+- `See-also: docs/ADR-001.md`
+- `Signed-off-by: Name <email>`
+
+**Multi-line footers:** If a footer value spans multiple lines, each subsequent line must be indented.
+
+### Squashing & History
+When using `gh pr merge --squash`, the PR title is usually used as the commit subject. 
+- **PR Title:** MUST follow `<type>(<scope>): <description>`
+- **PR Body:** Content will be moved to the commit body.
+
+## Release Type Mapping (Default Angular Preset)
+
+This table reflects the **out-of-the-box** behavior of `semantic-release` using the `@semantic-release/commit-analyzer` default (Angular) rules.
+
+| Commit pattern | Release | Notes |
+|----------------|---------|-------|
+| `fix:` | **Patch** | Bug fixes |
+| `feat:` | **Minor** | New features |
+| `perf:` | **Patch** | Performance improvements |
+| `any type` + `BREAKING CHANGE:` footer | **Major** | **Mandatory** for Major version bumps in default configs. |
+| `any type!:` (exclamation mark) | **Major** | Supported by modern CC parsers, but use footer for max safety. |
+| `docs:`, `chore:`, `test:`, `ci:`, `refactor:`, `style:` | **None** | Does not trigger a new release by default. |
+
+> **Warning:** While `refactor:` and `style:` improve code, they do NOT trigger a release in the default Angular preset. Use `fix:` if a refactor also fixes a bug, or `feat:` if it adds new behavior.
+
+## Custom Repositories
+
+- Read `release.config.js`, `.releaserc`, or `package.json` → `release` / `semantic-release` config.
+- The **@semantic-release/commit-analyzer** preset may map types differently; prefer **their** rules when they conflict with this reference.
+
+## Squash and PR titles
+
+- If the team squashes on merge, the **PR title** often becomes the single squashed commit subject — it should still follow `type(scope): description` for tooling.
+- `revert:` type and `Refs:` footers are valid patterns; revert handling varies by [tooling](https://www.conventionalcommits.org/en/v1.0.0/#specification).
+
+## Links
+
+- [Conventional Commits — specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
+- [semantic-release — README (commit format & flow)](https://github.com/semantic-release/semantic-release#commit-message-format)
+- Fork pointer: [semantic-release-baby](https://github.com/danielvm-git/semantic-release-baby) (automation and docs align with upstream semantic-release)

package/commit-message/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: commit-message
+description: Reviews working-tree changes, then drafts a Conventional Commits title/body and states the semantic-release version bump a single such commit would imply. Also notes which defensive-code categories were touched. Use when the user wants to commit recent work, prepare a Conventional Commits message, or asks for semantic-release / semver-consistent messaging before git commit.
+---
+
+# Commit Message
+
+## What "last chat" means
+
+- **Primary source of truth:** `git status`, `git diff` (unstaged), and `git diff --cached` (staged). Run these in the repo root (or the paths the user changed).
+- **Context:** use the current conversation to summarize *intent* and to spot **breaking** API/behavior changes that diff alone may not show.
+- If the user tracks a session baseline (e.g. branch, tag, or `git stash create` at start), you may `git diff <baseline>..HEAD` plus uncommitted diffs; otherwise use only the index and working tree.
+
+## Quick workflow
+
+1. **Inventory** — List changed paths; group by feature vs chore vs docs vs test-only.
+2. **Decide commit shape** — One atomic commit is ideal. If the diff mixes unrelated concerns, recommend **multiple commits** (each with its own type/scope) before suggesting one message.
+3. **Classify for semantic release** — `fix` → patch, `feat` → minor, **breaking** → major.
+4. **Write the message** — `type(optional-scope)!: description` (see [REFERENCE.md](REFERENCE.md#message-format)). Use `!` or a `BREAKING CHANGE:` footer when behavior contracts change.
+5. **Note defensive-code categories touched** — from CONVENTIONS.md: Rate limit | Retry with backoff | Circuit breaker | Timeout | Graceful degradation
+6. **Deliver** — Output:
+   - Proposed **full commit message** (title + optional body + footers).
+   - **Release bump** this commit would drive: `patch` | `minor` | `major` | `none`.
+   - Optional `git add …` and `git commit -m` instructions; do **not** run destructive git commands unless the user asked.
+
+## Checklist before finalizing
+
+- [ ] Type matches the **dominant** user-visible outcome (`feat` vs `fix` vs `perf`, etc.).
+- [ ] **Scope** is a short noun in parentheses if it helps (e.g. `fix(api): …`).
+- [ ] Breaking changes are explicit (`!` and/or `BREAKING CHANGE:` in the body/footer).
+- [ ] Description is imperative, lowercase start after the prefix, no trailing period in the title line.
+
+## When not to invent a bump
+
+If the repo uses a custom `@semantic-release/commit-analyzer` preset, note that your bump is **heuristic** and they should match `.releaserc` / `release.config.*`. See [REFERENCE.md](REFERENCE.md#custom-repositories).
+
+## Further reading
+
+- [REFERENCE.md](REFERENCE.md) — Message shape, footers, release mapping, squashing notes.