bigpowers 2.26.0 → 2.27.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.27.0",
+  "description": "69 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

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/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`)
 

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [2.27.0](https://github.com/danielvm-git/bigpowers/compare/v2.26.0...v2.27.0) (2026-06-22)
+
+
+### Bug Fixes
+
+* **quick-fix:** add HARD GATE callout — completes 35/35 skills ([9782b85](https://github.com/danielvm-git/bigpowers/commit/9782b85de96fabc77c14fe8f7be3fd30b98e9cfb))
+
+
+### Features
+
+* **2.9.0:** implement e22/e23/e24 — Depth release ([c33d66c](https://github.com/danielvm-git/bigpowers/commit/c33d66c6a386a6c273ab1f4c2a71981309e1cda6))
+* **plan-release:** scope 2.9.0 Depth — e22/e23/e24 ([5a64698](https://github.com/danielvm-git/bigpowers/commit/5a646981c520f4874c4f2807d53af40e17b093fb))
+
 # [2.26.0](https://github.com/danielvm-git/bigpowers/compare/v2.25.0...v2.26.0) (2026-06-22)
 
 

package/SKILL-INDEX.md

@@ -3,8 +3,8 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-22T03:20:14Z
-**Skills:** 68
+**Generated:** 2026-06-22T11:54:00Z
+**Skills:** 69
 
 ---
 

package/elaborate-spec/SKILL.md

@@ -72,7 +72,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/evolve-skill/SKILL.md

@@ -10,15 +10,22 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.26.0",
+  "version": "2.27.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/quick-fix/SKILL.md

@@ -7,6 +7,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/run-benchmark/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: run-benchmark
+model: haiku
+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/run-planning/SKILL.md

@@ -37,6 +37,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?
@@ -53,6 +68,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/scope-work/SKILL.md

@@ -18,6 +18,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/scripts/run-skill-verify.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Run all SKILL.md → verify: commands and report PASS/FAIL/SKIP.
+# Exit 0 only when zero FAILs.
+# Usage: bash scripts/run-skill-verify.sh [skill-name]
+#   No args: runs all skills
+#   With arg: runs only the named skill
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+PASS=0; FAIL=0; SKIP=0
+TARGET="${1:-}"
+
+run_skill() {
+  local skill_md="$1"
+  local skill
+  skill=$(dirname "$skill_md")
+
+  local cmd
+  cmd=$(grep '→ verify:' "$skill_md" 2>/dev/null | head -1 | sed 's/.*→ verify: *//')
+
+  if [ -z "$cmd" ]; then
+    echo "SKIP: $skill"
+    SKIP=$((SKIP + 1))
+    return
+  fi
+
+  local output
+  if output=$(timeout 10 bash -c "$cmd" 2>&1); then
+    echo "PASS: $skill"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $skill — $cmd"
+    echo "      output: $(echo "$output" | head -1)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+if [ -n "$TARGET" ]; then
+  if [ -f "$TARGET/SKILL.md" ]; then
+    run_skill "$TARGET/SKILL.md"
+  else
+    echo "ERROR: $TARGET/SKILL.md not found"
+    exit 1
+  fi
+else
+  for skill_md in */SKILL.md; do
+    run_skill "$skill_md"
+  done
+fi
+
+echo ""
+echo "Results: $PASS PASS, $FAIL FAIL, $SKIP SKIP"
+
+[ "$FAIL" -eq 0 ]

package/skills-lock.json

@@ -93,7 +93,7 @@
     },
     "elaborate-spec": {
       "description": "Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn \"I want X\" into a concrete spec.",
-      "sha256": "6d60cffd5139347e",
+      "sha256": "9edc17057449444d",
       "path": "elaborate-spec/SKILL.md"
     },
     "enforce-first": {
@@ -103,7 +103,7 @@
     },
     "evolve-skill": {
       "description": "Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose plan-work change, edit skill via craft-skill, re-run benchmark, record ADR. Use when a skill underperforms on benchmark or stocktake finds systemic gap.",
-      "sha256": "3582333ff9b15942",
+      "sha256": "e2d127c4ae0b5af7",
       "path": "evolve-skill/SKILL.md"
     },
     "execute-plan": {
@@ -198,7 +198,7 @@
     },
     "quick-fix": {
       "description": "\"Streamlined fast-path for trivial data-only fixes — no TDD, no branching ceremony. Collapses 6 skills into 2 for changes that are purely data with no logic risk. Aborts with fallback to investigate-bug if guardrails trigger.\"",
-      "sha256": "6b83f22481ff4995",
+      "sha256": "2b9f1cd6557b6256",
       "path": "quick-fix/SKILL.md"
     },
     "release-branch": {
@@ -226,6 +226,11 @@
       "sha256": "c16bbe4854a0d665",
       "path": "respond-review/SKILL.md"
     },
+    "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.",
+      "sha256": "e27f4e682e505b19",
+      "path": "run-benchmark/SKILL.md"
+    },
     "run-evals": {
       "description": "Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs.",
       "sha256": "b3cd89a7e440c94f",
@@ -233,12 +238,12 @@
     },
     "run-planning": {
       "description": "\"DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning-status.yaml) through survey-context → scope-work → research-first → elaborate-spec → plan-release → slice-tasks. NOT a duplicate of plan-work or the planning spine; it orchestrates the pre-coding discover phase only.\"",
-      "sha256": "eb6c9d3c0e26b7fc",
+      "sha256": "a2e7c028e7f817de",
       "path": "run-planning/SKILL.md"
     },
     "scope-work": {
       "description": "\"PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in and out of scope and save as specs/product/SCOPE_LATEST.yaml. Use before slice-tasks or plan-release on any new initiative. Not a substitute for slice-tasks (step 2) or plan-work (step 3).\"",
-      "sha256": "3d333e2bfa5f9998",
+      "sha256": "d3cb167d8a5296be",
       "path": "scope-work/SKILL.md"
     },
     "search-skills": {
@@ -268,7 +273,7 @@
     },
     "slice-tasks": {
       "description": "\"PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical-slice stories in specs/epics/. Use after scope-work (step 1), before plan-work (step 3). Not a substitute for scope-work or plan-work.\"",
-      "sha256": "bda9db54dbe791b5",
+      "sha256": "7948164e218541ea",
       "path": "slice-tasks/SKILL.md"
     },
     "smoke-test": {
@@ -283,7 +288,7 @@
     },
     "stocktake-skills": {
       "description": "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.",
-      "sha256": "c58bf4f70ff02cd3",
+      "sha256": "6e73b2d2cf0cfbe1",
       "path": "stocktake-skills/SKILL.md"
     },
     "survey-context": {

package/slice-tasks/SKILL.md

@@ -18,6 +18,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/stocktake-skills/SKILL.md

@@ -15,7 +15,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
 
@@ -27,6 +28,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`)