bigpowers 2.41.0 → 2.42.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "71 skills — 70 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"

package/.pi/prompts/assess-impact.md

@@ -1,5 +1,5 @@
 ---
-description: Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks "what does this break?".
+description: Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT_LATEST.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks "what does this break?".
 ---
 
 
@@ -53,7 +53,7 @@ grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
 | Medium | 3–10 callers, partial test coverage |
 | High  | > 10 callers, or shared API/interface, or no tests |
 
-### 6. Write specs/IMPACT.md
+### 6. Write specs/IMPACT_LATEST.md
 
 ```
 ## Target
@@ -76,7 +76,7 @@ grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
 [Proceed / Add tests first / Discuss design]
 ```
 
-→ verify: `grep "Risk:" specs/IMPACT.md`
+→ verify: `grep "Risk:" specs/IMPACT_LATEST.md`
 
 Suggest `plan-work` once risk is understood and any test gaps are noted.
 

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

@@ -48,7 +48,7 @@ Assess an incoming project plan for alignment with bigpowers principles, identif
 
 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`**:
+4. **Write `specs/PLAN-AUDIT_LATEST.md`**:
 
 ```markdown
 # Plan Audit — <project>
@@ -85,4 +85,4 @@ NOT READY — N gaps remain; close before proceeding
 
 ## Verify
 
-→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`
+→ verify: `test -f specs/PLAN-AUDIT_LATEST.md && grep -q 'Verdict' specs/PLAN-AUDIT_LATEST.md && echo OK || echo FAIL`

package/.pi/prompts/define-language.md

@@ -1,11 +1,11 @@
 ---
-description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
+description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE_LATEST.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
 ---
 
 
 # Define Language
 
-Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE.md`.
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE_LATEST.md`.
 
 **Distinct from `model-domain` and `deepen-architecture`:** Use this skill to produce a canonical glossary of terms (words and definitions). Use `model-domain` to stress-test a plan through an interview that resolves domain model decisions. Use `deepen-architecture` to find module-level refactoring opportunities in the codebase.
 
@@ -19,12 +19,12 @@ Extract and formalize domain terminology from the current conversation into a co
    - Different words used for the same concept (synonyms)
    - Vague or overloaded terms
 3. **Propose a canonical glossary** with opinionated term choices
-4. **Write to `specs/UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+4. **Write to `specs/UBIQUITOUS_LANGUAGE_LATEST.md`** in the working directory using the format below
 5. **Output a summary** inline in the conversation
 
 ## Output Format
 
-Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
+Write a `specs/UBIQUITOUS_LANGUAGE_LATEST.md` file with this structure:
 
 ```md
 # Ubiquitous Language
@@ -72,7 +72,7 @@ Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
 
 When invoked again in the same conversation:
 
-1. Read the existing `specs/UBIQUITOUS_LANGUAGE.md`
+1. Read the existing `specs/UBIQUITOUS_LANGUAGE_LATEST.md`
 2. Incorporate any new terms from subsequent discussion
 3. Update definitions if understanding has evolved
 4. Re-flag any new ambiguities

package/.pi/prompts/inspect-quality.md

@@ -25,7 +25,7 @@ Do NOT over-interview. If the description is clear enough to log, move on.
 
 Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
 
-- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE.md` if present)
+- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if present)
 - Understand what the feature is supposed to do
 - Identify the user-facing behavior boundary
 
@@ -96,7 +96,7 @@ For each bug, also append a detail section:
 
 - **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
 - **No file paths or line numbers** — these go stale
-- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE.md` if it exists)
+- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if it exists)
 - **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
 - **Reproduction steps are mandatory** — if you can't determine them, ask the user
 

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

@@ -165,7 +165,7 @@ GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context,
 
 Transform:
 - `domain` → `plans/TECH_STACK_LATEST.md` Domain section
-- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG.md`
+- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG_LATEST.md`
 - `canonical_refs` → Reference links in TECH_STACK
 - `code_context` → Architecture section
 - `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)
@@ -338,11 +338,11 @@ Transform:
 - `[ASSUMPTION: ...]` inline tags → collected in scope YAML
 - Out-of-scope features → `out_of_scope`
 
-### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG.md`
+### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md`
 
 Transform:
 - Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`
-- Lightweight decisions → `specs/DECISION-LOG.md` (date | decision | rationale)
+- Lightweight decisions → `specs/DECISION-LOG_LATEST.md` (date | decision | rationale)
 - `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
 
 ### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
@@ -385,7 +385,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 ### From BMAD
 
 - [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
-- [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
+- [ ] **`specs/DECISION-LOG_LATEST.md`** — Lightweight decisions below ADR threshold.
 - [x] **Adversarial review pass** — Critique epic shard before `develop-tdd`. (adopted: optional Step 6 in migration)
 
 ---
@@ -782,7 +782,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 - **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`.
+- **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_LATEST.md`.
 - **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
 - **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.
 

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

@@ -1,5 +1,5 @@
 ---
-description: Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+description: Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR_LATEST.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
 ---
 
 
@@ -7,7 +7,7 @@ description: Create a detailed refactor plan with tiny commits via user intervie
 > **HARD GATE** — **HARD GATE** — Before refactoring, document the current behavior and why it is wrong. Extract one invariant that must be preserved. If you skip this, you will break things you don't expect.
 
 
-Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR.md`.
+Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR_LATEST.md`.
 
 ## Steps
 
@@ -25,7 +25,7 @@ Create a detailed refactor plan through a user interview. Save output to `specs/
 
 7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice: "make each refactoring step as small as possible, so that you can always see the program working."
 
-8. Save the refactor plan to `specs/REFACTOR.md`. Create the `specs/` directory if it doesn't exist.
+8. Save the refactor plan to `specs/REFACTOR_LATEST.md`. Create the `specs/` directory if it doesn't exist.
 
 <refactor-plan-template>
 
@@ -74,4 +74,4 @@ Any further notes about the refactor.
 
 </refactor-plan-template>
 
-After writing `specs/REFACTOR.md`, suggest running `kickoff-branch` next to create a refactor branch.
+After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next to create a refactor branch.

package/.pi/prompts/research-first.md

@@ -68,7 +68,7 @@ cat package.json | jq '.dependencies,.devDependencies' 2>/dev/null
 ## Registry checklist
 
 - [ ] npm / PyPI / crates.io (if applicable)
-- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX.md`)
+- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX_LATEST.md`)
 - [ ] Project `docs/` and `specs/adr/`
 - [ ] Official library documentation (quote one API detail)
 

package/.pi/prompts/search-skills.md

@@ -9,7 +9,7 @@ description: Find the right bigpowers skill from natural-language intent using a
 >
 > **HARD GATE** — Do NOT use external embedding APIs or AI-based semantic search. This is a lexical-only index (ADR: zero external dependency).
 
-Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
+Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX_LATEST.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
 
 ## When to use
 
@@ -20,16 +20,16 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Pre-flight
 
-- [ ] Does `specs/SKILL-SEARCH-INDEX.md` exist? If not, run `bash scripts/build-skill-index.sh`.
+- [ ] Does `specs/SKILL-SEARCH-INDEX_LATEST.md` exist? If not, run `bash scripts/build-skill-index.sh`.
 - [ ] Is the index fresh? Check its timestamp — if > 24 hours old or after any SKILL.md change, regenerate.
 
 ## Process
 
-1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` doesn't exist or was modified before the last SKILL.md change.
+1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX_LATEST.md` doesn't exist or was modified before the last SKILL.md change.
 
 2. **Search the index** — Use ripgrep on the lexical index:
    ```
-   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX_LATEST.md
    ```
    The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
 
@@ -47,7 +47,7 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Index Format
 
-`specs/SKILL-SEARCH-INDEX.md` contains one section per skill:
+`specs/SKILL-SEARCH-INDEX_LATEST.md` contains one section per skill:
 ```markdown
 ## <skill-name>
 - **Description:** <from frontmatter>
@@ -66,4 +66,4 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Verify
 
-→ verify: `test -f specs/SKILL-SEARCH-INDEX.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX.md && echo OK)`
+→ verify: `test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK)`

package/.pi/prompts/trace-requirement.md

@@ -1,5 +1,5 @@
 ---
-description: Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
+description: Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
 ---
 
 
@@ -43,7 +43,7 @@ For each story ID:
 For each tagged file with no matching story ID in release-plan.yaml:
 - **Orphan**: code exists but story was removed or never planned — flag for cleanup
 
-### 4. Write specs/TRACEABILITY.md
+### 4. Write specs/TRACEABILITY_LATEST.md
 
 ```
 ## Story Coverage
@@ -63,6 +63,6 @@ For each tagged file with no matching story ID in release-plan.yaml:
 Stories: [X] covered / [Y] dark / [Z] total
 ```
 
-→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY.md`
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY_LATEST.md`
 
 Suggest `plan-work` for each dark story found.

package/.pi/skills/assess-impact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assess-impact
-description: "Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks \"what does this break?\"."
+description: "Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT_LATEST.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks \"what does this break?\"."
 model: sonnet
 ---
 
@@ -55,7 +55,7 @@ grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
 | Medium | 3–10 callers, partial test coverage |
 | High  | > 10 callers, or shared API/interface, or no tests |
 
-### 6. Write specs/IMPACT.md
+### 6. Write specs/IMPACT_LATEST.md
 
 ```
 ## Target
@@ -78,7 +78,7 @@ grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
 [Proceed / Add tests first / Discuss design]
 ```
 
-→ verify: `grep "Risk:" specs/IMPACT.md`
+→ verify: `grep "Risk:" specs/IMPACT_LATEST.md`
 
 Suggest `plan-work` once risk is understood and any test gaps are noted.
 

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

@@ -50,7 +50,7 @@ Assess an incoming project plan for alignment with bigpowers principles, identif
 
 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`**:
+4. **Write `specs/PLAN-AUDIT_LATEST.md`**:
 
 ```markdown
 # Plan Audit — <project>
@@ -87,4 +87,4 @@ NOT READY — N gaps remain; close before proceeding
 
 ## Verify
 
-→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`
+→ verify: `test -f specs/PLAN-AUDIT_LATEST.md && grep -q 'Verdict' specs/PLAN-AUDIT_LATEST.md && echo OK || echo FAIL`

package/.pi/skills/define-language/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: define-language
-description: "Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions \"domain model\" or \"DDD\"."
+description: "Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE_LATEST.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions \"domain model\" or \"DDD\"."
 model: sonnet
 ---
 
 
 # Define Language
 
-Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE.md`.
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE_LATEST.md`.
 
 **Distinct from `model-domain` and `deepen-architecture`:** Use this skill to produce a canonical glossary of terms (words and definitions). Use `model-domain` to stress-test a plan through an interview that resolves domain model decisions. Use `deepen-architecture` to find module-level refactoring opportunities in the codebase.
 
@@ -21,12 +21,12 @@ Extract and formalize domain terminology from the current conversation into a co
    - Different words used for the same concept (synonyms)
    - Vague or overloaded terms
 3. **Propose a canonical glossary** with opinionated term choices
-4. **Write to `specs/UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+4. **Write to `specs/UBIQUITOUS_LANGUAGE_LATEST.md`** in the working directory using the format below
 5. **Output a summary** inline in the conversation
 
 ## Output Format
 
-Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
+Write a `specs/UBIQUITOUS_LANGUAGE_LATEST.md` file with this structure:
 
 ```md
 # Ubiquitous Language
@@ -74,7 +74,7 @@ Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
 
 When invoked again in the same conversation:
 
-1. Read the existing `specs/UBIQUITOUS_LANGUAGE.md`
+1. Read the existing `specs/UBIQUITOUS_LANGUAGE_LATEST.md`
 2. Incorporate any new terms from subsequent discussion
 3. Update definitions if understanding has evolved
 4. Re-flag any new ambiguities

package/.pi/skills/inspect-quality/SKILL.md

@@ -27,7 +27,7 @@ Do NOT over-interview. If the description is clear enough to log, move on.
 
 Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
 
-- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE.md` if present)
+- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if present)
 - Understand what the feature is supposed to do
 - Identify the user-facing behavior boundary
 
@@ -98,7 +98,7 @@ For each bug, also append a detail section:
 
 - **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
 - **No file paths or line numbers** — these go stale
-- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE.md` if it exists)
+- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if it exists)
 - **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
 - **Reproduction steps are mandatory** — if you can't determine them, ask the user
 

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

@@ -167,7 +167,7 @@ GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context,
 
 Transform:
 - `domain` → `plans/TECH_STACK_LATEST.md` Domain section
-- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG.md`
+- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG_LATEST.md`
 - `canonical_refs` → Reference links in TECH_STACK
 - `code_context` → Architecture section
 - `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)
@@ -340,11 +340,11 @@ Transform:
 - `[ASSUMPTION: ...]` inline tags → collected in scope YAML
 - Out-of-scope features → `out_of_scope`
 
-### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG.md`
+### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md`
 
 Transform:
 - Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`
-- Lightweight decisions → `specs/DECISION-LOG.md` (date | decision | rationale)
+- Lightweight decisions → `specs/DECISION-LOG_LATEST.md` (date | decision | rationale)
 - `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
 
 ### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
@@ -387,7 +387,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 ### From BMAD
 
 - [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
-- [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
+- [ ] **`specs/DECISION-LOG_LATEST.md`** — Lightweight decisions below ADR threshold.
 - [x] **Adversarial review pass** — Critique epic shard before `develop-tdd`. (adopted: optional Step 6 in migration)
 
 ---
@@ -784,7 +784,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 - **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`.
+- **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_LATEST.md`.
 - **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
 - **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.
 

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

@@ -1,6 +1,6 @@
 ---
 name: plan-refactor
-description: "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps."
+description: "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR_LATEST.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps."
 model: sonnet
 ---
 
@@ -9,7 +9,7 @@ model: sonnet
 > **HARD GATE** — **HARD GATE** — Before refactoring, document the current behavior and why it is wrong. Extract one invariant that must be preserved. If you skip this, you will break things you don't expect.
 
 
-Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR.md`.
+Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR_LATEST.md`.
 
 ## Steps
 
@@ -27,7 +27,7 @@ Create a detailed refactor plan through a user interview. Save output to `specs/
 
 7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice: "make each refactoring step as small as possible, so that you can always see the program working."
 
-8. Save the refactor plan to `specs/REFACTOR.md`. Create the `specs/` directory if it doesn't exist.
+8. Save the refactor plan to `specs/REFACTOR_LATEST.md`. Create the `specs/` directory if it doesn't exist.
 
 <refactor-plan-template>
 
@@ -76,4 +76,4 @@ Any further notes about the refactor.
 
 </refactor-plan-template>
 
-After writing `specs/REFACTOR.md`, suggest running `kickoff-branch` next to create a refactor branch.
+After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next to create a refactor branch.

package/.pi/skills/research-first/SKILL.md

@@ -70,7 +70,7 @@ cat package.json | jq '.dependencies,.devDependencies' 2>/dev/null
 ## Registry checklist
 
 - [ ] npm / PyPI / crates.io (if applicable)
-- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX.md`)
+- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX_LATEST.md`)
 - [ ] Project `docs/` and `specs/adr/`
 - [ ] Official library documentation (quote one API detail)
 

package/.pi/skills/search-skills/SKILL.md

@@ -11,7 +11,7 @@ model: haiku
 >
 > **HARD GATE** — Do NOT use external embedding APIs or AI-based semantic search. This is a lexical-only index (ADR: zero external dependency).
 
-Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
+Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX_LATEST.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
 
 ## When to use
 
@@ -22,16 +22,16 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Pre-flight
 
-- [ ] Does `specs/SKILL-SEARCH-INDEX.md` exist? If not, run `bash scripts/build-skill-index.sh`.
+- [ ] Does `specs/SKILL-SEARCH-INDEX_LATEST.md` exist? If not, run `bash scripts/build-skill-index.sh`.
 - [ ] Is the index fresh? Check its timestamp — if > 24 hours old or after any SKILL.md change, regenerate.
 
 ## Process
 
-1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` doesn't exist or was modified before the last SKILL.md change.
+1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX_LATEST.md` doesn't exist or was modified before the last SKILL.md change.
 
 2. **Search the index** — Use ripgrep on the lexical index:
    ```
-   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX_LATEST.md
    ```
    The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
 
@@ -49,7 +49,7 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Index Format
 
-`specs/SKILL-SEARCH-INDEX.md` contains one section per skill:
+`specs/SKILL-SEARCH-INDEX_LATEST.md` contains one section per skill:
 ```markdown
 ## <skill-name>
 - **Description:** <from frontmatter>
@@ -68,4 +68,4 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Verify
 
-→ verify: `test -f specs/SKILL-SEARCH-INDEX.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX.md && echo OK)`
+→ verify: `test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK)`

package/.pi/skills/trace-requirement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trace-requirement
-description: "Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find \"dark\" stories with no code."
+description: "Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find \"dark\" stories with no code."
 model: haiku
 ---
 
@@ -45,7 +45,7 @@ For each story ID:
 For each tagged file with no matching story ID in release-plan.yaml:
 - **Orphan**: code exists but story was removed or never planned — flag for cleanup
 
-### 4. Write specs/TRACEABILITY.md
+### 4. Write specs/TRACEABILITY_LATEST.md
 
 ```
 ## Story Coverage
@@ -65,6 +65,6 @@ For each tagged file with no matching story ID in release-plan.yaml:
 Stories: [X] covered / [Y] dark / [Z] total
 ```
 
-→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY.md`
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY_LATEST.md`
 
 Suggest `plan-work` for each dark story found.

package/.releaserc.json

@@ -13,7 +13,7 @@
           "package.json",
           "skills-lock.json",
           ".gemini/extensions/bigpowers/gemini-extension.json",
-          "specs/SKILL-SEARCH-INDEX.md"
+          "specs/SKILL-SEARCH-INDEX_LATEST.md"
         ],
         "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
       }

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.42.0](https://github.com/danielvm-git/bigpowers/compare/v2.41.0...v2.42.0) (2026-06-29)
+
+
+### Features
+
+* **skills:** rename generated specs-root outputs to _LATEST.md suffix ([#28](https://github.com/danielvm-git/bigpowers/issues/28)) ([9982d23](https://github.com/danielvm-git/bigpowers/commit/9982d238b9b5f30f948d3ac7f4e6b44cf56f6730))
+
 # [2.41.0](https://github.com/danielvm-git/bigpowers/compare/v2.40.0...v2.41.0) (2026-06-27)
 
 

package/GEMINI.md

@@ -52,3 +52,24 @@ Collection of 58 verb-noun skills, each with a SKILL.md source file and supporti
 - Run tests after every change. Show evidence before declaring done.
 - One clarifying question beats a wrong assumption baked into 200 lines.
 - All written output (plans, specs, investigations) goes in specs/.
+
+## bts toolchain
+
+`bts` is installed. Prefer its verbs over ad-hoc shell commands.
+
+| Task | Command | Avoid |
+|------|---------|-------|
+| Search code | `bts find --print <pattern>` | grep / find / cat |
+| Interactive search | `bts find <pattern>` | manual grep pipes |
+| Compress for context | `bts compress <file>` or `cmd \| bts compress` | summarising by hand |
+| Repo map | `bts map` | listing files by hand |
+| Library docs | `bts docs <lib>` | guessing from training data |
+| Package source | `bts src <pkg>` | git clone |
+| Toolchain health | `bts doctor` | which / command -v |
+
+**Rules**
+- Search with `bts find` before opening files to locate a symbol or pattern.
+- Pipe anything > 200 lines through `bts compress` before adding to context.
+- Run `bts map` when asked for a repo overview.
+- Use `bts docs <lib>` before answering questions about library APIs.
+- If a tool is missing, say so and run `bts doctor` — do not silently substitute.

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **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-27T16:42:29Z
+**Generated:** 2026-06-29T16:10:24Z
 **Skills:** 71
 
 ---

package/assess-impact/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: assess-impact
 model: sonnet
-description: Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks "what does this break?".
+description: Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT_LATEST.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks "what does this break?".
 ---
 
 # Assess Impact
@@ -54,7 +54,7 @@ grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
 | Medium | 3–10 callers, partial test coverage |
 | High  | > 10 callers, or shared API/interface, or no tests |
 
-### 6. Write specs/IMPACT.md
+### 6. Write specs/IMPACT_LATEST.md
 
 ```
 ## Target
@@ -77,7 +77,7 @@ grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
 [Proceed / Add tests first / Discuss design]
 ```
 
-→ verify: `grep "Risk:" specs/IMPACT.md`
+→ verify: `grep "Risk:" specs/IMPACT_LATEST.md`
 
 Suggest `plan-work` once risk is understood and any test gaps are noted.
 

package/audit-plan/SKILL.md

@@ -49,7 +49,7 @@ Assess an incoming project plan for alignment with bigpowers principles, identif
 
 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`**:
+4. **Write `specs/PLAN-AUDIT_LATEST.md`**:
 
 ```markdown
 # Plan Audit — <project>
@@ -86,4 +86,4 @@ NOT READY — N gaps remain; close before proceeding
 
 ## Verify
 
-→ verify: `test -f specs/PLAN-AUDIT.md && grep -q 'Verdict' specs/PLAN-AUDIT.md && echo OK || echo FAIL`
+→ verify: `test -f specs/PLAN-AUDIT_LATEST.md && grep -q 'Verdict' specs/PLAN-AUDIT_LATEST.md && echo OK || echo FAIL`

package/define-language/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: define-language
 model: sonnet
-description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
+description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE_LATEST.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
 ---
 
 # Define Language
 
-Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE.md`.
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE_LATEST.md`.
 
 **Distinct from `model-domain` and `deepen-architecture`:** Use this skill to produce a canonical glossary of terms (words and definitions). Use `model-domain` to stress-test a plan through an interview that resolves domain model decisions. Use `deepen-architecture` to find module-level refactoring opportunities in the codebase.
 
@@ -20,12 +20,12 @@ Extract and formalize domain terminology from the current conversation into a co
    - Different words used for the same concept (synonyms)
    - Vague or overloaded terms
 3. **Propose a canonical glossary** with opinionated term choices
-4. **Write to `specs/UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+4. **Write to `specs/UBIQUITOUS_LANGUAGE_LATEST.md`** in the working directory using the format below
 5. **Output a summary** inline in the conversation
 
 ## Output Format
 
-Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
+Write a `specs/UBIQUITOUS_LANGUAGE_LATEST.md` file with this structure:
 
 ```md
 # Ubiquitous Language
@@ -73,7 +73,7 @@ Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
 
 When invoked again in the same conversation:
 
-1. Read the existing `specs/UBIQUITOUS_LANGUAGE.md`
+1. Read the existing `specs/UBIQUITOUS_LANGUAGE_LATEST.md`
 2. Incorporate any new terms from subsequent discussion
 3. Update definitions if understanding has evolved
 4. Re-flag any new ambiguities

package/inspect-quality/SKILL.md

@@ -26,7 +26,7 @@ Do NOT over-interview. If the description is clear enough to log, move on.
 
 Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
 
-- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE.md` if present)
+- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if present)
 - Understand what the feature is supposed to do
 - Identify the user-facing behavior boundary
 
@@ -97,7 +97,7 @@ For each bug, also append a detail section:
 
 - **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
 - **No file paths or line numbers** — these go stale
-- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE.md` if it exists)
+- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if it exists)
 - **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
 - **Reproduction steps are mandatory** — if you can't determine them, ask the user
 

package/migrate-spec/REFERENCE-GSD.md

@@ -61,7 +61,7 @@ GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context,
 
 Transform:
 - `domain` → `plans/TECH_STACK_LATEST.md` Domain section
-- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG.md`
+- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG_LATEST.md`
 - `canonical_refs` → Reference links in TECH_STACK
 - `code_context` → Architecture section
 - `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)

package/migrate-spec/REFERENCE.md

@@ -100,11 +100,11 @@ Transform:
 - `[ASSUMPTION: ...]` inline tags → collected in scope YAML
 - Out-of-scope features → `out_of_scope`
 
-### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG.md`
+### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md`
 
 Transform:
 - Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`
-- Lightweight decisions → `specs/DECISION-LOG.md` (date | decision | rationale)
+- Lightweight decisions → `specs/DECISION-LOG_LATEST.md` (date | decision | rationale)
 - `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
 
 ### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
@@ -147,7 +147,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 ### From BMAD
 
 - [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
-- [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
+- [ ] **`specs/DECISION-LOG_LATEST.md`** — Lightweight decisions below ADR threshold.
 - [x] **Adversarial review pass** — Critique epic shard before `develop-tdd`. (adopted: optional Step 6 in migration)
 
 ---
@@ -544,7 +544,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 - **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`.
+- **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_LATEST.md`.
 - **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
 - **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "70 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
@@ -9,7 +9,7 @@
     "sync": "bash scripts/sync-skills.sh",
     "validate-specs": "bash scripts/validate-specs-yaml.sh",
     "enrich-epics": "bash scripts/enrich-epics-from-archive.sh",
-    "version": "bash scripts/sync-skills.sh && git add .gemini/extensions/bigpowers/gemini-extension.json specs/SKILL-SEARCH-INDEX.md",
+    "version": "bash scripts/sync-skills.sh && git add .gemini/extensions/bigpowers/gemini-extension.json specs/SKILL-SEARCH-INDEX_LATEST.md",
     "install": "bash scripts/install.sh",
     "postinstall": "bash scripts/sync-skills.sh && bash scripts/install.sh",
     "release": "semantic-release",

package/plan-refactor/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: plan-refactor
 model: sonnet
-description: Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+description: Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR_LATEST.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
 ---
 
 # Plan Refactor
 > **HARD GATE** — **HARD GATE** — Before refactoring, document the current behavior and why it is wrong. Extract one invariant that must be preserved. If you skip this, you will break things you don't expect.
 
 
-Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR.md`.
+Create a detailed refactor plan through a user interview. Save output to `specs/REFACTOR_LATEST.md`.
 
 ## Steps
 
@@ -26,7 +26,7 @@ Create a detailed refactor plan through a user interview. Save output to `specs/
 
 7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice: "make each refactoring step as small as possible, so that you can always see the program working."
 
-8. Save the refactor plan to `specs/REFACTOR.md`. Create the `specs/` directory if it doesn't exist.
+8. Save the refactor plan to `specs/REFACTOR_LATEST.md`. Create the `specs/` directory if it doesn't exist.
 
 <refactor-plan-template>
 
@@ -75,4 +75,4 @@ Any further notes about the refactor.
 
 </refactor-plan-template>
 
-After writing `specs/REFACTOR.md`, suggest running `kickoff-branch` next to create a refactor branch.
+After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next to create a refactor branch.

package/research-first/REFERENCE.md

@@ -14,7 +14,7 @@ cat package.json | jq '.dependencies,.devDependencies' 2>/dev/null
 ## Registry checklist
 
 - [ ] npm / PyPI / crates.io (if applicable)
-- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX.md`)
+- [ ] Existing bigpowers skill (`bash scripts/build-skill-index.sh && rg "<intent>" specs/SKILL-SEARCH-INDEX_LATEST.md`)
 - [ ] Project `docs/` and `specs/adr/`
 - [ ] Official library documentation (quote one API detail)
 

package/scripts/build-skill-index.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-OUT="$REPO_ROOT/specs/SKILL-SEARCH-INDEX.md"
+OUT="$REPO_ROOT/specs/SKILL-SEARCH-INDEX_LATEST.md"
 mkdir -p "$(dirname "$OUT")"
 
 {

package/search-skills/SKILL.md

@@ -10,7 +10,7 @@ model: haiku
 >
 > **HARD GATE** — Do NOT use external embedding APIs or AI-based semantic search. This is a lexical-only index (ADR: zero external dependency).
 
-Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
+Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX_LATEST.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
 
 ## When to use
 
@@ -21,16 +21,16 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Pre-flight
 
-- [ ] Does `specs/SKILL-SEARCH-INDEX.md` exist? If not, run `bash scripts/build-skill-index.sh`.
+- [ ] Does `specs/SKILL-SEARCH-INDEX_LATEST.md` exist? If not, run `bash scripts/build-skill-index.sh`.
 - [ ] Is the index fresh? Check its timestamp — if > 24 hours old or after any SKILL.md change, regenerate.
 
 ## Process
 
-1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` doesn't exist or was modified before the last SKILL.md change.
+1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX_LATEST.md` doesn't exist or was modified before the last SKILL.md change.
 
 2. **Search the index** — Use ripgrep on the lexical index:
    ```
-   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX_LATEST.md
    ```
    The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
 
@@ -48,7 +48,7 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Index Format
 
-`specs/SKILL-SEARCH-INDEX.md` contains one section per skill:
+`specs/SKILL-SEARCH-INDEX_LATEST.md` contains one section per skill:
 ```markdown
 ## <skill-name>
 - **Description:** <from frontmatter>
@@ -67,4 +67,4 @@ Lexical search only — no embedding service (ADR: zero external dependency). Th
 
 ## Verify
 
-→ verify: `test -f specs/SKILL-SEARCH-INDEX.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX.md && echo OK)`
+→ verify: `test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX_LATEST.md && echo OK)`

package/skills-lock.json

@@ -7,8 +7,8 @@
       "path": "align-grid/SKILL.md"
     },
     "assess-impact": {
-      "description": "Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks \"what does this break?\".",
-      "sha256": "740925970c6cf9ce",
+      "description": "Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT_LATEST.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks \"what does this break?\".",
+      "sha256": "29183a878aa2cb0d",
       "path": "assess-impact/SKILL.md"
     },
     "audit-code": {
@@ -18,7 +18,7 @@
     },
     "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",
+      "sha256": "571ab4f5ae9c7c13",
       "path": "audit-plan/SKILL.md"
     },
     "build-epic": {
@@ -52,8 +52,8 @@
       "path": "deepen-architecture/SKILL.md"
     },
     "define-language": {
-      "description": "Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions \"domain model\" or \"DDD\".",
-      "sha256": "d8386de827612d1a",
+      "description": "Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE_LATEST.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions \"domain model\" or \"DDD\".",
+      "sha256": "bffe0227335e5a41",
       "path": "define-language/SKILL.md"
     },
     "define-success": {
@@ -143,7 +143,7 @@
     },
     "inspect-quality": {
       "description": "Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/registry.yaml with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions \"QA session\".",
-      "sha256": "e5f9923e72550572",
+      "sha256": "de13d11018beab6a",
       "path": "inspect-quality/SKILL.md"
     },
     "investigate-bug": {
@@ -182,8 +182,8 @@
       "path": "organize-workspace/SKILL.md"
     },
     "plan-refactor": {
-      "description": "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.",
-      "sha256": "f146cb1327e32943",
+      "description": "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR_LATEST.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.",
+      "sha256": "2785dc22454f0104",
       "path": "plan-refactor/SKILL.md"
     },
     "plan-release": {
@@ -253,7 +253,7 @@
     },
     "search-skills": {
       "description": "Find the right bigpowers skill from natural-language intent using a local lexical index over SKILL.md frontmatter. Use when unsure which skill to invoke, or at start of research-first.",
-      "sha256": "34df830694a6459c",
+      "sha256": "5e5135b53c15f532",
       "path": "search-skills/SKILL.md"
     },
     "security-review": {
@@ -312,8 +312,8 @@
       "path": "terse-mode/SKILL.md"
     },
     "trace-requirement": {
-      "description": "Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find \"dark\" stories with no code.",
-      "sha256": "fbfe216d29b75058",
+      "description": "Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find \"dark\" stories with no code.",
+      "sha256": "4955b4bc05bb41bc",
       "path": "trace-requirement/SKILL.md"
     },
     "using-bigpowers": {

package/trace-requirement/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: trace-requirement
 model: haiku
-description: Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
+description: Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
 ---
 
 # Trace Requirement
@@ -44,7 +44,7 @@ For each story ID:
 For each tagged file with no matching story ID in release-plan.yaml:
 - **Orphan**: code exists but story was removed or never planned — flag for cleanup
 
-### 4. Write specs/TRACEABILITY.md
+### 4. Write specs/TRACEABILITY_LATEST.md
 
 ```
 ## Story Coverage
@@ -64,6 +64,6 @@ For each tagged file with no matching story ID in release-plan.yaml:
 Stories: [X] covered / [Y] dark / [Z] total
 ```
 
-→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY.md`
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY_LATEST.md`
 
 Suggest `plan-work` for each dark story found.