bigpowers 2.1.3 → 2.3.0

package/develop-tdd/SKILL.md

@@ -10,51 +10,21 @@ description: Test-driven development with red-green-refactor loop using vertical
 >
 > **HARD GATE** — Do NOT write code before you have a plan. New feature: `plan-work` → epic capsule tasks. Bug: `investigate-bug` → `specs/bugs/BUG-*.md` (or use `fix-bug` orchestrator).
 >
-> **RECURSIVE DISCIPLINE** — This lifecycle apply to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
 
 ## Philosophy
 
-**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
-
-**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
-
-**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means. The warning sign: your test breaks when you refactor, but behavior hasn't changed.
-
-See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
-
-## Anti-Pattern: Horizontal Slices
-
-**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
-
-This produces **crap tests**:
-
-- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
-- You end up testing the _shape_ of things rather than user-facing behavior
-- Tests become insensitive to real changes
-
-**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat.
-
-```
-WRONG (horizontal):
-  RED:   test1, test2, test3, test4, test5
-  GREEN: impl1, impl2, impl3, impl4, impl5
-
-RIGHT (vertical):
-  RED→GREEN: test1→impl1
-  RED→GREEN: test2→impl2
-  RED→GREEN: test3→impl3
-  ...
-```
+Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See [REFERENCE.md](REFERENCE.md) for the horizontal-slice anti-pattern and TDD phase detail.
 
 ## Red Flags
 
-If you find yourself thinking these things, you are likely deviating from production-grade craft. Stop and reconsider.
+If you catch yourself thinking these, stop and reconsider — you are likely deviating from production-grade craft.
 
 | Red Flag | Reality |
 | :--- | :--- |
 | "This is too simple to need tests." | Simple code is where bugs hide. If it's simple, the test is cheap. |
-| "I'll refactor this later." | "Later" is when technical debt becomes a bankruptcy. Refactor while Green. |
-| "The tests are already comprehensive." | If you're adding behavior, you need a new test. Coverage != Correctness. |
+| "I'll refactor this later." | "Later" is when technical debt becomes bankruptcy. Refactor while Green. |
+| "The tests are already comprehensive." | If you're adding behavior, you need a new test. Coverage ≠ Correctness. |
 | "I'm just fixing a small bug." | Small bugs often indicate deep interface flaws. Investigate root cause. |
 | "I need to mock this internal class." | Mocking internals couples tests to implementation. Mock only I/O. |
 | "This refactor is out of scope." | Leave the code cleaner than you found it (Boy Scout Rule). |
@@ -63,114 +33,44 @@ If you find yourself thinking these things, you are likely deviating from produc
 
 ### 1. Planning
 
-Before writing any code:
-
 - [ ] Read active `specs/epics/*/epic.yaml` story tasks or `specs/bugs/BUG-*.md` — understand verify steps
-- [ ] Confirm with user what interface changes are needed
-- [ ] Confirm with user which behaviors to test (prioritize)
-- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
-- [ ] Design interfaces for [testability](interface-design.md)
-- [ ] List the behaviors to test (not implementation steps)
+- [ ] Confirm interface changes and behaviors to test (prioritize)
+- [ ] Design interfaces for testability — identify [deep modules](deep-modules.md) opportunities
 - [ ] Get user approval on the plan
 
-Ask: "What should the public interface look like? Which behaviors are most important to test?"
-
-**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic.
-
-Apply the **enforce-first** F.I.R.S.T rubric when writing tests: Fast, Independent, Repeatable, Self-Validating, Timely.
+Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Self-Validating, Timely.
 
 ### 2. Tracer Bullet
 
 Write ONE test that confirms ONE thing about the system:
 
 ```
-RED:    Write test for first behavior → test fails → commit via commit-message: test(<scope>): ...
-GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ... or fix(<scope>): ...
+RED:    Write test for first behavior → test fails → commit: test(<scope>): ...
+GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...
 REFACTOR (optional): clean up → commit: refactor(<scope>): ...
 ```
 
-This is your tracer bullet — proves the path works end-to-end.
-
 ### 3. Incremental Loop
 
-> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
+> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent.
 
-For each remaining behavior:
+For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase.
 
-```
-RED:    Write next test → fails → commit: test(<scope>): ...
-GREEN:  Minimal code to pass → passes → commit: feat|fix(<scope>): ...
-REFACTOR (optional): → commit: refactor(<scope>): ...  (use commit-message skill for title/body)
-```
+### 4. Visual Slices (UI alternate workflow)
 
-Rules:
-
-- One test at a time
-- Only enough code to pass current test
-- Don't anticipate future tests
-- Keep tests focused on observable behavior
-- **Atomic Commits**: Commit after every GREEN phase to record progress and prevent large diffs.
-
-### 4. Visual Slices (UI Alternate Workflow)
-
-For UI components (SwiftUI, React, Flutter) where behavioral unit testing is brittle or low-signal:
-
-1. **Test-First Logic**: Extract logic (state transitions, formatting, validation) into a separate Controller, ViewModel, or Hook. This logic MUST follow pure TDD (Red-Green-Refactor).
-2. **Visual Verification**: For the View/Component itself, use "Visual Slices":
-   - **RED**: Write the component signature and a basic preview/test snapshot that fails (or displays placeholder).
-   - **GREEN**: Implement the UI and verify visually via manual run, preview, or snapshot test.
-   - **REFINE**: Adjust styling and layout until it matches the "rich aesthetics" requirement.
-3. **COMMIT**: git commit -m "feat(ui): <component name> visual slice verified"
+For UI components where behavioral unit testing is brittle: extract logic into a Controller/ViewModel/Hook (pure TDD), then use Visual Slices for the View layer. See [REFERENCE.md](REFERENCE.md) for the full Visual Slices procedure.
 
 ### 5. Refactor
 
-After all tests pass, look for [refactor candidates](refactoring.md):
-
-- [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
-- [ ] Apply SOLID principles where natural
-- [ ] Consider what new code reveals about existing code
-- [ ] Run tests after each refactor step
-
-**Never refactor while RED.** Get to GREEN first.
-
-### 5. Verify step
-
-After every behavior cycle, run the verify command from the active epic task if one exists. Show evidence before declaring the step done.
-
-### 6. Manual Verification Handover
-
-Once the story is complete and all tests pass:
-1. Locate the **Verification Script** in the active epic capsule (`specs/epics/`) for this story.
-2. Present the script to the user as a step-by-step guide.
-3. Wait for the user to confirm the behavioral correctness before moving to the next story or declaring the task done.
-
-## TDD phases
-
-### Red Phase
-
-Write a failing test first that confirms the behavior you want to implement:
-
-- Test describes the desired observable behavior through the public interface
-- Run the test to confirm it fails for the right reason (not a syntax error, not a typo)
-- Commit the failing test: `git commit -m "test(<scope>): <description>"`
-
-### Green Phase
-
-Write the minimum amount of code to make the test pass:
+After all tests pass: extract duplication, deepen modules, apply SOLID principles. **Never refactor while RED.**
 
-- No extra logic, no anticipated future cases, no premature optimization
-- Focus only on making the current test pass
-- Commit the passing code: `git commit -m "feat(<scope>): <description>" or "fix(<scope>): <description>"`
+### 6. Verify
 
-### Refactor Phase
+After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
 
-Improve the code structure, naming, and clarity without changing behavior:
+### 7. Manual Verification Handover
 
-- Extract duplication, apply SOLID principles where natural, deepen modules
-- Run tests after each refactor step to ensure behavior is preserved
-- Commit refactoring: `git commit -m "refactor(<scope>): <description>"`
-- Apply the Boy Scout Rule: leave the code cleaner than you found it
+Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.
 
 ## Checklist Per Cycle
 

package/diagnose-root/SKILL.md

@@ -6,6 +6,8 @@ model: sonnet
 
 # Diagnose Root
 
+**Boundary**: Canonical, reusable 4-phase RCA engine. Invoked by `investigate-bug` (as step 2 of the end-to-end flow) and by `fix-bug` (when no bug file exists). Does not write the bug file — that is `investigate-bug`'s responsibility.
+
 Four phases — do not skip. Update the active `specs/bugs/BUG-*.md` file at each phase.
 
 ## Phases

package/edit-document/SKILL.md

@@ -6,6 +6,8 @@ description: Edit and improve documents by restructuring sections, improving cla
 
 # Edit Document
 
+**Distinct from `write-document`:** Use this skill when the document already exists and needs restructuring, clarity, or prose improvements. Use `write-document` to create a document from scratch.
+
 > **HARD GATE** — Document edits must preserve intent and accuracy. Do NOT remove or contradict existing content without understanding why it was written. Check git history for context.
 
 ## Process

package/fix-bug/SKILL.md

@@ -6,13 +6,15 @@ description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-
 
 # Fix Bug
 
+**Boundary**: Orchestrator flow — chains `investigate-bug` (entry point + RCA via `diagnose-root`) → `develop-tdd` → `validate-fix`. Does not implement RCA or write bug files directly.
+
 Orchestrates **fix_bug** flow without mixing epic build state.
 
 > **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug`.
 
 ## Process
 
-1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first (YAML frontmatter + fix plan in file).
+1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file.
 2. `develop-tdd` against the bug file's verify steps.
 3. `validate-fix` — re-run failing test, full suite, lint.
 4. `bash scripts/sync-bugs-registry.sh` — refresh `specs/bugs/registry.yaml`.

package/grill-me/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: grill-me
 model: sonnet
-description: Stress-test a plan or design through relentless questioning until every decision is resolved. Two modes: Design (default Q&A on decisions) and Docs (grounds every challenge in real library or API documentation). Use when user wants to challenge a plan, validate API assumptions, or mentions "grill me" or "grill me with docs".
+description: Interactive assumption-surfacing Q&A that stress-tests a plan through relentless questioning until every decision is resolved. Use when user wants to challenge a plan, validate decisions from conversation/context, or mentions "grill me". For doc-grounded variant, use grill-with-docs.
 ---
 
 # Grill Me
 
+> **Use this vs grill-with-docs:** `grill-me` surfaces assumptions from the conversation and context alone — no documentation fetching. Use `grill-with-docs` (the doc-grounded variant) when the plan relies on a specific library or external API and every challenge must cite a real doc URL.
+
 Two modes. Default is **Design**. Switch to **Docs** by saying "grill me with docs" or when the plan relies on a specific library or external API.
 
 > **HARD GATE** — Do NOT accept a design until every hard decision has been stress-tested. "Seems right" is not a decision. Grilling must identify and resolve tensions before build begins.

package/grill-with-docs/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: grill-with-docs
-description: Stress-test plan assumptions grounded in real library or API documentation URLs. Use when the plan depends on a specific library or external API, or as a docs-grounded variant of grill-me.
+description: Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching and citing real library or API documentation. Every challenge must cite a real URL. Use when the plan depends on a specific library or external API.
 model: opus
 ---
 
 # Grill With Docs
 
+> **Use this vs grill-me:** `grill-with-docs` is the doc-grounded variant of `grill-me`. Use it when the plan relies on external libraries or APIs and every challenge must be grounded in and cite a real documentation URL. Use `grill-me` for context-only assumption surfacing without fetching docs.
+
 > **HARD GATE** — Every challenge must cite a real documentation URL. No hallucinated APIs.
 
 ## Process

package/investigate-bug/SKILL.md

@@ -6,6 +6,8 @@ description: Investigate a bug or issue by exploring the codebase to find root c
 
 # Investigate Bug
 
+**Boundary**: End-to-end bug entry point — history check → RCA (via `diagnose-root`) → fix approach → TDD plan → bug file. Delegates the 4-phase RCA to `diagnose-root`; does not re-implement it.
+
 Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/bugs/BUG-*.md`. This is a mostly hands-off workflow — minimize questions to the user.
 
 ## Process
@@ -26,23 +28,15 @@ Do NOT ask follow-up questions yet. Start investigating immediately.
 
 ### 2. Explore and diagnose (4-phase RCA)
 
-Use the Agent tool with subagent_type=Explore to investigate the codebase. Run these phases in order:
-
-**Phase 1 — Reproduce**: Confirm the failure is consistent. Document exact inputs, environment, and observed vs. expected output. Do not proceed until you can reproduce reliably.
-
-**Phase 2 — Isolate**: Trace the code path from entry point to failure. Binary-search the call stack to find which layer first produces wrong output. Target: a single function or module where the wrong behavior first appears.
-
-**Phase 3 — Hypothesize**: Write a falsifiable hypothesis: "The bug occurs because [condition] causes [behavior] instead of [expected]." Generate at least 2 alternatives. Rank by probability.
-
-**Phase 4 — Verify**: Add a targeted assertion or log that fires if your top hypothesis is correct. Run the reproduction case. If confirmed, document the root cause. If not, return to Phase 3 with new evidence.
-
-> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until Phase 4 produces a verified root cause. "It probably is X" is not verified.
+Run the 4-phase root-cause analysis via the `diagnose-root` skill (Reproduce → Isolate → Hypothesize → Verify). That skill is the canonical RCA engine — do not re-implement the phases here.
 
 Also look at:
 - Recent changes to affected files (`git log --oneline <file>`)
 - Existing tests (what's tested, what's missing)
 - Similar patterns elsewhere in the codebase that work correctly
 
+> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until `diagnose-root` Phase 4 produces a verified root cause. "It probably is X" is not verified.
+
 ### 3. Identify the fix approach
 
 Based on your investigation, determine:

package/map-codebase/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: map-codebase
 model: sonnet
-description: "High-fidelity codebase surveying — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists them into specs/tech-architecture/tech-stack.md. Goes beyond survey-context by identifying 'signals' for planning."
+description: "Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does."
 ---
 
 # Map Codebase
 
 Perform a deep architectural and structural analysis of the codebase. Unlike `survey-context` which identifies "where we are", `map-codebase` identifies "what we are dealing with" and "how things are done".
 
+> **Use this vs survey-context:** `map-codebase` BUILDS the tech-stack doc by scanning the codebase from scratch. `survey-context` READS existing specs/tech-architecture docs without re-deriving them. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
 > **HARD GATE** — Cold analysis only. Do NOT assume architectural patterns without reading the code. If the codebase structure surprises you, call out the delta.
 
 ## Process

package/migrate-spec/REFERENCE-GSD.md

@@ -43,7 +43,7 @@ Transform:
 
 ---
 
-### `.planning/REQUIREMENTS.md` → `specs/requirements/SCOPE_LATEST.yaml`
+### `.planning/REQUIREMENTS.md` → `specs/product/SCOPE_LATEST.yaml`
 
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
@@ -55,7 +55,7 @@ Transform:
 
 ---
 
-### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/plans/TECH_STACK_LATEST.md` + `specs/adr/`
+### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
 
 GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context, specifics, deferred.
 
@@ -80,12 +80,12 @@ Transform:
 
 ---
 
-### `.planning/METHODOLOGY.md` → `specs/plans/METHODOLOGY_LATEST.md`
+### `.planning/METHODOLOGY.md` → `specs/tech-architecture/METHODOLOGY_LATEST.md`
 
 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/plans/METHODOLOGY_LATEST.md`
+- Copy each lens as a section in `specs/tech-architecture/METHODOLOGY_LATEST.md`
 - Note: "These lenses should inform `plan-work` and `audit-code` sessions."
 
 ---

package/migrate-spec/REFERENCE.md

@@ -22,7 +22,7 @@ project-root/
         └── log.jsonl
 ```
 
-### `spec.md` → `specs/requirements/SCOPE_LATEST.yaml` + `specs/plans/TECH_STACK_LATEST.md`
+### `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md`
 
 spec-kit `spec.md` focuses on: who uses it, user journeys, success criteria, what's in/out of scope.
 
@@ -32,7 +32,7 @@ Transform:
 - Domain terms / glossary → `requirements/GLOSSARY_LATEST.yaml`
 - Problem statement / vision → `requirements/VISION_LATEST.yaml`
 
-### `plan.md` → `specs/plans/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/`
+### `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/`
 
 spec-kit `plan.md` covers: technology stack, architectural patterns, implementation constraints.
 
@@ -79,14 +79,14 @@ project-root/
     └── story-{slug}.md
 ```
 
-### `product-brief.md` / `prfaq-{project}.md` → `specs/requirements/VISION_LATEST.yaml`
+### `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml`
 
 Transform:
 - 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/requirements/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml`
+### `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml`
 
 BMAD `prd.md` has: Glossary, FR-XX functional requirements, UJ-XX user journeys, NFRs, assumptions.
 
@@ -105,7 +105,7 @@ Transform:
 - Lightweight decisions → `specs/DECISION-LOG.md` (date | decision | rationale)
 - `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
 
-### `architecture.md` → `specs/plans/TECH_STACK_LATEST.md` + `specs/adr/`
+### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
 
 Transform:
 - ADR sections → individual `specs/adr/NNNN-{slug}.md` files
@@ -132,7 +132,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 ### From GSD
 
-- [ ] **`specs/plans/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
+- [ ] **`specs/tech-architecture/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.
 
@@ -183,3 +183,30 @@ For lightweight decisions that don't warrant a full ADR:
 |------|----------|-----------|--------------|
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
+
+### `specs/state.yaml` template format
+
+Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:
+
+```markdown
+# Session State: <project name>
+
+## Current Milestone
+
+Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
+
+## Git Metadata
+
+- **Branch**: <current branch>
+- **Hash**: <git rev-parse HEAD>
+
+## Completed Releases
+
+(none — migration starting point)
+
+## Pending Releases
+
+- [ ] Review migrated specs
+- [ ] Run elaborate-spec to validate scope
+- [ ] Run plan-work to produce first release plan
+```

package/migrate-spec/SKILL.md

@@ -82,26 +82,13 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 
 ### Step 4 — Generate state.yaml
 
-Always regenerate `specs/state.yaml` from scratch in bigpowers format:
+Always regenerate `specs/state.yaml` from scratch in bigpowers format (see REFERENCE.md for template):
 
 ```markdown
 # Session State: <project name>
-
 ## Current Milestone
-
 Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-
-## Git Metadata
-
-- **Branch**: <current branch>
-- **Hash**: <git rev-parse HEAD>
-
-## Completed Releases
-
-(none — migration starting point)
-
 ## Pending Releases
-
 - [ ] Review migrated specs
 - [ ] Run elaborate-spec to validate scope
 - [ ] Run plan-work to produce first release plan

package/model-domain/SKILL.md

@@ -6,6 +6,8 @@ description: Grilling session that challenges your plan against the existing dom
 
 # Model Domain
 
+**Distinct from `define-language` and `deepen-architecture`:** Use this skill to stress-test a plan through a grilling interview that resolves domain model decisions and captures invariants. Use `define-language` to produce a canonical glossary of terms. Use `deepen-architecture` to find module-level refactoring opportunities in code.
+
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
 > **HARD GATE** — Capture invariants (what MUST always be true) and state machines (what transitions are legal) for core entities. If these are fuzzy, design will fail.

package/orchestrate-project/REFERENCE.md

@@ -26,7 +26,7 @@ Detailed documentation for the `orchestrate-project` meta-skill.
 - **Goal**: Execute the plan story-by-story using the 8-step `build-epic` cycle with TDD and vertical slices.
 - **Deliverables**: Code; `execution-status.yaml` updated per story; `specs/metrics/cycle-times.yaml` row per story.
 - **Skills**: `build-epic` (conductor) → per-story: `survey-context`, `plan-work`, `kickoff-branch`, `develop-tdd`, `verify-work`, `audit-code`, `commit-message`, `release-branch`.
-- **BCP tracking**: `plan-work` labels every task `[BCP N]`; total written to `state.yaml` as `epic_cycle.story_bcps`. BCP baseline must exist in `release-plan.yaml` before starting.
+- **BCP tracking**: `plan-release` sizes each story in Business Complexity Points (BCP) before the build queue; `plan-work` confirms and writes the size to `state.yaml` as `epic_cycle.story_bcps`. See `docs/references/bcp.md` for the canonical sizing method.
 - **Timestamps**: `survey-context` stamps `metrics.story_start`; `release-branch` stamps `metrics.story_end` and writes BCP/hr to `specs/metrics/cycle-times.yaml`.
 - **next_skill**: Each critical-path skill writes `handoff.next_skill` to `state.yaml`. Agents resume by reading `state.yaml` — no guessing.
 - **Dashboard**: `npm run dashboard` (TUI) or `npm run dashboard:web` (browser, port 7742) shows live pipeline, epic queue, BCP metrics, and cycle-time ledger.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "bigpowers",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
-    "compliance": "bash scripts/audit-compliance.sh specs/audit/features",
+    "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh",
+    "doctrine": "bash scripts/validate-doctrine.sh",
     "sync": "bash scripts/sync-skills.sh",
     "validate-specs": "bash scripts/validate-specs-yaml.sh",
     "enrich-epics": "bash scripts/enrich-epics-from-archive.sh",

package/plan-release/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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 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.
+description: "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics."
 ---
 
 # Plan Release

package/plan-work/REFERENCE.md

@@ -0,0 +1,104 @@
+# Plan Work — Reference
+
+## Output file formats
+
+### Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md`
+
+Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.
+
+### Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml`
+
+```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
+
+```
+### Story [X.Y]: [title] — Implementation Steps
+
+**type:** feat | fix | refactor
+**context:** domain | infra
+**Context**: [One paragraph: what this story implements and why]
+
+## Steps
+
+1. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
+2. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
+...
+
+## Verification Script (Step-by-Step)
+
+[A human-readable, step-by-step script for the user to verify the story's outcome.]
+
+1. [Action 1: e.g. Start the server]
+2. [Action 2: e.g. Open browser to http://localhost:3000]
+3. [Observation: e.g. Verify that the login modal appears]
+
+## Out of scope
+
+- [Explicit exclusions]
+
+## Risks
+
+- [Anything that could go wrong and how to detect it early]
+```
+
+## Verify step format rules
+
+Every step MUST follow this exact format:
+```
+N. <What to do> → verify: <runnable command that proves it worked>
+```
+
+**Good examples:**
+```
+1. Add User model with email and name fields → verify: npm test -- user.test.ts
+2. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
+3. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts
+```
+
+**Bad examples (no verify command):**
+```
+1. Implement the user creation flow
+2. Write tests for the API
+```
+
+## Sub-operations
+
+### Define Success
+
+Before planning, convert task statements into observable "step → verify: <cmd>" pairs:
+- Break the task into observable outcomes (behaviors) rather than implementation steps
+- Write pairs in the format: `[What must be true] → verify: <runnable command>`
+- Challenge completeness: are all required behaviors covered?
+- Get user confirmation: "Does this capture everything the task requires?"
+- Once confirmed, these pairs become the skeleton for plan-work steps
+
+### Zoom-Out Check
+
+When modifying an existing module, confirm scope is understood:
+- State the module's **purpose** — what is it responsible for?
+- Name the **callers** — who depends on it?
+- List the **contracts** — what invariants or interfaces must be preserved?
+
+If you cannot answer all three without deep code archaeology, scope is misunderstood. Clarify with the user before writing steps.
+
+### Slopcheck
+
+For every external package proposed in the plan, tag each with one of:
+- `[OK]` — package is mature, actively maintained, appropriate scope
+- `[SUS]` — suspiciously broad, has maintenance concerns, or unclear fit
+- `[SLOP]` — unmaintained, known security issues, or out of scope
+
+`[SUS]` and `[SLOP]` require explicit human approval before the step may execute. Document tags inline next to the package name.