bigpowers 1.2.3 → 1.3.1

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 `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` |
+| 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/epics/eNN-*.yaml` (tasks with verify) |
+| GSD `METHODOLOGY.md` | `specs/plans/METHODOLOGY_LATEST.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/release-plan.yaml` + `specs/epics/` |
+| 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/REFERENCE.md

@@ -6,25 +6,25 @@ Detailed documentation for the `orchestrate-project` meta-skill.
 
 ### PHASE 1: DISCOVER
 - **Goal**: Understand the problem completely and map existing context.
-- **Deliverables**: `PROJECT.md`, `CONTEXT.md`.
+- **Deliverables**: `requirements/VISION_LATEST.yaml`, `requirements/SCOPE_LATEST.yaml`, `plans/TECH_STACK_LATEST.md`.
 - **Skills**: `survey-context`, `elaborate-spec`, `grill-me`.
 - **Gate**: Confirm ("Is the problem clear?").
 
 ### PHASE 2: ELABORATE
 - **Goal**: Research solutions and lock architectural design.
-- **Deliverables**: `RESEARCH.md`, ADRs (Architecture Decision Records).
+- **Deliverables**: Prior art in scope YAML, ADRs in `specs/adr/`.
 - **Skills**: `model-domain`, `define-language`, `challenge-design`.
 - **Gate**: Quality ≥94% (via `request-review`) + Confirm ("Are decisions locked?").
 
 ### PHASE 3: PLAN
 - **Goal**: Write a verifiable implementation plan with success criteria.
-- **Deliverables**: `PLAN.md` with `verify:` commands.
+- **Deliverables**: `release-plan.yaml`, `epics/eNN-*.yaml` with `verify:` per task.
 - **Skills**: `scope-work`, `slice-tasks`, `define-success`, `plan-work`.
 - **Gate**: Quality (request-review ≥94%) + slopcheck [SUS]/[SLOP].
 
 ### PHASE 4: BUILD
 - **Goal**: Execute the plan step-by-step using TDD and vertical slices.
-- **Deliverables**: Code, `SUMMARY.md`.
+- **Deliverables**: Code; `execution-status.yaml` updated per story.
 - **Skills**: `kickoff-branch`, `develop-tdd`, `delegate-task`, `execute-plan`.
 - **Gate**: Integration tests PASS.
 
@@ -60,7 +60,7 @@ Detailed documentation for the `orchestrate-project` meta-skill.
 ### Mode 2: Fast-Track (Skip Negotiable Gates)
 **Use Case**: Hotfixes, minor improvements, refactors on well-tested code.
 **Behavior**:
-- Skip Discover if `PROJECT.md` exists.
+- Skip Discover if `requirements/SCOPE_LATEST.yaml` exists.
 - Skip Elaborate if design decisions are already locked.
 - Skip Verify if coverage ≥95% + all tests PASS.
 - Soft gates auto-approve if baseline conditions are met.
@@ -86,10 +86,10 @@ Detailed documentation for the `orchestrate-project` meta-skill.
 ---
 
 ## Error Recovery & State
-Orchestrate maintains `specs/STATE.md` to track:
-- **Current Phase**: Position in the loop.
-- **Artifacts**: Checklist of completed deliverables.
-- **Decisions**: Audit trail of architectural choices.
-- **Risks**: Active project risks and mitigation status.
+Orchestrate maintains `specs/state.yaml` to track:
+- **Current flow / epic**: `active_flow`, `active_epic_id`, `epic_cycle`.
+- **Handoff**: `last_step_completed`, `open_decisions`, `required_reading`, `next_skill`.
+- **Git**: `branch`, `hash` for session continuity.
+- **Progress**: Story status lives in `execution-status.yaml` only.
 
 In the event of a crash or exit, run `claude /orchestrate --resume` to pick up exactly where the session left off.

package/orchestrate-project/SKILL.md

@@ -11,7 +11,7 @@ The orchestrate skill coordinates projects through a prescriptive 6-phase core l
 ## Quick Start
 
 ```bash
-# Start a new project (creates PROJECT.md and begins discover phase)
+# Start a new project (initializes specs/ YAML cockpit and begins discover phase)
 claude /orchestrate --mode standard
 
 # Or resume an existing project at the current phase
@@ -23,27 +23,24 @@ claude /orchestrate --mode fast-track
 
 ## The 6-Phase Core Loop
 
-1. **DISCOVER** (3-6 hours): Understand problem. Deliverables: PROJECT.md, CONTEXT.md.
-2. **ELABORATE** (3-6 hours): Research solutions. Deliverables: RESEARCH.md.
-3. **PLAN** (2-4 hours): Write verifiable plan. Deliverables: PLAN.md.
-4. **BUILD** (1-8 hours): Execute plan. Deliverables: Code, SUMMARY.md.
-5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: VERIFICATION.md.
-6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag.
+1. **DISCOVER** (3-6 hours): Understand problem. Deliverables: `requirements/VISION_LATEST.yaml`, `requirements/SCOPE_LATEST.yaml`, `plans/TECH_STACK_LATEST.md`.
+2. **ELABORATE** (3-6 hours): Research solutions. Deliverables: Prior art in scope YAML, ADRs in `specs/adr/`.
+3. **PLAN** (2-4 hours): Write verifiable plan. Deliverables: `release-plan.yaml`, `epics/eNN-*.yaml` with `verify:` per task.
+4. **BUILD** (1-8 hours): Execute plan. Deliverables: Code; update `execution-status.yaml`.
+5. **VERIFY** (1-3 hours): Validate success criteria. Deliverables: UAT evidence, `specs/EVALS-*.md` if used.
+6. **RELEASE** (30 min - 2 hours): Ship to production. Deliverables: Release tag (vX.Y.Z), `state.yaml` `release.last_tag`.
 
 See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types.
 
 ## 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
 
@@ -57,5 +54,5 @@ See [REFERENCE.md](REFERENCE.md) for full mode behaviors.
 
 All phases complete with artifacts:
 ```bash
-verify: test -f specs/PROJECT.md && test -f specs/PLAN.md && test -f specs/VERIFICATION.md && echo "✅ All phases complete"
+verify: test -f specs/state.yaml && test -f specs/release-plan.yaml && test -f specs/requirements/SCOPE_LATEST.yaml && ls specs/epics/*.yaml 1>/dev/null && echo "✅ All phases complete"
 ```

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.1",
+  "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",
@@ -37,11 +39,9 @@
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^11.1.0",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^9.2.6",
-    "@semantic-release/npm": "^11.0.3",
-    "@semantic-release/release-notes-generator": "^12.1.0",
-    "semantic-release": "^22.0.12"
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "semantic-release": "^24.2.0"
   }
 }

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/request-review/SKILL.md

@@ -22,7 +22,7 @@ Write a self-contained brief for the reviewer agent. Include:
 
 - What was built (feature description, not implementation)
 - Which files changed (the diff context)
-- What `specs/` artifacts are relevant (PLAN.md, bugs/BUG-*.md, SCOPE.md)
+- What `specs/` artifacts are relevant (active `epics/eNN-*.yaml`, `requirements/SCOPE_LATEST.yaml`, `bugs/BUG-*.md`)
 - What CONVENTIONS.md requires
 - What the verify command is
 - What you're most uncertain about (where you want fresh eyes)
@@ -36,7 +36,7 @@ You are a code reviewer. Review the following code changes.
 
 Context: [feature description]
 CONVENTIONS.md rules: [paste relevant sections]
-specs/PLAN.md: [paste or summarize]
+Active epic shard: [paste or summarize from specs/epics/]
 
 Diff: [paste git diff or describe changed files]
 

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.

package/run-evals/REFERENCE.md

@@ -24,4 +24,4 @@
 
 ## pass@k
 
-Run capability evals k times (default k=3). Ship when all k pass or document known flake in STATE.md.
+Run capability evals k times (default k=3). Ship when all k pass or document known flake in `specs/state.yaml` `handoff.open_decisions`.

package/run-planning/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: run-planning
+model: sonnet
+description: Advance discover-phase workflows and update specs/planning-status.yaml. Use for survey, scope, research, plan-release chain without touching build epics.
+---
+
+# Run Planning
+
+Updates `specs/planning-status.yaml` as discover-phase skills complete.
+
+## Workflows (default keys)
+
+- `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
+
+## Process
+
+1. Read `specs/planning-status.yaml` and `specs/state.yaml`.
+2. Find first workflow with `status: pending` or `optional` not yet run.
+3. Invoke the matching skill; on success set `status: done` for that workflow key.
+4. Set `state.yaml` `active_flow: planning` while in this chain.
+
+## Verify
+
+→ verify: `test -f specs/planning-status.yaml && grep -c 'status: done' specs/planning-status.yaml | awk '{if($1>=3) print "OK"; else print "INCOMPLETE"}'`

package/scope-work/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: scope-work
-description: Define what is in and out of scope for the current effort and save as specs/SCOPE.md. Use when user wants a PRD, scope definition, or before plan-release on a new initiative.
+description: Define what is in and out of scope for the current effort and save as specs/requirements/SCOPE_LATEST.yaml. Use when user wants a PRD, scope definition, or before plan-release on a new initiative.
 model: sonnet
 ---
 
 # Scope Work
 
-Turn the current conversation into a bounded PRD at `specs/SCOPE.md`.
+Turn the current conversation into a bounded PRD at `specs/requirements/SCOPE_LATEST.yaml`.
 
 ## Process
 
-1. Read existing `specs/` artifacts (CONTEXT.md, RELEASE-PLAN.md if any).
+1. Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any).
 2. Interview (if needed): goal, users, in-scope, out-of-scope, constraints, success metrics.
-3. Write `specs/SCOPE.md` with: Vision, In Scope, Out of Scope, Constraints, Success Criteria.
+3. Write `specs/requirements/SCOPE_LATEST.yaml` with: `core_value`, `summary`, `in_scope[]`, `out_of_scope[]`, `constraints`, `success_criteria`, `references`.
 4. Run `research-first` if external dependencies are proposed.
 
-> **HARD GATE** — Every "in scope" item must map to a future story ID or explicit "deferred" with reason.
+> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`.
 
 ## Verify
 
-→ verify: `test -f specs/SCOPE.md && grep -c "Out of Scope" specs/SCOPE.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `test -f specs/requirements/SCOPE_LATEST.yaml && grep -c 'out_of_scope' specs/requirements/SCOPE_LATEST.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`

package/scripts/bp-yaml-set.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# bp-yaml-set.sh — patch a dotted key in a specs YAML file
+# Usage: bp-yaml-set.sh <file> <dotted.key> <value>
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FILE="${1:?file}"
+KEY="${2:?dotted.key}"
+VAL="${3:?value}"
+python3 "$REPO_ROOT/scripts/yaml-tools.py" set "$FILE" "$KEY" "$VAL"

package/scripts/bp-yaml-snapshot.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# bp-yaml-snapshot.sh — freeze release-plan + requirements into snapshots/
+# Usage: bp-yaml-snapshot.sh [version]  (default: read from release-plan.yaml)
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPECS="$REPO_ROOT/specs"
+VER="${1:-}"
+
+if [[ -z "$VER" ]]; then
+  VER=$(grep -E '^\s+version:' "$SPECS/release-plan.yaml" | head -1 | sed 's/.*"\(.*\)".*/\1/')
+fi
+DEST="$SPECS/requirements/snapshots/release-$VER"
+mkdir -p "$DEST"
+
+for f in release-plan.yaml requirements/VISION_LATEST.yaml requirements/SCOPE_LATEST.yaml; do
+  src="$SPECS/$f"
+  [[ -f "$src" ]] || continue
+  base=$(basename "$f")
+  cp "$src" "$DEST/$base"
+done
+
+echo "bp-yaml-snapshot: wrote $DEST"
+ls -la "$DEST"