bigpowers 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [1.3.1](https://github.com/danielvm-git/bigpowers/compare/v1.3.0...v1.3.1) (2026-06-02)
+
+
+### Bug Fixes
+
+* **ci:** repair sync-skills sed and refresh package-lock ([29d6e7c](https://github.com/danielvm-git/bigpowers/commit/29d6e7cee82ab25eae5188628d1ae2bc73c99e57))
+* **ci:** use Node 22 for semantic-release workflow ([43edf78](https://github.com/danielvm-git/bigpowers/commit/43edf7801ef06714861e16ed833e6b8b4c3eb66c))
+
+# [1.3.0](https://github.com/danielvm-git/bigpowers/compare/v1.2.3...v1.3.0) (2026-06-02)
+
+
+### Features
+
+* **specs:** complete YAML cockpit cohesion migration ([0a3cf16](https://github.com/danielvm-git/bigpowers/commit/0a3cf16b8030ef6b87ad5113b15265c76ea012c5))
+
 ## [1.2.3](https://github.com/danielvm-git/bigpowers/compare/v1.2.2...v1.2.3) (2026-05-31)
 
 

package/CLAUDE.md

@@ -4,7 +4,7 @@ Read CONVENTIONS.md before any GitHub or git operation.
 
 ## Project
 
-bigpowers — 59 agent skills for spec-driven, test-first software development by solo developers.
+bigpowers — 61 agent skills for spec-driven, test-first software development by solo developers.
 Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
 
 ## Commands
@@ -16,11 +16,12 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 | Test    | N/A (documentation project) |
 | Build   | `bash scripts/install.sh` (from source) |
 | Lint    | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |
+| Validate specs YAML | `bash scripts/validate-specs-yaml.sh` |
 | Compliance | `npm run compliance` |
 
 ## Architecture
 
-Collection of 59 verb-noun skills, each with a SKILL.md source file and supporting documentation. LLM-maintained wiki layer lives in `specs/wiki/`; run `maintain-wiki` sync before merge. Obsidian cockpit: open `specs/` as vault, landing page `COCKPIT.md` (see `profiles/obsidian-wiki.md`). Includes Verify phase (verify-work, run-evals) and optional stack profiles in profiles/. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.
+Collection of 61 verb-noun skills, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/requirements/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
 
 ## Conventions
 
@@ -49,8 +50,8 @@ Before any task, run this sequence — not optional:
 
 1. Read `CLAUDE.md` (this file)
 2. Read `CONVENTIONS.md`
-3. Read `specs/STATE.md` if it exists — current milestone and pending work
-4. Read `specs/RELEASE-PLAN.md` if it exists — active release context
+3. Read `specs/state.yaml` if it exists — current session and active epic
+4. Read `specs/release-plan.yaml` if it exists — active release context
 
 ## Agent Rules
 

package/CONVENTIONS.md

@@ -34,7 +34,7 @@ You are operating within the `bigpowers` spec-driven development methodology.
 - **No Direct Coding:** When a user issues a directive like "build feature X" or "go epic 10", you MUST NOT execute the request by writing code directly.
 - **Required Skills:** You MUST route all work through the appropriate bigpowers skills.
   - Start with `survey-context` if you lack context.
-  - Use `plan-work` to generate a verifiable plan in `specs/PLAN.md` before writing any feature code.
+  - Use `plan-work` to flesh out tasks in `specs/epics/eNN-*.yaml` (with `verify:` per task) before writing any feature code.
   - Use `develop-tdd` or `execute-plan` to implement the plan.
   - Use `investigate-bug` for bug reports before writing a fix.
 - **Verification Mandate:** Every story implementation MUST end with a step-by-step manual verification script provided to the user. You must wait for the user to confirm behavioral correctness (UAT) before declaring the story done or moving to the next.
@@ -43,20 +43,62 @@ You are operating within the `bigpowers` spec-driven development methodology.
 
 ## specs/ — All Planning Output Goes Here
 
-Every skill that produces written output writes to `specs/` at the project root:
+Every skill that produces written output writes to `specs/` at the project root.
+
+### YAML cockpit (runtime + delivery)
+
+| Layer | File | Answers |
+|-------|------|---------|
+| Session | `specs/state.yaml` | Active flow, epic/bug, ship-epic step, git |
+| Release index | `specs/release-plan.yaml` | Target semver, WSJF epic list, pointers to `epics/` |
+| Progress | `specs/execution-status.yaml` | Flat status keys (`e01`, `e01s01`) — sole SoT for story state |
+| Planning UI | `specs/planning-status.yaml` | Discover-phase workflow checklist (optional) |
+
+**Do not** put story status in `release-plan.yaml`. **Do not** duplicate the release plan inside `state.yaml`.
+
+### Intent vs delivery vs execution
+
+| Question | File | Format |
+|----------|------|--------|
+| What should the product do? | `specs/requirements/SCOPE_LATEST.yaml` | YAML |
+| North star / initiative | `specs/requirements/VISION_LATEST.yaml` | YAML |
+| Glossary | `specs/requirements/GLOSSARY_LATEST.yaml` | YAML |
+| What ships in this release, in what order? | `specs/release-plan.yaml` | YAML |
+| How to implement an epic/story? | `specs/epics/eNN-*.yaml` or `specs/epics/eNN-*/stories/` | YAML + MD |
+| Where are we in the session? | `specs/state.yaml` | YAML |
+
+Epic IDs: `e01`, `e30`. Story IDs: `e01s01`. One FR in SCOPE may span multiple epics or releases.
+
+### Frozen release (ex-baseline)
+
+When planning closes, copy to `specs/requirements/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
+
+### Semantic-release — three places
+
+1. **Planning intent** — `specs/release-plan.yaml` → `release.version`, `release.bump_hint` (minor/patch/major expectation).
+2. **Published version** — repo root: `package.json`, git tag `vX.Y.Z`, `CHANGELOG.md` (CI semantic-release; not hand-edited in specs).
+3. **Dashboard optional** — `specs/state.yaml` → `release.last_tag`, `release.last_publish` (from tags/CI).
+
+### Guardrails and other artifacts
 
 | Document | Path |
 |----------|------|
-| Domain context + ADRs | `specs/CONTEXT.md` + `specs/adr/` |
-| Domain glossary | `specs/UBIQUITOUS_LANGUAGE.md` |
-| Scope definition | `specs/SCOPE.md` |
-| Task breakdown | `specs/TASKS.md` |
-| Implementation plan | `specs/PLAN.md` (or `specs/PLAN-<feature>.md`) |
-| Project README | `README.md` (project root) |
-| Refactor plan | `specs/REFACTOR.md` |
-| Spike learnings | `specs/SPIKE-<name>.md` |
-| Bug investigation | `specs/bugs/BUG-*.md` |
-| QA session log | `specs/bugs/BUG-LOG.md` |
+| Stack / architecture | `specs/plans/TECH_STACK_LATEST.md` |
+| Security / test / design plans | `specs/plans/*_PLAN_LATEST.md` |
+| Domain context + ADRs | `specs/plans/TECH_STACK_LATEST.md` or legacy `specs/CONTEXT.md` + `specs/adr/` |
+| Bug investigation | `specs/bugs/BUG-*.md` + `specs/bugs/registry.yaml` (generated) |
+| Refactor / impact | `specs/plans/REFACTOR_LATEST.md`, `specs/plans/IMPACT_LATEST.md` |
+| Legacy markdown | `specs/archive/` after `bash scripts/convert-legado.sh` |
+
+Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys: `bash scripts/bp-yaml-set.sh specs/state.yaml git.branch feat/foo`.
+
+### Legacy paths (migrate away)
+
+| Old | New |
+|-----|-----|
+| `specs/STATE.md` | `specs/state.yaml` |
+| `specs/RELEASE-PLAN.md` | `specs/release-plan.yaml` + `specs/epics/` |
+| `specs/SCOPE.md` | `specs/requirements/SCOPE_LATEST.yaml` |
 
 ## Code Style
 
@@ -76,7 +118,7 @@ Every skill that produces written output writes to `specs/` at the project root:
 - Remove dead code (G9/F4): unused functions, unreachable branches, and stale imports must be deleted — not commented out.
 - Boy Scout Rule: leave every file you touch at least as clean as you found it. Fix the first broken window you see.
 - **Law of Demeter:** A method should call only its immediate collaborators — not `a.getB().getC().doX()`. Chain violations need explicit justification in code review.
-- **Verification mandate:** Every story in `specs/RELEASE-PLAN.md` must include a `## Verification Script`. No story is done until `verify-work` confirms it (or user explicitly waives with documented reason in STATE.md).
+- **Verification mandate:** Every story must include runnable `verify:` commands (in epic shards or story files). No story is done until `verify-work` confirms it (or user explicitly waives with documented reason in `specs/state.yaml` handoff).
 - Exception messages must include the offending value, expected shape, and an actionable remediation hint for the agent.
 - SOLID beyond SRP: favor interfaces over concrete types (DIP) when injecting dependencies.
 

package/README.md

@@ -2,9 +2,9 @@
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 ![npm version](https://img.shields.io/npm/v/bigpowers.svg)
-![Skills](https://img.shields.io/badge/skills-59-brightgreen.svg)
+![Skills](https://img.shields.io/badge/skills-61-brightgreen.svg)
 
-**59 agent skills for high-integrity, spec-driven, test-first software development by solo developers.**
+**61 agent skills for high-integrity, spec-driven, test-first software development by solo developers.**
 
 `bigpowers` provides a prescriptive, vertical-slice methodology for building software with AI agents (Claude Code, Gemini CLI, Cursor). It bridges the gap between raw LLM capabilities and professional engineering standards.
 
@@ -114,11 +114,12 @@ Every task in `bigpowers` follows a prescriptive lifecycle (see `SKILL-INDEX.md`
 | Level | Document | Responsibility |
 | :--- | :--- | :--- |
 | **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
-| **Context** | `specs/CONTEXT.md` | Tech stack, architecture, and glossary. |
-| **Scope** | `specs/SCOPE.md` | In-scope / out-of-scope and success criteria. |
+| **Context** | `specs/plans/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
+| **Scope** | `specs/requirements/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
+| **Vision** | `specs/requirements/VISION_LATEST.yaml` | North star and initiative success criteria. |
 | **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |
-| **Roadmap** | `specs/RELEASE-PLAN.md` | WSJF-prioritized releases and stories. |
-| **Current** | `specs/STATE.md` | Current milestone and session progress. |
+| **Roadmap** | `specs/release-plan.yaml` + `specs/epics/` | WSJF-prioritized epics and stories. |
+| **Current** | `specs/state.yaml` | Session flow, active epic, handoff. |
 | **Index** | `SKILL-INDEX.md` | Canonical list of all active skills. |
 | **Style** | `CONVENTIONS.md` | Coding, testing, and naming standards. |
 
@@ -127,9 +128,10 @@ Every task in `bigpowers` follows a prescriptive lifecycle (see `SKILL-INDEX.md`
 ## 📁 Project Structure
 
 - `scripts/`: Installation, syncing, and compliance tools.
-- `specs/`: The "Brain" of your project — all planning and decisions live here.
+- `specs/`: The "Brain" of your project — all planning and decisions live here (YAML cockpit: `state.yaml`, `release-plan.yaml`, `epics/`, `requirements/`).
+- `specs/wiki/`: Deprecated Obsidian layer — use `visual-dashboard` HTTP cockpit instead of `maintain-wiki`.
 - `docs/references/`: Theoretical foundations (Uncle Bob, Ousterhout, Karpathy, etc.).
-- `[skill-name]/`: Source files for each of the 59 skills.
+- `[skill-name]/`: Source files for each of the 61 skills.
 
 ---
 

package/SKILL-INDEX.md

@@ -2,7 +2,7 @@
 
 **Purpose:** One canonical reference for all bigpowers skills. Referenced by README.md, RELEASE-PLAN.md, and CONVENTIONS.md. Updated per-release.
 
-**Last updated:** 2026-05-31 (v3.0.0 — maintain-wiki + Obsidian wiki layer; 59 active, 0 planned, Verify phase)
+**Last updated:** 2026-06-02 (v3.0.0 — YAML cockpit; 61 active, 0 planned; maintain-wiki removed; build-epic, run-planning, fix-bug added)
 
 ---
 
@@ -17,15 +17,15 @@
 | **Plan** | 8 | assess-impact, change-request, scope-work, slice-tasks, define-success, plan-work, plan-refactor, plan-release |
 | **Spike** | 1 | spike-prototype |
 | **Initiate** | 4 | kickoff-branch, guard-git, hook-commits, seed-conventions |
-| **Build** | 5 | develop-tdd, enforce-first, delegate-task, dispatch-agents, execute-plan |
+| **Build** | 8 | develop-tdd, enforce-first, delegate-task, dispatch-agents, execute-plan, build-epic, run-planning, fix-bug |
 | **Harden** | 1 | wire-observability |
 | **Verify** | 2 | verify-work, run-evals |
 | **Bug** | 3 | investigate-bug, diagnose-root, validate-fix |
 | **Review** | 4 | audit-code, request-review, respond-review, trace-requirement |
 | **Integrate** | 2 | commit-message, release-branch |
 | **Sustain** | 4 | inspect-quality, organize-workspace, stocktake-skills, evolve-skill |
-| **Utility** | 13 | terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard, write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents, maintain-wiki |
-| **TOTAL** | **59** | |
+| **Utility** | 12 | terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard, write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents |
+| **TOTAL** | **61** | |
 
 ---
 
@@ -82,7 +82,7 @@
 | 47 | Utility | `terse-mode` | Ultra-terse output (fallback) | (prompt) | ✅ Active |
 | 48 | Utility | `craft-skill` | Build new bigpowers skill | skills/<name>/SKILL.md | ✅ Active |
 | 49 | Utility | `edit-document` | Edit documents in specs/ | specs/<name>.md | ✅ Active |
-| 50 | Utility | `session-state` | Track decisions in STATE.md | STATE.md | ✅ Active |
+| 50 | Utility | `session-state` | Track decisions in state.yaml | state.yaml | ✅ Active |
 | 51 | Utility | `migrate-spec` | Migrate foreign spec formats | specs/ | ✅ Active |
 | 52 | Utility | `visual-dashboard` | Browser dashboard | .bigpowers/dashboard/ | ✅ Active |
 | 53 | Utility | `write-document` | BMAD technical documents | specs/<name>.md | ✅ Active |
@@ -91,9 +91,11 @@
 | 56 | Utility | `search-skills` | Natural language → right skill | SKILL-SEARCH-INDEX.md | ✅ Active |
 | 57 | Utility | `compose-workflow` | Chain skills into workflow recipe | WORKFLOW-<name>.md | ✅ Active |
 | 58 | Utility | `simulate-agents` | Mock User + Auditor simulation | SIMULATION-<feature>.md | ✅ Active |
-| 59 | Utility | `maintain-wiki` | LLM wiki sync / ingest / lint | specs/wiki/ | ✅ Active |
+| 59 | Build | `build-epic` | Eight-step epic build cycle | state.yaml, epics/ | ✅ Active |
+| 60 | Build | `run-planning` | Discover-phase workflow tracker | planning-status.yaml | ✅ Active |
+| 61 | Bug | `fix-bug` | Bug fix orchestrator | bugs/BUG-*.md | ✅ Active |
 
-**Total: 59 ✅ Active, 0 📋 Planned.**
+**Total: 61 ✅ Active, 0 📋 Planned.**
 
 ---
 
@@ -113,13 +115,15 @@ survey-context → research-first → elaborate-spec → map-codebase
                          ↓
        [Unknown domain?] spike-prototype → (learnings feed back to plan-work)
                          ↓
-  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents / execute-plan
+  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents / execute-plan / build-epic
+                         ↓
+  run-planning (discover workflows → planning-status.yaml)
                          ↓
         wire-observability (production-readiness gate, any phase)
                          ↓
               ★ VERIFY ★  run-evals → verify-work  (prove it works)
                          ↓
-    investigate-bug → diagnose-root → validate-fix
+    fix-bug → investigate-bug → diagnose-root → validate-fix
                          ↓
       audit-code → request-review → respond-review → trace-requirement
                          ↓
@@ -129,8 +133,7 @@ survey-context → research-first → elaborate-spec → map-codebase
 
 Transversal utilities (any phase):
   terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard,
-  write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents,
-  maintain-wiki
+  write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents
 ```
 
 ---

package/assess-impact/SKILL.md

@@ -27,9 +27,9 @@ git log --oneline -10 -- [file-path]
 
 ### 3. Map to release plan stories
 
-Read `specs/RELEASE-PLAN.md` (if it exists). For each dependent found in Step 2, identify which story owns that module. List stories that will be affected by the change.
+Read `specs/release-plan.yaml + epic shards` (if it exists). For each dependent found in Step 2, identify which story owns that module. List stories that will be affected by the change.
 
-→ verify: `grep -c "Story" specs/RELEASE-PLAN.md 2>/dev/null || echo "no release plan"`
+→ verify: `grep -c "Story" specs/release-plan.yaml + epic shards 2>/dev/null || echo "no release plan"`
 
 ### 4. List test coverage
 

package/build-epic/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: build-epic
+model: sonnet
+description: Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic shard; 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.
+---
+
+# Build Epic
+
+Orchestrates the **build** flow for a single epic: survey → plan tasks → kickoff → TDD → verify → audit → commit → release.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: build_epic` and `active_epic: eNN` before starting.
+>
+> **HARD GATE** — Not on `main`/`master` before step 3 (kickoff-branch).
+
+## Eight steps (`epic_cycle` in state.yaml)
+
+| Step | Skill / action |
+|------|----------------|
+| 1 | `survey-context` — confirm epic + story |
+| 2 | `plan-work` — flesh out story `tasks[]` in `specs/epics/eNN-*.yaml` |
+| 3 | `kickoff-branch` — feature branch + clean baseline |
+| 4 | `develop-tdd` — red-green per task |
+| 5 | `verify-work` — UAT + mechanical gates |
+| 6 | `audit-code` — self-review checklist |
+| 7 | `commit-message` — Conventional Commits draft |
+| 8 | `release-branch` — PR or solo land |
+
+## Process
+
+1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-*.yaml`.
+2. If `epic_cycle.step` missing, set to `1`.
+3. Run **only the current step** (resume mode) unless user asked for full auto-run.
+4. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
+5. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
+
+## Handoff
+
+Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.
+
+## Verify
+
+→ verify: `grep -q 'active_flow: build_epic' specs/state.yaml && test -f specs/epics/*.yaml`

package/change-request/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: change-request
 model: sonnet
-description: Add a new requirement or reorder epics by WSJF value engineering against specs/RELEASE-PLAN.md. Two modes: Add (intake a new requirement mid-flight) and Reorder (re-score and re-sort all epics/stories). Use when a new requirement arrives mid-release, or when the plan needs prioritization.
+description: Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml and epic shards. Modes Add and Reorder. Use when a new requirement arrives mid-release or the plan needs prioritization.
 ---
 
 # Change Request
 
-> **HARD GATE** — `specs/RELEASE-PLAN.md` must exist before running either mode. If it doesn't, run `plan-release` first.
+> **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first.
 >
-> → verify: `[ -f specs/RELEASE-PLAN.md ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+> → verify: `[ -f specs/release-plan.yaml ] && echo "ready" || echo "BLOCKED: run plan-release first"`
 
 Two modes. State which one you want or the skill will ask.
 
@@ -17,27 +17,27 @@ Two modes. State which one you want or the skill will ask.
 Intake a new requirement mid-flight without disrupting work in progress.
 
 1. **Capture**: What is the change? What problem does it solve?
-2. **Locate**: Which existing stories does it affect or replace?
-3. **Draft**: Write the new story in RELEASE-PLAN.md format (with Gherkin AC and tasks + verify commands).
-4. **Place**: Append as a new story under an existing epic, or open a new epic if needed.
-5. **Score**: Compute WSJF score for the new story; note if it outranks in-progress work.
+2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace?
+3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`).
+4. **Place**: Append story under existing epic shard, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`.
+5. **Score**: Compute WSJF; note if it outranks in-progress work.
 
-→ verify: `grep -c "Story" specs/RELEASE-PLAN.md`
+→ verify: `grep -c 'stories:' specs/epics/*.yaml`
 
 ## Mode B — Reorder
 
-Value-engineering pass over the full release plan using WSJF.
+Value-engineering pass over the full release using WSJF.
 
 See [REFERENCE.md](REFERENCE.md) for the full WSJF scoring rubric.
 
-1. **Score** each epic/story: Business Value (1–10) + Time Criticality (1–10) + Risk Reduction (1–10) / Job Size (1–10).
-2. **Re-sort** epics and stories by WSJF score descending.
-3. **Flag cut candidates**: stories where Effort is L and Value is Low (WSJF < 1.5).
-4. **Update** `specs/RELEASE-PLAN.md` — add WSJF scores, new order, short rationale for any reordering.
-5. **Report** the delta: what moved up, what moved down, what is a cut candidate.
+1. **Score** each epic/story: BV + TC + RR / Job Size.
+2. **Re-sort** `release-plan.yaml` `epics[]` and per-epic `wsjf` fields.
+3. **Flag cut candidates**: WSJF < 1.5.
+4. **Update** `specs/release-plan.yaml` and epic `wsjf` keys with rationale.
+5. **Report** the delta.
 
-→ verify: `grep -c "WSJF:" specs/RELEASE-PLAN.md`
+→ verify: `grep -c 'wsjf' specs/release-plan.yaml specs/epics/*.yaml`
 
 ## After either mode
 
-Suggest `plan-work` for the top-ranked unstarted story.
+Run `bash scripts/sync-status-from-epics.sh`. Suggest `plan-work` or `build-epic` for the top-ranked unstarted story.

package/compose-workflow/REFERENCE.md

@@ -7,7 +7,7 @@
 
 | Step | Skill | Output | verify |
 |------|-------|--------|--------|
-| 1 | survey-context | STATE.md | ... |
-| 2 | research-first | Prior Art | ... |
-| 3 | plan-work | RELEASE-PLAN.md | ... |
+| 1 | survey-context | state.yaml handoff | ... |
+| 2 | research-first | Prior Art in SCOPE_LATEST.yaml | ... |
+| 3 | plan-work | epics/eNN-*.yaml tasks | ... |
 ```

package/compose-workflow/SKILL.md

@@ -13,7 +13,7 @@ model: sonnet
    - Trigger ("Use when...")
    - Ordered steps: `skill → artefact → verify`
    - HARD GATEs between phases
-3. Register in STATE.md Active Decisions.
+3. Register in state.yaml Active Decisions.
 4. Optional: reference from `orchestrate-project` Ad-Hoc mode.
 
 ## Verify

package/deepen-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: deepen-architecture
 model: sonnet
-description: Find deepening opportunities in a codebase, informed by the domain language in specs/CONTEXT.md and the decisions in specs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+description: Find deepening opportunities in a codebase, informed by the domain language in specs/plans/TECH_STACK_LATEST.md and the decisions in specs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
 ---
 
 # Deepen Architecture
@@ -27,7 +27,7 @@ Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
 - **The interface is the test surface.**
 - **One adapter = hypothetical seam. Two adapters = real seam.**
 
-This skill is _informed_ by the project's domain model — `specs/CONTEXT.md` and any `specs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../model-domain/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md).
+This skill is _informed_ by the project's domain model — `specs/plans/TECH_STACK_LATEST.md` and any `specs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../model-domain/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md).
 
 ## Process
 
@@ -35,7 +35,7 @@ This skill is _informed_ by the project's domain model — `specs/CONTEXT.md` an
 
 Read existing documentation first:
 
-- `specs/CONTEXT.md` (or `specs/CONTEXT-MAP.md` + each `specs/CONTEXT.md` in a multi-context repo)
+- `specs/plans/TECH_STACK_LATEST.md` (or `specs/CONTEXT-MAP.md` + each `specs/plans/TECH_STACK_LATEST.md` in a multi-context repo)
 - Relevant ADRs in `specs/adr/`
 
 If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront.
@@ -71,7 +71,7 @@ Present a numbered list of deepening opportunities. For each candidate:
 - **Solution** — plain English description of what would change
 - **Benefits** — explained in terms of locality and leverage, and how tests would improve
 
-**Use `specs/CONTEXT.md` vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.**
+**Use `specs/plans/TECH_STACK_LATEST.md` vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.**
 
 **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly. Don't list every theoretical refactor an ADR forbids.
 
@@ -83,7 +83,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
 
 Side effects happen inline as decisions crystallize:
 
-- **Naming a deepened module after a concept not in `specs/CONTEXT.md`?** Add the term to `specs/CONTEXT.md` — same discipline as `model-domain` (see [CONTEXT-FORMAT.md](../model-domain/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
-- **Sharpening a fuzzy term during the conversation?** Update `specs/CONTEXT.md` right there.
+- **Naming a deepened module after a concept not in `specs/plans/TECH_STACK_LATEST.md`?** Add the term to `specs/plans/TECH_STACK_LATEST.md` — same discipline as `model-domain` (see [CONTEXT-FORMAT.md](../model-domain/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `specs/plans/TECH_STACK_LATEST.md` right there.
 - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md).
 - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

package/define-success/SKILL.md

@@ -16,7 +16,7 @@ Transform "do X" into "step → verify: <cmd>" pairs. This is the pre-flight che
 
 ### 1. Read the task statement
 
-Take the task as stated (from conversation, or from `specs/TASKS.md`, or from `specs/SCOPE.md`).
+Take the task as stated (from conversation, or from `specs/epics/ (see slice-tasks)`, or from `specs/requirements/SCOPE_LATEST.yaml`).
 
 ### 2. Break into observable outcomes
 

package/delegate-task/SKILL.md

@@ -14,7 +14,7 @@ Delegate a single complex task to a subagent with a two-stage review gate before
 
 ### 1. Define the task
 
-Before spawning the agent, read `specs/STATE.md` if it exists. Then write a minimal self-contained brief using this template (brief size directly controls token cost and hallucination risk — do not pad):
+Before spawning the agent, read `specs/state.yaml` if it exists. Then write a minimal self-contained brief using this template (brief size directly controls token cost and hallucination risk — do not pad):
 
 ```
 Goal: [one sentence — specific, measurable outcome]
@@ -22,14 +22,14 @@ In scope: [explicit file or module list]
 Out of bounds: [what NOT to do]
 Constraints: [relevant CONVENTIONS.md rules, existing patterns, test requirements]
 Verify: [runnable command]
-Prior decisions: [relevant entries from specs/STATE.md — omit section if none apply]
+Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply]
 ```
 
 Do not include full file contents, full conversation history, or decisions unrelated to this task.
 
 ### 2. Spawn the subagent (iterative retrieval, max 3 cycles)
 
-Use the Agent tool with a **fresh context** per spawn. Pass prior decisions only via `specs/STATE.md`.
+Use the Agent tool with a **fresh context** per spawn. Pass prior decisions only via `specs/state.yaml`.
 
 **Cycle:** dispatch → evaluate output vs goal → refine brief → re-spawn if needed (max 3 cycles).
 
@@ -67,7 +67,7 @@ Check:
 - **Revise**: send back to the subagent with specific feedback
 - **Reject**: discard and re-approach differently
 
-**After accepting**, append to `specs/STATE.md` under `## Active Decisions`:
+**After accepting**, append to `specs/state.yaml` under `## Active Decisions`:
 ```
 **[task short name]**: [what approach the agent chose and why — one sentence]
 ```

package/develop-tdd/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: develop-tdd
 model: sonnet
-description: Test-driven development with red-green-refactor loop using vertical slices. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, asks for test-first development, or wants to implement a task from specs/PLAN.md.
+description: Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md).
 ---
 
 # Develop TDD
 
 > **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first to create a feature branch or worktree.
 >
-> **HARD GATE** — Do NOT write code before you have a plan. If you are starting a new task, run `plan-work` to create `specs/RELEASE-PLAN.md`. If you are fixing a bug, run `investigate-bug` to create `specs/bugs/BUG-*.md`.
+> **HARD GATE** — Do NOT write code before you have a plan. New feature: `plan-work` → epic shard tasks. Bug: `investigate-bug` → `specs/bugs/BUG-*.md` (or use `fix-bug` orchestrator).
 >
 > **RECURSIVE DISCIPLINE** — This lifecycle apply to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
 
@@ -65,7 +65,7 @@ If you find yourself thinking these things, you are likely deviating from produc
 
 Before writing any code:
 
-- [ ] Read `specs/RELEASE-PLAN.md` or `specs/bugs/BUG-*.md` if they exist — understand the task and verify steps
+- [ ] Read active `specs/epics/*.yaml` story tasks or `specs/bugs/BUG-*.md` — understand verify steps
 - [ ] Confirm with user what interface changes are needed
 - [ ] Confirm with user which behaviors to test (prioritize)
 - [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
@@ -136,12 +136,12 @@ After all tests pass, look for [refactor candidates](refactoring.md):
 
 ### 5. Verify step
 
-After every behavior cycle, run the verify command from `specs/RELEASE-PLAN.md` if one exists for this step. Show evidence before declaring the step done.
+After every behavior cycle, run the verify command from the active epic task if one exists. Show evidence before declaring the step done.
 
 ### 6. Manual Verification Handover
 
 Once the story is complete and all tests pass:
-1. Locate the **Verification Script** in `specs/RELEASE-PLAN.md` for this story.
+1. Locate the **Verification Script** in the active epic shard (`specs/epics/`) for this story.
 2. Present the script to the user as a step-by-step guide.
 3. Wait for the user to confirm the behavioral correctness before moving to the next story or declaring the task done.
 

package/dispatch-agents/SKILL.md

@@ -35,7 +35,7 @@ If any two tasks conflict, sequence them with `delegate-task` or `execute-plan`
 
 ### 2. Write task briefs
 
-Before writing briefs, read `specs/STATE.md` if it exists — each agent gets only the decisions relevant to its task, nothing else.
+Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else.
 
 For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk):
 
@@ -44,7 +44,7 @@ Goal: [one sentence — what success looks like]
 In scope: [explicit file or module list]
 Out of bounds: [what NOT to touch]
 Verify: [runnable command]
-Prior decisions: [relevant entries from specs/STATE.md — omit section if none apply]
+Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply]
 ```
 
 Do not include the full conversation, full file contents, or decisions unrelated to this agent's task.

package/evolve-skill/SKILL.md

@@ -10,7 +10,7 @@ model: opus
 
 ## Loop
 
-1. Run `bigpowers-benchmark` (external repo); save report path in STATE.md.
+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`.
@@ -19,6 +19,6 @@ model: opus
 
 ## Verify
 
-→ verify: benchmark report shows post-change score ≥ baseline (document paths in STATE.md)
+→ verify: benchmark report shows post-change score ≥ baseline (document paths in state.yaml)
 
 See [REFERENCE.md](REFERENCE.md) for ADR template.