bigpowers 2.26.0 → 2.28.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.26.0",
-  "description": "68 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.28.0",
+  "description": "70 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/audit-plan.md

@@ -0,0 +1,88 @@
+---
+description: Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase.
+---
+
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`

package/.pi/prompts/elaborate-spec.md

@@ -71,7 +71,26 @@ Summarize your understanding in 3–5 bullet points aligned with [countable-stor
 
 Ask: "Is this an accurate summary? Anything missing or wrong?"
 
-### 5. Suggest next skill
+### 5. Write specs/planning-context.yaml
+
+After the user confirms the summary in step 4, persist the key decisions:
+
+```yaml
+# specs/planning-context.yaml — written by elaborate-spec; consumed by scope-work and slice-tasks
+feature_name: "<from step 1>"
+problem_statement: "<one paragraph>"
+constraints:
+  - "<constraint 1>"
+out_of_scope:
+  - "<excluded item 1>"
+key_decisions:
+  - decision: "<what was decided>"
+    rationale: "<why>"
+```
+
+If `specs/planning-context.yaml` already exists, ask: `"Planning context from a prior session exists. Update it? [Y/n]"`. Overwrite on Y; leave unchanged on N.
+
+### 6. Suggest next skill
 
 Once the spec is clear, recommend the next step:
 - If domain model needs work → `model-domain`

package/.pi/prompts/evolve-skill.md

@@ -9,16 +9,23 @@ description: Benchmark-gated skill evolution — consume bigpowers-benchmark rep
 
 ## Loop
 
-1. Run `bigpowers-benchmark` (external repo); save report path in state.yaml.
-2. Identify target skill + measurable gap from report.
-3. `plan-work` — minimal change proposal with verify commands.
-4. Edit via `craft-skill` / direct SKILL.md edit; run `sync-skills.sh`.
-5. Re-run benchmark; compare scores.
-6. Record decision in `specs/adr/` + `session-state`; revert if regression.
+1. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
+
+2. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
+
+3. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
+
+4. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
+
+5. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
+   - **IMPROVED or STABLE** → advance to step 6.
+   - **REGRESSION** (`new pass_at_k < baseline`) → revert the change and loop back to step 3.
+
+6. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
 
 ## Verify
 
-→ verify: benchmark report shows post-change score ≥ baseline (document paths in state.yaml)
+→ verify: `grep -c 'run-benchmark\|pass_at_k\|BASELINE-' evolve-skill/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
 
 See [REFERENCE.md](REFERENCE.md) for ADR template.
 

package/.pi/prompts/quick-fix.md

@@ -6,6 +6,8 @@ description: "Streamlined fast-path for trivial data-only fixes — no TDD, no b
 
 # Quick Fix
 
+> **HARD GATE** — ALL entry criteria must pass before invoking quick-fix. If any guardrail triggers during execution, abort immediately and fall back to `investigate-bug`. Do NOT use quick-fix for logic changes, multi-file edits, or diffs > 5 lines.
+
 Fast-track for trivial data-only fixes that do not require the full bug-fix chain.
 
 When a bug fix is purely data — an add-missing-key, a typo correction, a config value update — the standard 6-skill chain (investigate-bug → diagnose-root → develop-tdd → kickoff-branch → verify-work → release-branch) is wasteful overhead. Quick-fix collapses it to 2 skills: **quick-fix** then **release-branch**.

package/.pi/prompts/run-benchmark.md

@@ -0,0 +1,69 @@
+---
+description: Run skill quality benchmarks from specs/benchmarks/ definitions and write pass@k reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions.
+---
+
+
+# Run Benchmark
+
+> **HARD GATE** — Do NOT use benchmark scores to declare a skill "good" or "bad" in isolation. Benchmarks measure relative quality vs. a baseline — they catch regressions, they do not certify correctness.
+
+Reads benchmark definitions from `specs/benchmarks/`, executes each scenario's grader, and writes a structured `pass@k` report that `evolve-skill` consumes.
+
+## Usage
+
+```bash
+# Benchmark a single skill
+run-benchmark <skill-name>
+
+# Benchmark all skills with definitions
+run-benchmark --all
+
+# Pin current results as baseline
+run-benchmark <skill-name> --baseline
+```
+
+## Process
+
+1. **Locate definition** — Read `specs/benchmarks/<skill>.yaml`. If absent, report: `"No benchmark definition found for <skill>. Create specs/benchmarks/<skill>.yaml first."` and stop.
+
+2. **Run each scenario** — For each scenario in `scenarios[]`:
+   - **Code grader:** Run `grader.command` in repo root via `bash -c`. Exit 0 → PASS. Non-zero → FAIL. Timeout: 15 seconds.
+   - **Rubric grader:** Present each criterion to the agent as a yes/no question about the scenario output. ≥ 80% yes → PASS, else FAIL.
+
+3. **Calculate pass@k** — `pass@k = sum(weight of PASS scenarios) / sum(all weights)`. Round to 2 decimal places.
+
+4. **Write report** to `specs/benchmarks/reports/BENCHMARK-<skill>-<YYYY-MM-DD>.yaml`:
+
+```yaml
+skill: survey-context
+run_date: "2026-06-22"
+pass_at_k: 0.83
+total_scenarios: 3
+passed: 2
+failed: 1
+scenarios:
+  - id: s01
+    name: "detects active epic from state.yaml"
+    result: PASS
+    weight: 1.0
+  - id: s02
+    name: "reads release-plan.yaml and reports next epic"
+    result: PASS
+    weight: 1.0
+  - id: s03
+    name: "handles missing state.yaml gracefully"
+    result: FAIL
+    weight: 0.5
+    failure_note: "crashed instead of suggesting state.yaml creation"
+```
+
+5. **Baseline mode** (`--baseline`) — Copy the report to `specs/benchmarks/reports/BASELINE-<skill>.yaml`. This is the reference point for regression checks in `evolve-skill`.
+
+6. **Compare to baseline** — If a `BASELINE-<skill>.yaml` exists, compare `pass_at_k`. Report:
+   - `IMPROVED: 0.67 → 0.83`
+   - `REGRESSION: 0.83 → 0.67 — do NOT ship this change`
+   - `STABLE: 0.83 = 0.83`
+
+## Verify
+
+→ verify: `test -f run-benchmark/SKILL.md && grep -q 'pass_at_k\|pass.at.k' run-benchmark/SKILL.md && echo OK || echo FAIL`

package/.pi/prompts/run-planning.md

@@ -36,6 +36,21 @@ Each key maps to a skill invocation. Optional keys can be skipped; required keys
 
 2. **Find next step** — Find the first workflow key with `status: pending`. If the key is `optional`, check if the user wants to run it. If not, mark it `skipped`.
 
+2a. **Context capsule check** — Before invoking `elaborate-spec`, check whether a fresh `specs/planning-context.yaml` exists:
+   ```bash
+   test -f specs/planning-context.yaml && python3 -c "
+import yaml, datetime
+d = yaml.safe_load(open('specs/planning-context.yaml'))
+written = d.get('written_at','')
+if written:
+    age = (datetime.datetime.now(datetime.timezone.utc) - datetime.datetime.fromisoformat(written)).total_seconds() / 3600
+    print(f'Context age: {age:.1f}h')
+" 2>/dev/null || echo "No context or no written_at"
+   ```
+   - If context is **< 24h old**, ask: `"Planning context from Xh ago exists for '<feature_name>'. Re-run elaborate-spec? [y/N]"`. Skip elaborate-spec on N.
+   - If context is **≥ 24h old** or absent, run elaborate-spec normally.
+   - On planning cycle completion (all required keys done), clear the capsule: delete `specs/planning-context.yaml` and set `planning-status.yaml` `context_capsule: null`.
+
 3. **Invoke the matching skill** — Run the skill that matches the workflow key:
    - `survey-context` — where are we?
    - `scope-work` — what's in and out?
@@ -52,6 +67,10 @@ Each key maps to a skill invocation. Optional keys can be skipped; required keys
 
 In `specs/planning-status.yaml`:
 ```yaml
+context_capsule:             # written by elaborate-spec; cleared on cycle completion
+  written_at: "2026-06-22T03:00:00Z"
+  written_by: elaborate-spec
+  feature_name: "add dark mode"
 workflows:
   survey-context:
     required: true

package/.pi/prompts/scope-work.md

@@ -17,6 +17,12 @@ Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.
 
 ## Process
 
+0. **Read planning-context.yaml** — If `specs/planning-context.yaml` exists, read it before doing anything else:
+   ```bash
+   test -f specs/planning-context.yaml && echo "Context found" || echo "No context — starting fresh"
+   ```
+   Pre-populate `feature_name`, `constraints`, and `out_of_scope` from the file. Skip re-asking questions already answered by elaborate-spec. If the file is absent, proceed normally.
+
 1. **Gather context** — Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any). Understand what the project is building and why.
 
 2. **Interview (if needed)** — Clarify: What is the goal? Who are the users? What is definitely in scope? What is explicitly out of scope? What constraints exist (time, budget, tech)? How will success be measured?

package/.pi/prompts/slice-tasks.md

@@ -17,6 +17,12 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli
 
 ## Process
 
+0. **Read planning-context.yaml** — If `specs/planning-context.yaml` exists, read it first:
+   ```bash
+   test -f specs/planning-context.yaml && echo "Context found" || echo "No context — starting fresh"
+   ```
+   Use `feature_name`, `constraints`, and `out_of_scope` to inform slice boundaries. `key_decisions` in the file may constrain how stories are cut (e.g., "no external deps" constrains slice 2). If absent, proceed normally.
+
 1. **Read context** — Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`. Understand what the epic delivers end-to-end.
 
 2. **Cut tracer-bullet slices** — Identify the thinnest possible vertical path through the stack that delivers user value. Start with this slice; it will catch integration issues first. For example:

package/.pi/prompts/stocktake-skills.md

@@ -14,7 +14,8 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 | Mode | Scope |
 |------|-------|
 | **Quick Scan** | Skills changed since last tag or in current diff |
-| **Full** | All 62 skills per SKILL-INDEX.md + catalog audit |
+| **Full** | All skills per SKILL-INDEX.md + catalog audit |
+| **--verify** | Run `bash scripts/run-skill-verify.sh` and append health results to the stocktake report |
 
 ## Process
 
@@ -26,6 +27,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
    - Skills with zero calls (potential dead weight)
    - Skills with high average time (candidates for `evolve-skill`)
 5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
+6. **--verify mode:** Run `bash scripts/run-skill-verify.sh` and append a `## Verify Health` section to the stocktake report: `"N/68 PASS, M FAIL, K SKIP"`. FAIL skills are critical findings and go straight to `plan-work`.
 
 ### Skill timing data (`metrics.skill_timings`)
 

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

@@ -0,0 +1,90 @@
+---
+name: audit-plan
+description: "Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase."
+model: sonnet
+---
+
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`

package/.pi/skills/elaborate-spec/SKILL.md

@@ -73,7 +73,26 @@ Summarize your understanding in 3–5 bullet points aligned with [countable-stor
 
 Ask: "Is this an accurate summary? Anything missing or wrong?"
 
-### 5. Suggest next skill
+### 5. Write specs/planning-context.yaml
+
+After the user confirms the summary in step 4, persist the key decisions:
+
+```yaml
+# specs/planning-context.yaml — written by elaborate-spec; consumed by scope-work and slice-tasks
+feature_name: "<from step 1>"
+problem_statement: "<one paragraph>"
+constraints:
+  - "<constraint 1>"
+out_of_scope:
+  - "<excluded item 1>"
+key_decisions:
+  - decision: "<what was decided>"
+    rationale: "<why>"
+```
+
+If `specs/planning-context.yaml` already exists, ask: `"Planning context from a prior session exists. Update it? [Y/n]"`. Overwrite on Y; leave unchanged on N.
+
+### 6. Suggest next skill
 
 Once the spec is clear, recommend the next step:
 - If domain model needs work → `model-domain`

package/.pi/skills/evolve-skill/SKILL.md

@@ -11,16 +11,23 @@ model: opus
 
 ## Loop
 
-1. Run `bigpowers-benchmark` (external repo); save report path in state.yaml.
-2. Identify target skill + measurable gap from report.
-3. `plan-work` — minimal change proposal with verify commands.
-4. Edit via `craft-skill` / direct SKILL.md edit; run `sync-skills.sh`.
-5. Re-run benchmark; compare scores.
-6. Record decision in `specs/adr/` + `session-state`; revert if regression.
+1. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
+
+2. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
+
+3. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
+
+4. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
+
+5. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
+   - **IMPROVED or STABLE** → advance to step 6.
+   - **REGRESSION** (`new pass_at_k < baseline`) → revert the change and loop back to step 3.
+
+6. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
 
 ## Verify
 
-→ verify: benchmark report shows post-change score ≥ baseline (document paths in state.yaml)
+→ verify: `grep -c 'run-benchmark\|pass_at_k\|BASELINE-' evolve-skill/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
 
 See [REFERENCE.md](REFERENCE.md) for ADR template.
 

package/.pi/skills/quick-fix/SKILL.md

@@ -8,6 +8,8 @@ model: sonnet
 
 # Quick Fix
 
+> **HARD GATE** — ALL entry criteria must pass before invoking quick-fix. If any guardrail triggers during execution, abort immediately and fall back to `investigate-bug`. Do NOT use quick-fix for logic changes, multi-file edits, or diffs > 5 lines.
+
 Fast-track for trivial data-only fixes that do not require the full bug-fix chain.
 
 When a bug fix is purely data — an add-missing-key, a typo correction, a config value update — the standard 6-skill chain (investigate-bug → diagnose-root → develop-tdd → kickoff-branch → verify-work → release-branch) is wasteful overhead. Quick-fix collapses it to 2 skills: **quick-fix** then **release-branch**.

package/.pi/skills/run-benchmark/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: run-benchmark
+description: "Run skill quality benchmarks from specs/benchmarks/ definitions and write pass@k reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions."
+model: haiku
+---
+
+
+# Run Benchmark
+
+> **HARD GATE** — Do NOT use benchmark scores to declare a skill "good" or "bad" in isolation. Benchmarks measure relative quality vs. a baseline — they catch regressions, they do not certify correctness.
+
+Reads benchmark definitions from `specs/benchmarks/`, executes each scenario's grader, and writes a structured `pass@k` report that `evolve-skill` consumes.
+
+## Usage
+
+```bash
+# Benchmark a single skill
+run-benchmark <skill-name>
+
+# Benchmark all skills with definitions
+run-benchmark --all
+
+# Pin current results as baseline
+run-benchmark <skill-name> --baseline
+```
+
+## Process
+
+1. **Locate definition** — Read `specs/benchmarks/<skill>.yaml`. If absent, report: `"No benchmark definition found for <skill>. Create specs/benchmarks/<skill>.yaml first."` and stop.
+
+2. **Run each scenario** — For each scenario in `scenarios[]`:
+   - **Code grader:** Run `grader.command` in repo root via `bash -c`. Exit 0 → PASS. Non-zero → FAIL. Timeout: 15 seconds.
+   - **Rubric grader:** Present each criterion to the agent as a yes/no question about the scenario output. ≥ 80% yes → PASS, else FAIL.
+
+3. **Calculate pass@k** — `pass@k = sum(weight of PASS scenarios) / sum(all weights)`. Round to 2 decimal places.
+
+4. **Write report** to `specs/benchmarks/reports/BENCHMARK-<skill>-<YYYY-MM-DD>.yaml`:
+
+```yaml
+skill: survey-context
+run_date: "2026-06-22"
+pass_at_k: 0.83
+total_scenarios: 3
+passed: 2
+failed: 1
+scenarios:
+  - id: s01
+    name: "detects active epic from state.yaml"
+    result: PASS
+    weight: 1.0
+  - id: s02
+    name: "reads release-plan.yaml and reports next epic"
+    result: PASS
+    weight: 1.0
+  - id: s03
+    name: "handles missing state.yaml gracefully"
+    result: FAIL
+    weight: 0.5
+    failure_note: "crashed instead of suggesting state.yaml creation"
+```
+
+5. **Baseline mode** (`--baseline`) — Copy the report to `specs/benchmarks/reports/BASELINE-<skill>.yaml`. This is the reference point for regression checks in `evolve-skill`.
+
+6. **Compare to baseline** — If a `BASELINE-<skill>.yaml` exists, compare `pass_at_k`. Report:
+   - `IMPROVED: 0.67 → 0.83`
+   - `REGRESSION: 0.83 → 0.67 — do NOT ship this change`
+   - `STABLE: 0.83 = 0.83`
+
+## Verify
+
+→ verify: `test -f run-benchmark/SKILL.md && grep -q 'pass_at_k\|pass.at.k' run-benchmark/SKILL.md && echo OK || echo FAIL`

package/.pi/skills/run-planning/SKILL.md

@@ -38,6 +38,21 @@ Each key maps to a skill invocation. Optional keys can be skipped; required keys
 
 2. **Find next step** — Find the first workflow key with `status: pending`. If the key is `optional`, check if the user wants to run it. If not, mark it `skipped`.
 
+2a. **Context capsule check** — Before invoking `elaborate-spec`, check whether a fresh `specs/planning-context.yaml` exists:
+   ```bash
+   test -f specs/planning-context.yaml && python3 -c "
+import yaml, datetime
+d = yaml.safe_load(open('specs/planning-context.yaml'))
+written = d.get('written_at','')
+if written:
+    age = (datetime.datetime.now(datetime.timezone.utc) - datetime.datetime.fromisoformat(written)).total_seconds() / 3600
+    print(f'Context age: {age:.1f}h')
+" 2>/dev/null || echo "No context or no written_at"
+   ```
+   - If context is **< 24h old**, ask: `"Planning context from Xh ago exists for '<feature_name>'. Re-run elaborate-spec? [y/N]"`. Skip elaborate-spec on N.
+   - If context is **≥ 24h old** or absent, run elaborate-spec normally.
+   - On planning cycle completion (all required keys done), clear the capsule: delete `specs/planning-context.yaml` and set `planning-status.yaml` `context_capsule: null`.
+
 3. **Invoke the matching skill** — Run the skill that matches the workflow key:
    - `survey-context` — where are we?
    - `scope-work` — what's in and out?
@@ -54,6 +69,10 @@ Each key maps to a skill invocation. Optional keys can be skipped; required keys
 
 In `specs/planning-status.yaml`:
 ```yaml
+context_capsule:             # written by elaborate-spec; cleared on cycle completion
+  written_at: "2026-06-22T03:00:00Z"
+  written_by: elaborate-spec
+  feature_name: "add dark mode"
 workflows:
   survey-context:
     required: true

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

@@ -19,6 +19,12 @@ Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.
 
 ## Process
 
+0. **Read planning-context.yaml** — If `specs/planning-context.yaml` exists, read it before doing anything else:
+   ```bash
+   test -f specs/planning-context.yaml && echo "Context found" || echo "No context — starting fresh"
+   ```
+   Pre-populate `feature_name`, `constraints`, and `out_of_scope` from the file. Skip re-asking questions already answered by elaborate-spec. If the file is absent, proceed normally.
+
 1. **Gather context** — Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any). Understand what the project is building and why.
 
 2. **Interview (if needed)** — Clarify: What is the goal? Who are the users? What is definitely in scope? What is explicitly out of scope? What constraints exist (time, budget, tech)? How will success be measured?

package/.pi/skills/slice-tasks/SKILL.md

@@ -19,6 +19,12 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli
 
 ## Process
 
+0. **Read planning-context.yaml** — If `specs/planning-context.yaml` exists, read it first:
+   ```bash
+   test -f specs/planning-context.yaml && echo "Context found" || echo "No context — starting fresh"
+   ```
+   Use `feature_name`, `constraints`, and `out_of_scope` to inform slice boundaries. `key_decisions` in the file may constrain how stories are cut (e.g., "no external deps" constrains slice 2). If absent, proceed normally.
+
 1. **Read context** — Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`. Understand what the epic delivers end-to-end.
 
 2. **Cut tracer-bullet slices** — Identify the thinnest possible vertical path through the stack that delivers user value. Start with this slice; it will catch integration issues first. For example:

package/.pi/skills/stocktake-skills/SKILL.md

@@ -16,7 +16,8 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 | Mode | Scope |
 |------|-------|
 | **Quick Scan** | Skills changed since last tag or in current diff |
-| **Full** | All 62 skills per SKILL-INDEX.md + catalog audit |
+| **Full** | All skills per SKILL-INDEX.md + catalog audit |
+| **--verify** | Run `bash scripts/run-skill-verify.sh` and append health results to the stocktake report |
 
 ## Process
 
@@ -28,6 +29,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
    - Skills with zero calls (potential dead weight)
    - Skills with high average time (candidates for `evolve-skill`)
 5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
+6. **--verify mode:** Run `bash scripts/run-skill-verify.sh` and append a `## Verify Health` section to the stocktake report: `"N/68 PASS, M FAIL, K SKIP"`. FAIL skills are critical findings and go straight to `plan-work`.
 
 ### Skill timing data (`metrics.skill_timings`)