bigpowers 2.1.3 → 2.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.2.0](https://github.com/danielvm-git/bigpowers/compare/v2.1.3...v2.2.0) (2026-06-13)
+
+
+### Features
+
+* **skills:** enforce tiered SKILL.md size cap (Epic 4) ([5b66257](https://github.com/danielvm-git/bigpowers/commit/5b66257bcb7c5c01246e8cbf02e6cb701120eae0))
+
 ## [2.1.3](https://github.com/danielvm-git/bigpowers/compare/v2.1.2...v2.1.3) (2026-06-12)
 
 

package/CLAUDE.md

@@ -21,7 +21,7 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 
 ## Architecture
 
-Collection of 61 verb-noun skills, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/requirements/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
+Collection of 61 verb-noun skills, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
 
 ## Conventions
 

package/CONVENTIONS.md

@@ -59,7 +59,13 @@ Every skill that produces written output writes to `specs/` at the project root.
 
 ### BCP accounting mandate (v2.0.0)
 
-Every task written by `plan-work` MUST be labeled `[BCP N]` where N is the estimated Build Commit Points for that task. The story total is summed and written to `state.yaml` as `epic_cycle.story_bcps`. The BCP baseline for each story MUST appear in `specs/release-plan.yaml` before implementation begins. `release-branch` automatically appends a row to `specs/metrics/cycle-times.yaml` with the final BCP/hr after the story lands.
+**BCP = Business Complexity Points** — a pre-build story size, not a per-task annotation. Canonical method: [`docs/references/bcp.md`](docs/references/bcp.md) (sourced from `flow-ciandt/bcp-agent`).
+
+- **Sizing (plan-release):** Every story in `specs/release-plan.yaml` MUST have a `bcps:` field set via the 6-step BCP sizing method before implementation begins. No story enters the build queue without a BCP baseline.
+- **Session state:** `plan-work` confirms the BCP size and writes it to `specs/state.yaml` as `epic_cycle.story_bcps`.
+- **Velocity (release-branch):** After landing, `release-branch` appends a row to `specs/metrics/cycle-times.yaml` with `bcp_per_hour = story_bcps / cycle_minutes * 60`.
+
+BCP is a **story-level** size. Per-task `[BCP N]` annotations are not part of the canonical method.
 
 ### Timestamp mandate (v2.0.0)
 
@@ -76,9 +82,9 @@ Every critical-path skill (survey-context, plan-work, kickoff-branch, develop-td
 
 | Question | File | Format |
 |----------|------|--------|
-| What should the product do? | `specs/requirements/SCOPE_LATEST.yaml` | YAML |
-| North star / initiative | `specs/requirements/VISION_LATEST.yaml` | YAML |
-| Glossary | `specs/requirements/GLOSSARY_LATEST.yaml` | YAML |
+| What should the product do? | `specs/product/SCOPE_LATEST.yaml` | YAML |
+| North star / initiative | `specs/product/VISION_LATEST.yaml` | YAML |
+| Glossary | `specs/product/GLOSSARY_LATEST.yaml` | YAML |
 | What ships in this release, in what order? | `specs/release-plan.yaml` | YAML |
 | How to implement an epic/story? | `specs/epics/eNN-*.yaml` or `specs/epics/eNN-*/stories/` | YAML + MD |
 | Where are we in the session? | `specs/state.yaml` | YAML |
@@ -87,7 +93,7 @@ Epic IDs: `e01`, `e30`. Story IDs: `e01s01`. One FR in SCOPE may span multiple e
 
 ### Frozen release (ex-baseline)
 
-When planning closes, copy to `specs/requirements/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
+When planning closes, copy to `specs/product/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
 
 ### Semantic-release — three places
 
@@ -99,11 +105,11 @@ When planning closes, copy to `specs/requirements/snapshots/release-<version>/`
 
 | Document | Path |
 |----------|------|
-| Stack / architecture | `specs/plans/TECH_STACK_LATEST.md` |
-| Security / test / design plans | `specs/plans/*_PLAN_LATEST.md` |
-| Domain context + ADRs | `specs/plans/TECH_STACK_LATEST.md` or legacy `specs/CONTEXT.md` + `specs/adr/` |
+| Stack / architecture | `specs/tech-architecture/TECH_STACK_LATEST.md` |
+| Security / test / design plans | `specs/tech-architecture/*_PLAN_LATEST.md` |
+| Domain context + ADRs | `specs/tech-architecture/TECH_STACK_LATEST.md` or legacy `specs/CONTEXT.md` + `specs/adr/` |
 | Bug investigation | `specs/bugs/BUG-*.md` + `specs/bugs/registry.yaml` (generated) |
-| Refactor / impact | `specs/plans/REFACTOR_LATEST.md`, `specs/plans/IMPACT_LATEST.md` |
+| Refactor / impact | `specs/tech-architecture/REFACTOR_LATEST.md`, `specs/tech-architecture/IMPACT_LATEST.md` |
 | Legacy markdown | `specs/archive/` after `bash scripts/convert-legado.sh` |
 
 Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys: `bash scripts/bp-yaml-set.sh specs/state.yaml git.branch feat/foo`.
@@ -114,7 +120,7 @@ Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys:
 |-----|-----|
 | `specs/STATE.md` | `specs/state.yaml` |
 | `specs/RELEASE-PLAN.md` | `specs/release-plan.yaml` + `specs/epics/` |
-| `specs/SCOPE.md` | `specs/requirements/SCOPE_LATEST.yaml` |
+| `specs/SCOPE.md` | `specs/product/SCOPE_LATEST.yaml` |
 
 ## Code Style
 

package/README.md

@@ -137,9 +137,9 @@ ONCE/PROJECT orchestrate-project
 | Level | Document | Responsibility |
 | :--- | :--- | :--- |
 | **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
-| **Context** | `specs/plans/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
-| **Scope** | `specs/requirements/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
-| **Vision** | `specs/requirements/VISION_LATEST.yaml` | North star and initiative success criteria. |
+| **Context** | `specs/tech-architecture/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
+| **Scope** | `specs/product/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
+| **Vision** | `specs/product/VISION_LATEST.yaml` | North star and initiative success criteria. |
 | **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |
 | **Roadmap** | `specs/release-plan.yaml` + `specs/epics/` | WSJF-prioritized epics and stories with BCP baseline. |
 | **Current** | `specs/state.yaml` | Session flow, active epic, `handoff.next_skill`, timestamps. |

package/build-epic/SKILL.md

@@ -30,7 +30,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 ## Process
 
 1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
-2. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
+2. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
 3. If `epic_cycle.step` missing, set to `1`.
 4. Run **only the current step** (resume mode) unless user asked for full auto-run.
 5. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).

package/develop-tdd/REFERENCE.md

@@ -0,0 +1,61 @@
+# Develop TDD — Reference
+
+## 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
+  ...
+```
+
+> The Red Flags table lives in [SKILL.md](SKILL.md#red-flags) — it is core behavioral guidance, not reference detail.
+
+## TDD Phases (Detail)
+
+### Red Phase
+
+Write a failing test first:
+- 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: `git commit -m "test(<scope>): <description>"`
+
+### Green Phase
+
+Write the minimum code to make the test pass:
+- No extra logic, no anticipated future cases, no premature optimization
+- Focus only on making the current test pass
+- Commit: `git commit -m "feat(<scope>): <description>"` or `"fix(<scope>): <description>"`
+
+### Refactor Phase
+
+Improve structure without changing behavior:
+- Extract duplication, apply SOLID principles where natural, deepen modules
+- Run tests after each refactor step to ensure behavior is preserved
+- Commit: `git commit -m "refactor(<scope>): <description>"`
+- Apply the Boy Scout Rule: leave the code cleaner than you found it
+
+## 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 Controller, ViewModel, or Hook. This logic MUST follow pure TDD.
+2. **Visual Verification**: For the View/Component itself:
+   - **RED**: Write the component signature and a basic preview/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 design.
+3. **COMMIT**: `git commit -m "feat(ui): <component name> visual slice verified"`

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/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/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.2.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-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.