bigpowers 2.25.0 → 2.27.0

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/.pi/skills/verify-work/SKILL.md

@@ -17,6 +17,7 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 
 - Default: full UAT plus gaps loop
 - --smoke: Cold-start only plus one happy-path flow. Use for hotfixes.
+- --cli: CLI tool verification — replaces cold-start with binary smoke checklist. Use for CLI tools with no server process.
 
 ## Process
 
@@ -25,6 +26,12 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 0. **Branch check** — must not be `main`/`master`.
 
 1. Read active story tasks from `specs/epics/<capsule>/eNNsYY-tasks.yaml` and story spec from `specs/epics/<capsule>/eNNsYY-<slug>.md` (countable-story-format, Gherkin in §17).
+1a. **Pre-UAT verify validation** — for each task's `verify:` command, run it and detect pattern mismatches before UAT begins. If a grep/awk/jq command fails, check whether the pattern is wrong vs. a genuine failure:
+    ```bash
+    # For a failing grep -q 'PATTERN' FILE, check what is actually in FILE
+    grep 'PATTERN' FILE || grep -n '' FILE | head -20   # show nearest lines
+    ```
+    Report: `"Pattern 'X' not found. Nearest match: 'Y' at line N"` and ask `"Update verify command? [Y/n]"`. Fix before proceeding — a mismatched verify command produces false failures during UAT.
 2. **Cold-start smoke** (if app): stop server, clear caches, boot from scratch.
 3. **AGENTS.md preflight** — before running default checks, call `bash scripts/bp-read-agents.sh` to detect project-specific commands. If `BP_PREFLIGHT` is set, run it instead of the default mechanical gates (or in addition to them if the project requires both). Output: `"Using preflight from AGENTS.md: <cmd>"`. Fall back to `CLAUDE.md` commands if AGENTS.md is absent.
 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md).
@@ -92,6 +99,29 @@ phases:
 
 > **HARD GATE** — Verification evidence MUST be persisted before marking the story done. No evidence = not verified.
 
+## --cli mode
+
+For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`.
+
+**Auto-detect binary name:**
+```bash
+# Cargo.toml
+BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}')
+# package.json
+BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null)
+# Makefile
+BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}')
+```
+
+**CLI verification checklist (replaces cold-start smoke):**
+
+1. `--help` smoke: `$BINARY --help` → assert output contains "Usage"
+2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json)
+3. Happy-path: run documented example command from README.md → assert non-empty output
+4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed
+
+No "stop server" or "clear caches" steps are executed in `--cli` mode. Steps 3–6 of the default process (mechanical gates, UAT, gaps loop) still run unchanged.
+
 ## Verify
 
 → verify: `test -f specs/verifications/<story_id>-verify.yaml && echo "Evidence persisted"`

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [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)
+
+
+### Bug Fixes
+
+* **compose-workflow:** respond to code review — fix recipes and docs ([17ac105](https://github.com/danielvm-git/bigpowers/commit/17ac105371c25fd111821b3711648eb4009db314))
+
+
+### Features
+
+* **e20:** Build-Epic Ergonomics & Flow Polish — all stories done ([80b4b9a](https://github.com/danielvm-git/bigpowers/commit/80b4b9acd049ae2521c29e1d66fc0be5b509cac9))
+
 # [2.25.0](https://github.com/danielvm-git/bigpowers/compare/v2.24.0...v2.25.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-22T02:29:38Z
-**Skills:** 68
+**Generated:** 2026-06-22T11:54:00Z
+**Skills:** 69
 
 ---
 

package/build-epic/SKILL.md

@@ -47,6 +47,28 @@ After step 5 (verify-work) completes successfully, step 6 runs `audit-code` auto
 4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
 5. **Enforce F.I.R.S.T:** After audit-code passes, run `enforce-first --quick` on new/modified tests. Append F.I.R.S.T violations (if any) to the audit report. Failing F.I.R.S.T criteria trigger the same loop-back to step 4.
 
+## --fast mode
+
+Coalesces read-and-report steps to reduce token overhead. Activate with `build-epic --fast`.
+
+| Normal | --fast | Change |
+|--------|--------|--------|
+| Step 1 (survey-context) | 1+2 together | survey + plan in one invocation |
+| Step 2 (plan-work) | (absorbed into 1) | — |
+| Step 3 (kickoff-branch) | Step 2 | unchanged, sequential |
+| Step 4 (develop-tdd) | Step 3 | unchanged, sequential |
+| Step 5 (verify-work) | Step 4 | unchanged, sequential |
+| Step 6 (audit-code) | 5+6 together | audit + commit-message in one invocation |
+| Step 7 (commit-message) | (absorbed into 6) | — |
+| Step 8 (release-branch) | Step 7 | unchanged, sequential |
+
+**Total invocations:** 8 → 6 per story.
+
+**Rules:**
+- Steps 3/4/5/8 (kickoff, develop, verify, release) still run sequentially — they require user interaction or branch state.
+- `--fast` does NOT skip any checklist items; it only coalesces steps that are pure read-and-report.
+- Record `epic_cycle.fast_mode: true` in `state.yaml` when this flag is active.
+
 ## Handoff
 
 Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.

package/compose-workflow/SKILL.md

@@ -11,13 +11,15 @@ model: sonnet
 ## Process
 
 1. Interview: goal, phases, which skills, gates between steps.
-2. Write `specs/WORKFLOW-<name>.md`:
-   - Trigger ("Use when...")
-   - Ordered steps: `skill → artefact → verify`
-   - HARD GATEs between phases
+2. Write `specs/workflows/<name>.yaml`:
+   - `name`, `command`, `description`, `skills[]`, `verify`
+   - Optional: `args` for skill-specific arguments
 3. Register in state.yaml Active Decisions.
 4. Optional: reference from `orchestrate-project` Ad-Hoc mode.
 
+> **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-<name>.md` markdown format.
+> YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library.
+
 ## Standard Recipe Library
 
 Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains.
@@ -25,13 +27,13 @@ Reference them in AGENTS.md so `/command` directly invokes the matching recipe.
 
 | Command | Workflow | Skill chain |
 |---------|----------|-------------|
-| `/check-stack` | check-stack | survey-context → assess-impact → verify-work |
+| `/check-stack` | check-stack | survey-context → assess-impact → setup-environment |
 | `/ship` | ship | audit-code → commit-message → release-branch |
 | `/tdd` | tdd | develop-tdd → enforce-first |
 | `/code-review` | code-review | audit-code → request-review → respond-review |
-| `/security` | security | audit-code (security focus) → request-review |
+| `/security` | security | audit-code → request-review |
 | `/plan` | plan | survey-context → research-first → plan-work |
-| `/build-fix` | build-fix | investigate-bug → diagnose-root → quick-fix → validate-fix |
+| `/build-fix` | build-fix | investigate-bug → diagnose-root → develop-tdd → validate-fix |
 | `/e2e` | e2e | smoke-test → verify-work |
 
 Add to `AGENTS.md`:

package/develop-tdd/SKILL.md

@@ -149,6 +149,26 @@ Once all tests pass: locate the Verification Script in the active epic capsule,
 [ ] verify: command passes
 ```
 
+## --config mode
+
+For pure-config tasks (update package.json, edit YAML, tweak manifest) where there is no test infrastructure to write against. The RED state is "verify command fails"; GREEN is "verify command passes."
+
+**When to use:** task has a runnable `verify:` command and the deliverable is a config file change with no new behavior to unit-test. Invoke as `develop-tdd --config`.
+
+**Cycle:**
+
+```
+RED:    Run verify command → it fails (expected)
+GREEN:  Apply config change → verify passes
+COMMIT: commit: chore(<scope>): <change>
+```
+
+**Rules:**
+- Skips test-writing phase entirely — do NOT write a test file for config tasks.
+- `verify:` command is **required** and must be runnable (no placeholder).
+- Commit message follows Conventional Commits (`chore:` or `feat:` as appropriate).
+- Still runs full `verify-work` after all tasks complete.
+
 ## Handoff
 
 Gate: READY -> next: verify-work

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/kickoff-branch/SKILL.md

@@ -32,7 +32,32 @@ git status                             # working tree MUST be clean
 git log --oneline -5
 ```
 
-If working tree is dirty, ask the user to stash or commit first. If not on `$DEFAULT` after checkout, stop and fix before continuing.
+**Spec-only pre-kickoff** — before enforcing the clean-tree gate, check whether dirty files are spec artifacts:
+
+```bash
+DIRTY=$(git status --porcelain | awk '{print $2}')
+NON_SPEC=$(echo "$DIRTY" | grep -v '^specs/' || true)
+
+if [ -z "$DIRTY" ]; then
+  : # clean — proceed
+elif [ -z "$NON_SPEC" ]; then
+  # spec-only dirty tree — offer auto-commit
+  echo "Dirty spec artifacts: $(echo $DIRTY | tr '\n' ' ')"
+  read -p "Commit spec artifacts before kickoff? [Y/n]: " CONFIRM
+  CONFIRM=${CONFIRM:-Y}
+  if [[ "$CONFIRM" =~ ^[Yy] ]]; then
+    git add specs/
+    git commit -m "chore(state): checkpoint before kickoff"
+  fi
+else
+  echo "Dirty tree: $NON_SPEC (not a spec artifact). Stash or commit before proceeding."
+  exit 1
+fi
+```
+
+- **Spec artifacts** match `specs/` — state.yaml, epics YAMLs, execution-status.yaml, etc.
+- **Non-spec dirty files** (src/, scripts/, SKILL.md, …) still enforce the full clean-tree gate.
+- If not on `$DEFAULT` after checkout, stop and fix before continuing.
 
 ### 3. Pre-flight & Conflict Resolution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.25.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 ]