bigpowers 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **dashboard:** resolve wrong folder targeting and update TUI metrics ([bc8d84a](https://github.com/danielvm-git/bigpowers/commit/bc8d84af6221aa59aa131bf3fdd03f25bc67ac33))
+
 ## [2.1.2](https://github.com/danielvm-git/bigpowers/compare/v2.1.1...v2.1.2) (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/dashboard/src/loaders/reader.js

@@ -66,14 +66,31 @@ function readEpicShards(projectRoot) {
     if (!fs.existsSync(epicsDir)) {
       return null;
     }
-    const files = fs.readdirSync(epicsDir)
-      .filter(f => f.endsWith('.yaml'))
-      .sort();
-
     const epics = [];
-    for (const file of files) {
-      const filePath = path.join(epicsDir, file);
-      const content = fs.readFileSync(filePath, 'utf8');
+
+    function scanDir(dirPath) {
+      if (!fs.existsSync(dirPath)) return;
+      const entries = fs.readdirSync(dirPath);
+      for (const entry of entries) {
+        const entryPath = path.join(dirPath, entry);
+        const stat = fs.statSync(entryPath);
+        if (stat.isDirectory()) {
+          if (entry === 'archive') {
+            scanDir(entryPath);
+          } else {
+            const possibleYaml = path.join(entryPath, 'epic.yaml');
+            if (fs.existsSync(possibleYaml)) {
+              loadYaml(possibleYaml);
+            }
+          }
+        } else if (stat.isFile() && entry.endsWith('.yaml')) {
+          loadYaml(entryPath);
+        }
+      }
+    }
+
+    function loadYaml(yamlPath) {
+      const content = fs.readFileSync(yamlPath, 'utf8');
       const data = yaml.load(content);
       epics.push({
         id: data.id || data.epic || null,
@@ -81,6 +98,16 @@ function readEpicShards(projectRoot) {
         stories: data.stories || []
       });
     }
+
+    scanDir(epicsDir);
+
+    // Sort epics by ID numerically/alphabetically
+    epics.sort((a, b) => {
+      const idA = a.id || '';
+      const idB = b.id || '';
+      return idA.localeCompare(idB, undefined, { numeric: true, sensitivity: 'base' });
+    });
+
     return epics.length > 0 ? epics : null;
   } catch (err) {
     return null;

package/dashboard/src/tui/index.js

@@ -156,7 +156,7 @@ function start(projectRoot) {
     // Title bar: fixed project identity
     titleBar.setContent(' {bold}{cyan-fg}⚙ bigpowers factory{/cyan-fg}{/bold} {gray-fg}v2 — seed {cyan-fg}→{/cyan-fg} epics {cyan-fg}→{/cyan-fg} mvp{/gray-fg}');
 
-    renderMetricsBar(metricsBar, metrics, stateData, epics, cycleTimes);
+    renderMetricsBar(metricsBar, metrics, stateData, epics, cycleTimes, executionStatus);
     renderPipeline(pipeline, stateData);
     renderEpicQueue(epicQueue, epics, executionStatus);
     renderStateYaml(actionLog, stateData);

package/dashboard/src/tui/metrics-bar.js

@@ -1,29 +1,40 @@
-function renderMetricsBar(box, projectMetrics, stateData, epics, cycleTimes) {
+function renderMetricsBar(box, projectMetrics, stateData, epics, cycleTimes, executionStatus) {
   if (!box || typeof box.setContent !== 'function') {
     return;
   }
 
-  const ct = cycleTimes || [];
   const epicList = epics && Array.isArray(epics) ? epics : [];
+  const statusMap = executionStatus?.epics || new Map();
 
-  // Compute totals
+  // Compute totals and completed counts dynamically from execution-status.yaml
   let totalStories = 0;
   let targetBcps = 0;
+  let doneStories = 0;
+  let deliveredBcps = 0;
+  let doneEpics = 0;
+
   epicList.forEach(epic => {
+    let epicDone = true;
+    let hasStories = false;
     if (epic.stories && Array.isArray(epic.stories)) {
-      totalStories += epic.stories.length;
-      epic.stories.forEach(s => { targetBcps += s.bcps || 0; });
+      epic.stories.forEach(s => {
+        hasStories = true;
+        totalStories++;
+        targetBcps += s.bcps || 0;
+        if (statusMap.get(s.id) === 'done') {
+          doneStories++;
+          deliveredBcps += s.bcps || 0;
+        } else {
+          epicDone = false;
+        }
+      });
+    }
+    if (hasStories && epicDone) {
+      doneEpics++;
     }
   });
 
-  const doneStories = ct.length;
   const totalEpics = epicList.length;
-  const doneStoryIds = new Set(ct.map(c => c.id));
-  const doneEpics = epicList.filter(e =>
-    e.stories && e.stories.length > 0 && e.stories.every(s => doneStoryIds.has(s.id))
-  ).length;
-
-  const deliveredBcps = projectMetrics?.totalBcps ?? 0;
   const totalMin = projectMetrics?.totalMin ?? 0;
   const avgBcpPerHour = projectMetrics?.avgBcpPerHour;
   const version = stateData?.release?.target_version ?? '—';

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.