bigpowers 1.2.3 → 1.3.1

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/REFERENCE-GSD.md

@@ -1,6 +1,6 @@
 # migrate-spec Reference — GSD
 
-Full artifact transformation rules for migrating GSD projects to bigpowers.
+Full artifact transformation rules for migrating GSD projects to bigpowers YAML layout.
 
 See [REFERENCE.md](./REFERENCE.md) for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats.
 
@@ -32,95 +32,89 @@ GSD stores everything under `.planning/` at the project root.
 
 ## Transformation Rules
 
-### `.planning/ROADMAP.md` → `specs/RELEASE-PLAN.md`
+### `.planning/ROADMAP.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`
 
 GSD ROADMAP has: milestone name, phases, success criteria per phase, plan count.
 
-bigpowers RELEASE-PLAN needs: release version, status, WSJF, focus, objective.
-
 Transform:
-- Each GSD phase → one release entry in RELEASE-PLAN.md
-- Phase name → release name (add version number e.g. v1.0.0)
-- GSD success criteria → "Success Criteria" subsection under each release entry
-- Phase plan count → "Job Size" hint for WSJF (ask user to score)
-- Completed phases → `✅` status; active phase → `⏳`; future phases → `📋`
+- Each GSD phase → one epic entry in `release-plan.yaml` (`id`, `title`, `wsjf`, `file`)
+- Phase detail → matching `specs/epics/eNN-slug.yaml` (stories, tasks, `verify`)
+- Completed phases → `done` in `execution-status.yaml`; active → `in_progress`
 
 ---
 
-### `.planning/REQUIREMENTS.md` → `specs/SCOPE.md`
+### `.planning/REQUIREMENTS.md` → `specs/requirements/SCOPE_LATEST.yaml`
 
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
 - Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → "In Scope" section
-- Out-of-Scope → "Out of Scope" section
-- Active (in-progress) → "In Scope (WIP)" section
-- Add header: `# Scope — migrated from GSD REQUIREMENTS.md`
+- Validated requirements → `in_scope` entries
+- Out-of-Scope → `out_of_scope` entries
+- Active (in-progress) → `in_scope` with status note
 
 ---
 
-### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/CONTEXT.md` + `specs/adr/`
+### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/plans/TECH_STACK_LATEST.md` + `specs/adr/`
 
 GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context, specifics, deferred.
 
 Transform:
-- `domain` → `specs/CONTEXT.md` Domain section (domain model, terms, aggregates)
+- `domain` → `plans/TECH_STACK_LATEST.md` Domain section
 - `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG.md`
-- `canonical_refs` → Reference links in CONTEXT.md
-- `code_context` → `specs/CONTEXT.md` Architecture section
-- `specifics` → merge into relevant CONTEXT.md section
-- `deferred` → `specs/SCOPE.md` Out-of-Scope section (with "(deferred from GSD)" note)
+- `canonical_refs` → Reference links in TECH_STACK
+- `code_context` → Architecture section
+- `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)
 
 ---
 
-### `.planning/phases/XX-name/XX-YY-PLAN.md` → `specs/PLAN-vX.Y.Z.md`
+### `.planning/phases/XX-name/XX-YY-PLAN.md` → `specs/epics/eNN-*.yaml` tasks
 
 GSD PLAN has: frontmatter (depends-on, verify), objective, typed tasks, success criteria, output spec.
 
 Transform:
-- Preserve task structure
-- Keep `verify: <command>` lines (same format bigpowers uses)
-- Map GSD `depends-on` to a "Dependencies" note in bigpowers PLAN header
-- Add bigpowers frontmatter with release version
-- SUMMARY.md (execution record) → append as "## Execution Record" if needed; otherwise skip
+- Preserve task structure as `tasks[]` in epic shard
+- Keep `verify: <command>` lines
+- Map GSD `depends-on` to task `depends-on` notes
+- SUMMARY.md (execution record) → skip or append to `specs/archive/`
 
 ---
 
-### `.planning/METHODOLOGY.md` → `specs/SPIKE-methodology.md`
+### `.planning/METHODOLOGY.md` → `specs/plans/METHODOLOGY_LATEST.md`
 
-GSD METHODOLOGY.md is a standing reference for analytical lenses (Bayesian updating, STRIDE, cost-of-delay). bigpowers has no direct equivalent.
+GSD METHODOLOGY.md is a standing reference for analytical lenses (Bayesian updating, STRIDE, cost-of-delay).
 
 Transform:
-- Copy each lens as a section in `specs/SPIKE-methodology.md`
-- Add header: `# Project Methodology — migrated from GSD`
+- Copy each lens as a section in `specs/plans/METHODOLOGY_LATEST.md`
 - Note: "These lenses should inform `plan-work` and `audit-code` sessions."
 
 ---
 
-### `.planning/HANDOFF.json` + `.continue-here.md` → `specs/STATE.md` (resume block)
+### `.planning/HANDOFF.json` + `.continue-here.md` → `specs/state.yaml` `handoff`
 
 GSD HANDOFF has: current phase, last plan, blocking reason, required reading list.
 
-Transform — add a "## Session Resume" block to `specs/STATE.md`:
-
-```markdown
-## Session Resume
+Transform — populate `handoff` in `state.yaml`:
 
-- Last active: <phase/plan from HANDOFF>
-- Blocking: <reason if any>
-- Required reading before next session: <required_reading list>
+```yaml
+handoff:
+  last_step_completed: "<phase/plan from HANDOFF>"
+  open_decisions:
+    - "<blocking reason if any>"
+  required_reading:
+    - "<required_reading list>"
+  next_skill: survey-context
 ```
 
 ---
 
-### `.planning/spikes/SPIKE-NNN/README.md` → `specs/SPIKE-{name}.md`
+### `.planning/spikes/SPIKE-NNN/README.md` → `specs/archive/spikes/SPIKE-{name}.md`
 
 GSD spike README has: YAML frontmatter (verdict, validates, related), methodology, findings, recommendation.
 
 Transform:
-- Flatten directory into single `specs/SPIKE-{name}.md`
-- Preserve frontmatter as YAML block comment at top
+- Flatten directory into `specs/archive/spikes/SPIKE-{name}.md`
+- Preserve frontmatter as YAML block at top
 - Keep verdict prominently: `**Verdict:** ADOPTED / REJECTED / DEFERRED`
 
 ---

package/migrate-spec/REFERENCE.md

@@ -2,7 +2,7 @@
 
 Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.
 
-See [REFERENCE-GSD.md](./REFERENCE-GSD.md) for full GSD → bigpowers mapping.
+See [REFERENCE-GSD.md](./REFERENCE-GSD.md) for full GSD → bigpowers YAML mapping.
 
 ---
 
@@ -22,35 +22,35 @@ project-root/
         └── log.jsonl
 ```
 
-### `spec.md` → `specs/SCOPE.md` + `specs/CONTEXT.md`
+### `spec.md` → `specs/requirements/SCOPE_LATEST.yaml` + `specs/plans/TECH_STACK_LATEST.md`
 
 spec-kit `spec.md` focuses on: who uses it, user journeys, success criteria, what's in/out of scope.
 
 Transform:
-- User journeys → `specs/SCOPE.md` "Success Criteria" subsection (observable behaviors)
-- In/out of scope → `specs/SCOPE.md` main sections
-- Domain terms / glossary → `specs/CONTEXT.md` glossary section
-- Problem statement / vision → first paragraph of `specs/CONTEXT.md`
+- User journeys → `SCOPE_LATEST.yaml` success criteria / `in_scope` entries
+- In/out of scope → `in_scope` / `out_of_scope` sections
+- Domain terms / glossary → `requirements/GLOSSARY_LATEST.yaml`
+- Problem statement / vision → `requirements/VISION_LATEST.yaml`
 
-### `plan.md` → `specs/CONTEXT.md` + `specs/PLAN.md`
+### `plan.md` → `specs/plans/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/`
 
 spec-kit `plan.md` covers: technology stack, architectural patterns, implementation constraints.
 
 Transform:
-- Technology decisions → `specs/CONTEXT.md` "Technology" section
-- Architecture patterns → `specs/CONTEXT.md` "Architecture" section
+- Technology decisions → `plans/TECH_STACK_LATEST.md` Technology section
+- Architecture patterns → Architecture section
 - Hard decisions with trade-offs → `specs/adr/NNNN-{slug}.md`
-- Phased approach / milestones → `specs/RELEASE-PLAN.md` release entries
-- Implementation steps → `specs/PLAN.md` task list
+- Phased approach / milestones → `release-plan.yaml` epic entries
+- Implementation steps → `epics/eNN-*.yaml` task list with `verify:`
 
-### `tasks.md` → `specs/TASKS.md`
+### `tasks.md` → `specs/epics/` (via slice-tasks)
 
 spec-kit tasks are atomic, verifiable in isolation — same principle as bigpowers `verify:` mandate.
 
 Transform:
-- Copy tasks directly; preserve task numbers
+- Copy tasks into epic shard `tasks[]`; preserve task numbers
 - Add `verify:` line if spec-kit task has an acceptance criterion
-- Group into phases matching `specs/RELEASE-PLAN.md` releases
+- Group into epics matching `release-plan.yaml` entries
 
 ### `.specify/` state
 
@@ -79,50 +79,50 @@ project-root/
     └── story-{slug}.md
 ```
 
-### `product-brief.md` / `prfaq-{project}.md` → `specs/CONTEXT.md` (Vision)
+### `product-brief.md` / `prfaq-{project}.md` → `specs/requirements/VISION_LATEST.yaml`
 
 Transform:
-- Vision + core value → `specs/CONTEXT.md` Vision section (first section)
-- Target users → personas list in CONTEXT.md
-- prfaq customer FAQ → can inform success criteria in SCOPE.md
+- Vision + core value → `VISION_LATEST.yaml` north_star / success_criteria
+- Target users → notes in VISION or SCOPE
+- prfaq customer FAQ → can inform success criteria in SCOPE
 
-### `prd.md` → `specs/SCOPE.md`
+### `prd.md` → `specs/requirements/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml`
 
 BMAD `prd.md` has: Glossary, FR-XX functional requirements, UJ-XX user journeys, NFRs, assumptions.
 
 Transform:
-- Glossary → `specs/CONTEXT.md` Glossary section (keep exactly; it's domain language)
-- FR-XX items → `specs/SCOPE.md` "In Scope" with IDs preserved as comments: `<!-- FR-3 -->`
-- UJ-XX user journeys → `specs/SCOPE.md` "Success Criteria" section
-- NFRs → `specs/SCOPE.md` "Constraints" section
-- `[ASSUMPTION: ...]` inline tags → `specs/SCOPE.md` "Assumptions" section (collected)
-- Out-of-scope features → `specs/SCOPE.md` "Out of Scope" section
+- Glossary → `GLOSSARY_LATEST.yaml`
+- FR-XX items → `in_scope` with IDs preserved
+- UJ-XX user journeys → success criteria
+- NFRs → `constraints` section
+- `[ASSUMPTION: ...]` inline tags → collected in scope YAML
+- Out-of-scope features → `out_of_scope`
 
 ### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG.md`
 
 Transform:
 - Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`
 - Lightweight decisions → `specs/DECISION-LOG.md` (date | decision | rationale)
-- `addendum.md` change signals → note at top of SCOPE.md: "PRD amended: see decision-log"
+- `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
 
-### `architecture.md` → `specs/CONTEXT.md` + `specs/adr/`
+### `architecture.md` → `specs/plans/TECH_STACK_LATEST.md` + `specs/adr/`
 
 Transform:
 - ADR sections → individual `specs/adr/NNNN-{slug}.md` files
-- System overview / data models → `specs/CONTEXT.md` Architecture section
-- API contracts → keep at `docs/api.md` or similar; link from CONTEXT.md
+- System overview / data models → TECH_STACK Architecture section
+- API contracts → keep at `docs/api.md` or similar; link from TECH_STACK
 
-### `epic-*.md` → `specs/RELEASE-PLAN.md`
+### `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`
 
-Each epic → one release entry. Epic acceptance criteria → "Success Criteria" subsection.
+Each epic → one release-plan entry + one epic shard. Acceptance criteria → story tasks with `verify:`.
 
-### `story-*.md` → `specs/TASKS.md`
+### `story-*.md` → `specs/epics/` stories
 
-Each story → one entry. Acceptance criteria → `verify:` lines. Story tasks → subtask checklist.
+Each story → one story entry in epic shard. Acceptance criteria → `verify:` lines.
 
 ### `project-context.md` → `CLAUDE.md`
 
-Add a "## Project Context" section to `CLAUDE.md` (or create `PROJECT-CONTEXT.md` if CLAUDE.md is bigpowers-managed). Copy tech stack, coding rules, preferences verbatim. Note: `<!-- Migrated from BMAD project-context.md -->`.
+Add a "## Project Context" section to `CLAUDE.md`. Copy tech stack, coding rules, preferences verbatim.
 
 ---
 
@@ -132,22 +132,21 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 ### From GSD
 
-- [ ] **`specs/METHODOLOGY.md`** — Standing analytical lenses (Bayesian updating, STRIDE, cost-of-delay). Agents read this before planning.
-- [ ] **Session Resume block in STATE.md** — Last skill used, last step completed, required reading for next session.
-- [ ] **ID tracking in SCOPE.md** — Add SCOPE-XX IDs to requirements for spec → plan → verification traceability.
+- [ ] **`specs/plans/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
+- [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
+- [ ] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability.
 
 ### From spec-kit
 
-- [ ] **Two-pass spec writing** — User-journey pass first (what/why, no technical details), then technical-decisions pass. Cleaner specs.
-- [ ] **Explicit inter-phase gate** — "Approve to proceed?" checkpoint at end of `elaborate-spec` before starting `plan-work`.
-- [ ] **`specs/TASKS.md` isolation guarantee** — Each task entry completable and verifiable in isolation; declared dependencies explicit.
+- [ ] **Two-pass spec writing** — User-journey pass first, then technical-decisions pass.
+- [ ] **Explicit inter-phase gate** — "Approve to proceed?" at end of `elaborate-spec`.
+- [ ] **Epic task isolation** — Each task completable in isolation; `depends-on` explicit in epic YAML.
 
 ### From BMAD
 
-- [ ] **FR-XX + UJ-XX in SCOPE.md** — Functional requirement + user journey numbering for rigorous traceability.
-- [ ] **`specs/DECISION-LOG.md`** — Lightweight decision log for PRD-level choices below the ADR threshold. Format: `date | decision | rationale | alternatives`.
-- [ ] **`PROJECT-CONTEXT.md`** — Project-specific constitution read by all implementation agents. Generated from `model-domain` output.
-- [ ] **Adversarial review pass** — Dedicated critique pass on the plan before `develop-tdd`. Critic checks for gaps, edge cases, contradictions with SCOPE.md.
+- [ ] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability.
+- [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
+- [ ] **Adversarial review pass** — Critique epic shard before `develop-tdd`.
 
 ---