bigpowers 2.24.0 → 2.26.0

package/.pi/package.json

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

package/.pi/prompts/build-epic.md

@@ -46,6 +46,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/.pi/prompts/compose-workflow.md

@@ -10,16 +10,40 @@ description: Chain multiple bigpowers skills into a custom workflow recipe saved
 ## 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.
+Reference them in AGENTS.md so `/command` directly invokes the matching recipe.
+
+| Command | Workflow | Skill chain |
+|---------|----------|-------------|
+| `/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 → request-review |
+| `/plan` | plan | survey-context → research-first → plan-work |
+| `/build-fix` | build-fix | investigate-bug → diagnose-root → develop-tdd → validate-fix |
+| `/e2e` | e2e | smoke-test → verify-work |
+
+Add to `AGENTS.md`:
+```
+/check-stack = compose-workflow check-stack
+/ship        = compose-workflow ship
+```
+
 ## Verify
 
-→ verify: `test -f specs/WORKFLOW-*.md && grep -c "verify:" specs/WORKFLOW-*.md | awk '{if($1>0) print "OK"}'`
+→ verify: `ls specs/workflows/*.yaml 2>/dev/null | wc -l | awk '{if($1>=8) print "OK: " $1 " recipes"; else print "FAIL"}'`
 
 See [REFERENCE.md](REFERENCE.md) for template.
 

package/.pi/prompts/develop-tdd.md

@@ -148,6 +148,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/.pi/prompts/kickoff-branch.md

@@ -31,7 +31,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/.pi/prompts/verify-work.md

@@ -15,6 +15,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
 
@@ -23,6 +24,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).
@@ -90,6 +97,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/.pi/skills/build-epic/SKILL.md

@@ -48,6 +48,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/.pi/skills/compose-workflow/SKILL.md

@@ -12,16 +12,40 @@ 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.
+Reference them in AGENTS.md so `/command` directly invokes the matching recipe.
+
+| Command | Workflow | Skill chain |
+|---------|----------|-------------|
+| `/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 → request-review |
+| `/plan` | plan | survey-context → research-first → plan-work |
+| `/build-fix` | build-fix | investigate-bug → diagnose-root → develop-tdd → validate-fix |
+| `/e2e` | e2e | smoke-test → verify-work |
+
+Add to `AGENTS.md`:
+```
+/check-stack = compose-workflow check-stack
+/ship        = compose-workflow ship
+```
+
 ## Verify
 
-→ verify: `test -f specs/WORKFLOW-*.md && grep -c "verify:" specs/WORKFLOW-*.md | awk '{if($1>0) print "OK"}'`
+→ verify: `ls specs/workflows/*.yaml 2>/dev/null | wc -l | awk '{if($1>=8) print "OK: " $1 " recipes"; else print "FAIL"}'`
 
 See [REFERENCE.md](REFERENCE.md) for template.
 

package/.pi/skills/develop-tdd/SKILL.md

@@ -150,6 +150,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/.pi/skills/kickoff-branch/SKILL.md

@@ -33,7 +33,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/.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,22 @@
+# [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)
+
+
+### Features
+
+* **compose-workflow:** add standard recipe library with 8 agentic stack workflows ([2d61aed](https://github.com/danielvm-git/bigpowers/commit/2d61aedb60a5ee881d568b23cb922d49ee896990))
+
 # [2.24.0](https://github.com/danielvm-git/bigpowers/compare/v2.23.0...v2.24.0) (2026-06-22)
 
 

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **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:28:01Z
+**Generated:** 2026-06-22T03:20:14Z
 **Skills:** 68
 
 ---

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,15 +11,39 @@ 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.
+Reference them in AGENTS.md so `/command` directly invokes the matching recipe.
+
+| Command | Workflow | Skill chain |
+|---------|----------|-------------|
+| `/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 → request-review |
+| `/plan` | plan | survey-context → research-first → plan-work |
+| `/build-fix` | build-fix | investigate-bug → diagnose-root → develop-tdd → validate-fix |
+| `/e2e` | e2e | smoke-test → verify-work |
+
+Add to `AGENTS.md`:
+```
+/check-stack = compose-workflow check-stack
+/ship        = compose-workflow ship
+```
+
 ## Verify
 
-→ verify: `test -f specs/WORKFLOW-*.md && grep -c "verify:" specs/WORKFLOW-*.md | awk '{if($1>0) print "OK"}'`
+→ verify: `ls specs/workflows/*.yaml 2>/dev/null | wc -l | awk '{if($1>=8) print "OK: " $1 " recipes"; else print "FAIL"}'`
 
 See [REFERENCE.md](REFERENCE.md) for template.

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/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.24.0",
+  "version": "2.26.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/skills-lock.json

@@ -18,7 +18,7 @@
     },
     "build-epic": {
       "description": "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.",
-      "sha256": "b7049084cd180053",
+      "sha256": "7a376ef092fde9cc",
       "path": "build-epic/SKILL.md"
     },
     "change-request": {
@@ -33,7 +33,7 @@
     },
     "compose-workflow": {
       "description": "Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. Use when a project repeats a non-standard skill sequence, or user wants a documented playbook beyond orchestrate-project modes.",
-      "sha256": "dc9abafd52cde7b3",
+      "sha256": "854e272ca7bd6e3a",
       "path": "compose-workflow/SKILL.md"
     },
     "craft-skill": {
@@ -73,7 +73,7 @@
     },
     "develop-tdd": {
       "description": "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md).",
-      "sha256": "6ace47f7db4642d4",
+      "sha256": "e050f400da14eff3",
       "path": "develop-tdd/SKILL.md"
     },
     "diagnose-root": {
@@ -148,7 +148,7 @@
     },
     "kickoff-branch": {
       "description": "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions \"start a branch\" or \"new worktree\".",
-      "sha256": "77864a4086f91f60",
+      "sha256": "d3c74c05a8d790c0",
       "path": "kickoff-branch/SKILL.md"
     },
     "map-codebase": {
@@ -318,7 +318,7 @@
     },
     "verify-work": {
       "description": "Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.",
-      "sha256": "d1aeab669a9c5621",
+      "sha256": "44f96eac8380c15b",
       "path": "verify-work/SKILL.md"
     },
     "visual-dashboard": {

package/verify-work/SKILL.md

@@ -16,6 +16,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
 
@@ -24,6 +25,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).
@@ -91,6 +98,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"`