bigpowers 2.27.0 → 2.29.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.27.0",
-  "description": "69 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.29.0",
+  "description": "70 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/audit-plan.md

@@ -0,0 +1,88 @@
+---
+description: Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase.
+---
+
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`

package/.pi/prompts/migrate-spec.md

@@ -71,6 +71,28 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 2. Ask: "Create this? [yes / edit / skip]"
 3. On yes: write to `specs/`.
 
+#### ID Tracking (REQ-XX, FR-XX, UJ-XX)
+
+When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments:
+
+```yaml
+# CORRECT — first-class id: field
+in_scope:
+  - id: REQ-001
+    description: "User can register with email/password"
+    source: "REQUIREMENTS.md"
+
+# DEPRECATED — comment-only
+in_scope:
+  - "User can register with email/password"  # REQ-001
+```
+
+**When source has no IDs:** Prompt the user: "No IDs found. Assign auto-generated IDs? [yes / no]". If yes, emit `REQ-{NNN}` with `# auto-generated` annotation.
+
+**When source has MIXED IDs:** Items with IDs get `id:` fields; items without IDs receive auto-generated `REQ-NNN` entries. Document which were auto-generated in a comment block at the top of `in_scope`.
+
+See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples.
+
 > **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber.
 >
 > → verify: `git diff --name-only HEAD -- specs/ 2>/dev/null | head -20`
@@ -126,7 +148,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 ## Rules
 
-- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
+- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX are emitted as first-class `id:` fields in bigpowers YAML targets (e.g., `in_scope` entries). Never silently renumber. See Step 3 ID Tracking subsection for details.
 - **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
 - **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG.md`.
 - **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
@@ -184,9 +206,9 @@ Transform:
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
-- Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → `in_scope` entries
-- Out-of-Scope → `out_of_scope` entries
+- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](./REFERENCE.md#in_scope-format-with-id-tracking))
+- Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields
+- Out-of-Scope → `out_of_scope` entries (preserve IDs if present)
 - Active (in-progress) → `in_scope` with status note
 
 ---
@@ -404,7 +426,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 - [ ] **`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.
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
 
 ### From spec-kit
 
@@ -454,6 +476,27 @@ For lightweight decisions that don't warrant a full ADR:
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
 
+### in_scope format with ID tracking
+
+Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:
+
+```yaml
+in_scope:
+  - id: REQ-001
+    description: "User can register with email and password"
+    source: "REQUIREMENTS.md"
+  - id: FR-015
+    description: "Auth service must support OAuth2 token flow"
+    source: "prd.md"
+  - id: REQ-AUTO-002  # auto-generated when source had no ID
+    description: "Dashboard displays user profile"
+    # auto-generated: true  (optional comment for tracking)
+```
+
+**When source has no IDs:** If the user opts in, auto-generated IDs follow the `REQ-{NNN}` format with an optional `# auto-generated` comment.
+
+**When source has mixed IDs:** Entries with source IDs get `id:` fields; entries without IDs receive auto-generated IDs. A comment block at the top of `in_scope` documents which IDs were auto-generated.
+
 ### `specs/state.yaml` template format
 
 Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:

package/.pi/prompts/plan-release.md

@@ -57,9 +57,13 @@ Every task must have a `verify:` command. No verify command = not a task.
 
 ### 4. Save specs/release-plan.yaml
 
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
 ```yaml
 release:
-  version: "3.0.0"
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
   codename: "Feature Name"
   status: planning          # planning | in_progress | released
   semantic_release: true

package/.pi/prompts/session-state.md

@@ -108,8 +108,8 @@ active_epic_id: e02
 active_story_id: e02s01       # required when epic mode: folder
 active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
 release:
-  target_version: "3.0.0"
-  last_tag: null
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
   last_publish: null
 epic_cycle:
   current_step: develop-tdd

package/.pi/skills/audit-plan/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: audit-plan
+description: "Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase."
+model: sonnet
+---
+
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`

package/.pi/skills/migrate-spec/SKILL.md

@@ -73,6 +73,28 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 2. Ask: "Create this? [yes / edit / skip]"
 3. On yes: write to `specs/`.
 
+#### ID Tracking (REQ-XX, FR-XX, UJ-XX)
+
+When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments:
+
+```yaml
+# CORRECT — first-class id: field
+in_scope:
+  - id: REQ-001
+    description: "User can register with email/password"
+    source: "REQUIREMENTS.md"
+
+# DEPRECATED — comment-only
+in_scope:
+  - "User can register with email/password"  # REQ-001
+```
+
+**When source has no IDs:** Prompt the user: "No IDs found. Assign auto-generated IDs? [yes / no]". If yes, emit `REQ-{NNN}` with `# auto-generated` annotation.
+
+**When source has MIXED IDs:** Items with IDs get `id:` fields; items without IDs receive auto-generated `REQ-NNN` entries. Document which were auto-generated in a comment block at the top of `in_scope`.
+
+See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples.
+
 > **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber.
 >
 > → verify: `git diff --name-only HEAD -- specs/ 2>/dev/null | head -20`
@@ -128,7 +150,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 ## Rules
 
-- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
+- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX are emitted as first-class `id:` fields in bigpowers YAML targets (e.g., `in_scope` entries). Never silently renumber. See Step 3 ID Tracking subsection for details.
 - **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
 - **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG.md`.
 - **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
@@ -186,9 +208,9 @@ Transform:
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
-- Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → `in_scope` entries
-- Out-of-Scope → `out_of_scope` entries
+- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](./REFERENCE.md#in_scope-format-with-id-tracking))
+- Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields
+- Out-of-Scope → `out_of_scope` entries (preserve IDs if present)
 - Active (in-progress) → `in_scope` with status note
 
 ---
@@ -406,7 +428,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 - [ ] **`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.
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
 
 ### From spec-kit
 
@@ -456,6 +478,27 @@ For lightweight decisions that don't warrant a full ADR:
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
 
+### in_scope format with ID tracking
+
+Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:
+
+```yaml
+in_scope:
+  - id: REQ-001
+    description: "User can register with email and password"
+    source: "REQUIREMENTS.md"
+  - id: FR-015
+    description: "Auth service must support OAuth2 token flow"
+    source: "prd.md"
+  - id: REQ-AUTO-002  # auto-generated when source had no ID
+    description: "Dashboard displays user profile"
+    # auto-generated: true  (optional comment for tracking)
+```
+
+**When source has no IDs:** If the user opts in, auto-generated IDs follow the `REQ-{NNN}` format with an optional `# auto-generated` comment.
+
+**When source has mixed IDs:** Entries with source IDs get `id:` fields; entries without IDs receive auto-generated IDs. A comment block at the top of `in_scope` documents which IDs were auto-generated.
+
 ### `specs/state.yaml` template format
 
 Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:

package/.pi/skills/plan-release/SKILL.md

@@ -59,9 +59,13 @@ Every task must have a `verify:` command. No verify command = not a task.
 
 ### 4. Save specs/release-plan.yaml
 
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
 ```yaml
 release:
-  version: "3.0.0"
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
   codename: "Feature Name"
   status: planning          # planning | in_progress | released
   semantic_release: true

package/.pi/skills/session-state/SKILL.md

@@ -110,8 +110,8 @@ active_epic_id: e02
 active_story_id: e02s01       # required when epic mode: folder
 active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
 release:
-  target_version: "3.0.0"
-  last_tag: null
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
   last_publish: null
 epic_cycle:
   current_step: develop-tdd

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.29.0](https://github.com/danielvm-git/bigpowers/compare/v2.28.0...v2.29.0) (2026-06-26)
+
+
+### Features
+
+* **migrate-spec:** promote ID tracking from comments to first-class YAML fields ([f1c8d73](https://github.com/danielvm-git/bigpowers/commit/f1c8d73a5140175fc0067a191f119eea70395075)), closes [#22](https://github.com/danielvm-git/bigpowers/issues/22)
+
+# [2.28.0](https://github.com/danielvm-git/bigpowers/compare/v2.27.0...v2.28.0) (2026-06-22)
+
+
+### Features
+
+* **audit-plan:** new skill — evaluate project plan for bigpowers readiness ([509deba](https://github.com/danielvm-git/bigpowers/commit/509deba5a45b3f688d087b11091fc854449c7e46))
+
 # [2.27.0](https://github.com/danielvm-git/bigpowers/compare/v2.26.0...v2.27.0) (2026-06-22)
 
 

package/CONVENTIONS.md

@@ -96,11 +96,16 @@ Epic IDs: `e01`, `e30`. Story IDs: `e01s01`. One FR in SCOPE may span multiple e
 
 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
+### Semantic-release — the real version is never hand-tracked
 
-1. **Planning intent** — `specs/release-plan.yaml` → `release.version`, `release.bump_hint` (minor/patch/major expectation).
-2. **Published version** — repo root: `package.json`, git tag `vX.Y.Z`, `CHANGELOG.md` (CI semantic-release; not hand-edited in specs).
-3. **Dashboard optional** — `specs/state.yaml` → `release.last_tag`, `release.last_publish` (from tags/CI).
+> **The authority is `gh release view` / git tags.** semantic-release decides the version
+> at merge from Conventional Commits. Never hand-maintain a `target_version` to "predict" it —
+> that field drifts from reality every release. The specs only *mirror* the real tag for reference.
+
+1. **Planning intent (codename only)** — `specs/release-plan.yaml` → `release.version`, `release.bump_hint`.
+   Treat `version` as a non-authoritative label; if you write a number, mark it "mirror, not the authority".
+2. **Published version (authority)** — repo root `package.json`, git tag `vX.Y.Z`, `CHANGELOG.md` (CI semantic-release; not hand-edited in specs). Read with `gh release view`.
+3. **Dashboard mirror** — `specs/state.yaml` → `release.last_tag`, `release.last_publish` (copied from `gh release view`; `target_version` is `null` — not tracked manually).
 
 ### Guardrails and other artifacts
 

package/SKILL-INDEX.md

@@ -3,8 +3,8 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-22T11:54:00Z
-**Skills:** 69
+**Generated:** 2026-06-26T22:20:53Z
+**Skills:** 70
 
 ---
 
@@ -12,14 +12,14 @@
 
 | Phase | Count | Skills |
 |---|---|---|
-| Discover | 6 | `elaborate-spec, map-codebase, research-first, search-skills, survey-context, using-bigpowers` |
+| Discover | 7 | `audit-plan, elaborate-spec, map-codebase, research-first, search-skills, survey-context, using-bigpowers` |
 | Design | 7 | `deepen-architecture, define-language, define-success, design-interface, grill-me, grill-with-docs, model-domain` |
 | Plan | 9 | `assess-impact, change-request, plan-refactor, plan-release, plan-work, run-planning, scope-work, seed-conventions, slice-tasks` |
 | Build | 18 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, quick-fix, setup-environment, smoke-test, spike-prototype, validate-contracts, wire-ci, wire-observability` |
 | Verify | 12 | `audit-code, diagnose-root, enforce-first, fix-bug, inspect-quality, investigate-bug, request-review, respond-review, run-evals, trace-requirement, validate-fix, verify-work` |
 | Release | 2 | `commit-message, release-branch` |
-| Sustain | 13 | `compose-workflow, delegate-task, dispatch-agents, edit-document, evolve-skill, migrate-spec, organize-workspace, reset-baseline, session-state, simulate-agents, stocktake-skills, terse-mode, write-document` |
-| **TOTAL** | **67** | |
+| Sustain | 14 | `compose-workflow, delegate-task, dispatch-agents, edit-document, evolve-skill, migrate-spec, organize-workspace, reset-baseline, run-benchmark, session-state, simulate-agents, stocktake-skills, terse-mode, write-document` |
+| **TOTAL** | **69** | |
 
 ---
 
@@ -27,75 +27,77 @@
 
 | # | Phase | Skill | Description | Status |
 |---|---|---|---|---|
-| 1 | Discover | `elaborate-spec` | Refine a rough idea into a clear, detailed specification through dialogue. Does  | ✅ Active |
-| 2 | Discover | `map-codebase` | "Derives the tech-stack doc from scratch by scanning the codebase — analyzes s | ✅ Active |
-| 3 | Discover | `research-first` | Look-before-build — search registries, repo, existing skills, and web for prio | ✅ Active |
-| 4 | Discover | `search-skills` | Find the right bigpowers skill from natural-language intent using a local lexica | ✅ Active |
-| 5 | Discover | `survey-context` | Per-task context bootstrap — reads existing specs/ and tech-architecture docs  | ✅ Active |
-| 6 | Discover | `using-bigpowers` | One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecy | ✅ Active |
-| 7 | Design | `deepen-architecture` | Find deepening opportunities in a codebase, informed by the domain language in s | ✅ Active |
-| 8 | Design | `define-language` | Extract a DDD-style ubiquitous language glossary from the current conversation,  | ✅ Active |
-| 9 | Design | `define-success` | Convert an imperative task statement into explicit "step → verify: <cmd>" pair | ✅ Active |
-| 10 | Design | `design-interface` | Generate multiple radically different interface designs for a module using paral | ✅ Active |
-| 11 | Design | `grill-me` | Interactive assumption-surfacing Q&A that stress-tests a plan through relentless | ✅ Active |
-| 12 | Design | `grill-with-docs` | Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching a | ✅ Active |
-| 13 | Design | `model-domain` | Grilling session that challenges your plan against the existing domain model, sh | ✅ Active |
-| 14 | Plan | `assess-impact` | Analyze the blast radius of a proposed change before any code is written. Maps d | ✅ Active |
-| 15 | Plan | `change-request` | Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml a | ✅ Active |
-| 16 | Plan | `plan-refactor` | Create a detailed refactor plan with tiny commits via user interview, then save  | ✅ Active |
-| 17 | Plan | `plan-release` | "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yam | ✅ Active |
-| 18 | Plan | `plan-work` | "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tas | ✅ Active |
-| 19 | Plan | `run-planning` | "DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning- | ✅ Active |
-| 20 | Plan | `scope-work` | "PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in and out of sco | ✅ Active |
-| 21 | Plan | `seed-conventions` | Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief in | ✅ Active |
-| 22 | Plan | `slice-tasks` | "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical | ✅ Active |
-| 23 | Build | `align-grid` | "Build editorial/magazine/report webpages on a GENUINE Müller-Brockmann modular | ✅ Active |
-| 24 | Build | `build-epic` | Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one | ✅ Active |
-| 25 | Build | `craft-skill` | Create new bigpowers skills with proper structure, progressive disclosure, and b | ✅ Active |
-| 26 | Build | `deploy` | "Build → verify artifact → deploy → wait → smoke deployment pipeline. Pl | ✅ Active |
-| 27 | Build | `develop-tdd` | Test-driven development with red-green-refactor loop using vertical slices. Use  | ✅ Active |
-| 28 | Build | `execute-plan` | Batch-execute tasks from the active epic capsule sequentially, with a human chec | ✅ Active |
-| 29 | Build | `guard-git` | Block dangerous git commands (push, force push, reset --hard, clean, branch -D,  | ✅ Active |
-| 30 | Build | `hook-commits` | Set up pre-commit hooks with lint-staged (Prettier), type checking, and tests in | ✅ Active |
-| 31 | Build | `kickoff-branch` | Create a git worktree and feature branch, then verify a clean test baseline befo | ✅ Active |
-| 32 | Build | `orchestrate-project` | Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan  | ✅ Active |
-| 33 | Build | `publish-package` | "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies pr | ✅ Active |
-| 34 | Build | `quick-fix` | "Streamlined fast-path for trivial data-only fixes — no TDD, no branching cere | ✅ Active |
-| 35 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
-| 36 | Build | `smoke-test` | "Post-deploy health-check against a live URL. Validates HTTP status, response co | ✅ Active |
-| 37 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
-| 38 | Build | `validate-contracts` | "Assert data shape consistency across system boundaries — live API responses a | ✅ Active |
-| 39 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
-| 40 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
-| 41 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
-| 42 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
-| 43 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
-| 44 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
-| 45 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
-| 46 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
-| 47 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
-| 48 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
-| 49 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
-| 50 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
-| 51 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
-| 52 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
-| 53 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
-| 54 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
-| 55 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
-| 56 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
-| 57 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
-| 58 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
-| 59 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
-| 60 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
-| 61 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
-| 62 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
-| 63 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
-| 64 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
-| 65 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
-| 66 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
-| 67 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
-
-**Total: 67 active skills.**
+| 1 | Discover | `audit-plan` | Evaluate an incoming project plan against bigpowers principles and conventions,  | ✅ Active |
+| 2 | Discover | `elaborate-spec` | Refine a rough idea into a clear, detailed specification through dialogue. Does  | ✅ Active |
+| 3 | Discover | `map-codebase` | "Derives the tech-stack doc from scratch by scanning the codebase — analyzes s | ✅ Active |
+| 4 | Discover | `research-first` | Look-before-build — search registries, repo, existing skills, and web for prio | ✅ Active |
+| 5 | Discover | `search-skills` | Find the right bigpowers skill from natural-language intent using a local lexica | ✅ Active |
+| 6 | Discover | `survey-context` | Per-task context bootstrap — reads existing specs/ and tech-architecture docs  | ✅ Active |
+| 7 | Discover | `using-bigpowers` | One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecy | ✅ Active |
+| 8 | Design | `deepen-architecture` | Find deepening opportunities in a codebase, informed by the domain language in s | ✅ Active |
+| 9 | Design | `define-language` | Extract a DDD-style ubiquitous language glossary from the current conversation,  | ✅ Active |
+| 10 | Design | `define-success` | Convert an imperative task statement into explicit "step → verify: <cmd>" pair | ✅ Active |
+| 11 | Design | `design-interface` | Generate multiple radically different interface designs for a module using paral | ✅ Active |
+| 12 | Design | `grill-me` | Interactive assumption-surfacing Q&A that stress-tests a plan through relentless | ✅ Active |
+| 13 | Design | `grill-with-docs` | Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching a | ✅ Active |
+| 14 | Design | `model-domain` | Grilling session that challenges your plan against the existing domain model, sh | ✅ Active |
+| 15 | Plan | `assess-impact` | Analyze the blast radius of a proposed change before any code is written. Maps d | ✅ Active |
+| 16 | Plan | `change-request` | Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml a | ✅ Active |
+| 17 | Plan | `plan-refactor` | Create a detailed refactor plan with tiny commits via user interview, then save  | ✅ Active |
+| 18 | Plan | `plan-release` | "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yam | ✅ Active |
+| 19 | Plan | `plan-work` | "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tas | ✅ Active |
+| 20 | Plan | `run-planning` | "DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning- | ✅ Active |
+| 21 | Plan | `scope-work` | "PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in and out of sco | ✅ Active |
+| 22 | Plan | `seed-conventions` | Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief in | ✅ Active |
+| 23 | Plan | `slice-tasks` | "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical | ✅ Active |
+| 24 | Build | `align-grid` | "Build editorial/magazine/report webpages on a GENUINE Müller-Brockmann modular | ✅ Active |
+| 25 | Build | `build-epic` | Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one | ✅ Active |
+| 26 | Build | `craft-skill` | Create new bigpowers skills with proper structure, progressive disclosure, and b | ✅ Active |
+| 27 | Build | `deploy` | "Build → verify artifact → deploy → wait → smoke deployment pipeline. Pl | ✅ Active |
+| 28 | Build | `develop-tdd` | Test-driven development with red-green-refactor loop using vertical slices. Use  | ✅ Active |
+| 29 | Build | `execute-plan` | Batch-execute tasks from the active epic capsule sequentially, with a human chec | ✅ Active |
+| 30 | Build | `guard-git` | Block dangerous git commands (push, force push, reset --hard, clean, branch -D,  | ✅ Active |
+| 31 | Build | `hook-commits` | Set up pre-commit hooks with lint-staged (Prettier), type checking, and tests in | ✅ Active |
+| 32 | Build | `kickoff-branch` | Create a git worktree and feature branch, then verify a clean test baseline befo | ✅ Active |
+| 33 | Build | `orchestrate-project` | Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan  | ✅ Active |
+| 34 | Build | `publish-package` | "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies pr | ✅ Active |
+| 35 | Build | `quick-fix` | "Streamlined fast-path for trivial data-only fixes — no TDD, no branching cere | ✅ Active |
+| 36 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
+| 37 | Build | `smoke-test` | "Post-deploy health-check against a live URL. Validates HTTP status, response co | ✅ Active |
+| 38 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
+| 39 | Build | `validate-contracts` | "Assert data shape consistency across system boundaries — live API responses a | ✅ Active |
+| 40 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
+| 41 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
+| 42 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
+| 43 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
+| 44 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
+| 45 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
+| 46 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
+| 47 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
+| 48 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
+| 49 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
+| 50 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
+| 51 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
+| 52 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
+| 53 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
+| 54 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
+| 55 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
+| 56 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
+| 57 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
+| 58 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
+| 59 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
+| 60 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
+| 61 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
+| 62 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
+| 63 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
+| 64 | Sustain | `run-benchmark` | Run skill quality benchmarks from specs/benchmarks/ definitions and write pass@k | ✅ Active |
+| 65 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
+| 66 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
+| 67 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
+| 68 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
+| 69 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
+
+**Total: 69 active skills.**
 
 ---
 

package/audit-plan/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: audit-plan
+model: sonnet
+description: Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase.
+---
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`

package/migrate-spec/REFERENCE-GSD.md

@@ -48,9 +48,9 @@ Transform:
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
-- Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → `in_scope` entries
-- Out-of-Scope → `out_of_scope` entries
+- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](./REFERENCE.md#in_scope-format-with-id-tracking))
+- Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields
+- Out-of-Scope → `out_of_scope` entries (preserve IDs if present)
 - Active (in-progress) → `in_scope` with status note
 
 ---

package/migrate-spec/REFERENCE.md

@@ -134,7 +134,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 - [ ] **`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.
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
 
 ### From spec-kit
 
@@ -184,6 +184,27 @@ For lightweight decisions that don't warrant a full ADR:
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
 
+### in_scope format with ID tracking
+
+Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:
+
+```yaml
+in_scope:
+  - id: REQ-001
+    description: "User can register with email and password"
+    source: "REQUIREMENTS.md"
+  - id: FR-015
+    description: "Auth service must support OAuth2 token flow"
+    source: "prd.md"
+  - id: REQ-AUTO-002  # auto-generated when source had no ID
+    description: "Dashboard displays user profile"
+    # auto-generated: true  (optional comment for tracking)
+```
+
+**When source has no IDs:** If the user opts in, auto-generated IDs follow the `REQ-{NNN}` format with an optional `# auto-generated` comment.
+
+**When source has mixed IDs:** Entries with source IDs get `id:` fields; entries without IDs receive auto-generated IDs. A comment block at the top of `in_scope` documents which IDs were auto-generated.
+
 ### `specs/state.yaml` template format
 
 Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:

package/migrate-spec/SKILL.md

@@ -74,6 +74,28 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 2. Ask: "Create this? [yes / edit / skip]"
 3. On yes: write to `specs/`.
 
+#### ID Tracking (REQ-XX, FR-XX, UJ-XX)
+
+When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments:
+
+```yaml
+# CORRECT — first-class id: field
+in_scope:
+  - id: REQ-001
+    description: "User can register with email/password"
+    source: "REQUIREMENTS.md"
+
+# DEPRECATED — comment-only
+in_scope:
+  - "User can register with email/password"  # REQ-001
+```
+
+**When source has no IDs:** Prompt the user: "No IDs found. Assign auto-generated IDs? [yes / no]". If yes, emit `REQ-{NNN}` with `# auto-generated` annotation.
+
+**When source has MIXED IDs:** Items with IDs get `id:` fields; items without IDs receive auto-generated `REQ-NNN` entries. Document which were auto-generated in a comment block at the top of `in_scope`.
+
+See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples.
+
 > **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber.
 >
 > → verify: `git diff --name-only HEAD -- specs/ 2>/dev/null | head -20`
@@ -131,7 +153,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 ## Rules
 
-- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
+- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX are emitted as first-class `id:` fields in bigpowers YAML targets (e.g., `in_scope` entries). Never silently renumber. See Step 3 ID Tracking subsection for details.
 - **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
 - **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG.md`.
 - **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.27.0",
+  "version": "2.29.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/plan-release/SKILL.md

@@ -58,9 +58,13 @@ Every task must have a `verify:` command. No verify command = not a task.
 
 ### 4. Save specs/release-plan.yaml
 
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
 ```yaml
 release:
-  version: "3.0.0"
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
   codename: "Feature Name"
   status: planning          # planning | in_progress | released
   semantic_release: true

package/scripts/generate-skill-index.sh

@@ -23,6 +23,7 @@ PHASE_MAP=(
   [using-bigpowers]="Discover"
   [map-codebase]="Discover"
   [elaborate-spec]="Discover"
+  [audit-plan]="Discover"
   # Elaborate / Design
   [model-domain]="Design"
   [define-language]="Design"
@@ -84,6 +85,7 @@ PHASE_MAP=(
   [reset-baseline]="Sustain"
   [stocktake-skills]="Sustain"
   [evolve-skill]="Sustain"
+  [run-benchmark]="Sustain"
   [terse-mode]="Sustain"
   [delegate-task]="Sustain"
   [dispatch-agents]="Sustain"

package/scripts/sync-status-from-epics.sh

@@ -37,6 +37,9 @@ for folder in sorted(epics_dir.glob("e*/")):
         em = re.search(r"^id:\s*(e\d+)", text, re.M)
         if em:
             keys.setdefault(em.group(1), "backlog")
+        # Parse inline story IDs from capsule epic.yaml (same pattern as flat files)
+        for sm in re.finditer(r"^\s+- id:\s*(e\d+s\d+)", text, re.M):
+            keys.setdefault(sm.group(1), "backlog")
     for story in (folder / "stories").glob("e*s*.md"):
         m = re.match(r"(e\d+s\d+)", story.name)
         if m:

package/session-state/SKILL.md

@@ -109,8 +109,8 @@ active_epic_id: e02
 active_story_id: e02s01       # required when epic mode: folder
 active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
 release:
-  target_version: "3.0.0"
-  last_tag: null
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
   last_publish: null
 epic_cycle:
   current_step: develop-tdd

package/skills-lock.json

@@ -16,6 +16,11 @@
       "sha256": "8192ebe6f66a9f91",
       "path": "audit-code/SKILL.md"
     },
+    "audit-plan": {
+      "description": "Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase.",
+      "sha256": "3e88b606fc8e886c",
+      "path": "audit-plan/SKILL.md"
+    },
     "build-epic": {
       "description": "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.",
       "sha256": "7a376ef092fde9cc",
@@ -158,7 +163,7 @@
     },
     "migrate-spec": {
       "description": "Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers YAML layout (state.yaml, release-plan.yaml, epics/, requirements/, plans/, ADRs). Use when migrating foreign spec docs.",
-      "sha256": "912299321559a5e2",
+      "sha256": "3570ec13243de9b8",
       "path": "migrate-spec/SKILL.md"
     },
     "model-domain": {
@@ -183,7 +188,7 @@
     },
     "plan-release": {
       "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.\"",
-      "sha256": "4eeb65607ca2f799",
+      "sha256": "352d54fe911757ad",
       "path": "plan-release/SKILL.md"
     },
     "plan-work": {
@@ -258,7 +263,7 @@
     },
     "session-state": {
       "description": "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.",
-      "sha256": "4efd54a453e3e2cd",
+      "sha256": "0141daaed69b05dc",
       "path": "session-state/SKILL.md"
     },
     "setup-environment": {