bigpowers 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [1.3.1](https://github.com/danielvm-git/bigpowers/compare/v1.3.0...v1.3.1) (2026-06-02)
+
+
+### Bug Fixes
+
+* **ci:** repair sync-skills sed and refresh package-lock ([29d6e7c](https://github.com/danielvm-git/bigpowers/commit/29d6e7cee82ab25eae5188628d1ae2bc73c99e57))
+* **ci:** use Node 22 for semantic-release workflow ([43edf78](https://github.com/danielvm-git/bigpowers/commit/43edf7801ef06714861e16ed833e6b8b4c3eb66c))
+
 # [1.3.0](https://github.com/danielvm-git/bigpowers/compare/v1.2.3...v1.3.0) (2026-06-02)
 
 

package/CONVENTIONS.md

@@ -34,7 +34,7 @@ You are operating within the `bigpowers` spec-driven development methodology.
 - **No Direct Coding:** When a user issues a directive like "build feature X" or "go epic 10", you MUST NOT execute the request by writing code directly.
 - **Required Skills:** You MUST route all work through the appropriate bigpowers skills.
   - Start with `survey-context` if you lack context.
-  - Use `plan-work` to generate a verifiable plan in `specs/PLAN.md` before writing any feature code.
+  - Use `plan-work` to flesh out tasks in `specs/epics/eNN-*.yaml` (with `verify:` per task) before writing any feature code.
   - Use `develop-tdd` or `execute-plan` to implement the plan.
   - Use `investigate-bug` for bug reports before writing a fix.
 - **Verification Mandate:** Every story implementation MUST end with a step-by-step manual verification script provided to the user. You must wait for the user to confirm behavioral correctness (UAT) before declaring the story done or moving to the next.

package/README.md

@@ -114,8 +114,9 @@ Every task in `bigpowers` follows a prescriptive lifecycle (see `SKILL-INDEX.md`
 | Level | Document | Responsibility |
 | :--- | :--- | :--- |
 | **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
-| **Context** | `specs/CONTEXT.md` | Tech stack, architecture, and glossary. |
-| **Scope** | `specs/SCOPE.md` | In-scope / out-of-scope and success criteria. |
+| **Context** | `specs/plans/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
+| **Scope** | `specs/requirements/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
+| **Vision** | `specs/requirements/VISION_LATEST.yaml` | North star and initiative success criteria. |
 | **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |
 | **Roadmap** | `specs/release-plan.yaml` + `specs/epics/` | WSJF-prioritized epics and stories. |
 | **Current** | `specs/state.yaml` | Session flow, active epic, handoff. |
@@ -127,7 +128,8 @@ Every task in `bigpowers` follows a prescriptive lifecycle (see `SKILL-INDEX.md`
 ## 📁 Project Structure
 
 - `scripts/`: Installation, syncing, and compliance tools.
-- `specs/`: The "Brain" of your project — all planning and decisions live here.
+- `specs/`: The "Brain" of your project — all planning and decisions live here (YAML cockpit: `state.yaml`, `release-plan.yaml`, `epics/`, `requirements/`).
+- `specs/wiki/`: Deprecated Obsidian layer — use `visual-dashboard` HTTP cockpit instead of `maintain-wiki`.
 - `docs/references/`: Theoretical foundations (Uncle Bob, Ousterhout, Karpathy, etc.).
 - `[skill-name]/`: Source files for each of the 61 skills.
 

package/compose-workflow/REFERENCE.md

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

package/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`.
 
 ---
 

package/migrate-spec/SKILL.md

@@ -128,10 +128,10 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 | 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` |
+| 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/PLAN.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/` |

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,12 +23,12 @@ 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.
 
@@ -54,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,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
@@ -39,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/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/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/scripts/sync-skills.sh

@@ -31,7 +31,7 @@ for skill_dir in "$REPO_ROOT"/*/; do
   description=$(awk '/^---/{f++} f==1 && /^description:/{p=1} p && !/^---/{print} f==2{exit}' "$skill_md" \
     | sed 's/^description:[[:space:]]*//' \
     | tr -d '\n' \
-    | sed 's/[[:space:]]\+/ /g')
+    | sed -E 's/[[:space:]]+/ /g')
 
   [[ -z "$name" ]] && continue
 
@@ -85,13 +85,13 @@ for skill_dir in "$REPO_ROOT"/*/; do
   skill_count=$((skill_count + 1))
 done
 
-# Assemble final gemini-extension.json
-pkg_version=$(grep '"version":' "$REPO_ROOT/package.json" | sed 's/.*: "\(.*\)".*/\1/')
-pkg_desc=$(grep '"description":' "$REPO_ROOT/package.json" | sed 's/.*: "\(.*\)".*/\1/')
+# Assemble final gemini-extension.json (top-level fields only — not scripts.version)
+pkg_version=$(jq -r '.version' "$REPO_ROOT/package.json")
+pkg_desc=$(jq -r '.description' "$REPO_ROOT/package.json")
 
 jq -n --arg name "bigpowers" \
       --arg version "$pkg_version" \
-      --arg desc "$skill_count+ $pkg_desc" \
+      --arg desc "${skill_count} skills — ${pkg_desc}" \
       '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
 
 # 4. Write OpenCode configuration: opencode.json (minimal project-level config)

package/seed-conventions/SKILL.md

@@ -73,7 +73,7 @@ Stack: [language, framework, runtime]
 ## Agent Rules
 - **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
 - Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
 - Write the minimum code that solves the stated problem. Nothing extra.
 - Never refactor, rename, or reorganize code outside the task scope.
 - Run tests after every change. Show evidence before declaring done.
@@ -113,7 +113,7 @@ Stack: [language, framework, runtime]
 ## Agent Rules
 - **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
 - Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
 - Write the minimum code that solves the stated problem. Nothing extra.
 - Never refactor, rename, or reorganize code outside the task scope.
 - Run tests after every change. Show evidence before declaring done.
@@ -153,7 +153,7 @@ Stack: [language, framework, runtime]
 ## Agent Rules
 - **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
 - Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
 - Write the minimum code that solves the stated problem. Nothing extra.
 - Never refactor, rename, or reorganize code outside the task scope.
 - Run tests after every change. Show evidence before declaring done.

package/session-state/SKILL.md

@@ -12,7 +12,7 @@ Track the current state of implementation, including decisions made, pending tas
 
 Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/plans/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.
 
-Legacy `specs/state.yaml` is deprecated — use `state.yaml` only.
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
 
 ## Handoff block (cold start)
 

package/spike-prototype/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: spike-prototype
 model: sonnet
-description: Throw-away prototype for unknown problem spaces. Output is learning notes in specs/SPIKE-<name>.md, not production code. Use when the domain or technology is unexplored, when estimates are impossible without experimentation, or when user says "spike", "prototype", or "proof of concept".
+description: Throw-away prototype for unknown problem spaces. Output is learning notes in specs/archive/spikes/SPIKE-<name>.md, not production code. Use when the domain or technology is unexplored, when estimates are impossible without experimentation, or when user says "spike", "prototype", or "proof of concept".
 ---
 
 # Spike Prototype
 
-A spike is a time-boxed experiment to answer a specific question. The code is thrown away. The learning is kept in `specs/SPIKE-<name>.md`.
+A spike is a time-boxed experiment to answer a specific question. The code is thrown away. The learning is kept in `specs/archive/spikes/SPIKE-<name>.md`.
 
 **The spike produces learning, not code to ship.** If you find yourself cleaning up spike code for production, stop — run `plan-work` and `develop-tdd` instead with the insights you gained.
 
@@ -46,9 +46,9 @@ Write the simplest code that could answer the question. Ignore:
 
 Focus entirely on answering the question.
 
-### 4. Write specs/SPIKE-<name>.md
+### 4. Write specs/archive/spikes/SPIKE-<name>.md
 
-Save the learning to `specs/SPIKE-<name>.md`. Create the `specs/` directory if it doesn't exist.
+Save the learning to `specs/archive/spikes/SPIKE-<name>.md`. Create the `specs/` directory if it doesn't exist.
 
 <spike-template>
 
@@ -90,4 +90,4 @@ After writing the findings, delete or discard the spike code. It is not meant to
 
 ### 6. Feed back into plan-work
 
-The spike findings are the input to `plan-work`. Call `plan-work` next, informed by `specs/SPIKE-<name>.md`.
+The spike findings are the input to `plan-work`. Call `plan-work` next, informed by `specs/archive/spikes/SPIKE-<name>.md`.

package/validate-fix/SKILL.md

@@ -92,6 +92,6 @@ Mechanical verification (tests passing) is only half the fix. You must prove **b
 - **Loop until behavioral correctness is verified**: if any checklist item fails, or if the behavior is still incorrect despite passing tests, return to step 1 and run all checks again from the top — do not declare done until every item is green and the behavior is proven correct in a single run.
 - **Never use `@ts-ignore`, `as any`, or `// eslint-disable`** to "fix" a bug — these suppress the symptom without fixing the root cause
 - **Never mark the task done if any test is still failing**
-- **The verify command from specs/bugs/BUG-*.md or specs/PLAN.md must pass**
+- **The verify command from specs/bugs/BUG-*.md or the active epic task `verify` field must pass**
 
 Suggest next skill: `audit-code` → `commit-message`.