bigpowers 1.2.3 → 1.3.0

package/execute-plan/SKILL.md

@@ -1,92 +1,55 @@
 ---
 name: execute-plan
 model: haiku
-description: Batch-execute tasks from specs/RELEASE-PLAN.md sequentially, with a human checkpoint after each step. Use when user has an approved plan and wants to execute it step-by-step with oversight, or mentions "execute the plan" or "run the plan".
+description: Batch-execute tasks from the active epic shard sequentially, with a human checkpoint after each step. Use when user has an approved plan and wants step-by-step oversight.
 ---
 
 # Execute Plan
 
-Execute the tasks in `specs/RELEASE-PLAN.md` one at a time, showing evidence after each step before proceeding.
+Execute tasks from the **active epic** (`specs/epics/eNN-*.yaml` story `tasks[]`) one at a time, showing evidence after each step before proceeding.
 
-> **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 proceed if on `main` or `master`. Run `kickoff-branch` first.
 >
-> **HARD GATE** — Do NOT execute a plan if `specs/RELEASE-PLAN.md` does not exist or if its tasks lack runnable `verify:` commands. If the plan is missing or weak, run `plan-release` then `plan-work` first.
+> **HARD GATE** — Active epic must exist with runnable `verify` on each task. If missing, run `plan-release` then `plan-work` or `build-epic`.
 
 ## Process
 
 ### 1. Read the plan
 
-Read `specs/RELEASE-PLAN.md` in full. Parse `depends-on:` fields from `specs/TASKS.md` or story steps to build **execution waves** (steps with no unresolved deps run in parallel when user approves).
+Read `specs/state.yaml` (`active_epic`, `active_story`) and the matching `specs/epics/*.yaml`. Parse `depends-on` in task descriptions for execution waves.
 
-> **CONTEXT ISOLATION** — Spawn each skill invocation (via `delegate-task` / subagent) with a **fresh context window**. Pass decisions only through `specs/STATE.md` — never rely on chat history from prior spawns.
+> **CONTEXT ISOLATION** — Spawn each skill with a **fresh context window**. Pass decisions only through `specs/state.yaml` `handoff` — never rely on prior chat history.
 
-Confirm with the user:
-- How many steps are there?
-- Any steps to skip or reorder?
-- Should you stop after a specific step?
+Confirm with the user: step count, skip/reorder, stop-after step.
 
 ### 2. Execute step by step
 
-For each step in the plan:
+For each task in the active story:
 
-**a. Announce the step**
-```
-─── Step N of M ─────────────────────────
-Task: [step description]
-verify: [verify command]
-```
+**a. Announce** — task `desc` and `verify` command.
 
-**b. Execute the work**
+**b. Execute** — code or `delegate-task` / `dispatch-agents` for waves.
 
-For **wave execution**: group steps that share no `depends-on:` edges; run wave members in parallel via `dispatch-agents`; wait for all verify commands green before next wave. Use atomic `STATE.md` updates (read-modify-write one block) to avoid race conditions.
+**c. Run verify** — must be green before advancing.
 
-Implement each step using:
-- Write/edit code directly for small focused changes
-- Spawn a subagent via `delegate-task` for complex isolated work (fresh context; read STATE.md first)
+**d. Log** — non-obvious decisions in `specs/state.yaml` under `decisions[]` or `handoff` block.
 
-> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
+**e. Checkpoint** — ask to proceed unless autonomous mode requested.
 
-**c. Run the verify command**
-Every task in `specs/RELEASE-PLAN.md` must have a `verify: <cmd>`. Run it and show the output.
+**f. Story UAT** — after last task, run manual verification script from story notes or `verify-work`.
 
-**d. Log the decision**
-After verify passes, append to `specs/STATE.md` under `## Active Decisions`:
-```
-**Step N — [short name]**: [what approach was chosen and why — one sentence]
-```
-Only log if a non-obvious decision was made (approach chosen, constraint discovered, blocker resolved). Skip if the step was mechanical.
+On verify failure: fix and re-run; never advance on red.
 
-**e. Checkpoint**
-Report the result and ask: "Step N complete. Proceed to step N+1?" (or proceed automatically if the user asked for fully autonomous execution)
+Update `specs/execution-status.yaml` when a story/epic completes (`bash scripts/sync-status-from-epics.sh` or direct edit).
 
-**f. Story Verification (UAT)**
-After the last step of a Story is completed:
-1. Present the **Verification Script** from `specs/RELEASE-PLAN.md` for this story.
-2. Ask the user to perform the manual verification steps.
-3. Wait for the user to confirm "pass" or describe issues.
-4. If issues are reported, log them and stop execution for diagnosis.
+### 3. Blockers
 
-If verify fails:
-- Do NOT move to the next step — never advance on a red verify
-- Diagnose the failure
-- Fix it and re-run verify
-- Loop on this step until the verify command is green
-- Only then proceed to the next step
+Report blocker; ask skip/adapt/stop; update epic shard if plan changes.
 
-If verify passes but behavioral correctness is in doubt, do not advance — a mechanical green is not enough; confirm behavior is correct first.
-
-### 3. Handle blockers
+### 4. Final report
 
-If a step cannot be completed as written:
-- Report the blocker clearly
-- Ask the user whether to skip, adapt, or stop
-- Update `specs/RELEASE-PLAN.md` if the plan needs revision
+Suggest: `verify-work` → `run-evals` → `audit-code` → `simulate-agents` → `commit-message` → `release-branch`
 
-### 4. Final report
+## Rules
 
-After all steps complete:
-```
-✓ Plan complete: N/N steps executed
-All verify commands passed.
-Suggested next: verify-work → run-evals → audit-code → simulate-agents → commit-message → release-branch
-```
+- **Loop until behavioral correctness is verified**: if a verify command passes but the observed behavior is still wrong, return to step 1 and run the execution cycle again.

package/fix-bug/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fix-bug
+model: sonnet
+description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect.
+---
+
+# Fix Bug
+
+Orchestrates **fix_bug** flow without mixing epic build state.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug`.
+
+## Process
+
+1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first (YAML frontmatter + fix plan in file).
+2. `develop-tdd` against the bug file's verify steps.
+3. `validate-fix` — re-run failing test, full suite, lint.
+4. `bash scripts/sync-bugs-registry.sh` — refresh `specs/bugs/registry.yaml`.
+5. Clear `active_flow` or return to `build_epic` when done.
+
+## Bug file SoT
+
+One markdown file per bug with frontmatter:
+
+```yaml
+---
+bug_id: BUG-001
+status: open
+severity: high
+scope: api
+title: Short title
+---
+```
+
+## Verify
+
+→ verify: `test -d specs/bugs && bash scripts/sync-bugs-registry.sh`

package/grill-with-docs/SKILL.md

@@ -10,7 +10,7 @@ model: opus
 
 ## Process
 
-1. Read the plan or design under test (`specs/RELEASE-PLAN.md`, INTERFACE-OPTIONS.md, etc.).
+1. Read the plan or design under test (`specs/release-plan.yaml + epic shards`, INTERFACE-OPTIONS.md, etc.).
 2. List assumptions that depend on external libraries or APIs.
 3. For each assumption: fetch or quote official docs; challenge with "docs say X, plan says Y."
 4. Resolve or update the plan inline; unresolved items block `plan-work`.

package/inspect-quality/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: inspect-quality
 model: sonnet
-description: Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/BUG-LOG.md with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions "QA session".
+description: Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/registry.yaml with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions "QA session".
 ---
 
 # Inspect Quality
 
-Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and log each issue to `specs/bugs/BUG-LOG.md` with a structured, durable format.
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and log each issue to `specs/bugs/registry.yaml` with a structured, durable format.
 
 ## For each issue the user raises
 
@@ -41,11 +41,11 @@ Keep as a single issue when:
 - It's one behavior that's wrong in one place
 - The symptoms are all caused by the same root behavior
 
-### 4. Log to specs/bugs/BUG-LOG.md
+### 4. Log to specs/bugs/registry.yaml
 
-Append the issue to `specs/bugs/BUG-LOG.md`. Create the `specs/bugs/` directory if it doesn't exist.
+Append the issue to `specs/bugs/registry.yaml`. Create the `specs/bugs/` directory if it doesn't exist.
 
-#### BUG-LOG.md format
+#### registry.yaml format
 
 The file maintains a Markdown table with the following columns (derived from structured audit practice):
 

package/investigate-bug/SKILL.md

@@ -14,7 +14,7 @@ Investigate a reported problem, find its root cause, and write a TDD fix plan to
 
 Before starting diagnosis:
 
-1. Read `specs/bugs/BUG-LOG.md` (if it exists) — check for prior bugs in the same `scope` or with similar symptoms.
+1. Read `specs/bugs/registry.yaml` (if it exists) — check for prior bugs in the same `scope` or with similar symptoms.
 2. If a relevant prior bug is found, read the corresponding `specs/bugs/BUG-*.md` file to understand previous root cause analysis and fix approach.
 3. Note in your investigation whether this is a recurrence, a related issue, or novel.
 
@@ -71,7 +71,7 @@ Rules:
 
 Save the investigation and fix plan to `specs/bugs/BUG-YYYY-MM-DDTHHMMSS.md`. Create the `specs/bugs/` directory if it doesn't exist.
 
-After writing, append a row to `specs/bugs/BUG-LOG.md` with: bug_id (same timestamp), date, severity, priority, scope, summary, and file path. Create `specs/bugs/BUG-LOG.md` if it doesn't exist.
+After writing, append a row to `specs/bugs/registry.yaml` with: bug_id (same timestamp), date, severity, priority, scope, summary, and file path. Create `specs/bugs/registry.yaml` if it doesn't exist.
 
 <diagnosis-template>
 

package/kickoff-branch/SKILL.md

@@ -92,4 +92,4 @@ Worktree: ../<task-slug>
 Ready to develop.
 ```
 
-Suggest next skill: `develop-tdd` to start the TDD loop, or `execute-plan` if `specs/RELEASE-PLAN.md` already exists.
+Suggest next skill: `develop-tdd` to start the TDD loop, or `execute-plan` if `specs/release-plan.yaml + epic shards` already exists.

package/map-codebase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: map-codebase
 model: sonnet
-description: "High-fidelity codebase surveying — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists them into specs/CONTEXT.md. Goes beyond survey-context by identifying 'signals' for planning."
+description: "High-fidelity codebase surveying — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists them into specs/plans/TECH_STACK_LATEST.md. Goes beyond survey-context by identifying 'signals' for planning."
 ---
 
 # Map Codebase
@@ -36,8 +36,8 @@ Look for signals that will influence upcoming plans:
 - **Integration Points:** "We need to talk to the Stripe API, but there's no wrapper yet."
 - **Conventions:** "The team always uses functional components over classes."
 
-### 5. Persist to specs/CONTEXT.md
-Compile all findings into `specs/CONTEXT.md`. This file serves as the project's "Long-Term Memory".
+### 5. Persist to specs/plans/TECH_STACK_LATEST.md
+Compile all findings into `specs/plans/TECH_STACK_LATEST.md`. This file serves as the project's "Long-Term Memory".
 
 ```markdown
 # Project Context
@@ -64,4 +64,4 @@ Compile all findings into `specs/CONTEXT.md`. This file serves as the project's
 - When first joining a project.
 - Before a major refactor or architectural change.
 - When `survey-context` reveals a lack of domain knowledge.
-- To refresh `specs/CONTEXT.md` after significant changes.
+- To refresh `specs/plans/TECH_STACK_LATEST.md` after significant changes.

package/migrate-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: migrate-spec
 model: sonnet
-description: Detect GSD, spec-kit, or BMAD spec artifacts in the current project and transform them into bigpowers format (specs/ directory, CONTEXT.md, SCOPE.md, TASKS.md, RELEASE-PLAN.md, ADRs). Use when user has an existing project with foreign spec docs and wants to adopt bigpowers conventions, or says "migrate", "import specs", "convert from GSD/BMAD/spec-kit".
+description: Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers YAML layout (state.yaml, release-plan.yaml, epics/, requirements/, plans/, ADRs). Use when migrating foreign spec docs.
 ---
 
 # Migrate Spec
@@ -23,7 +23,7 @@ Before proceeding, check for these rationalization traps:
 - **Partial artifact set** — only one fingerprint file found (e.g. just `spec.md` with no `plan.md`). Don't assume it's a complete project. Ask: "I found only X — is this the full set of your spec artifacts?"
 - **Wrong trigger** — user said "migrate my code" or "migrate the database", not "migrate my specs". Confirm before running.
 - **Stale source** — source artifacts have commit dates older than 6 months with no recent activity. Flag: "These specs appear inactive since <date>. Are they still the source of truth?"
-- **Active divergence** — source `STATE.md` or `sprint-status.yaml` shows in-progress work. Flag: "There is active work in flight. Migrating now may lose in-progress context. Proceed?"
+- **Active divergence** — source `state.yaml` or `sprint-status.yaml` shows in-progress work. Flag: "There is active work in flight. Migrating now may lose in-progress context. Proceed?"
 
 If any red flag fires: surface it, wait for explicit user confirmation before continuing.
 
@@ -54,7 +54,7 @@ Detected: GSD
 Found:
   ✓ .planning/ROADMAP.md
   ✓ .planning/REQUIREMENTS.md  (12 REQ-XX items)
-  ✓ .planning/STATE.md
+  ✓ .planning/state.yaml
   ✓ .planning/phases/01-auth/01-CONTEXT.md
   ✗ .planning/METHODOLOGY.md  (not present)
 
@@ -80,9 +80,9 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 
 → verify: `ls specs/*.md 2>/dev/null | head -15`
 
-### Step 4 — Generate STATE.md
+### Step 4 — Generate state.yaml
 
-Always regenerate `specs/STATE.md` from scratch in bigpowers format:
+Always regenerate `specs/state.yaml` from scratch in bigpowers format:
 
 ```markdown
 # Session State: <project name>
@@ -107,7 +107,7 @@ Migrated from <framework> on <date>. Next: review generated specs and run plan-w
 - [ ] Run plan-work to produce first release plan
 ```
 
-→ verify: `[ -f specs/STATE.md ] && echo "ok" || echo "MISSING: specs/STATE.md not created"`
+→ verify: `[ -f specs/state.yaml ] && echo "ok" || echo "MISSING: specs/state.yaml not created"`
 
 ### Step 5 — Surface learnings (optional)
 
@@ -115,7 +115,7 @@ After migration, offer the user a brief analysis of what the source framework di
 
 Use the learnings table from [REFERENCE.md](./REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt.
 
-→ verify: `grep -c "\- \[ \]" specs/STATE.md 2>/dev/null && echo "pending items recorded" || echo "no pending items in STATE.md"`
+→ verify: `grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"`
 
 ---
 
@@ -125,18 +125,18 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 | Source | Target |
 |--------|--------|
-| GSD `ROADMAP.md` | `specs/RELEASE-PLAN.md` |
-| GSD `REQUIREMENTS.md` | `specs/SCOPE.md` |
-| GSD `CONTEXT.md` (phases) | `specs/CONTEXT.md` + `specs/adr/` |
+| GSD `ROADMAP.md` | `specs/release-plan.yaml + epic shards` |
+| GSD `REQUIREMENTS.md` | `specs/requirements/SCOPE_LATEST.yaml` |
+| GSD `CONTEXT.md` (phases) | `specs/plans/TECH_STACK_LATEST.md` + `specs/adr/` |
 | GSD `PLAN.md` | `specs/PLAN-vX.Y.Z.md` |
 | GSD `METHODOLOGY.md` | `specs/SPIKE-methodology.md` |
-| spec-kit `spec.md` | `specs/SCOPE.md` + `specs/CONTEXT.md` |
-| spec-kit `plan.md` | `specs/CONTEXT.md` + `specs/PLAN.md` |
-| spec-kit `tasks.md` | `specs/TASKS.md` |
-| BMAD `prd.md` | `specs/SCOPE.md` |
-| BMAD `architecture.md` | `specs/CONTEXT.md` + `specs/adr/` |
-| BMAD `epic-*.md` | `specs/RELEASE-PLAN.md` |
-| BMAD `story-*.md` | `specs/TASKS.md` |
+| spec-kit `spec.md` | `specs/requirements/SCOPE_LATEST.yaml` + `specs/plans/TECH_STACK_LATEST.md` |
+| spec-kit `plan.md` | `specs/plans/TECH_STACK_LATEST.md` + `specs/PLAN.md` |
+| spec-kit `tasks.md` | `specs/epics/ (see slice-tasks)` |
+| BMAD `prd.md` | `specs/requirements/SCOPE_LATEST.yaml` |
+| BMAD `architecture.md` | `specs/plans/TECH_STACK_LATEST.md` + `specs/adr/` |
+| BMAD `epic-*.md` | `specs/release-plan.yaml + epic shards` |
+| BMAD `story-*.md` | `specs/epics/ (see slice-tasks)` |
 | BMAD `project-context.md` | `CLAUDE.md` (append project-specific section) |
 | BMAD `decision-log.md` | `specs/adr/` (one ADR per logged decision) |
 
@@ -147,5 +147,5 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 - **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
 - **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
 - **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG.md`.
-- **STATE.md is always regenerated** — never migrate source STATE verbatim; bigpowers STATE.md needs its own format.
+- **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
 - **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.

package/model-domain/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: model-domain
 model: sonnet
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates specs/CONTEXT.md and specs/adr/ inline as decisions crystallise. Use when user wants to stress-test a plan against their project's domain language and documented decisions.
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates specs/plans/TECH_STACK_LATEST.md and specs/adr/ inline as decisions crystallise. Use when user wants to stress-test a plan against their project's domain language and documented decisions.
 ---
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
@@ -46,13 +46,13 @@ If a `specs/CONTEXT-MAP.md` exists, the repo has multiple contexts. The map poin
             └── adr/
 ```
 
-Create files lazily — only when you have something to write. If no `specs/CONTEXT.md` exists, create it when the first term is resolved. If no `specs/adr/` exists, create it when the first ADR is needed.
+Create files lazily — only when you have something to write. If no `specs/plans/TECH_STACK_LATEST.md` exists, create it when the first term is resolved. If no `specs/adr/` exists, create it when the first ADR is needed.
 
 ## During the session
 
 ### Challenge against the glossary
 
-When the user uses a term that conflicts with the existing language in `specs/CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+When the user uses a term that conflicts with the existing language in `specs/plans/TECH_STACK_LATEST.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
 
 ### Sharpen fuzzy language
 
@@ -66,11 +66,11 @@ When domain relationships are being discussed, stress-test them with specific sc
 
 When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
 
-### Update specs/CONTEXT.md inline
+### Update specs/plans/TECH_STACK_LATEST.md inline
 
-When a term is resolved, update `specs/CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+When a term is resolved, update `specs/plans/TECH_STACK_LATEST.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
 
-Don't couple `specs/CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
+Don't couple `specs/plans/TECH_STACK_LATEST.md` to implementation details. Only include terms that are meaningful to domain experts.
 
 ### Offer ADRs sparingly
 
@@ -89,4 +89,4 @@ When the plan touches shared state, async, or multi-threaded code:
 - [ ] List every **shared mutable** location (globals, singletons, module-level caches).
 - [ ] For each: who reads, who writes, synchronization mechanism (lock, actor, immutable copy).
 - [ ] Flag **race risks** (check-then-act, non-atomic read-modify-write) with severity.
-- [ ] Record findings in `specs/CONTEXT.md` under `## Concurrency` or in an ADR if architectural.
+- [ ] Record findings in `specs/plans/TECH_STACK_LATEST.md` under `## Concurrency` or in an ADR if architectural.

package/orchestrate-project/SKILL.md

@@ -34,16 +34,13 @@ See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate type
 
 ## How Orchestrate Works
 
-1. **Maintains STATE.md** — Tracks current phase, artifacts, decisions, risks.
-2. **Spawns appropriate skills** — Reads each skill's `model:` frontmatter and routes (haiku/sonnet/opus). Calls survey-context, research-first, elaborate-spec, plan-work, develop-tdd, verify-work, run-evals, etc. Decisions pass only via `specs/STATE.md` between spawns.
-3. **Methodology lenses** — If `specs/METHODOLOGY.md` exists, apply active reasoning modes (STRIDE, Cost-of-Delay) at phase gates.
+1. **Maintains state.yaml** — Tracks current phase, `active_epic`, `active_flow`, decisions, risks.
+2. **Spawns appropriate skills** — Routes by `model:` frontmatter. Decisions pass only via `specs/state.yaml` `handoff` between spawns.
+3. **Methodology lenses** — If `specs/plans/TEST_PLAN_LATEST.md` or ADRs exist, apply at phase gates.
 4. **Enforces gates** — Hard stops if success criteria not met.
-5. **The Gatekeeper** (v1.19.0) — Between every Story implementation in PHASE 4:
-   - READ `specs/RELEASE-PLAN.md` to verify completion.
-   - REQUIRE that the previous Story is marked `[x] Done`.
-   - REFUSE to call `update_topic` for a new Story until the previous one is physically evidenced as complete.
+5. **The Gatekeeper** — Between stories in BUILD: read `specs/execution-status.yaml`; previous story must be `done` before starting the next; use `build-epic` for the 8-step epic cycle.
 6. **Pauses for confirmation** — After each phase, asks "Ready to proceed?".
-7. **Archives history** — Saves RELEASE-PLAN snapshots as specs/RELEASE-PLAN-vX.Y.Z.md when needed.
+7. **Snapshots** — `bash scripts/bp-yaml-snapshot.sh` before major release cuts.
 
 ## Orchestration Modes
 

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "bigpowers",
-  "version": "1.2.3",
-  "description": "59 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "1.3.0",
+  "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
     "compliance": "bash scripts/audit-compliance.sh specs/audit/features",
     "sync": "bash scripts/sync-skills.sh",
+    "validate-specs": "bash scripts/validate-specs-yaml.sh",
+    "enrich-epics": "bash scripts/enrich-epics-from-archive.sh",
     "version": "bash scripts/sync-skills.sh && git add .gemini/extensions/bigpowers/gemini-extension.json specs/SKILL-SEARCH-INDEX.md",
     "install": "bash scripts/install.sh",
     "postinstall": "bash scripts/sync-skills.sh && bash scripts/install.sh",

package/plan-release/SKILL.md

@@ -1,76 +1,100 @@
 ---
 name: plan-release
 model: sonnet
-description: Convert elaborated specs into a structured release plan with Gherkin acceptance criteria and WSJF-sorted epics. Produces specs/RELEASE-PLAN.md. Use when a spec is clear and ready to plan, after elaborate-spec, or when the user wants a release plan broken into epics and stories.
+description: Convert elaborated specs into a structured release plan with Gherkin acceptance criteria and WSJF-sorted epics. Produces specs/release-plan.yaml and specs/epics/eNN-*.yaml. Use when a spec is clear and ready to plan, after elaborate-spec, or when the user wants a release plan broken into epics and stories.
 ---
 
 # Plan Release
 
 > **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.
 
-Synthesize the conversation context into `specs/RELEASE-PLAN.md`. No new interview — only clarify if something is genuinely ambiguous.
+> **HARD GATE** — `specs/requirements/SCOPE_LATEST.yaml` (or legacy `specs/requirements/SCOPE_LATEST.yaml`) must exist. If missing, run `scope-work` first.
+
+Synthesize the conversation context into `specs/release-plan.yaml` (index) and shard detail under `specs/epics/`. No new interview — only clarify if something is genuinely ambiguous.
+
+## Outputs
+
+| File | Content |
+|------|---------|
+| `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list (`id: e01`, `file:`, `mode:`) — **no story status** |
+| `specs/epics/eNN-<slug>.yaml` | Epic metadata, `covers: [fr-x]`, stories with tasks and `verify:` |
+| `specs/execution-status.yaml` | Regenerate keys via `bash scripts/sync-status-from-epics.sh` after epics exist |
 
 ## Process
 
 ### 1. Draft epics and stories
 
 From the conversation context, define:
-- **Epics** — major capability areas (Priority: P1/P2/P3 | Value: High/Med/Low | Effort: S/M/L)
-- **Stories** — "As a [actor], I want [feature] so that [benefit]"
+- **Epics** — `e01`, `e02`, … (stable IDs; WSJF order in `release-plan.yaml` only)
+- **Stories** — `e01s01`, `e01s02`, … with Gherkin acceptance criteria
 
 WSJF-sort epics: score = (Business Value + Time Criticality + Risk Reduction) / Job Size. Highest score first.
 
 ### 2. Write acceptance criteria (Gherkin)
 
-For each story, write at least one happy-path and one edge-case scenario:
-
-```
-Acceptance Criteria:
-  Feature: [name]
-    Scenario: [happy path]
-      Given [initial state]
-      When  [user action]
-      Then  [observable outcome]
-    Scenario: [edge case]
-      Given ...
-      When  ...
-      Then  ...
-```
+For each story, write at least one happy-path and one edge-case scenario (countable format §17 if maturity ≥ 3).
 
 ### 3. Write tasks with verify commands
 
-Under each story, list implementation tasks:
+Every task must have a `verify:` command. No verify command = not a task.
 
-```
-Tasks:
-  - [ ] Write failing test for scenario 1 → verify: <cmd>
-  - [ ] Implement [module/function]       → verify: <cmd>
-  - [ ] Integrate and smoke-test          → verify: <cmd>
+### 4. Save specs/release-plan.yaml
+
+```yaml
+release:
+  version: "3.0.0"
+  codename: "Feature Name"
+  status: planning          # planning | in_progress | released
+  semantic_release: true
+  bump_hint: minor          # patch | minor | major — CI decides at merge
+epics:
+  - id: e01
+    title: Security
+    wsjf: 4.5
+    file: epics/e01-security.yaml
+    mode: flat              # flat | folder (folder if >5 stories)
+  - id: e02
+    title: Verification
+    wsjf: 4.3
+    file: epics/e02-verification/epic.yaml
+    mode: folder
 ```
 
-Every task must have a `verify:` command. No verify command = not a task.
+### 5. Save epic shards
+
+**Flat** (`mode: flat`, ≤ ~5 stories):
+
+```yaml
+id: e01
+title: Security
+wsjf: 4.5
+covers: [fr-08]
+stories:
+  - id: e01s01
+    title: Guard git hooks
+    tasks:
+      - desc: Block push on main
+        verify: "grep -q guard-git .cursor/rules/guard-git.mdc"
+```
 
-### 4. Save specs/RELEASE-PLAN.md
+**Folder GSD** (`mode: folder`): `epics/e02-verification/epic.yaml` + `stories/e02s01-*.md` with YAML frontmatter for tasks.
 
-```
-## Epic 1: [Name]
-Priority: P1 | Value: High | Effort: M | WSJF: [score]
+→ verify: `bash scripts/validate-specs-yaml.sh`
 
-### Story 1.1: As a [actor], I want [feature] so that [benefit]
-Status: [ ] Not started
+→ verify: `grep -c 'id: e' specs/release-plan.yaml`
 
-Acceptance Criteria:
-  Feature: ...
-    Scenario: ...
+### 6. Sync execution status
 
-Tasks:
-  - [ ] ... → verify: <cmd>
+```bash
+bash scripts/sync-status-from-epics.sh
 ```
 
-→ verify: `grep -c "Scenario:" specs/RELEASE-PLAN.md`
+### 7. Snapshot on planning close (optional)
+
+Copy to `specs/requirements/snapshots/release-<version>/` when the user approves the plan.
 
-### 5. Suggest next steps
+### 8. Suggest next steps
 
 - Run `assess-impact` before `plan-work` for any story touching existing modules.
-- Run `plan-work` per story to produce the detailed step-by-step plan.
+- Run `plan-work` per story for detailed steps inside the epic shard.
 - Run `change-request` if a new requirement arrives mid-flight.

package/plan-work/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: plan-work
 model: opus
-description: Write a detailed implementation plan to specs/RELEASE-PLAN.md. Every step must include a runnable verify command (Karpathy verification template). Use when user has a task to implement and needs a step-by-step plan with evidence checkpoints, or after plan-release produces specs/RELEASE-PLAN.md.
+description: Write detailed implementation tasks into the active epic shard (specs/epics/eNN-*.yaml). Every task must include a runnable verify command. Use when user needs step-by-step plan with evidence, or after plan-release.
 ---
 
 # Plan Work
 
-Produce a detailed, verifiable implementation plan in `specs/RELEASE-PLAN.md`. Every step must be paired with a runnable verify command — "I think it works" is not a step.
+Produce a detailed, verifiable implementation plan in the **active epic shard** (`specs/epics/eNN-*.yaml` under the target story's `tasks[]`). Every step must be paired with a runnable verify command — "I think it works" is not a step.
 
 > **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
 >
@@ -16,7 +16,7 @@ Produce a detailed, verifiable implementation plan in `specs/RELEASE-PLAN.md`. E
 
 Before writing the plan, check if `define-success` has been run. If the task's success criteria are unclear, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
 
-Read any existing `specs/` files: RELEASE-PLAN.md, SCOPE.md, TASKS.md, CONTEXT.md, UBIQUITOUS_LANGUAGE.md.
+Read any existing `specs/` files: `release-plan.yaml`, `requirements/SCOPE_LATEST.yaml`, active `epics/*.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/GLOSSARY_LATEST.yaml`.
 
 > **ZOOM-OUT MANDATE** (v1.17.0 Guardrails) — If this plan modifies an existing module, function, or behavior:
 > 1. State the module's **purpose** — what is it responsible for?
@@ -58,9 +58,9 @@ Break the implementation into the smallest possible steps where each step:
 
 **Red-flag check**: before moving to Step 3, name any rationalization you caught yourself making — skipping a gate, adding out-of-scope steps, omitting a verify command. Write them out; do not suppress them.
 
-### 3. Write specs/RELEASE-PLAN.md
+### 3. Write epic shard tasks
 
-Append the detailed steps under the relevant story in `specs/RELEASE-PLAN.md`. Create the `specs/` directory if it doesn't exist.
+Append tasks under the relevant story in `specs/epics/{epic-id}-*.yaml` (`tasks[]` with `desc` + `verify`). Update `specs/release-plan.yaml` if a new story is needed. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
 
 <plan-template>
 
@@ -126,4 +126,4 @@ Before finalizing, confirm:
 - Is the granularity right (not too coarse, not too fine)?
 - Are the verify commands actually runnable in this project?
 
-After writing `specs/RELEASE-PLAN.md`, suggest `kickoff-branch` (if not already on a feature branch) then `execute-plan` or `develop-tdd`.
+After writing epic tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.

package/research-first/SKILL.md

@@ -10,10 +10,10 @@ model: sonnet
 
 ## Process
 
-1. Read `specs/SCOPE.md`, `specs/RELEASE-PLAN.md`, and the current task statement.
+1. Read `specs/requirements/SCOPE_LATEST.yaml`, `specs/release-plan.yaml + epic shards`, and the current task statement.
 2. Search in order: this repo → bigpowers skills (`search-skills`) → package registries → web docs.
 3. For each candidate: note name, URL/path, fit (adopt | extend | compose | build).
-4. Append `## Prior Art` to the active spec (SCOPE.md or story in RELEASE-PLAN.md).
+4. Append `## Prior Art` to `requirements/SCOPE_LATEST.yaml` notes or the active epic story.
 
 ## Outcome matrix
 
@@ -26,6 +26,6 @@ model: sonnet
 
 ## Verify
 
-→ verify: `grep -c "Prior Art" specs/SCOPE.md specs/RELEASE-PLAN.md 2>/dev/null | awk '{s+=$1} END {if(s>0) print "OK"; else print "MISSING"}'`
+→ verify: `grep -c "Prior Art" specs/requirements/SCOPE_LATEST.yaml specs/release-plan.yaml + epic shards 2>/dev/null | awk '{s+=$1} END {if(s>0) print "OK"; else print "MISSING"}'`
 
 See [REFERENCE.md](REFERENCE.md) for search commands and registry checklist.