bigpowers 1.5.1 → 2.0.0

package/plan-release/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: plan-release
 model: sonnet
-description: Convert elaborated specs into a structured release plan with Gherkin acceptance criteria and WSJF-sorted epics. Produces specs/release-plan.yaml and specs/epics/eNN-*.yaml. Use when a spec is clear and ready to plan, after elaborate-spec, or when the user wants a release plan broken into epics and stories.
+description: Convert elaborated specs into a structured release plan with Gherkin acceptance criteria and WSJF-sorted epics. Produces specs/release-plan.yaml and epic capsule directories (specs/epics/eNN-slug/) with epic.yaml manifests, countable-story-format .md specs, and decoupled -tasks.yaml files. Use when a spec is clear and ready to plan, after elaborate-spec, or when the user wants a release plan broken into epics and stories.
 ---
 
 # Plan Release
 
 > **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.
 
-> **HARD GATE** — `specs/requirements/SCOPE_LATEST.yaml` (or legacy `specs/requirements/SCOPE_LATEST.yaml`) must exist. If missing, run `scope-work` first.
+> **HARD GATE** — `specs/product/SCOPE_LATEST.yaml` (or legacy `specs/product/SCOPE_LATEST.yaml`) must exist. If missing, run `scope-work` first.
 
 Synthesize the conversation context into `specs/release-plan.yaml` (index) and shard detail under `specs/epics/`. No new interview — only clarify if something is genuinely ambiguous.
 
@@ -16,9 +16,27 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s
 
 | File | Content |
 |------|---------|
-| `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list (`id: e01`, `file:`, `mode:`) — **no story status** |
-| `specs/epics/eNN-<slug>.yaml` | Epic metadata, `covers: [fr-x]`, stories with tasks and `verify:` |
-| `specs/execution-status.yaml` | Regenerate keys via `bash scripts/sync-status-from-epics.sh` after epics exist |
+| `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** |
+| `specs/epics/eNN-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
+| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
+| `specs/epics/eNN-<slug>/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task |
+| `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) |
+
+## Epic Capsule Structure
+
+All epics use capsule directories (no flat/folder distinction):
+
+```
+specs/epics/e01-auth-system/
+├── epic.yaml              # Epic manifest
+├── adr/                   # Epic-local ADRs (created lazily)
+├── e01s01-login.md        # Story spec (countable-story-format)
+├── e01s01-tasks.yaml      # Decoupled task checklist
+├── e01s02-jwt.md          # Story spec
+└── e01s02-tasks.yaml      # Decoupled task checklist
+```
+
+**Rationale:** Capsule dirs achieve change isolation (C9), enable archive pruning (C2/C6), and enforce SRP by decoupling spec `.md` from execution `-tasks.yaml` (C1). See `sdd-adequacy-ranking.md` for the full 10-criteria scoring.
 
 ## Process
 
@@ -49,51 +67,79 @@ release:
   bump_hint: minor          # patch | minor | major — CI decides at merge
 epics:
   - id: e01
-    title: Security
+    title: Auth System
     wsjf: 4.5
-    file: epics/e01-security.yaml
-    mode: flat              # flat | folder (folder if >5 stories)
+    capsule_dir: epics/e01-auth-system
   - id: e02
-    title: Verification
-    wsjf: 4.3
-    file: epics/e02-verification/epic.yaml
-    mode: folder
+    title: User Profile
+    wsjf: 3.8
+    capsule_dir: epics/e02-user-profile
 ```
 
-### 5. Save epic shards
+### 5. Save epic manifest (`epic.yaml`)
 
-**Flat** (`mode: flat`, ≤ ~5 stories):
+Each epic capsule directory contains an `epic.yaml` manifest:
 
 ```yaml
 id: e01
-title: Security
+title: Auth System
 wsjf: 4.5
-covers: [fr-08]
+total_bcps: 8
+status: in_progress
 stories:
   - id: e01s01
-    title: Guard git hooks
-    tasks:
-      - desc: Block push on main
-        verify: "grep -q guard-git .cursor/rules/guard-git.mdc"
+    title: Login
+    bcps: 3
+    status: todo
+    spec: e01s01-login.md
+    tasks: e01s01-tasks.yaml
+  - id: e01s02
+    title: JWT Token Management
+    bcps: 5
+    status: todo
+    spec: e01s02-jwt.md
+    tasks: e01s02-tasks.yaml
 ```
 
-**Folder GSD** (`mode: folder`): `epics/e02-verification/epic.yaml` + `stories/e02s01-*.md` with YAML frontmatter for tasks.
+### 6. Save story specs (countable-story-format .md)
 
-→ verify: `bash scripts/validate-specs-yaml.sh`
+Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
 
-→ verify: `grep -c 'id: e' specs/release-plan.yaml`
+### 7. Save decoupled task files (`-tasks.yaml`)
+
+Each story has a decoupled `-tasks.yaml` with implementation steps:
+
+```yaml
+story_id: e01s01
+title: Login
+status: todo
+bcps: 3
+tasks:
+  - id: 1
+    description: "Add login form component tests"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+  - id: 2
+    description: "Implement login form with validation"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+```
+
+> **HARD GATE** — Every task MUST have a runnable `verify:` command. No `verify:` = not a task.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
 
-### 6. Sync execution status
+### 8. Sync execution status
 
 ```bash
 bash scripts/sync-status-from-epics.sh
 ```
 
-### 7. Snapshot on planning close (optional)
+### 9. Snapshot on planning close (optional)
 
-Copy to `specs/requirements/snapshots/release-<version>/` when the user approves the plan.
+Copy to `specs/product/snapshots/release-<version>/` when the user approves the plan.
 
-### 8. Suggest next steps
+### 10. Suggest next steps
 
 - Run `assess-impact` before `plan-work` for any story touching existing modules.
 - Run `plan-work` per story for detailed steps inside the epic shard.

package/plan-work/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: plan-work
 model: opus
-description: Write detailed implementation tasks into the active epic shard (specs/epics/eNN-*.yaml). Every task must include a runnable verify command. Use when user needs step-by-step plan with evidence, or after plan-release.
+description: Write detailed implementation tasks into the active epic capsule directory (specs/epics/eNN-slug/). Produces decoupled story .md specs (countable-story-format) and runnable -tasks.yaml files. Every task must include a runnable verify command. Use when user needs step-by-step plan with evidence, or after plan-release.
 ---
 
 # Plan Work
 
-Produce a detailed, verifiable implementation plan in the **active epic shard** (`specs/epics/eNN-*.yaml` under the target story's `tasks[]`). Every step must be paired with a runnable verify command — "I think it works" is not a step.
+Produce a detailed, verifiable implementation plan in the **active epic capsule directory** (`specs/epics/eNN-slug/`). Output: a story spec `.md` file (countable-story-format) and a decoupled `eNNsYY-tasks.yaml` with runnable verify commands. "I think it works" is not a step.
 
 > **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
 >
@@ -16,7 +16,7 @@ Produce a detailed, verifiable implementation plan in the **active epic shard**
 
 Before writing the plan, check if `define-success` has been run. If the task's success criteria are unclear, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
 
-Read any existing `specs/` files: `release-plan.yaml`, `requirements/SCOPE_LATEST.yaml`, active `epics/*.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/GLOSSARY_LATEST.yaml`.
+Read any existing `specs/` files: `release-plan.yaml`, `product/SCOPE_LATEST.yaml`, active epic capsule `epics/<capsule_dir>/epic.yaml`, `tech-architecture/tech-stack.md`, `product/GLOSSARY_LATEST.yaml`.
 
 > **ZOOM-OUT MANDATE** (v1.17.0 Guardrails) — If this plan modifies an existing module, function, or behavior:
 > 1. State the module's **purpose** — what is it responsible for?
@@ -63,11 +63,27 @@ Break the implementation into the smallest possible steps where each step:
 
 **Red-flag check**: before moving to Step 3, name any rationalization you caught yourself making — skipping a gate, adding out-of-scope steps, omitting a verify command. Write them out; do not suppress them.
 
-### 3. Write epic shard tasks
+### 3. Write capsule story spec + tasks
 
-Append tasks under the relevant story in `specs/epics/{epic-id}-*.yaml` (`tasks[]` with `desc` + `verify`). Update `specs/release-plan.yaml` if a new story is needed. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
+Output two files inside the active epic capsule directory:
 
-**BCP Accounting:** Each task line MUST be prefixed `[BCP N]` where N is its sequence number. After all tasks, write `bcps: <total>` to the epic shard YAML under the story's metadata.
+**Story spec:** `specs/epics/<capsule>/eNNsYY-<slug>.md` — populated [countable-story-format](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.
+
+**Task checklist:** `specs/epics/<capsule>/eNNsYY-tasks.yaml` — decoupled execution steps:
+
+```yaml
+story_id: e01s01
+title: Login
+status: todo
+bcps: 3
+tasks:
+  - id: 1
+    description: "Add login form component tests"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+```
+
+Update `specs/epics/<capsule>/epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
 
 <plan-template>
 
@@ -133,7 +149,7 @@ Before finalizing, confirm:
 - Is the granularity right (not too coarse, not too fine)?
 - Are the verify commands actually runnable in this project?
 
-After writing epic tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.
+After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.
 
 ## Sub-operations
 

package/release-branch/SKILL.md

@@ -132,6 +132,21 @@ gh pr merge --squash --delete-branch
 3. Tag the repo (e.g., `v2.1.0`).
 4. Generate release notes.
 
+### 7a. Archive completed epic capsule
+
+> **HARD GATE** — When an epic's stories are all complete (all marked `done` in `execution-status.yaml`), move the epic capsule directory to the archive.
+
+```bash
+EPIC_CAPSULE="specs/epics/eNN-slug"
+if [ -d "$EPIC_CAPSULE" ]; then
+  mkdir -p specs/epics/archive
+  mv "$EPIC_CAPSULE" "specs/epics/archive/"
+  echo "Archived: $EPIC_CAPSULE → specs/epics/archive/"
+fi
+```
+
+**Rationale:** Archiving completed epics removes inactive context from the agent workspace, preserving token budget (C2/C6). The capsule directory (epic.yaml + stories + tasks + epic-local ADRs) moves as a unit — nothing is orphaned.
+
 ### 8. Clean up worktree (if not done by land-branch.sh)
 
 ```bash

package/research-first/SKILL.md

@@ -10,7 +10,7 @@ model: sonnet
 
 ## Process
 
-1. Read `specs/requirements/SCOPE_LATEST.yaml`, `specs/release-plan.yaml + epic shards`, and the current task statement.
+1. Read `specs/product/SCOPE_LATEST.yaml`, `specs/release-plan.yaml + epic shards`, and the current task statement.
 2. Search in order: this repo → bigpowers skills (`search-skills`) → package registries → web docs.
 3. For each candidate: note name, URL/path, fit (adopt | extend | compose | build).
 4. Append `## Prior Art` to `requirements/SCOPE_LATEST.yaml` notes or the active epic story.
@@ -26,6 +26,6 @@ model: sonnet
 
 ## Verify
 
-→ verify: `grep -c "Prior Art" specs/requirements/SCOPE_LATEST.yaml specs/release-plan.yaml + epic shards 2>/dev/null | awk '{s+=$1} END {if(s>0) print "OK"; else print "MISSING"}'`
+→ verify: `grep -c "Prior Art" specs/product/SCOPE_LATEST.yaml specs/release-plan.yaml + epic shards 2>/dev/null | awk '{s+=$1} END {if(s>0) print "OK"; else print "MISSING"}'`
 
 See [REFERENCE.md](REFERENCE.md) for search commands and registry checklist.

package/run-evals/SKILL.md

@@ -20,8 +20,8 @@ model: sonnet
 
 ## Artefact
 
-`specs/EVALS-<feature>.md` — see [REFERENCE.md](REFERENCE.md) for template.
+`specs/verifications/eNNsYY-eval-report.md` — see [REFERENCE.md](REFERENCE.md) for template. Eval reports are stored alongside verification evidence in `specs/verifications/`, keyed by story ID for traceability.
 
 ## Verify
 
-→ verify: `ls specs/EVALS-*.md 2>/dev/null | head -1 | grep -q EVALS && echo OK || echo MISSING`
+→ verify: `find specs/verifications -name "*-eval-report.md" | wc -l | awk '{if($1>0) print "OK: "$1" eval reports"; else print "MISSING"}'`

package/run-planning/SKILL.md

@@ -5,7 +5,7 @@ description: Advance discover-phase workflows and update specs/planning-status.y
 ---
 
 # Run Planning
-> **HARD GATE** — **HARD GATE** — Before running planning skills, confirm the epic shard exists and the active story is clear. Planning without a target is noise.
+> **HARD GATE** — **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
 
 
 Updates `specs/planning-status.yaml` as discover-phase skills complete.

package/scope-work/SKILL.md

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

package/scripts/land-branch.sh

@@ -143,6 +143,34 @@ if git remote get-url origin >/dev/null 2>&1; then
   git push origin "$DEFAULT_BRANCH"
 fi
 
+# Epic capsule archival (evolved bigpowers v4.0.0+)
+# Move completed epic capsules to archive when all stories are done
+echo "==> Checking for completed epic capsules to archive..."
+if [ -d specs/epics ] && [ -f specs/execution-status.yaml ]; then
+  for capsule in specs/epics/e[0-9]*-*/; do
+    [ -d "$capsule" ] || continue
+    capsule_name=$(basename "$capsule")
+    epic_id=$(echo "$capsule_name" | grep -o '^e[0-9]*' || true)
+    [ -n "$epic_id" ] || continue
+    # Check if all stories in this epic are done
+    ALL_DONE=true
+    if [ -f "$capsule/epic.yaml" ]; then
+      for story_id in $(grep -o 'e[0-9]*s[0-9]*' "$capsule/epic.yaml" 2>/dev/null || true); do
+        STATUS=$(grep "$story_id:" specs/execution-status.yaml 2>/dev/null | awk '{print $2}' || echo "todo")
+        if [ "$STATUS" != "done" ]; then
+          ALL_DONE=false
+          break
+        fi
+      done
+    fi
+    if [ "$ALL_DONE" = true ]; then
+      mkdir -p specs/epics/archive
+      echo "  Archiving completed epic: $capsule_name → specs/epics/archive/"
+      mv "$capsule" "specs/epics/archive/"
+    fi
+  done
+fi
+
 # Worktree cleanup
 WORKTREE_PATH="../$FEATURE_BRANCH"
 if git worktree list --porcelain 2>/dev/null | grep -q "^worktree $WORKTREE_PATH$"; then

package/seed-conventions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: seed-conventions
 model: sonnet
-description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory. Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet.
+description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory with evolved bigpowers structure (product/, tech-architecture/, verifications/, epics/archive/). Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet.
 ---
 
 # Seed Conventions
@@ -75,7 +75,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/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`product/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.
@@ -115,7 +115,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/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`product/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.
@@ -155,7 +155,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/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`product/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.
@@ -177,14 +177,45 @@ Use the standard bigpowers CONVENTIONS.md template, filling in the project-speci
 
 ### `specs/` directory
 
+Create the evolved bigpowers directory structure:
+
 ```bash
-mkdir -p specs
-echo "# Specs\n\nAll planning documents for this project." > specs/README.md
+mkdir -p specs/product
+mkdir -p specs/product/snapshots
+mkdir -p specs/epics/archive
+mkdir -p specs/tech-architecture
+mkdir -p specs/adr
+mkdir -p specs/verifications
+mkdir -p specs/bugs
+
+# Create empty placeholder files
+touch specs/product/SCOPE_LATEST.yaml
+touch specs/product/VISION_LATEST.yaml
+touch specs/product/GLOSSARY_LATEST.yaml
+touch specs/release-plan.yaml
+touch specs/execution-status.yaml
+touch specs/planning-status.yaml
+touch specs/state.yaml
+touch specs/tech-architecture/tech-stack.md
+touch specs/tech-architecture/security.md
+touch specs/tech-architecture/test.md
+touch specs/tech-architecture/design.md
+touch specs/tech-architecture/REFACTOR_LATEST.md
+touch specs/tech-architecture/IMPACT_LATEST.md
+touch specs/bugs/registry.yaml
+echo "# Specs\n\nAll planning documents for this project. Evolved bigpowers structure (v4.0.0+)." > specs/README.md
 ```
 
+**Note:** `specs/state.yaml.lock` is NOT pre-created — it is acquired and released dynamically during writes to prevent concurrency conflicts.
+
 ### Verify
 
 - [ ] CLAUDE.md exists and is populated
 - [ ] CONVENTIONS.md exists and includes specs/ output convention
 - [ ] specs/ directory exists
+- [ ] specs/product/ exists with SCOPE_LATEST.yaml, VISION_LATEST.yaml, GLOSSARY_LATEST.yaml
+- [ ] specs/tech-architecture/ exists with tech-stack.md, security.md, test.md, design.md
+- [ ] specs/verifications/ exists
+- [ ] specs/epics/archive/ exists
+- [ ] specs/bugs/registry.yaml exists
 - [ ] Confirm with user: "Does CLAUDE.md accurately describe your project?"

package/session-state/SKILL.md

@@ -12,7 +12,7 @@ Track the current state of implementation, including decisions made, pending tas
 
 ## Goal
 
-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`.
+Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.
 
 Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
 
@@ -45,7 +45,7 @@ handoff:
 
 If `specs/state.yaml` does not exist, or if starting a new major phase:
 
-- [ ] Read `specs/release-plan.yaml` and `specs/requirements/SCOPE_LATEST.yaml`.
+- [ ] Read `specs/release-plan.yaml` and `specs/product/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.
 
@@ -68,6 +68,32 @@ Whenever a significant decision is made or a milestone is reached:
 
 → verify: `bash scripts/validate-specs-yaml.sh`
 
+## State Write-Lock Protocol
+
+> **HARD GATE** — Before any write to `specs/state.yaml` or `specs/execution-status.yaml`, acquire `specs/state.yaml.lock`. Release it immediately after the write. A stale lock (>60s) may be force-released.
+
+### Acquire
+
+1. Check if `specs/state.yaml.lock` exists.
+2. If it exists, read the agent ID and timestamp inside.
+3. If the lock is stale (>60s old), remove it and proceed.
+4. If the lock is fresh (<60s), wait 2s and retry (max 15 attempts = 30s).
+5. Write `agent_id: <name>\nacquired_at: <ISO-8601>` to `specs/state.yaml.lock`.
+
+### Release
+
+1. After the write to `state.yaml` or `execution-status.yaml` completes:
+2. `rm specs/state.yaml.lock`
+
+### Lock format (`specs/state.yaml.lock`)
+
+```yaml
+agent_id: session-state
+acquired_at: "2026-06-11T14:30:00Z"
+```
+
+
+
 ## Operations
 
 ### show-state (absorbed)
@@ -80,7 +106,12 @@ Clear ephemeral session state. Set `active_epic_id`, `active_story_id`, and `epi
 
 ### compact-state (absorbed)
 
-Archive verbose decisions before a context transition. Move all entries from `handoff.open_decisions` to `specs/adr/` as individual ADR files, then reset `handoff.open_decisions` to an empty list.
+Archive verbose decisions before a context transition. Move all entries from `handoff.open_decisions` to their appropriate location:
+
+- **System-wide decisions** → `specs/adr/NNNN-slug.md` (global Architectural Decision Records)
+- **Epic-scoped decisions** → `specs/epics/<active_epic_id>-<slug>/adr/NNNN-slug.md` (epic-local ADRs, archived with epic)
+
+After archiving, reset `handoff.open_decisions` to an empty list.
 
 ## File Format: specs/state.yaml
 

package/slice-tasks/SKILL.md

@@ -6,17 +6,17 @@ model: sonnet
 
 # Slice Tasks
 
-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`.
+Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical slices, each independently deliverable and testable. Output: decoupled `eNNsYY-tasks.yaml` files with runnable verify commands. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use capsule dirs + `execution-status.yaml`.
 
 ## Process
 
-1. Read `specs/requirements/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
+1. Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
 2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
-3. Each story: `id` (e.g. `e03s01`), `title`, optional `depends-on` in task desc, `tasks[]` with `desc` + `verify`.
+3. Each story: writes `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`). Story spec `.md` files are written by `plan-work` and follow [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md).
 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: `grep -c 'id: e' specs/epics/*.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `find specs/epics -name "*-tasks.yaml" | wc -l | awk '{if($1>0) print "OK: "$1" task files"; else print "MISSING"}'`

package/survey-context/SKILL.md

@@ -67,7 +67,7 @@ Based on what you've found, identify which PMBOK phase this project is currently
 | **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 shard in progress |
+| **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 |
@@ -116,7 +116,7 @@ At story start, write `metrics.story_start` with the current ISO 8601 timestamp
 
 ### list-epics (absorbed)
 
-Loop through all `specs/epics/*.yaml` files and print a summary of story counts per epic. Useful for understanding overall project scope and epic distribution.
+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)
 

package/trace-requirement/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: trace-requirement
 model: haiku
-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.
+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 shards` 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 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 shards` must exist. If it doesn't, run `plan-release` first.
+> **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 shards ] && echo "ready" || echo "BLOCKED: 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 shards` fully before proceeding.
+Read `specs/release-plan.yaml + epic capsule directories` fully before proceeding.
 
 ## Process
 
@@ -22,7 +22,7 @@ Read `specs/release-plan.yaml + epic shards` fully before proceeding.
 
 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 shards | sort -u`
+→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/release-plan.yaml + epic capsule directories | sort -u`
 
 ### 2. Search for story tags in code
 

package/verify-work/SKILL.md

@@ -21,7 +21,7 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 
 0. **Branch check** — must not be `main`/`master`.
 
-1. Read active story tasks and any **Verification Script** notes in `specs/epics/{active}.yaml` or story `.md` under `specs/epics/eNN/stories/`.
+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.
@@ -55,9 +55,42 @@ After UAT, identify and close any gaps between promised behavior and actual beha
 - 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: `grep -c 'verify:' specs/epics/*.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `test -f specs/verifications/<story_id>-verify.yaml && echo "Evidence persisted"`
 
 See [REFERENCE.md](REFERENCE.md) for cold-start and gaps template.
 

package/write-document/SKILL.md

@@ -25,7 +25,7 @@ Create high-signal technical documentation that serves as an expert collaborator
 
 Choose the correct BMAD-BigPowers artifact:
 - **Decision Record (ADR)**: For "Why" decisions (saved to `specs/adr/`).
-- **Context Map**: For system-wide architectural mapping (`specs/plans/TECH_STACK_LATEST.md`).
+- **Context Map**: For system-wide architectural mapping (`specs/tech-architecture/tech-stack.md`).
 - **Technical Guide**: For "How-to" with verification (saved to `<module>/REFERENCE.md`).
 - **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/audit/features/`).
 - **Project README**: Project-facing documentation (saved to `README.md` at project root).