bigpowers 1.2.3 → 1.3.1

package/session-state/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: session-state
 model: haiku
-description: Track implementation decisions and progress in specs/STATE.md to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
+description: Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
 ---
 
 # Session State
@@ -10,82 +10,91 @@ Track the current state of implementation, including decisions made, pending tas
 
 ## Goal
 
-Maintain a single source of truth for the *current* state of the work in `specs/STATE.md`. This file acts as the project's short-term memory, complementing the long-term memory of `specs/CONTEXT.md` and the task-specific instructions in `specs/RELEASE-PLAN.md`.
+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`.
 
-## Handoff block (cold start)
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
 
-When ending a session or before a context-heavy spawn, write a **Handoff** section at the top of STATE.md:
+## Handoff block (cold start)
 
-```markdown
-## Handoff
-- **Last step completed:** ...
-- **Open decisions:** ...
-- **Required reading:** CONVENTIONS.md, RELEASE-PLAN.md story X.Y, ...
-- **Next skill:** verify-work | develop-tdd | ...
+When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
+
+```yaml
+handoff:
+  last_step_completed: "e02s01 verify-work passed"
+  open_decisions:
+    - "Use folder mode for e07 (>5 stories)"
+  required_reading:
+    - CONVENTIONS.md
+    - specs/epics/e02-verification/epic.yaml
+  next_skill: develop-tdd
 ```
 
 ## Strategic compaction
 
 | Trigger | Action |
 |---------|--------|
-| Phase transition (Plan → Build → Verify) | Compact Handoff; archive verbose decisions to ADR |
+| Phase transition (Plan → Build → Verify) | Compact handoff; archive verbose decisions to ADR |
 | Context > 70% estimated | Run terse-mode for status only; move detail to specs/ |
-| Before `dispatch-agents` wave | STATE.md only channel between spawns |
+| Before `dispatch-agents` wave | `state.yaml` only channel between spawns |
 
 ## Workflow
 
 ### 1. Initialize (Session Start)
 
-If `specs/STATE.md` does not exist, or if starting a new major phase:
+If `specs/state.yaml` does not exist, or if starting a new major phase:
 
-- [ ] Read `specs/RELEASE-PLAN.md` and `specs/SCOPE.md`.
-- [ ] Get git metadata: `git branch --show-current` and `git rev-parse HEAD`.
-- [ ] Create `specs/STATE.md` with the current milestone, git metadata, pending tasks, and any active decisions.
+- [ ] Read `specs/release-plan.yaml` and `specs/requirements/SCOPE_LATEST.yaml`.
+- [ ] Get git metadata: `git branch --show-current` and `git rev-parse --short HEAD`.
+- [ ] Create `specs/state.yaml` with active flow, git, handoff, and epic cycle if in build.
 
 ### 2. Load (Context Refresh)
 
 When starting a new session or after a significant context flush:
 
-- [ ] Read `specs/STATE.md` to understand where the previous agent left off.
-- [ ] Verify the current state matches the actual codebase (run `git branch` and `git diff`).
-- [ ] Surface any discrepancies between recorded git hash and current hash.
+- [ ] Read `specs/state.yaml` to understand where the previous agent left off.
+- [ ] Read `specs/execution-status.yaml` for story progress (do not infer from release-plan).
+- [ ] Verify git matches `state.yaml` `git.branch` / `git.hash`.
 
 ### 3. Update (Decision Point/Milestone)
 
 Whenever a significant decision is made or a milestone is reached:
 
-- [ ] Update git metadata if the branch or hash has changed.
-- [ ] Update the `Active Decisions` section with the rationale for the choice.
-- [ ] Mark completed tasks as done.
-- [ ] Add new pending tasks discovered during implementation.
-- [ ] Record any "Open Questions" that need user clarification.
-
-## File Format: specs/STATE.md
-
-```markdown
-# Session State: [Feature Name]
-
-## Current Milestone
-[What is being worked on right now]
-
-## Git Metadata
-- **Branch**: [branch-name]
-- **Hash**: [commit-hash]
-
-## Pending Tasks
-...
-```
-- [ ] Task 2
-
-## Active Decisions
-- **Decision Name**: [Rationale and impact]
-
-## Open Questions
-- [Question for the user]
+- [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
+- [ ] Update `handoff.open_decisions` with rationale.
+- [ ] Update `epic_cycle` when advancing `ship-epic` steps.
+- [ ] Record open questions under `handoff.open_decisions` or an ADR.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+
+## File Format: specs/state.yaml
+
+```yaml
+active_flow: build_epic       # planning | build_epic | fix_bug
+active_epic_id: e02
+active_story_id: e02s01       # required when epic mode: folder
+active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
+release:
+  target_version: "3.0.0"
+  last_tag: null
+  last_publish: null
+epic_cycle:
+  current_step: develop-tdd
+  next_skill: develop-tdd
+  completed_steps: [kickoff-branch]
+bug_cycle:
+  current_step: null
+  completed_steps: []
+git:
+  branch: feat/e02-verify
+  hash: abc1234
+handoff:
+  last_step_completed: null
+  open_decisions: []
+  next_skill: survey-context
 ```
 
 ## Anti-Patterns
 
-- **Duplicate Plan**: Don't just copy `specs/RELEASE-PLAN.md`. The plan is the *intended* path; the state is the *actual* progress and the deviations from that path.
-- **Stale State**: Forgetting to update `specs/STATE.md` after a major refactor or decision.
-- **Verbose History**: Keep it focused on the *current* state. Use git history for the past.
+- **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.
+- **Stale State**: Forgetting to update `state.yaml` after a major refactor or decision.
+- **Status in release-plan**: Story/epic status lives only in `execution-status.yaml`.

package/setup-environment/SKILL.md

@@ -15,7 +15,7 @@ Idempotent prep so BUILD phase commands succeed on first run.
 3. Install dependencies (`npm ci`, `bundle install`, etc.) — prefer lockfile installs.
 4. Copy `.env.example` → `.env` if documented; never commit secrets.
 5. Run smoke: lint + one fast test or `--version` on key tools.
-6. Record versions in `specs/STATE.md` under Environment.
+6. Record versions in `specs/state.yaml` under Environment.
 
 ## Verify
 

package/slice-tasks/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: slice-tasks
-description: Break a plan or PRD into independently-grabbable vertical-slice tasks in specs/TASKS.md. Use after scope-work or plan-release, before plan-work, when user wants implementation tickets or tracer-bullet slices.
+description: Break a plan or PRD into vertical-slice stories in specs/epics/ (replaces legacy TASKS.md). Use after scope-work or plan-release, before plan-work.
 model: sonnet
 ---
 
 # Slice Tasks
 
-Produce `specs/TASKS.md` — vertical slices, each independently deliverable and testable.
+Produce **epic shard stories** in `specs/epics/eNN-*.yaml` — vertical slices, each independently deliverable and testable. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use epics + `execution-status.yaml`.
 
 ## Process
 
-1. Read `specs/SCOPE.md` and/or `specs/RELEASE-PLAN.md`.
+1. Read `specs/requirements/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
 2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
-3. Each task entry: `id`, `title`, `depends-on:` (optional), `verify:` command, `story:` link.
-4. Order by WSJF within the file.
+3. Each story: `id` (e.g. `e03s01`), `title`, optional `depends-on` in task desc, `tasks[]` with `desc` + `verify`.
+4. Order by WSJF in `release-plan.yaml` epic list.
 
 > **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration.
 
 ## Verify
 
-→ verify: `test -f specs/TASKS.md && grep -c "verify:" specs/TASKS.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `grep -c 'id: e' specs/epics/*.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`

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/survey-context/SKILL.md

@@ -14,23 +14,30 @@ Read the project's current state and give a phase map + next-skill recommendatio
 
 If `CONVENTIONS.md` exists at the project root, read it first. It contains the rules all agents must follow in this project.
 
-### 2. Read specs/
+### 2. Read specs/ (YAML-first)
 
 Scan the `specs/` directory if it exists:
 
 ```
 specs/
-├── CONTEXT.md          → domain model status
-├── UBIQUITOUS_LANGUAGE.md → glossary status
-├── SCOPE.md            → scope definition status
-├── TASKS.md            → task breakdown status
-├── RELEASE-PLAN.md     → implementation plan status
-├── REFACTOR.md         → refactor plan status
-├── bugs/               → bug investigations (BUG-*.md) + BUG-LOG.md
-└── SPIKE-*.md          → spike learning notes
+├── state.yaml                  → session: active_flow, epic, git, handoff
+├── release-plan.yaml           → target version, WSJF epic index
+├── execution-status.yaml       → flat story/epic status
+├── planning-status.yaml        → discover-phase checklist (optional)
+├── requirements/
+│   ├── VISION_LATEST.yaml
+│   ├── SCOPE_LATEST.yaml
+│   └── GLOSSARY_LATEST.yaml
+├── plans/                      → TECH_STACK, TEST_PLAN, etc.
+├── epics/                      → eNN shards (flat yaml or eNN/stories/)
+└── bugs/                       → BUG-*.md + registry.yaml
 ```
 
-For each file found, note: does it exist? Is it complete? Does it have open items?
+For each YAML file found, note: exists? keys populated? `handoff.next_skill`?
+
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT if YAML exists.
+
+→ verify: `bash scripts/validate-specs-yaml.sh 2>/dev/null || echo "YAML layout incomplete"`
 
 ### 3. Read CLAUDE.md
 
@@ -44,7 +51,7 @@ git log --oneline -5
 git branch --show-current
 ```
 
-Note: is there a feature branch active? Are there uncommitted changes? Are there unpushed commits?
+Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
 
 ### 5. Map the lifecycle phase
 
@@ -52,33 +59,36 @@ Based on what you've found, identify which PMBOK phase this project is currently
 
 | Phase | Signals |
 |-------|---------|
-| **Discover** | No specs/ yet, or only rough notes |
-| **Design** | specs/SCOPE.md exists but no RELEASE-PLAN.md |
-| **Plan** | specs/TASKS.md or RELEASE-PLAN.md exists; on `main`/`master` branch |
+| **Discover** | No `requirements/SCOPE_LATEST.yaml` yet, or only rough notes |
+| **Design** | SCOPE exists but no `release-plan.yaml` |
+| **Plan** | `release-plan.yaml` exists; on `main`/`master` branch |
 | **Initiate** | On a feature branch; no code changes yet |
-| **Execute** | RELEASE-PLAN.md exists; on feature branch; steps in progress |
-| **Verify** | Implementation done; run `verify-work` or `run-evals`; awaiting UAT |
-| **Bug** | `specs/bugs/BUG-*.md` exists; on `main`/`master` |
+| **Execute** | `state.yaml` `active_flow: build_epic`; epic shard in progress |
+| **Verify** | Implementation done; run `verify-work` or `run-evals` |
+| **Bug** | `state.yaml` `active_flow: fix_bug` or open `specs/bugs/BUG-*.md` |
 | **Review** | All code written; no PR yet |
 | **Integrate** | PR open; tests passing |
 | **Sustain** | Ongoing; no active task |
 
+Prefer `specs/state.yaml` `active_flow` and `handoff.next_skill` when present.
+
 ### 6. Suggest next skill
 
 Based on the phase and state, recommend the most useful next step:
 
 - **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
-- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan`.
-- **If in Execute phase**: Suggest `develop-tdd` (continue step X) or `execute-plan`.
-- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals` (capability evals).
+- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan` or `ship-epic`.
+- **If in Execute phase**: Suggest `ship-epic` (resume) or `develop-tdd` for `active_story_id`.
+- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals`.
 
 Example:
 ```
-Phase: Plan
-Active branch: main
-RELEASE-PLAN.md: exists
+Phase: Execute
+Active branch: feat/e02-verify (state.yaml matches)
+release-plan.yaml: v3.0.0, 10 epics
+active_epic_id: e02
 
-Suggested next: kickoff-branch (to create feature/auth branch)
+Suggested next: ship-epic (resume e02s01 at develop-tdd)
 ```
 
 Be specific — name the exact skill and why. If multiple options exist, list them in priority order.
@@ -87,8 +97,9 @@ Be specific — name the exact skill and why. If multiple options exist, list th
 
 If something looks wrong:
 - Broken tests in the baseline
-- `specs/bugs/BUG-*.md` open with no active fix branch
-- RELEASE-PLAN.md with missing verify commands or Verification Script sections
-- CONVENTIONS.md violations in recent commits
+- Open `specs/bugs/BUG-*.md` with no active fix branch
+- Epic shards missing `verify:` on tasks
+- `validate-specs-yaml.sh` fails
+- Git hash in `state.yaml` stale vs `git rev-parse`
 
 Report blockers first, before recommendations.

package/trace-requirement/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: trace-requirement
 model: haiku
-description: Link story IDs from specs/RELEASE-PLAN.md to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
+description: Link story IDs from specs/release-plan.yaml + epic shards to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
 ---
 
 # Trace Requirement
 
-Build a traceability matrix from `specs/RELEASE-PLAN.md` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
+Build a traceability matrix from `specs/release-plan.yaml + epic shards` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
 
 ## Pre-flight
 
-> **HARD GATE** — `specs/RELEASE-PLAN.md` must exist. If it doesn't, run `plan-release` first.
+> **HARD GATE** — `specs/release-plan.yaml + epic shards` must exist. If it doesn't, run `plan-release` first.
 
-→ verify: `[ -f specs/RELEASE-PLAN.md ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+→ verify: `[ -f specs/release-plan.yaml + epic shards ] && echo "ready" || echo "BLOCKED: run plan-release first"`
 
-Read `specs/RELEASE-PLAN.md` fully before proceeding.
+Read `specs/release-plan.yaml + epic shards` fully before proceeding.
 
 ## Process
 
 ### 1. Extract story IDs
 
-From RELEASE-PLAN.md, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
+From release-plan.yaml, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
 
-→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/RELEASE-PLAN.md | sort -u`
+→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/release-plan.yaml + epic shards | sort -u`
 
 ### 2. Search for story tags in code
 
@@ -41,7 +41,7 @@ For each story ID:
 - **Tested**: list test files that contain `// story: X.Y`
 - **Dark**: story has no tag in any file — flag as unimplemented
 
-For each tagged file with no matching story ID in RELEASE-PLAN.md:
+For each tagged file with no matching story ID in release-plan.yaml:
 - **Orphan**: code exists but story was removed or never planned — flag for cleanup
 
 ### 4. Write specs/TRACEABILITY.md

package/using-bigpowers/SKILL.md

@@ -6,7 +6,7 @@ description: One-time bootstrap that introduces the bigpowers skills system, the
 
 # Using bigpowers
 
-Welcome to **bigpowers** — a lifecycle of **59** agent skills for production-ready, TDD-driven software by solo developers.
+Welcome to **bigpowers** — a lifecycle of **61** agent skills for production-ready, TDD-driven software by solo developers.
 
 ## Install
 
@@ -78,23 +78,24 @@ If you work alone and do not want PR ceremony every task:
 
 You still use worktrees, protected `main`, and verification gates — only the integrate step changes.
 
-## Obsidian wiki cockpit (optional)
+## YAML cockpit and dashboard
 
-For accumulated project understanding and a read-only PM view:
+Operational source of truth:
 
-1. Read [profiles/obsidian-wiki.md](../profiles/obsidian-wiki.md).
-2. Open `specs/` as an Obsidian vault; landing page `COCKPIT.md`.
-3. Run `maintain-wiki` **sync** before merge (merge gate).
+- `specs/state.yaml` — session, active epic/story, handoff
+- `specs/release-plan.yaml` — release index and epic list
+- `specs/epics/eNN-*.yaml` — stories and tasks with `verify`
+- `specs/execution-status.yaml` — done/pending per story
 
-Operational specs (STATE, RELEASE-PLAN) stay source of truth; `specs/wiki/` is LLM-synthesized navigation.
+Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir=<abs>` and `GET /cockpit.html` for a read-only PM view.
 
 ## Key conventions
 
 - **specs/ is your memory.** All domain docs, plans, and investigation outputs go in `specs/` at your project root.
 - **Integrate:** team default is `gh pr` (team-pr); solo profile uses `land-branch.sh`. Never create GitHub issues from skills — use local Markdown files instead.
 - **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
-- **verify: every step.** Every task in `specs/RELEASE-PLAN.md` must have a `verify: <runnable command>`. Evidence over claims.
-- **59 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+- **verify: every step.** Every epic task must have `verify: <runnable command>`. Evidence over claims.
+- **61 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
 
 ## After this
 

package/validate-fix/SKILL.md

@@ -59,7 +59,7 @@ For every bug fixed, add at least one prevention layer:
 - [ ] At least one hardening mechanism added
 - [ ] Hardening mechanism is tested
 
-### 6. Update the bug file and BUG-LOG.md
+### 6. Update the bug file and registry.yaml
 
 Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
 
@@ -74,10 +74,10 @@ Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
 **Commit:** `fix(<scope>): <description>`
 ```
 
-Also update the corresponding row in `specs/bugs/BUG-LOG.md`: set `status` to `fixed`, fill in `files_changed`, `approach`, `risk_level`, `commit_message`, and any other resolution fields.
+Also update the corresponding row in `specs/bugs/registry.yaml`: set `status` to `fixed`, fill in `files_changed`, `approach`, `risk_level`, `commit_message`, and any other resolution fields.
 
 - [ ] specs/bugs/BUG-*.md updated with resolution
-- [ ] specs/bugs/BUG-LOG.md row updated with resolution fields
+- [ ] specs/bugs/registry.yaml row updated with resolution fields
 
 ### 7. Behavioral Proof (HARD GATE)
 
@@ -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`.

package/verify-work/SKILL.md

@@ -1,39 +1,34 @@
 ---
 name: verify-work
-description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code, when a story needs proof it works.
+description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.
 model: haiku
 ---
 
 # Verify Work
 
-> **HARD GATE** — No story is "done" until its `## Verification Script` from RELEASE-PLAN.md is confirmed by the user or agent with evidence.
-
-> **HARD GATE** — Do NOT run verify-work on `main` or `master`. Run from the feature branch or worktree created by `kickoff-branch`.
+> **HARD GATE** — No story is "done" until manual UAT for the active story is confirmed with evidence.
+>
+> **HARD GATE** — Do NOT run on `main` or `master`. Use the feature branch from `kickoff-branch`.
 
 Review answers "is the code good?"; Verify answers "does the built thing do what was promised?"
 
 ## Process
 
-0. **Branch check** (before any gates):
-
-```bash
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-# Must not be main or master — run kickoff-branch first
-```
+0. **Branch check** — must not be `main`/`master`.
 
-1. Read the story's `## Verification Script` from `specs/RELEASE-PLAN.md`.
+1. Read active story tasks and any **Verification Script** notes in `specs/epics/{active}.yaml` or story `.md` under `specs/epics/eNN/stories/`.
 2. **Cold-start smoke** (if app): stop server, clear caches, boot from scratch.
-3. Run mechanical gates: build → typecheck → lint → full test suite (commands from CLAUDE.md).
-4. **Step-by-step UAT**: one user-observable action at a time; record pass/fail.
-5. **Gaps loop**: failed steps → log as Gaps → feed back to `plan-work` → re-verify until pass.
+3. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md`).
+4. **Step-by-step UAT** — one user-observable action at a time.
+5. **Gaps loop** — failures → log → `plan-work` → re-verify.
 
 ## UAT dialogue
 
-- Pass: user confirms `yes` / `next` / `ok` per step.
-- Fail: capture expected vs actual; do not mark story done.
+- Pass: user confirms per step.
+- Fail: capture expected vs actual; do not mark done in `execution-status.yaml`.
 
 ## Verify
 
-→ verify: `grep -c "Verification Script" specs/RELEASE-PLAN.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `grep -c 'verify:' specs/epics/*.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`
 
 See [REFERENCE.md](REFERENCE.md) for cold-start and gaps template.

package/visual-dashboard/SKILL.md

@@ -1,99 +1,50 @@
 ---
 name: visual-dashboard
 model: sonnet
-description: Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Use when showing complex diagrams, progress roadmaps, or UI mockups would be clearer than text. Persists artifacts in .bigpowers/dashboard/. Also maintains specs/STATE.md and specs/RELEASE-PLAN.md in the correct format for the opencode progress panel.
+description: Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Persists artifacts in .bigpowers/dashboard/. Reads specs/state.yaml, release-plan.yaml, epics, and planning-status via HTTP API or opencode panel.
 ---
 
 # Visual Dashboard
 
 Browser-based visual companion for bigpowers. Visualizes architecture, plans, and status.
 
-## Opencode Progress Panel
-
-Projects using bigpowers in opencode get a **live progress panel** (right sidebar) that reads `specs/STATE.md` and `specs/RELEASE-PLAN.md` directly. Toggle it with the document icon (⬚) in the opencode session header.
-
-### Spec file format requirements
-
-**`specs/STATE.md`** — the parser extracts:
-- Project name from `# Session State: <name>`
-- Milestone from `## Current Milestone` → first `**bold**` = name, `(parens)` = status
-- Pending items from `## Pending` → `- [ ]` / `- [x]` lines
-
-```markdown
-# Session State: my-project
-
-## Current Milestone
-
-**v1.0.0 — Feature Name** (in progress)
-
-## Pending
-
-- [ ] Remaining task
-- [x] Completed task
-```
-
-**`specs/RELEASE-PLAN.md`** — the parser extracts:
-- Workstreams from `### WSN — Title · WSJF N.N` headings
-- Steps from `- [ ]` / `- [x]` lines inside each workstream block
-
-```markdown
-## Workstreams (WSJF order)
-
-### WS1 — Feature Area · WSJF 4.5
+## HTTP cockpit (YAML SoT)
 
-- [x] Step already done
-- [ ] Step pending
+Start the server:
 
-→ verify: `<command>`
+```bash
+bash visual-dashboard/scripts/start-server.sh
 ```
 
-**Parser rules:**
-- Only `[ ]` and `[x]`/`[X]` are recognised as step markers.
-- `→ verify:` lines are ignored.
-- Steps outside a `### WSN —` block are not picked up.
-- Missing `## Current Milestone` → panel shows "No specs found".
-
-After completing a step, update the checkbox in-place; the panel auto-refreshes every 30 s or on manual ↺.
-
----
-
-## When to Use
-
-Use when the user would understand the project state better by seeing it than reading it.
+Endpoints:
 
-- **Architecture maps** — visualizing module dependencies and "code rot."
-- **Implementation progress** — seeing the vertical slices of a `PLAN.md` as a visual roadmap.
-- **UI brainstorming** — wireframes and layout options.
-- **Complexity audits** — visualizing "God classes" vs "Clean modules."
+| Route | Purpose |
+|-------|---------|
+| `GET /api/status?projectDir=<abs>` | JSON: `state`, `release`, `epics[]`, `planning_status`, `active_epic` |
+| `GET /cockpit.html?projectDir=<abs>` | Read-only PM view (planning left, epics right) |
+| `GET /` | Agent-pushed HTML screens (legacy, unchanged) |
 
-## How It Works
-
-The server watches for updates to your artifacts and serves a dashboard to the browser. You write visual representations (HTML fragments) to the dashboard's `screen_dir`, and the user interacts with them.
-
-## Starting a Session
+Example:
 
 ```bash
-# Start server with project persistence
-visual-dashboard/scripts/start-server.sh --project-dir $(pwd)
+curl -s "http://127.0.0.1:PORT/api/status?projectDir=$PWD" | jq .release.version
 ```
 
-Save the `url`, `screen_dir`, and `state_dir` from the response. Tell the user to open the dashboard.
+Implementation: `visual-dashboard/scripts/read-specs-status.cjs` + `server.cjs`.
+
+## Opencode Progress Panel
 
-## Dashboard Loops
+Projects using bigpowers in opencode can read `specs/state.yaml`, `specs/release-plan.yaml`, and active `specs/epics/*.yaml` directly (no checkbox `### WS1` markdown).
 
-### 1. The Architecture View
-When using `deepen-architecture`, push a Mermaid diagram of the target modules to the dashboard.
-Filename: `architecture.html`
+Required YAML keys:
 
-### 2. The Plan View
-When using `plan-work`, push a step-by-step progress map.
-Filename: `plan.html`
+- **state.yaml** — `active_flow`, `active_epic_id`, `git`, `handoff`, `epic_cycle`
+- **release-plan.yaml** — `release.version`, `epics[]` with `id`, `title`, `wsjf`, `file`
+- **execution-status.yaml** — `development_status` map (story/epic → `done` | `pending`)
+- **planning-status.yaml** — discover workflows and `status: done|pending`
 
-### 3. User Interaction
-Read `state_dir/events` to see which components or options the user clicked in the dashboard. Use this to refine your next design pass.
+## Agent screens (optional)
 
-## Cleaning Up
+Push HTML to the dashboard session dir for rich diagrams. See `start-server.sh` for `CONTENT_DIR`.
 
-```bash
-visual-dashboard/scripts/stop-server.sh $SESSION_DIR
-```
+→ verify: `test -f visual-dashboard/scripts/read-specs-status.cjs && test -f visual-dashboard/scripts/cockpit.html`