bigpowers 2.5.0 → 2.7.0

package/SKILL-INDEX.md

@@ -1,102 +1,95 @@
 # Skill Index — Single Source of Truth
 
-**Purpose:** One canonical reference for all bigpowers skills. Referenced by README.md, RELEASE-PLAN.md, and CONVENTIONS.md. Updated per-release.
+> **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.
 
-**Last updated:** 2026-06-11 (v2.0.0 — verified 61 active skills; 18 sub-op concepts absorbed as sub-sections into parent SKILL.md files; count confirmed accurate)
+**Generated:** 2026-06-20T18:59:07Z
+**Skills:** 62
 
 ---
 
-## Quick Navigation by BMAD Phase
+## Quick Navigation by Phase
 
-| Phase | Active | Skills |
+| Phase | Count | Skills |
 |---|---|---|
-| **Bootstrap** | 1 | using-bigpowers |
-| **Orchestrate** | 1 | orchestrate-project |
-| **Discover** | 4 | survey-context, research-first, elaborate-spec, map-codebase |
-| **Elaborate** | 6 | model-domain, define-language, grill-me, grill-with-docs, deepen-architecture, design-interface |
-| **Plan** | 8 | assess-impact, change-request, scope-work, slice-tasks, define-success, plan-work, plan-refactor, plan-release |
-| **Spike** | 1 | spike-prototype |
-| **Initiate** | 4 | kickoff-branch, guard-git, hook-commits, seed-conventions |
-| **Build** | 8 | develop-tdd, enforce-first, delegate-task, dispatch-agents, execute-plan, build-epic, run-planning, fix-bug |
-| **Harden** | 1 | wire-observability |
-| **Verify** | 3 | verify-work, run-evals, align-grid |
-| **Bug** | 3 | investigate-bug, diagnose-root, validate-fix |
-| **Review** | 4 | audit-code, request-review, respond-review, trace-requirement |
-| **Integrate** | 2 | commit-message, release-branch |
-| **Sustain** | 4 | inspect-quality, organize-workspace, stocktake-skills, evolve-skill |
-| **Utility** | 12 | terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard, write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents |
-| **TOTAL** | **62** | |
+| Discover | 6 | `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 | 12 | `align-grid, build-epic, craft-skill, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, setup-environment, spike-prototype, 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** | **61** | |
 
 ---
 
 ## Full Reference Table
 
-| # | Phase | Skill | Intent | Artefact Output | Status |
-|---|---|---|---|---|---|
-| 1 | Bootstrap | `using-bigpowers` | Lifecycle intro; where to start | (dialogue) | ✅ Active |
-| 2 | Orchestrate | `orchestrate-project` | Meta-skill enforcing 6-phase core loop | (orchestration) | ✅ Active |
-| 3 | Discover | `survey-context` | Per-task context map; suggests next skill | STATE.md update | ✅ Active |
-| 4 | Discover | `research-first` | Look-before-build; prior art search | Prior Art in spec | ✅ Active |
-| 5 | Discover | `elaborate-spec` | Dialogue to refine rough idea into spec | (dialogue) | ✅ Active |
-| 6 | Discover | `map-codebase` | High-fidelity codebase survey | CONTEXT.md | ✅ Active |
-| 7 | Elaborate | `model-domain` | Interactive domain model | CONTEXT.md, adr/ | ✅ Active |
-| 8 | Elaborate | `define-language` | Extract ubiquitous language glossary | UBIQUITOUS_LANGUAGE.md | ✅ Active |
-| 9 | Elaborate | `grill-me` | Stress-test design (Design + Docs modes) | (dialogue) | ✅ Active |
-| 10 | Elaborate | `grill-with-docs` | Grill assumptions grounded in real library docs | (dialogue) | ✅ Active |
-| 11 | Elaborate | `deepen-architecture` | Architecture deepening (Ousterhout deep modules) | CONTEXT.md | ✅ Active |
-| 12 | Elaborate | `design-interface` | Multiple interface designs via parallel subagents | INTERFACE-OPTIONS.md | ✅ Active |
-| 13 | Plan | `assess-impact` | Blast radius before code | IMPACT.md | ✅ Active |
-| 14 | Plan | `change-request` | Add requirement or WSJF reorder | RELEASE-PLAN.md | ✅ Active |
-| 15 | Plan | `scope-work` | Define in/out boundaries | SCOPE.md | ✅ Active |
-| 16 | Plan | `slice-tasks` | Vertical slices | TASKS.md | ✅ Active |
-| 17 | Plan | `define-success` | Step → verify pairs; absorbs zoom-out, slopcheck | (dialogue) | ✅ Active |
-| 18 | Plan | `plan-work` | Detailed plan with verify steps; absorbs plan-work-fast | RELEASE-PLAN.md | ✅ Active |
-| 19 | Plan | `plan-refactor` | Refactor plan via interview | REFACTOR.md | ✅ Active |
-| 20 | Plan | `plan-release` | Release plan with Gherkin criteria | RELEASE-PLAN.md | ✅ Active |
-| 21 | Spike | `spike-prototype` | Throw-away spike | SPIKE-<name>.md | ✅ Active |
-| 22 | Initiate | `kickoff-branch` | Worktree + branch + test baseline | (git state) | ✅ Active |
-| 23 | Initiate | `guard-git` | Block dangerous git commands | (git state) | ✅ Active |
-| 24 | Initiate | `hook-commits` | Pre-commit hooks | (git state) | ✅ Active |
-| 25 | Initiate | `seed-conventions` | CLAUDE.md + CONVENTIONS.md + specs/ | CLAUDE.md, CONVENTIONS.md | ✅ Active |
-| 26 | Build | `develop-tdd` | Red → green → refactor TDD; absorbs red-phase, green-phase, refactor-phase | src/ | ✅ Active |
-| 27 | Build | `enforce-first` | F.I.R.S.T test-quality rubric | (checklist) | ✅ Active |
-| 28 | Build | `delegate-task` | One subagent, sequential + review | (code) | ✅ Active |
-| 29 | Build | `dispatch-agents` | Parallel subagents on independent tasks | (code) | ✅ Active |
-| 30 | Build | `execute-plan` | Batch execute plan with checkpoints | src/ | ✅ Active |
-| 31 | Harden | `wire-observability` | Structured logging + observability | src/, CLAUDE.md | ✅ Active |
-| 32 | Verify | `verify-work` | Multi-phase UAT; loop on gaps; absorbs cold-start-smoke, gaps-loop, verify-work-smoke | (dialogue) | ✅ Active |
-| 33 | Verify | `run-evals` | EDD capability + regression evals | EVALS-<feature>.md | ✅ Active |
-| 34 | Verify | `align-grid` | Müller-Brockmann modular grid layout alignment and verification harness | (code / config) | ✅ Active |
-| 35 | Bug | `investigate-bug` | Investigate bug → diagnosis | bugs/BUG-*.md | ✅ Active |
-| 36 | Bug | `diagnose-root` | 4-phase root cause analysis | bugs/BUG-*.md | ✅ Active |
-| 37 | Bug | `validate-fix` | Prove fix works | (verify) | ✅ Active |
-| 38 | Review | `audit-code` | Self-review checklist; absorbs audit-code-quick | (checklist) | ✅ Active |
-| 39 | Review | `request-review` | Fresh reviewer agent | review-report | ✅ Active |
-| 40 | Review | `respond-review` | Act on reviewer feedback | src/ | ✅ Active |
-| 41 | Review | `trace-requirement` | Story ID → code/tests | TRACEABILITY.md | ✅ Active |
-| 42 | Integrate | `commit-message` | Conventional Commits + semver; absorbs commit-message-fix | (git message) | ✅ Active |
-| 43 | Integrate | `release-branch` | Merge/PR decision + cleanup; absorbs release-branch-hotfix | (git PR) | ✅ Active |
-| 44 | Sustain | `inspect-quality` | Structured QA session | BUG-LOG.md | ✅ Active |
-| 45 | Sustain | `organize-workspace` | Safe workspace cleanup | (filesystem) | ✅ Active |
-| 46 | Sustain | `stocktake-skills` | Batch audit of skill catalog | specs/ audit report | ✅ Active |
-| 47 | Sustain | `evolve-skill` | Benchmark-gated skill evolution | ADR, STATE.md | ✅ Active |
-| 48 | Utility | `terse-mode` | Ultra-terse output (fallback) | (prompt) | ✅ Active |
-| 49 | Utility | `craft-skill` | Build new bigpowers skill | skills/<name>/SKILL.md | ✅ Active |
-| 50 | Utility | `edit-document` | Edit documents in specs/ | specs/<name>.md | ✅ Active |
-| 51 | Utility | `session-state` | Track decisions in state.yaml; absorbs show-state, reset-state, compact-state, list-epics, check-gates | state.yaml | ✅ Active |
-| 52 | Utility | `migrate-spec` | Migrate foreign spec formats | specs/ | ✅ Active |
-| 53 | Utility | `visual-dashboard` | Browser dashboard (HTTP cockpit) | `npm run visual-dashboard` → GET /cockpit.html | ✅ Active |
-| 54 | Utility | `write-document` | BMAD technical documents | specs/<name>.md | ✅ Active |
-| 55 | Utility | `setup-environment` | Pre-install deps before work | (.env, packages) | ✅ Active |
-| 56 | Utility | `reset-baseline` | Restore clean known state | (clean tree) | ✅ Active |
-| 57 | Utility | `search-skills` | Natural language → right skill | SKILL-SEARCH-INDEX.md | ✅ Active |
-| 58 | Utility | `compose-workflow` | Chain skills into workflow recipe | WORKFLOW-<name>.md | ✅ Active |
-| 59 | Utility | `simulate-agents` | Mock User + Auditor simulation | SIMULATION-<feature>.md | ✅ Active |
-| 60 | Build | `build-epic` | Eight-step epic build cycle | state.yaml, epics/ | ✅ Active |
-| 61 | Build | `run-planning` | Discover-phase workflow tracker | planning-status.yaml | ✅ Active |
-| 62 | Bug | `fix-bug` | Bug fix orchestrator | bugs/BUG-*.md | ✅ Active |
-
-**Total: 62 active skills.** 18 sub-op concepts (zoom-out, slopcheck, red-phase, green-phase, refactor-phase, cold-start-smoke, gaps-loop, plan-work-fast, commit-message-fix, release-branch-hotfix, audit-code-quick, verify-work-smoke, show-state, reset-state, compact-state, list-epics, check-gates) are documented as sub-sections within parent SKILL.md files; none were standalone SKILL.md directories, so the count remains 62.
+| # | 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 | `develop-tdd` | Test-driven development with red-green-refactor loop using vertical slices. Use  | ✅ Active |
+| 27 | Build | `execute-plan` | Batch-execute tasks from the active epic capsule sequentially, with a human chec | ✅ Active |
+| 28 | Build | `guard-git` | Block dangerous git commands (push, force push, reset --hard, clean, branch -D,  | ✅ Active |
+| 29 | Build | `hook-commits` | Set up pre-commit hooks with lint-staged (Prettier), type checking, and tests in | ✅ Active |
+| 30 | Build | `kickoff-branch` | Create a git worktree and feature branch, then verify a clean test baseline befo | ✅ Active |
+| 31 | Build | `orchestrate-project` | Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan  | ✅ Active |
+| 32 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
+| 33 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
+| 34 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
+| 35 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
+| 36 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
+| 37 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
+| 38 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
+| 39 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
+| 40 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
+| 41 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
+| 42 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
+| 43 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
+| 44 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
+| 45 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
+| 46 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
+| 47 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
+| 48 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
+| 49 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
+| 50 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
+| 51 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
+| 52 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
+| 53 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
+| 54 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
+| 55 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
+| 56 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
+| 57 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
+| 58 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
+| 59 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
+| 60 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
+| 61 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
+
+**Total: 61 active skills.**
 
 ---
 
@@ -104,37 +97,37 @@
 
 ```
 [First time]
-using-bigpowers → orchestrate-project (Standard / Fast-Track / Ad-Hoc)
+using-bigpowers → orchestrate-project
                          ↓
 survey-context → research-first → elaborate-spec → map-codebase
                          ↓
-  model-domain / define-language / grill-me / grill-with-docs / design-interface / deepen-architecture
+  model-domain / define-language / grill-me / grill-with-docs
+  design-interface / deepen-architecture / define-success
                          ↓
-  scope-work → assess-impact → change-request → define-success → slice-tasks → plan-work / plan-refactor / plan-release
+  scope-work → assess-impact → change-request → slice-tasks
+  → plan-work / plan-refactor / plan-release / seed-conventions
                          ↓
-    kickoff-branch → guard-git / hook-commits / seed-conventions
+    kickoff-branch → guard-git / hook-commits / setup-environment
                          ↓
-       [Unknown domain?] spike-prototype → (learnings feed back to plan-work)
+       [Unknown domain?] spike-prototype → (learnings)
                          ↓
-  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents / execute-plan / build-epic
+  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents
+  execute-plan / build-epic / craft-skill / align-grid
                          ↓
-  run-planning (discover workflows → planning-status.yaml)
-                         ↓
-        wire-observability (production-readiness gate, any phase)
-                         ↓
-              ★ VERIFY ★  run-evals → verify-work → align-grid  (prove it works)
+              ★ VERIFY ★  verify-work → run-evals → audit-code
                          ↓
     fix-bug → investigate-bug → diagnose-root → validate-fix
                          ↓
-      audit-code → request-review → respond-review → trace-requirement
+      request-review → respond-review → trace-requirement
                          ↓
       commit-message → release-branch
                          ↓
-   inspect-quality → organize-workspace → stocktake-skills → evolve-skill
+   inspect-quality → organize-workspace → stocktake-skills
+   → evolve-skill → edit-document / write-document / migrate-spec
 
 Transversal utilities (any phase):
-  terse-mode, craft-skill, edit-document, session-state, migrate-spec, visual-dashboard,
-  write-document, setup-environment, reset-baseline, search-skills, compose-workflow, simulate-agents
+  terse-mode, session-state, visual-dashboard, reset-baseline,
+  search-skills, compose-workflow, simulate-agents, wire-observability
 ```
 
 ---
@@ -156,7 +149,8 @@ All skills follow `verb-noun` kebab-case (ADR-0001). Documented exceptions:
 
 ## How to Update
 
-1. Every new skill: add a row here before publishing.
-2. After any change: bump "Last updated" and run `bash scripts/sync-skills.sh`.
+1. Run `bash scripts/sync-skills.sh` to regenerate this file and all artifacts.
+2. Or run `bash scripts/generate-skill-index.sh` to only regenerate this index.
 
 → verify: `find . -maxdepth 2 -name "SKILL.md" | grep -v ".git\|.cursor\|.gemini" | wc -l`
+

package/align-grid/SKILL.md

@@ -8,6 +8,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/package.json

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

package/run-planning/SKILL.md

@@ -5,22 +5,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/scope-work/SKILL.md

@@ -8,16 +8,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