bigpowers 2.1.3 → 2.3.0

package/.pi/skills/survey-context/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: survey-context
+description: "Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first."
+---
+
+
+# Survey Context
+
+Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
+
+> **Use this vs map-codebase:** `survey-context` consumes existing specs and docs (fast; does not re-derive). `map-codebase` builds the tech-stack doc from scratch by scanning the codebase. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
+> **HARD GATE** — Read specs/ files before suggesting next steps. If state.yaml is stale or contradicts the codebase, request clarification rather than assuming intent.
+
+Orchestrate-project 6 phases: Phase 1 Discover - Phase 2 Elaborate - Phase 3 Plan - Phase 4 Build - Phase 5 Verify - Phase 6 Release
+
+## Process
+
+### 1. Read CONVENTIONS.md
+
+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/ (YAML-first)
+
+Scan the `specs/` directory if it exists:
+
+```
+specs/
+├── 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 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
+
+If `CLAUDE.md` exists at the project root, read it for project context (stack, commands, architecture, conventions).
+
+### 4. Check git state
+
+```bash
+git status --short
+git log --oneline -5
+git branch --show-current
+```
+
+Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
+
+### 5. Map the lifecycle phase
+
+Based on what you've found, identify which PMBOK phase this project is currently in:
+
+| Phase | Signals |
+|-------|---------|
+| **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** | `state.yaml` `active_flow: build_epic`; epic capsule 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` 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: Execute
+Active branch: feat/e02-verify (state.yaml matches)
+release-plan.yaml: v3.0.0, 10 epics
+active_epic_id: e02
+
+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.
+
+### 7. Surface blockers
+
+If something looks wrong:
+- Broken tests in the baseline
+- 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.
+
+### 8. Record story start timestamp
+
+At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` for cycle-time tracking.
+
+## Utility outputs
+
+### list-epics (absorbed)
+
+Loop through all `specs/epics/*/epic.yaml` files and print a summary of story counts per epic. Useful for understanding overall project scope and epic distribution.
+
+### check-gates (absorbed)
+
+Print the current `active_flow` from `specs/state.yaml`, run `bash scripts/validate-specs-yaml.sh` to verify YAML integrity, and show `git status` to report uncommitted changes and branch state. Use before handoffs or context transitions.
+
+## Handoff
+
+Gate: READY -> next: plan-work
+Writes: state.yaml handoff.next_skill = plan-work

package/.pi/skills/terse-mode/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: terse-mode
+description: "Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use ONLY when context is critically long and compressing output is necessary to continue. Not a strategy — token discipline comes from code shape (small functions, unique names, headless tests), not terser prompts. Use when user says "caveman mode", "terse mode", "less tokens", "be brief", or invokes /terse-mode."
+---
+
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+> **HARD GATE** — **HARD GATE** — Terse mode is for reducing token usage in long sessions. Do NOT use terse mode when clarity is critical (complex design decisions, bug investigations). Enable it only on explicit user request.
+
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Auto-Clarity Exception
+
+Drop terse temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Terse resume. Verify backup exist first.

package/.pi/skills/trace-requirement/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: trace-requirement
+description: "Link story IDs from specs/release-plan.yaml + epic capsule directories 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.yaml + epic capsule directories` 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.yaml + epic capsule directories` must exist. If it doesn't, run `plan-release` first.
+
+→ verify: `[ -f specs/release-plan.yaml + epic capsule directories ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+
+Read `specs/release-plan.yaml + epic capsule directories` fully before proceeding.
+
+## Process
+
+### 1. Extract story IDs
+
+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.yaml + epic capsule directories | sort -u`
+
+### 2. Search for story tags in code
+
+Look for `// story: X.Y` or `# story: X.Y` comments in source files and tests:
+
+```
+grep -rn "story: " . --include="*.ts" --include="*.js" --include="*.py" --include="*.sh" | grep -v node_modules
+```
+
+→ verify: `grep -rn "story: " . --include="*.ts" --include="*.sh" | wc -l`
+
+### 3. Build the matrix
+
+For each story ID:
+- **Implemented**: list files that contain `// story: X.Y`
+- **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.yaml:
+- **Orphan**: code exists but story was removed or never planned — flag for cleanup
+
+### 4. Write specs/TRACEABILITY.md
+
+```
+## Story Coverage
+
+| Story | Title              | Files | Tests | Status    |
+|-------|--------------------|-------|-------|-----------|
+| 1.1   | [title]            | 2     | 1     | Covered   |
+| 1.2   | [title]            | 0     | 0     | Dark      |
+
+## Orphan Code (no story tag)
+- [file]: contains untagged implementation
+
+## Gaps (dark stories)
+- Story 1.2: no implementation found → run plan-work
+
+## Coverage summary
+Stories: [X] covered / [Y] dark / [Z] total
+```
+
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY.md`
+
+Suggest `plan-work` for each dark story found.

package/.pi/skills/using-bigpowers/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: using-bigpowers
+description: "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks "where do I start?", or when the skills system needs to be explained."
+---
+
+
+# Using bigpowers
+> **HARD GATE** — **HARD GATE** — This skill is the entry point. Do NOT skip it when onboarding new users or starting a new session. It establishes the bigpowers methodology, lifecycle phases, and conventions.
+
+
+Welcome to **bigpowers** — a lifecycle of **61** agent skills for production-ready, TDD-driven software by solo developers.
+
+## Install
+
+```bash
+npx bigpowers                  # one-shot setup
+npm install -g bigpowers       # global install, then run: bigpowers
+```
+
+From source (contributors): `git clone` → `npm install` or `bash scripts/install.sh`.
+
+Package: [bigpowers on npm](https://www.npmjs.com/package/bigpowers)
+
+## What bigpowers is
+
+A curated set of skills organized around the PMBOK developer lifecycle. Each skill does one thing. Skills reference each other by name only — low coupling, high cohesion. All written output goes to `specs/` at your project root.
+
+## The lifecycle at a glance
+
+See orchestrate-project for the canonical 6-phase lifecycle.
+
+```
+BOOTSTRAP   using-bigpowers (this skill, first time only)
+              ↓
+DISCOVER    survey-context → research-first → elaborate-spec
+              ↓
+DESIGN      model-domain / define-language / grill-me / deepen-architecture / design-interface
+              ↓
+PLAN        scope-work → slice-tasks → define-success → plan-work / plan-refactor
+              ↓
+INITIATE    kickoff-branch → guard-git / hook-commits / seed-conventions
+              ↓
+SPIKE?      spike-prototype → (feeds back to plan-work)
+              ↓
+EXECUTE     develop-tdd + enforce-first ←→ delegate-task / dispatch-agents / execute-plan
+              ↓
+VERIFY      run-evals → verify-work
+              ↓
+HARDEN      wire-observability (any phase)
+              ↓
+BUG?        investigate-bug → diagnose-root → validate-fix
+              ↓
+REVIEW      audit-code → request-review → respond-review
+              ↓
+INTEGRATE   commit-message → release-branch
+              ↓
+SUSTAIN     inspect-quality / organize-workspace (ongoing)
+
+UTILITY     terse-mode / craft-skill / edit-document (any phase)
+```
+
+## Where to start
+
+| Your situation | First skill to call |
+|---------------|---------------------|
+| Greenfield project, nothing set up | `seed-conventions` |
+| Existing project, new task | `survey-context` |
+| Vague idea that needs shaping | `elaborate-spec` |
+| Plan exists, ready to implement | `kickoff-branch` → `develop-tdd` |
+| Bug to fix | `investigate-bug` |
+| Code ready for review | `audit-code` |
+| Shipping a feature | `commit-message` → `release-branch` |
+| Solo dev, PRs feel heavy | Enable `profiles/solo-git.md` → `specs/WORKFLOW-solo-git.md` → land via `scripts/land-branch.sh` |
+
+## Solo Git profile
+
+If you work alone and do not want PR ceremony every task:
+
+1. Read [profiles/solo-git.md](../profiles/solo-git.md).
+2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`.
+3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`.
+
+You still use worktrees, protected `main`, and verification gates — only the integrate step changes.
+
+## YAML cockpit and dashboard
+
+Operational source of truth:
+
+- `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
+
+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 epic task must have `verify: <runnable command>`. Evidence over claims.
+- **61 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+
+## After this
+
+Call `survey-context` to read your project's current state and get a personalized recommendation for where to go next.

package/.pi/skills/validate-fix/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: validate-fix
+description: "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says "is this fixed?", or before closing an investigation."
+---
+
+
+# Validate Fix
+> **HARD GATE** — **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success. A fix that passes tests but breaks something else is a failure.
+
+
+Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence.
+
+## Checklist
+
+### 1. Re-run the originally failing test
+
+```bash
+# Run the specific test that captured the bug
+<test command for the failing test>
+```
+
+- [ ] Previously failing test now passes
+
+### 2. Run the full test suite
+
+```bash
+# Run all tests — no filtering
+<full test command from CLAUDE.md>
+```
+
+- [ ] All tests pass (zero regressions)
+
+### 3. Type check
+
+```bash
+<typecheck command>
+```
+
+- [ ] No type errors introduced
+
+### 4. Lint
+
+```bash
+<lint command>
+```
+
+- [ ] No lint violations introduced
+
+### 5. Harden against recurrence
+
+For every bug fixed, add at least one prevention layer:
+
+| Mechanism | When to use |
+|-----------|-------------|
+| Type guard | Input could be the wrong shape |
+| Schema validation (Zod, Pydantic, etc.) | External data crossing a boundary |
+| Invariant assertion | Internal state that must always hold |
+| Lint rule | Pattern that's easy to repeat by mistake |
+| Environment check at startup | Missing config causes silent failure |
+
+- [ ] At least one hardening mechanism added
+- [ ] Hardening mechanism is tested
+
+### 6. Update the bug file and registry.yaml
+
+Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
+
+```markdown
+## Resolution
+
+**Fixed:** [date]
+**Root cause confirmed:** [one sentence]
+**Fix applied:** [what was changed]
+**Hardening added:** [type guard / schema / assertion / lint rule]
+**Evidence:** all tests pass (`<verify command>`)
+**Commit:** `fix(<scope>): <description>`
+```
+
+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/registry.yaml row updated with resolution fields
+
+### 7. Behavioral Proof (HARD GATE)
+
+Mechanical verification (tests passing) is only half the fix. You must prove **behavioral correctness**.
+
+- [ ] Manually demonstrate the fixed behavior (e.g., via `run_shell_command` or `web_fetch`)
+- [ ] Compare the output/state against the "Expected Behavior" in the bug file
+- [ ] Show the user evidence of the behavior, not just the test logs
+
+## Rules
+
+- **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 the active epic task `verify` field must pass**
+
+Suggest next skill: `audit-code` → `commit-message`.

package/.pi/skills/verify-work/SKILL.md

@@ -0,0 +1,126 @@
+---
+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.model: haiku"
+---
+
+
+# Verify Work
+
+> **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?"
+
+## Modes
+
+- Default: full UAT plus gaps loop
+- --smoke: Cold-start only plus one happy-path flow. Use for hotfixes.
+
+## Process
+
+0. **Branch check** — must not be `main`/`master`.
+
+1. Read active story tasks from `specs/epics/<capsule>/eNNsYY-tasks.yaml` and story spec from `specs/epics/<capsule>/eNNsYY-<slug>.md` (countable-story-format, Gherkin in §17).
+2. **Cold-start smoke** (if app): stop server, clear caches, boot from scratch.
+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.
+
+## Verify sub-operations
+
+### Cold-Start Smoke (absorbed)
+
+For applications, verify correctness from a clean state:
+
+- Stop the running server (if any)
+- Clear any caches (browser, application caches, compiled artifacts)
+- Boot the application from scratch
+- Verify that no stale artifacts or configuration are affecting the behavior
+
+This catches environment-specific bugs and ensures the build is reproducible.
+
+### Gaps Loop (absorbed)
+
+After UAT, identify and close any gaps between promised behavior and actual behavior:
+
+- Capture what was promised in the epic task description
+- Document what actually happened (expected vs actual)
+- If behavior doesn't match the promises, log the gap
+- Loop back to `plan-work` or `develop-tdd` to fix the gap
+- Re-verify until all gaps are closed (gaps count = 0)
+
+## UAT dialogue
+
+- Pass: user confirms per step.
+- Fail: capture expected vs actual; do not mark done in `execution-status.yaml`.
+
+## Persist verification evidence
+
+After UAT passes, write structured evidence to `specs/verifications/eNNsYY-verify.yaml`:
+
+```yaml
+story_id: e01s01
+verified_at: "2026-06-11T14:30:00Z"
+verifier: verify-work
+phases:
+  smoke:
+    passed: true
+  build:
+    passed: true
+    command: "npm run build"
+  typecheck:
+    passed: true
+  lint:
+    passed: true
+  tests:
+    passed: true
+    coverage: "94.2%"
+  manual:
+    steps:
+      - step: "Open /login"
+        expected: "Login form renders"
+        actual: "Login form rendered correctly"
+        passed: true
+  gaps:
+    closed: true
+```
+
+> **HARD GATE** — Verification evidence MUST be persisted before marking the story done. No evidence = not verified.
+
+## Verify
+
+→ verify: `test -f specs/verifications/<story_id>-verify.yaml && echo "Evidence persisted"`
+
+See [REFERENCE.md](REFERENCE.md) for cold-start and gaps template.
+
+## Handoff
+
+Gate: READY -> next: audit-code
+Writes: state.yaml handoff.next_skill = audit-code
+
+---
+
+# Verify Work — Reference
+
+## Cold-start smoke
+
+```bash
+# Example — adapt to project CLAUDE.md
+pkill -f "<dev-server>" 2>/dev/null || true
+rm -rf .next/cache node_modules/.cache 2>/dev/null || true
+<run command> &
+sleep 3 && curl -sf http://localhost:<port>/health || echo "BOOT FAIL"
+```
+
+## Gaps template
+
+```markdown
+## Gaps (verify-work)
+
+| Step | Expected | Actual | Status |
+|------|----------|--------|--------|
+| 1 | ... | ... | FAIL |
+```
+
+Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work.

package/.pi/skills/visual-dashboard/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: visual-dashboard
+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
+> **HARD GATE** — **HARD GATE** — Dashboards are read-only. Do NOT use visualization to make decisions without consulting the source data. 'The chart looks better' is not a decision.
+
+
+Browser-based visual companion for bigpowers. Visualizes architecture, plans, and status.
+
+## HTTP cockpit (YAML SoT)
+
+Start the server:
+
+```bash
+bash visual-dashboard/scripts/start-server.sh
+```
+
+Endpoints:
+
+| 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) |
+
+Example:
+
+```bash
+curl -s "http://127.0.0.1:PORT/api/status?projectDir=$PWD" | jq .release.version
+```
+
+Implementation: `visual-dashboard/scripts/read-specs-status.cjs` + `server.cjs`.
+
+## Opencode Progress Panel
+
+Projects using bigpowers in opencode can read `specs/state.yaml`, `specs/release-plan.yaml`, and active `specs/epics/*.yaml` directly (no checkbox `### WS1` markdown).
+
+Required YAML keys:
+
+- **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`
+
+## Agent screens (optional)
+
+Push HTML to the dashboard session dir for rich diagrams. See `start-server.sh` for `CONTENT_DIR`.
+
+→ verify: `test -f visual-dashboard/scripts/read-specs-status.cjs && test -f visual-dashboard/scripts/cockpit.html`