bigpowers 2.6.0 → 2.7.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "62 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"

package/.pi/prompts/align-grid.md

@@ -7,6 +7,8 @@ description: "Build editorial/magazine/report webpages on a GENUINE Müller-Broc
 
 Josef Müller-Brockmann (1914–1996), Zurich; *Grid Systems in Graphic Design* (1981) is the corpus. The grid is treated as an ethic, not decoration: **"The grid system is an aid, not a guarantee. It permits a number of possible uses and each designer can look for a solution appropriate to his personal style. But one must learn how to use the grid; it is an art that requires practice."** This skill encodes that discipline AND — the part most attempts get wrong — the front-end engineering to make the grid genuinely load-bearing on the web, plus a harness that PROVES it.
 
+> **HARD GATE** — Do NOT ship a grid page without running `verify_grid.js` first. A visually plausible layout is not evidence of grid adherence — the harness is. Zero failing assertions is the only passing bar.
+
 > Two real review notes this skill exists to prevent:
 > 1. *"the grid is just slapped on top and misaligned"* → the overlay wasn't in the same content box as the content (see §2.2).
 > 2. *"the H in the headline is off the grid"* → the headline's BOX was on the grid but its INK wasn't; large glyphs carry a side-bearing (see §2.6). **Box-on-grid ≠ ink-on-grid.**

package/.pi/prompts/run-planning.md

@@ -4,22 +4,75 @@ description: "DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (sp
 
 
 # Run Planning
-> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
 
+> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
+>
 > **Role:** DISCOVER-PHASE ADVANCER — orchestrates the discover-phase sequence; hands off to the scope-work → slice-tasks → plan-work spine for implementation planning.
 
-Updates `specs/planning-status.yaml` as discover-phase skills complete.
+Updates `specs/planning-status.yaml` as discover-phase skills complete. This is NOT a duplicate of plan-work — it orchestrates the *pre-coding* discovery phase only (Discover phase in the 6-phase PMBOK lifecycle), handing off to the planning spine for implementation detail.
+
+## When to use
+
+- Starting a brand-new feature or initiative with no prior planning artifacts
+- Returning to a stalled initiative and needing to resume the discovery workflow
+- After `orchestrate-project` hands off to the Discover phase
+- When a new epic emerges from `change-request` and needs to go through full discovery
+
+## Pre-flight
+
+- [ ] Does `specs/planning-status.yaml` exist? If not, create it with the default workflow keys.
+- [ ] Does `specs/state.yaml` have `active_flow: planning`? Set it if not already.
+- [ ] Is the epic identified in `release-plan.yaml`? The epic must exist before discovery begins.
 
 ## Workflows (default keys)
 
 - `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
 
+Each key maps to a skill invocation. Optional keys can be skipped; required keys must complete before the phase advances.
+
 ## Process
 
-1. Read `specs/planning-status.yaml` and `specs/state.yaml`.
-2. Find first workflow with `status: pending` or `optional` not yet run.
-3. Invoke the matching skill; on success set `status: done` for that workflow key.
-4. Set `state.yaml` `active_flow: planning` while in this chain.
+1. **Read state** — Read `specs/planning-status.yaml` and `specs/state.yaml`. Understand where discovery stands: which workflow keys are `done`, which are `pending`, and which are `optional` (can be skipped).
+
+2. **Find next step** — Find the first workflow key with `status: pending`. If the key is `optional`, check if the user wants to run it. If not, mark it `skipped`.
+
+3. **Invoke the matching skill** — Run the skill that matches the workflow key:
+   - `survey-context` — where are we?
+   - `scope-work` — what's in and out?
+   - `research-first` — what already exists?
+   - `elaborate-spec` — refine the idea (optional)
+   - `plan-release` — sequence epics by WSJF
+   - `slice-tasks` — cut vertical slices
+
+4. **Update status** — On successful completion, set `status: done` for that workflow key in `planning-status.yaml`.
+
+5. **Advance** — Set `state.yaml` `active_flow: planning` while in this chain. When all required keys are done, set `handoff.next_skill` to `plan-work`.
+
+## Workflow Keys Schema
+
+In `specs/planning-status.yaml`:
+```yaml
+workflows:
+  survey-context:
+    required: true
+    status: done
+  scope-work:
+    required: true
+    status: pending
+  research-first:
+    required: false
+    status: optional
+    note: "Skip if no external dependencies"
+  elaborate-spec:
+    required: false
+    status: optional
+  plan-release:
+    required: true
+    status: pending
+  slice-tasks:
+    required: true
+    status: pending
+```
 
 ## Verify
 

package/.pi/prompts/scope-work.md

@@ -7,16 +7,46 @@ description: "PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in a
 
 > **Spine position:** Step 1 — scope-work → slice-tasks → plan-work.
 
-Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`.
+Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`. Without a scope boundary, implementation drifts — stories expand, estimates blow up, and "done" becomes undefined.
+
+## Pre-flight
+
+- [ ] Do you have a clear user need or problem statement? If not, run `elaborate-spec` first.
+- [ ] Does `specs/product/VISION_LATEST.yaml` exist? If yes, read it for north-star alignment.
+- [ ] Is there an existing `SCOPE_LATEST.yaml`? If yes, you're refining, not creating from scratch.
 
 ## Process
 
-1. Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any).
-2. Interview (if needed): goal, users, in-scope, out-of-scope, constraints, success metrics.
-3. Write `specs/product/SCOPE_LATEST.yaml` with: `core_value`, `summary`, `in_scope[]`, `out_of_scope[]`, `constraints`, `success_criteria`, `references`.
-4. Run `research-first` if external dependencies are proposed.
+1. **Gather context** — Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any). Understand what the project is building and why.
+
+2. **Interview (if needed)** — Clarify: What is the goal? Who are the users? What is definitely in scope? What is explicitly out of scope? What constraints exist (time, budget, tech)? How will success be measured?
+
+3. **Write `specs/product/SCOPE_LATEST.yaml`** with these fields:
+   - `core_value` — one-sentence value proposition
+   - `summary` — 2-3 paragraph scope overview
+   - `in_scope[]` — list of what this initiative covers (each maps to an epic/story)
+   - `out_of_scope[]` — explicit exclusions (prevents scope creep)
+   - `constraints` — tech, time, resource boundaries
+   - `success_criteria` — observable outcomes that prove the scope is delivered
+   - `references` — links to related specs, ADRs, or documents
+
+4. **Lightweight trade-off analysis** — For each `out_of_scope` item, note *why* it's excluded (deferred, not valuable, too risky, depends on external factor). This protects against "what about X?" questions later.
+
+5. **Run `research-first`** if external dependencies are proposed — verify the dependency exists, is maintained, and fits the scope before committing to it.
+
+> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`. If an item can't be mapped, the scope is too vague — refine before proceeding.
+
+> **HARD GATE** — Do NOT include implementation details in SCOPE_LATEST.yaml. Scope is *what* and *why*, not *how*. Implementation detail belongs in epic capsules and slice-tasks.
+
+## Common Anti-Patterns
+
+- **"Everything is in scope"** — If nothing is out of scope, you haven't defined a scope. You've described a universe. Cut aggressively.
+- **"We'll figure it out later"** — Ambiguity in scope propagates to every downstream decision. Resolve now or explicitly defer in writing.
+- **Scope as architecture** — Saying "we need a PostgreSQL database" is architecture, not scope. Scope says "we need to store user profiles and transaction history."
+
+## Output
 
-> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`.
+`specs/product/SCOPE_LATEST.yaml` — the bounded PRD. Subsequent skills (`slice-tasks`, `plan-work`) reference this as the source of truth for what to build.
 
 ## Verify
 

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

@@ -4,17 +4,65 @@ description: Find the right bigpowers skill from natural-language intent using a
 
 
 # Search Skills
-> **HARD GATE** — **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
 
+> **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
+>
+> **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).
+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.
+
+## When to use
+
+- You're unsure which skill to invoke for a user's request
+- At the start of `research-first` to find pre-existing skills that might solve the problem
+- When a user asks "is there a skill for X?"
+- Before calling a skill by name, to confirm it's the right one
+
+## Pre-flight
+
+- [ ] Does `specs/SKILL-SEARCH-INDEX.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. Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` is stale.
-2. Search index: `rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md`
-3. Read top 3 matches' `description` and "Use when" triggers.
-4. Recommend one skill with rationale; invoke via orchestrator or direct call.
+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.
+
+2. **Search the index** — Use ripgrep on the lexical index:
+   ```
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md
+   ```
+   The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
+
+3. **Rank results** — Read the top 3 matches. Evaluate by:
+   - **Exactness** — Does the description literally match the user's intent?
+   - **Phase fit** — Is the skill designed for the current lifecycle phase?
+   - **Trigger phrases** — Does the skill's "Use when" section match the situation?
+
+4. **Recommend one skill** — Select the single best-matching skill. Provide:
+   - The skill name
+   - Why it's the best match (citing the description or trigger phrase)
+   - What it produces (artifact, dialogue, or state change)
+
+5. **Invoke** — Call the skill directly or through the orchestrator. If no match found, suggest the closest phase-appropriate skill or `using-bigpowers` as a general entry point.
+
+## Index Format
+
+`specs/SKILL-SEARCH-INDEX.md` contains one section per skill:
+```markdown
+## <skill-name>
+- **Description:** <from frontmatter>
+- **Phase:** <lifecycle phase>
+- **Triggers:** <key phrases from description>
+- **Keywords:** <extracted terms>
+```
+
+## Why Not Semantic Search?
+
+- Zero network dependency — works fully offline
+- Zero cost — no API keys, no usage limits
+- Instant — ripgrep on a local file is sub-second
+- Deterministic — same query always returns same results
+- Auditable — you can read the full index
 
 ## Verify
 

package/.pi/prompts/slice-tasks.md

@@ -9,14 +9,46 @@ description: "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD
 
 Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical slices, each independently deliverable and testable. Output: decoupled `eNNsYY-tasks.yaml` files with runnable verify commands. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use capsule dirs + `execution-status.yaml`.
 
+## Pre-flight
+
+- [ ] Does `specs/product/SCOPE_LATEST.yaml` exist? If not, run `scope-work` first — you can't slice what you haven't bounded.
+- [ ] Is the `release-plan.yaml` populated with the epics you're slicing? Epic IDs (e01, e02…) should exist before you create stories.
+- [ ] Do you understand the difference between a horizontal layer and a vertical slice? (See anti-patterns below.)
+
 ## Process
 
-1. Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
-2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
-3. Each story: writes `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`). Story spec `.md` files are written by `plan-work` and follow [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md).
-4. Order by WSJF in `release-plan.yaml` epic list.
+1. **Read context** — Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`. Understand what the epic delivers end-to-end.
+
+2. **Cut tracer-bullet slices** — Identify the thinnest possible vertical path through the stack that delivers user value. Start with this slice; it will catch integration issues first. For example:
+   - A search feature: first slice is "user types query → API returns results" (no filters, no pagination, no ranking — just the plumbing working end-to-end).
+   - A checkout flow: first slice is "user clicks buy → order created" (no payment, no inventory, no email).
+
+3. **Assign BCPs** — For each story, estimate Business Complexity Points (1–13). A 1-BCP story is a trivial change (one file, one concept). A 13-BCP story is a major feature across multiple modules. If a story exceeds 8 BCPs, consider splitting it.
+
+4. **Each story** writes:
+   - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`)
+   - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md
+   - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs
+
+5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest.
+
+6. **Validate slices** — Every slice must answer: "If this story ships, does a user get new value?" If the answer is "no, they need a later story too", the slice is too horizontal — cut vertically deeper.
+
+> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration. Every story must be independently demonstrable, even if it only handles the happy path.
+
+> **HARD GATE** — Each task's `verify:` field must contain a runnable command (not "manually check" or "review visually"). If verification requires manual steps, prefix with `verify-script:` and write the steps in the story file.
+
+## Anti-Patterns
+
+- **Layer cakes** — "Week 1: all models. Week 2: all controllers. Week 3: all views." This hides integration risk until the end. Every story must cut through all layers.
+- **Too-small slices** — If a slice takes < 30 minutes to implement, it's probably noise. Combine with adjacent slices.
+- **Too-large slices** — If a slice takes > 3 days, it's an epic, not a story. Split further.
+
+## Output
 
-> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration.
+- `specs/epics/eNN-slug/eNNsYY-tasks.yaml` — per-story task breakdown with verify commands
+- `specs/epics/eNN-slug/epic.yaml` — updated with story list and BCPs
+- `specs/release-plan.yaml` — updated WSJF ordering (if needed)
 
 ## Verify
 

package/.pi/skills/align-grid/SKILL.md

@@ -9,6 +9,8 @@ model: sonnet
 
 Josef Müller-Brockmann (1914–1996), Zurich; *Grid Systems in Graphic Design* (1981) is the corpus. The grid is treated as an ethic, not decoration: **"The grid system is an aid, not a guarantee. It permits a number of possible uses and each designer can look for a solution appropriate to his personal style. But one must learn how to use the grid; it is an art that requires practice."** This skill encodes that discipline AND — the part most attempts get wrong — the front-end engineering to make the grid genuinely load-bearing on the web, plus a harness that PROVES it.
 
+> **HARD GATE** — Do NOT ship a grid page without running `verify_grid.js` first. A visually plausible layout is not evidence of grid adherence — the harness is. Zero failing assertions is the only passing bar.
+
 > Two real review notes this skill exists to prevent:
 > 1. *"the grid is just slapped on top and misaligned"* → the overlay wasn't in the same content box as the content (see §2.2).
 > 2. *"the H in the headline is off the grid"* → the headline's BOX was on the grid but its INK wasn't; large glyphs carry a side-bearing (see §2.6). **Box-on-grid ≠ ink-on-grid.**

package/.pi/skills/run-planning/SKILL.md

@@ -6,22 +6,75 @@ model: sonnet
 
 
 # Run Planning
-> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
 
+> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
+>
 > **Role:** DISCOVER-PHASE ADVANCER — orchestrates the discover-phase sequence; hands off to the scope-work → slice-tasks → plan-work spine for implementation planning.
 
-Updates `specs/planning-status.yaml` as discover-phase skills complete.
+Updates `specs/planning-status.yaml` as discover-phase skills complete. This is NOT a duplicate of plan-work — it orchestrates the *pre-coding* discovery phase only (Discover phase in the 6-phase PMBOK lifecycle), handing off to the planning spine for implementation detail.
+
+## When to use
+
+- Starting a brand-new feature or initiative with no prior planning artifacts
+- Returning to a stalled initiative and needing to resume the discovery workflow
+- After `orchestrate-project` hands off to the Discover phase
+- When a new epic emerges from `change-request` and needs to go through full discovery
+
+## Pre-flight
+
+- [ ] Does `specs/planning-status.yaml` exist? If not, create it with the default workflow keys.
+- [ ] Does `specs/state.yaml` have `active_flow: planning`? Set it if not already.
+- [ ] Is the epic identified in `release-plan.yaml`? The epic must exist before discovery begins.
 
 ## Workflows (default keys)
 
 - `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
 
+Each key maps to a skill invocation. Optional keys can be skipped; required keys must complete before the phase advances.
+
 ## Process
 
-1. Read `specs/planning-status.yaml` and `specs/state.yaml`.
-2. Find first workflow with `status: pending` or `optional` not yet run.
-3. Invoke the matching skill; on success set `status: done` for that workflow key.
-4. Set `state.yaml` `active_flow: planning` while in this chain.
+1. **Read state** — Read `specs/planning-status.yaml` and `specs/state.yaml`. Understand where discovery stands: which workflow keys are `done`, which are `pending`, and which are `optional` (can be skipped).
+
+2. **Find next step** — Find the first workflow key with `status: pending`. If the key is `optional`, check if the user wants to run it. If not, mark it `skipped`.
+
+3. **Invoke the matching skill** — Run the skill that matches the workflow key:
+   - `survey-context` — where are we?
+   - `scope-work` — what's in and out?
+   - `research-first` — what already exists?
+   - `elaborate-spec` — refine the idea (optional)
+   - `plan-release` — sequence epics by WSJF
+   - `slice-tasks` — cut vertical slices
+
+4. **Update status** — On successful completion, set `status: done` for that workflow key in `planning-status.yaml`.
+
+5. **Advance** — Set `state.yaml` `active_flow: planning` while in this chain. When all required keys are done, set `handoff.next_skill` to `plan-work`.
+
+## Workflow Keys Schema
+
+In `specs/planning-status.yaml`:
+```yaml
+workflows:
+  survey-context:
+    required: true
+    status: done
+  scope-work:
+    required: true
+    status: pending
+  research-first:
+    required: false
+    status: optional
+    note: "Skip if no external dependencies"
+  elaborate-spec:
+    required: false
+    status: optional
+  plan-release:
+    required: true
+    status: pending
+  slice-tasks:
+    required: true
+    status: pending
+```
 
 ## Verify
 

package/.pi/skills/scope-work/SKILL.md

@@ -9,16 +9,46 @@ model: sonnet
 
 > **Spine position:** Step 1 — scope-work → slice-tasks → plan-work.
 
-Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`.
+Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`. Without a scope boundary, implementation drifts — stories expand, estimates blow up, and "done" becomes undefined.
+
+## Pre-flight
+
+- [ ] Do you have a clear user need or problem statement? If not, run `elaborate-spec` first.
+- [ ] Does `specs/product/VISION_LATEST.yaml` exist? If yes, read it for north-star alignment.
+- [ ] Is there an existing `SCOPE_LATEST.yaml`? If yes, you're refining, not creating from scratch.
 
 ## Process
 
-1. Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any).
-2. Interview (if needed): goal, users, in-scope, out-of-scope, constraints, success metrics.
-3. Write `specs/product/SCOPE_LATEST.yaml` with: `core_value`, `summary`, `in_scope[]`, `out_of_scope[]`, `constraints`, `success_criteria`, `references`.
-4. Run `research-first` if external dependencies are proposed.
+1. **Gather context** — Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any). Understand what the project is building and why.
+
+2. **Interview (if needed)** — Clarify: What is the goal? Who are the users? What is definitely in scope? What is explicitly out of scope? What constraints exist (time, budget, tech)? How will success be measured?
+
+3. **Write `specs/product/SCOPE_LATEST.yaml`** with these fields:
+   - `core_value` — one-sentence value proposition
+   - `summary` — 2-3 paragraph scope overview
+   - `in_scope[]` — list of what this initiative covers (each maps to an epic/story)
+   - `out_of_scope[]` — explicit exclusions (prevents scope creep)
+   - `constraints` — tech, time, resource boundaries
+   - `success_criteria` — observable outcomes that prove the scope is delivered
+   - `references` — links to related specs, ADRs, or documents
+
+4. **Lightweight trade-off analysis** — For each `out_of_scope` item, note *why* it's excluded (deferred, not valuable, too risky, depends on external factor). This protects against "what about X?" questions later.
+
+5. **Run `research-first`** if external dependencies are proposed — verify the dependency exists, is maintained, and fits the scope before committing to it.
+
+> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`. If an item can't be mapped, the scope is too vague — refine before proceeding.
+
+> **HARD GATE** — Do NOT include implementation details in SCOPE_LATEST.yaml. Scope is *what* and *why*, not *how*. Implementation detail belongs in epic capsules and slice-tasks.
+
+## Common Anti-Patterns
+
+- **"Everything is in scope"** — If nothing is out of scope, you haven't defined a scope. You've described a universe. Cut aggressively.
+- **"We'll figure it out later"** — Ambiguity in scope propagates to every downstream decision. Resolve now or explicitly defer in writing.
+- **Scope as architecture** — Saying "we need a PostgreSQL database" is architecture, not scope. Scope says "we need to store user profiles and transaction history."
+
+## Output
 
-> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`.
+`specs/product/SCOPE_LATEST.yaml` — the bounded PRD. Subsequent skills (`slice-tasks`, `plan-work`) reference this as the source of truth for what to build.
 
 ## Verify
 

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

@@ -6,17 +6,65 @@ model: haiku
 
 
 # Search Skills
-> **HARD GATE** — **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
 
+> **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
+>
+> **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).
+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.
+
+## When to use
+
+- You're unsure which skill to invoke for a user's request
+- At the start of `research-first` to find pre-existing skills that might solve the problem
+- When a user asks "is there a skill for X?"
+- Before calling a skill by name, to confirm it's the right one
+
+## Pre-flight
+
+- [ ] Does `specs/SKILL-SEARCH-INDEX.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. Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` is stale.
-2. Search index: `rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md`
-3. Read top 3 matches' `description` and "Use when" triggers.
-4. Recommend one skill with rationale; invoke via orchestrator or direct call.
+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.
+
+2. **Search the index** — Use ripgrep on the lexical index:
+   ```
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md
+   ```
+   The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
+
+3. **Rank results** — Read the top 3 matches. Evaluate by:
+   - **Exactness** — Does the description literally match the user's intent?
+   - **Phase fit** — Is the skill designed for the current lifecycle phase?
+   - **Trigger phrases** — Does the skill's "Use when" section match the situation?
+
+4. **Recommend one skill** — Select the single best-matching skill. Provide:
+   - The skill name
+   - Why it's the best match (citing the description or trigger phrase)
+   - What it produces (artifact, dialogue, or state change)
+
+5. **Invoke** — Call the skill directly or through the orchestrator. If no match found, suggest the closest phase-appropriate skill or `using-bigpowers` as a general entry point.
+
+## Index Format
+
+`specs/SKILL-SEARCH-INDEX.md` contains one section per skill:
+```markdown
+## <skill-name>
+- **Description:** <from frontmatter>
+- **Phase:** <lifecycle phase>
+- **Triggers:** <key phrases from description>
+- **Keywords:** <extracted terms>
+```
+
+## Why Not Semantic Search?
+
+- Zero network dependency — works fully offline
+- Zero cost — no API keys, no usage limits
+- Instant — ripgrep on a local file is sub-second
+- Deterministic — same query always returns same results
+- Auditable — you can read the full index
 
 ## Verify
 

package/.pi/skills/slice-tasks/SKILL.md

@@ -11,14 +11,46 @@ model: sonnet
 
 Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical slices, each independently deliverable and testable. Output: decoupled `eNNsYY-tasks.yaml` files with runnable verify commands. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use capsule dirs + `execution-status.yaml`.
 
+## Pre-flight
+
+- [ ] Does `specs/product/SCOPE_LATEST.yaml` exist? If not, run `scope-work` first — you can't slice what you haven't bounded.
+- [ ] Is the `release-plan.yaml` populated with the epics you're slicing? Epic IDs (e01, e02…) should exist before you create stories.
+- [ ] Do you understand the difference between a horizontal layer and a vertical slice? (See anti-patterns below.)
+
 ## Process
 
-1. Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
-2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
-3. Each story: writes `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`). Story spec `.md` files are written by `plan-work` and follow [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md).
-4. Order by WSJF in `release-plan.yaml` epic list.
+1. **Read context** — Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`. Understand what the epic delivers end-to-end.
+
+2. **Cut tracer-bullet slices** — Identify the thinnest possible vertical path through the stack that delivers user value. Start with this slice; it will catch integration issues first. For example:
+   - A search feature: first slice is "user types query → API returns results" (no filters, no pagination, no ranking — just the plumbing working end-to-end).
+   - A checkout flow: first slice is "user clicks buy → order created" (no payment, no inventory, no email).
+
+3. **Assign BCPs** — For each story, estimate Business Complexity Points (1–13). A 1-BCP story is a trivial change (one file, one concept). A 13-BCP story is a major feature across multiple modules. If a story exceeds 8 BCPs, consider splitting it.
+
+4. **Each story** writes:
+   - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`)
+   - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md
+   - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs
+
+5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest.
+
+6. **Validate slices** — Every slice must answer: "If this story ships, does a user get new value?" If the answer is "no, they need a later story too", the slice is too horizontal — cut vertically deeper.
+
+> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration. Every story must be independently demonstrable, even if it only handles the happy path.
+
+> **HARD GATE** — Each task's `verify:` field must contain a runnable command (not "manually check" or "review visually"). If verification requires manual steps, prefix with `verify-script:` and write the steps in the story file.
+
+## Anti-Patterns
+
+- **Layer cakes** — "Week 1: all models. Week 2: all controllers. Week 3: all views." This hides integration risk until the end. Every story must cut through all layers.
+- **Too-small slices** — If a slice takes < 30 minutes to implement, it's probably noise. Combine with adjacent slices.
+- **Too-large slices** — If a slice takes > 3 days, it's an epic, not a story. Split further.
+
+## Output
 
-> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration.
+- `specs/epics/eNN-slug/eNNsYY-tasks.yaml` — per-story task breakdown with verify commands
+- `specs/epics/eNN-slug/epic.yaml` — updated with story list and BCPs
+- `specs/release-plan.yaml` — updated WSJF ordering (if needed)
 
 ## Verify
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.7.0](https://github.com/danielvm-git/bigpowers/compare/v2.6.0...v2.7.0) (2026-06-20)
+
+
+### Features
+
+* **catalog:** add lockfile regeneration and auto-generated SKILL-INDEX ([#20](https://github.com/danielvm-git/bigpowers/issues/20)) ([2437dd0](https://github.com/danielvm-git/bigpowers/commit/2437dd0cf32858809623e8cca7680224f8394020))
+
 # [2.6.0](https://github.com/danielvm-git/bigpowers/compare/v2.5.0...v2.6.0) (2026-06-18)