bigpowers 2.1.3 → 2.3.0

package/.pi/skills/plan-release/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: plan-release
+description: ""RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics.""
+---
+
+
+# Plan Release
+
+> **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.
+
+> **HARD GATE** — `specs/product/SCOPE_LATEST.yaml` (or legacy `specs/product/SCOPE_LATEST.yaml`) must exist. If missing, run `scope-work` first.
+
+Synthesize the conversation context into `specs/release-plan.yaml` (index) and shard detail under `specs/epics/`. No new interview — only clarify if something is genuinely ambiguous.
+
+## Outputs
+
+| File | Content |
+|------|---------|
+| `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** |
+| `specs/epics/eNN-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
+| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
+| `specs/epics/eNN-<slug>/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task |
+| `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) |
+
+## Epic Capsule Structure
+
+All epics use capsule directories (no flat/folder distinction):
+
+```
+specs/epics/e01-auth-system/
+├── epic.yaml              # Epic manifest
+├── adr/                   # Epic-local ADRs (created lazily)
+├── e01s01-login.md        # Story spec (countable-story-format)
+├── e01s01-tasks.yaml      # Decoupled task checklist
+├── e01s02-jwt.md          # Story spec
+└── e01s02-tasks.yaml      # Decoupled task checklist
+```
+
+**Rationale:** Capsule dirs achieve change isolation (C9), enable archive pruning (C2/C6), and enforce SRP by decoupling spec `.md` from execution `-tasks.yaml` (C1). See `sdd-adequacy-ranking.md` for the full 10-criteria scoring.
+
+## Process
+
+### 1. Draft epics and stories
+
+From the conversation context, define:
+- **Epics** — `e01`, `e02`, … (stable IDs; WSJF order in `release-plan.yaml` only)
+- **Stories** — `e01s01`, `e01s02`, … with Gherkin acceptance criteria
+
+WSJF-sort epics: score = (Business Value + Time Criticality + Risk Reduction) / Job Size. Highest score first.
+
+### 2. Write acceptance criteria (Gherkin)
+
+For each story, write at least one happy-path and one edge-case scenario (countable format §17 if maturity ≥ 3).
+
+### 3. Write tasks with verify commands
+
+Every task must have a `verify:` command. No verify command = not a task.
+
+### 4. Save specs/release-plan.yaml
+
+```yaml
+release:
+  version: "3.0.0"
+  codename: "Feature Name"
+  status: planning          # planning | in_progress | released
+  semantic_release: true
+  bump_hint: minor          # patch | minor | major — CI decides at merge
+epics:
+  - id: e01
+    title: Auth System
+    wsjf: 4.5
+    capsule_dir: epics/e01-auth-system
+  - id: e02
+    title: User Profile
+    wsjf: 3.8
+    capsule_dir: epics/e02-user-profile
+```
+
+### 5. Save epic manifest (`epic.yaml`)
+
+Each epic capsule directory contains an `epic.yaml` manifest:
+
+```yaml
+id: e01
+title: Auth System
+wsjf: 4.5
+total_bcps: 8
+status: in_progress
+stories:
+  - id: e01s01
+    title: Login
+    bcps: 3
+    status: todo
+    spec: e01s01-login.md
+    tasks: e01s01-tasks.yaml
+  - id: e01s02
+    title: JWT Token Management
+    bcps: 5
+    status: todo
+    spec: e01s02-jwt.md
+    tasks: e01s02-tasks.yaml
+```
+
+### 6. Save story specs (countable-story-format .md)
+
+Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
+
+### 7. Save decoupled task files (`-tasks.yaml`)
+
+Each story has a decoupled `-tasks.yaml` with implementation steps:
+
+```yaml
+story_id: e01s01
+title: Login
+status: todo
+bcps: 3
+tasks:
+  - id: 1
+    description: "Add login form component tests"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+  - id: 2
+    description: "Implement login form with validation"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+```
+
+> **HARD GATE** — Every task MUST have a runnable `verify:` command. No `verify:` = not a task.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+
+### 8. Sync execution status
+
+```bash
+bash scripts/sync-status-from-epics.sh
+```
+
+### 9. Snapshot on planning close (optional)
+
+Copy to `specs/product/snapshots/release-<version>/` when the user approves the plan.
+
+### 10. Suggest next steps
+
+- Run `assess-impact` before `plan-work` for any story touching existing modules.
+- Run `plan-work` per story for detailed steps inside the epic shard.
+- Run `change-request` if a new requirement arrives mid-flight.

package/.pi/skills/plan-work/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: plan-work
+description: ""PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2).""
+---
+
+
+# Plan Work
+
+> **Spine position:** Step 3 — scope-work → slice-tasks → plan-work.
+
+Produce a detailed, verifiable implementation plan in the **active epic capsule directory** (`specs/epics/eNN-slug/`). Output: a story spec `.md` file (countable-story-format) and a decoupled `eNNsYY-tasks.yaml` with runnable verify commands. "I think it works" is not a step.
+
+> **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
+>
+> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+
+## Pre-flight
+
+Read: `release-plan.yaml`, `product/SCOPE_LATEST.yaml`, active `epics/<capsule>/epic.yaml`, `tech-architecture/tech-stack.md`, `product/GLOSSARY_LATEST.yaml`.
+
+> **ZOOM-OUT MANDATE** (v1.17.0) — If modifying an existing module: (1) State the module's **purpose**. (2) Name its **callers**. (3) List its **contracts**. Cannot answer all three? Stop — scope is misunderstood.
+
+If this plan touches an existing module, run `assess-impact` first to understand blast radius.
+
+> **DISCOVERY MANDATE** (v1.18.0) — For external API integration, verify the API signature via local docs or search and quote at least one technical detail in the step's context.
+
+> **MULTIPLE INTERPRETATIONS (HARD GATE)** — If the task admits ≥2 valid interpretations, list them and get a user decision before drafting any steps.
+
+> **COMPLEXITY PUSHBACK (HARD GATE)** — Every new abstraction MUST include a one-sentence "Reason for Depth." If it can't be filled non-trivially, the abstraction is premature — use inline code instead.
+
+> **SLOPCHECK (HARD GATE)** — For every external package, tag it `[OK]`, `[SUS]`, or `[SLOP]`. `[SUS]`/`[SLOP]` require human approval before execution.
+
+## Invocation modes
+
+- Default: full plan with zoom-out mandate, impact assessment, slopcheck
+- `--fast`: Skip zoom-out and impact assessment. Use for tasks under 3 BCPs with no module interface changes.
+
+## Process
+
+1. **Explore** — Use `Explore` subagent to understand affected modules, existing test patterns, similar prior art, and dependencies.
+
+2. **Draft steps** — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3.
+
+3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template.
+
+4. **Verify step format** — Every step MUST follow: `N. <What to do> → verify: <runnable command>`. See [REFERENCE.md](REFERENCE.md) for good/bad examples.
+
+5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project.
+
+After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.
+
+## Handoff
+
+Gate: READY -> next: kickoff-branch
+Writes: state.yaml handoff.next_skill = kickoff-branch
+
+---
+
+# Plan Work — Reference
+
+## Output file formats
+
+### Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md`
+
+Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.
+
+### Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml`
+
+```yaml
+story_id: e01s01
+title: Login
+status: todo
+bcps: 3
+tasks:
+  - id: 1
+    description: "Add login form component tests"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+```
+
+Update `specs/epics/<capsule>/epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
+
+## Plan template
+
+```
+### Story [X.Y]: [title] — Implementation Steps
+
+**type:** feat | fix | refactor
+**context:** domain | infra
+**Context**: [One paragraph: what this story implements and why]
+
+## Steps
+
+1. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
+2. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
+...
+
+## Verification Script (Step-by-Step)
+
+[A human-readable, step-by-step script for the user to verify the story's outcome.]
+
+1. [Action 1: e.g. Start the server]
+2. [Action 2: e.g. Open browser to http://localhost:3000]
+3. [Observation: e.g. Verify that the login modal appears]
+
+## Out of scope
+
+- [Explicit exclusions]
+
+## Risks
+
+- [Anything that could go wrong and how to detect it early]
+```
+
+## Verify step format rules
+
+Every step MUST follow this exact format:
+```
+N. <What to do> → verify: <runnable command that proves it worked>
+```
+
+**Good examples:**
+```
+1. Add User model with email and name fields → verify: npm test -- user.test.ts
+2. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
+3. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts
+```
+
+**Bad examples (no verify command):**
+```
+1. Implement the user creation flow
+2. Write tests for the API
+```
+
+## Sub-operations
+
+### Define Success
+
+Before planning, convert task statements into observable "step → verify: <cmd>" pairs:
+- Break the task into observable outcomes (behaviors) rather than implementation steps
+- Write pairs in the format: `[What must be true] → verify: <runnable command>`
+- Challenge completeness: are all required behaviors covered?
+- Get user confirmation: "Does this capture everything the task requires?"
+- Once confirmed, these pairs become the skeleton for plan-work steps
+
+### Zoom-Out Check
+
+When modifying an existing module, confirm scope is understood:
+- State the module's **purpose** — what is it responsible for?
+- Name the **callers** — who depends on it?
+- List the **contracts** — what invariants or interfaces must be preserved?
+
+If you cannot answer all three without deep code archaeology, scope is misunderstood. Clarify with the user before writing steps.
+
+### Slopcheck
+
+For every external package proposed in the plan, tag each with one of:
+- `[OK]` — package is mature, actively maintained, appropriate scope
+- `[SUS]` — suspiciously broad, has maintenance concerns, or unclear fit
+- `[SLOP]` — unmaintained, known security issues, or out of scope
+
+`[SUS]` and `[SLOP]` require explicit human approval before the step may execute. Document tags inline next to the package name.

package/.pi/skills/release-branch/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: release-branch
+description: "Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says "release", "merge", or "open a PR"."
+---
+
+
+# Release Branch
+
+> **HARD GATE** — Do NOT merge or release if tests fail or if coverage gates are not met. If the branch is red, return to `develop-tdd` to fix regressions or add missing tests before proceeding.
+
+Finalize a completed feature branch: verify coverage gates, integrate onto `main`, and clean up the worktree.
+
+## Additional modes
+
+- `--hotfix`: Emergency fix. Cherry-pick to main plus immediate tag. Skip PR in solo profile.
+
+## Integrate mode
+
+Read `specs/state.yaml` key `workflow_mode` first (`team-pr` | `solo-git`). Fall back to sniffing `profiles/solo-git.md` only when the key is absent.
+
+| Mode | When | Ship path |
+|------|------|-----------|
+| **solo-local** | `workflow_mode: solo-git` (or `profiles/solo-git.md` present as fallback) | `bash scripts/land-branch.sh <branch> "<conventional message>"` |
+| **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
+
+If unsure and working alone, prefer **solo-local**.
+
+## Process
+
+### 1. Final verification
+
+```bash
+<full test command> && <typecheck command> && <lint command>
+git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ Non-conventional commits found" || echo "✅ Commits verified"
+```
+
+- [ ] All tests pass, no type errors, no lint violations, all commits follow Conventional Commits
+
+### 2. Coverage check
+
+- [ ] Overall coverage ≥ 80%; business logic coverage ≥ 95%
+
+### 3. Diff review
+
+- [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
+
+### 4. Decision
+
+Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
+
+### 5. Solo-local integrate
+
+Run `commit-message` to produce the squash commit subject, then:
+```bash
+bash scripts/land-branch.sh <task-slug> "feat(scope): description"
+```
+
+### 6. Create PR (team-pr only)
+
+See [REFERENCE.md](REFERENCE.md) for the full PR body template and gh commands.
+
+### 7. Merge (team-pr only)
+
+```bash
+gh pr merge --squash --delete-branch
+```
+
+`semantic-release` auto-detects the commit, bumps SemVer, tags the repo, generates release notes.
+
+### 7a. Archive completed epic capsule
+
+> **HARD GATE** — When all epic stories are done (all `done` in `execution-status.yaml`), archive the capsule:
+
+```bash
+mv specs/epics/eNN-slug specs/epics/archive/
+```
+
+### 8. Clean up worktree
+
+```bash
+git worktree prune
+git worktree remove ../<branch-name> 2>/dev/null || true
+git branch -d <branch-name>
+```
+
+### 8a. Cycle-time recording
+
+After landing, record delivery metrics. See [REFERENCE.md](REFERENCE.md) for fields and example row.
+
+### 9. Return to main
+
+```bash
+git checkout main && git status && pwd
+```
+
+Report: "Branch released. Integrate mode: <solo-local|team-pr>. cwd: $(pwd) on $(git branch --show-current)."
+
+## Handoff
+
+Gate: READY -> next: survey-context
+Writes: state.yaml handoff.next_skill = survey-context
+
+---
+
+# Release Branch — Reference
+
+## PR body template (team-pr mode)
+
+```bash
+PR_TITLE="<type>(<scope>): <description>"
+echo "$PR_TITLE" | grep -vE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ ERROR: PR Title must follow Conventional Commits"
+
+gh pr create \
+  --title "$PR_TITLE" \
+  --body "$(cat <<'EOF'
+## Summary
+- [What this PR does]
+- [Key decisions made]
+
+## Verify
+- [ ] All tests pass
+- [ ] Coverage gates met (≥80% overall, ≥95% business logic)
+- [ ] CONVENTIONS.md compliance verified
+- [ ] PR Title follows Conventional Commits (for automated release)
+
+## specs/ artifacts
+- [List any specs/ files produced or updated]
+EOF
+)"
+```
+
+## Worktree cleanup details
+
+```bash
+# From the main repo root
+git worktree prune
+git worktree remove ../<branch-name> 2>/dev/null || true
+git branch -d <branch-name>
+```
+
+If `git worktree remove` fails due to uncommitted changes, ask: "There are uncommitted changes in the worktree. Force remove? (y/n)". If yes: `git worktree remove -f ../<branch-name>`.
+
+## Cycle-time recording
+
+After landing the branch, record delivery metrics for this story:
+
+1. Write `metrics.story_end` (ISO 8601) to `specs/state.yaml`
+2. Compute `cycle_minutes`: `story_end` minus `story_start` in minutes
+3. Compute `bcp_per_hour`: `epic_cycle.story_bcps / (cycle_minutes / 60)`
+4. Append a row to `specs/metrics/cycle-times.yaml`:
+
+```yaml
+- id: e01s01
+  bcps: 3
+  start: "2026-06-10T09:45:00Z"
+  end: "2026-06-10T11:15:00Z"
+  cycle_minutes: 90
+  bcp_per_hour: 2.0
+```

package/.pi/skills/request-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: request-review
+description: "Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review."
+---
+
+
+# Request Review
+
+Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code.
+
+**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed.
+
+**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer.
+
+**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself.
+
+## Process
+
+### 1. Prepare the review brief
+
+Write a self-contained brief for the reviewer agent. Include:
+
+- What was built (feature description, not implementation)
+- Which files changed (the diff context)
+- What `specs/` artifacts are relevant (active `epics/eNN-*.yaml`, `requirements/SCOPE_LATEST.yaml`, `bugs/BUG-*.md`)
+- What CONVENTIONS.md requires
+- What the verify command is
+- What you're most uncertain about (where you want fresh eyes)
+
+### 2. Dispatch the reviewer agent
+
+Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed."
+
+```
+You are a code reviewer. Review the following code changes.
+
+Context: [feature description]
+CONVENTIONS.md rules: [paste relevant sections]
+Active epic shard: [paste or summarize from specs/epics/]
+
+Diff: [paste git diff or describe changed files]
+
+Verify command: [runnable command]
+
+Review for:
+1. Correctness — does the code do what was intended?
+2. CONVENTIONS.md compliance — are all rules followed?
+3. Test quality — do tests verify behavior (not implementation)?
+4. Design — are there simpler or more robust approaches?
+5. Edge cases — what inputs or states could cause failures?
+6. Security — any injection, auth, or data exposure risks?
+
+For each finding, categorize as: must-fix / should-fix / consider.
+Run the verify command and report the result.
+```
+
+### 3. Collect the report
+
+When the reviewer returns:
+- Read every finding before acting on any
+- Note the verify command result
+- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items`
+- Report the score to the user
+
+> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100.
+
+### 4. Hand off to respond-review
+
+Pass the reviewer's report to `respond-review` to categorize findings and apply fixes.
+
+Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review."

package/.pi/skills/research-first/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: research-first
+description: "Look-before-build — search registries, repo, existing skills, and web for prior art before implementing. Appends Prior Art to the spec. Use after survey-context and before elaborate-spec, when adding dependencies, or when the task may already be solved.model: sonnet"
+---
+
+
+# Research First
+
+> **HARD GATE** — Do NOT implement until prior art is searched. Minimum outcome: adopt, extend, compose, or build — with evidence.
+
+## Process
+
+1. Read `specs/product/SCOPE_LATEST.yaml`, `specs/release-plan.yaml + epic shards`, and the current task statement.
+2. Search in order: this repo → bigpowers skills (`search-skills`) → package registries → web docs.
+3. For each candidate: note name, URL/path, fit (adopt | extend | compose | build).
+4. Append `## Prior Art` to `requirements/SCOPE_LATEST.yaml` notes or the active epic story.
+
+## Outcome matrix
+
+| Verdict | Action |
+|---------|--------|
+| **adopt** | Use as-is; link in plan; no new code |
+| **extend** | Wrap or configure existing solution |
+| **compose** | Chain existing skills/modules |
+| **build** | New implementation — justify why others failed |
+
+## Verify
+
+→ verify: `grep -c "Prior Art" specs/product/SCOPE_LATEST.yaml specs/release-plan.yaml + epic shards 2>/dev/null | awk '{s+=$1} END {if(s>0) print "OK"; else print "MISSING"}'`
+
+See [REFERENCE.md](REFERENCE.md) for search commands and registry checklist.
+
+---
+
+# Research First — Reference
+
+## Search commands
+
+```bash
+# Repo prior art
+rg -l "<keyword>" --glob '!node_modules' .
+find . -maxdepth 3 -name "SKILL.md" | xargs grep -l "<intent>"
+
+# Installed packages (if package.json exists)
+cat package.json | jq '.dependencies,.devDependencies' 2>/dev/null
+```
+
+## Registry checklist
+
+- [ ] npm / PyPI / crates.io (if applicable)
+- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX.md`)
+- [ ] Project `docs/` and `specs/adr/`
+- [ ] Official library documentation (quote one API detail)
+
+## Prior Art template
+
+```markdown
+## Prior Art
+
+| Candidate | Source | Verdict | Notes |
+|-----------|--------|---------|-------|
+| ... | ... | adopt/extend/compose/build | ... |
+```

package/.pi/skills/reset-baseline/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: reset-baseline
+description: "Restore the project to a known clean state between agent runs or experiments. Use between benchmark runs, after a failed spike, or when user wants a clean working tree.model: haiku"
+---
+
+
+# Reset Baseline
+
+> **HARD GATE** — Confirm with user before any destructive git operation. Never `reset --hard` without explicit approval.
+
+## Process
+
+1. `git status` — list uncommitted and untracked files.
+2. Ask: stash, discard, or keep each category.
+3. Safe defaults: `git stash push -u -m "reset-baseline"` for WIP; never force-push.
+4. Re-run `setup-environment` after reset.
+5. Run test baseline from `kickoff-branch` verify command.
+
+## Verify
+
+→ verify: `git status --short | wc -l | awk '{if($1==0) print "OK"; else print "DIRTY:" $1}'

package/.pi/skills/respond-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: respond-review
+description: "Act on a reviewer agent's feedback systematically — categorize findings, apply fixes, verify tests still pass. Use after request-review returns a report, or when user wants to work through code review findings."
+---
+
+
+# Respond Review
+> **HARD GATE** — **HARD GATE** — Every reviewer comment must be addressed (fix, disagree + document reason, or ask clarification). Do NOT ignore feedback and merge.
+
+
+Work through reviewer findings systematically. Don't apply changes blindly — categorize first, then decide, then fix, then verify.
+
+## Process
+
+### 1. Read the full review report
+
+Read every finding before acting on any of them. Get the full picture first.
+
+### 2. Categorize findings
+
+For each finding, assign a category:
+
+| Category | Meaning | Action |
+|----------|---------|--------|
+| **must-fix** | Correctness bug, security issue, test failure, CONVENTIONS.md violation | Fix before proceeding |
+| **should-fix** | Code quality issue, naming, clarity — worth fixing but not blocking | Fix if time allows |
+| **consider** | Architectural suggestion, alternative approach — may or may not apply | Discuss with user |
+
+Create a numbered list of all findings with their categories.
+
+### 3. Confirm with user (for consider-category items)
+
+For each "consider" item, briefly describe the trade-off and ask: "Apply, skip, or discuss?"
+
+### 4. Apply must-fix items first
+
+Fix every must-fix item. For each one:
+- Describe what you're changing and why
+- Make the change
+- Run the verify command if one exists for this area
+
+### 5. Apply should-fix items
+
+Apply should-fix items. If any are large enough to warrant their own commit, note them separately.
+
+### 6. Run the full suite
+
+After all changes are applied:
+
+```bash
+<full test command>
+<typecheck command>
+<lint command>
+```
+
+- [ ] All tests pass
+- [ ] No type errors
+- [ ] No lint violations
+
+### 7. Report
+
+Summarize what was applied and what was skipped:
+
+```
+Applied (must-fix): #1, #2, #3
+Applied (should-fix): #4
+Skipped (consider): #5 — agreed with user to defer
+All tests pass.
+```
+
+Suggest next skill: `commit-message`.