docs: enforce spec-first beads/OpenSpec workflow

.claude/commands/brain-dump.md

@@ -19,28 +19,37 @@ openspec update
 
 ### Step 1: Parse the dump into a structured brief
 
-Populate:
-- `docs/SPEC.md` — goals, scope, non-goals, success criteria
+Ask clarifying questions to resolve:
+- Open questions that block coding
+- Ambiguous scope (what is explicitly out of scope?)
+- Key technical decisions with rationale
+
+Then populate:
+- `docs/SPEC.md` — high-level goals, scope, non-goals, success criteria, assumptions, risks, checkpoint plan (human approval gates)
 - `docs/DECISIONS.md` — key technical decisions + rationale
-- `CLAUDE.md` — stack-specific commands/structure
+- `CLAUDE.md` — stack-specific commands/structure (update placeholders)
 - `README.md` — project quick start and purpose
 
-Also include these required sections in `docs/SPEC.md`:
-- Assumptions
-- Risks and mitigations
-- Open questions that block coding
-- Checkpoint plan (where human approval is required)
+`docs/SPEC.md` is a human-readable summary. It is NOT the authoritative spec for implementation — that lives in `openspec/`.
 
-### Step 2: Create OpenSpec artifacts (preferred)
+### Step 2: Create OpenSpec artifacts (REQUIRED — primary spec source)
 
-Prefer OpenSpec-native change artifacts under `openspec/changes/<change-id>/` (proposal/tasks/spec deltas).
-If the project is using the simpler legacy mode, create/update `openspec/specs/*.md`.
+This step is mandatory, not optional. OpenSpec artifacts under `openspec/` are the authoritative source of truth for implementation work.
 
-Every feature/change must have explicit acceptance criteria.
+For each significant feature or change:
+- **Preferred:** create a change artifact under `openspec/changes/<change-id>/` (proposal, tasks, spec deltas)
+- **Simpler/legacy mode:** create/update `openspec/specs/<feature>.md`
+
+Every artifact MUST include:
+- Explicit acceptance criteria (testable, unambiguous)
+- Open questions / assumptions
+- Risks and mitigations
+
+Do NOT create beads issues that have no corresponding OpenSpec artifact. The spec comes before the task queue.
 
 ### Step 3: Create Beads execution queue
 
-Create beads issues tied to spec/change artifacts:
+Create beads issues linked to spec/change artifacts:
 ```bash
 bd create "feat: [feature] (spec: openspec/...)" -p N --json
 ```
@@ -50,7 +59,7 @@ Add dependencies where needed:
 bd dep add <id> --blocked-by <other-id>
 ```
 
-Store traceability in notes:
+Store traceability in notes (mandatory):
 ```bash
 bd update <id> --notes "Spec source: openspec/..."
 ```
@@ -59,14 +68,20 @@ bd update <id> --notes "Spec source: openspec/..."
 
 Output phases with:
 - objective
-- outside-in tests to write first
+- outside-in tests to write first (acceptance/E2E -> integration -> unit)
 - completion evidence
 - checkpoint gate (requires human approval before next phase)
 
 ### Step 5: Summarize and handoff
 
-Summarize generated artifacts, unresolved blockers, and the first recommended bead.
-Suggest:
+Summarize:
+- Generated OpenSpec artifacts (list paths)
+- Generated beads issues (list IDs and titles)
+- Unresolved blockers / open questions
+- First recommended bead to start
+
+Then suggest:
 ```bash
 bd ready --json
+/start-bead
 ```

.claude/commands/checkpoint.md

@@ -12,11 +12,11 @@ Create a safety save point to preserve current progress.
 
 2. Ask for a brief description of current state.
 
-3. Stage specific changed files (NOT `git add -A`), commit, and sync:
+3. Stage specific changed files (NOT `git add -A`), commit, and optionally verify tracker state:
    ```bash
    git add [specific files]
    git commit -m "checkpoint: [description] (bd-xxx)"
-   bd sync
+   bd list --json --all
    ```
 
 4. Confirm with commit hash and files included.

.claude/commands/complete-bead.md

@@ -4,44 +4,70 @@ Finish the current task, run quality gates, and close the beads issue.
 
 ## Instructions
 
-1. Find the in-progress issue:
-   ```bash
-   bd list --json
-   ```
-   If none: suggest `/start-bead`.
-
-2. Run quality gates (adapt to project stack):
-   ```bash
-   npm test
-   npm run lint
-   npm run typecheck
-   ```
-   If `typecheck` does not exist, continue without failing on that step.
-
-3. Confirm outside-in evidence is present:
-   - Acceptance/E2E or contract tests for user-visible behavior
-   - Integration/unit coverage for critical logic
-
-4. Review uncommitted changes:
-   ```bash
-   git status
-   git diff --stat
-   ```
-
-5. If checks pass — stage specific files (NOT `git add -A`), commit, close and sync:
-   ```bash
-   git add [specific files]
-   git commit -m "type(scope): description (bd-xxx)"
-   bd close [id] --reason "Completed" --json
-   bd sync
-   ```
-
-6. If checks fail — show failures, fix or propose fixes, do NOT close the issue.
+### 1. Find the in-progress issue
+
+```bash
+bd list --json
+```
+
+If none: suggest `/start-bead`. Do not proceed without an active issue.
+
+### 2. Verify spec linkage
+
+Check the bead's notes for a `Spec source:` entry. If it's missing:
+- Add it now: `bd update <id> --notes "Spec source: openspec/..."`
+- If no spec exists for this work, flag it: "WARNING: this bead has no linked OpenSpec artifact. Consider backfilling one in `openspec/specs/` for traceability."
+
+### 3. Run quality gates (adapt to project stack)
+
+```bash
+npm test
+npm run lint
+npm run typecheck
+```
+
+If `typecheck` does not exist, continue without failing on that step.
+
+### 4. Confirm outside-in evidence is present
+
+- Acceptance/E2E or contract tests covering user-visible behavior
+- Integration/unit coverage for critical logic
+
+If evidence is missing for non-trivial work, do NOT close the issue — show what's missing.
+
+### 5. Review uncommitted changes
+
+```bash
+git status
+git diff --stat
+```
+
+### 6. If checks pass — commit, close, sync, push
+
+Stage specific files (NOT `git add -A`):
+```bash
+git add [specific files]
+git commit -m "type(scope): description (bd-xxx)"
+bd close [id] --reason "Completed" --json
+bd list --json --all
+git push
+```
+
+### 7. If checks fail
+
+Show failures. Fix or propose fixes. Do NOT close the issue.
 
 ## Human-in-the-loop
 
-Before closing, provide a concise checkpoint summary (what changed, test evidence, risks) and wait for user approval if this is a phase boundary.
+Before closing, provide a concise checkpoint summary:
+- What changed
+- Test evidence (pass/fail counts, coverage if available)
+- Spec linkage confirmed or flagged
+- Any risks or follow-up issues
+
+Wait for user approval if this is a phase boundary.
 
 ## Forbidden
 
-NEVER use `git add -A` (may stage secrets). Stage specific files by name.
+NEVER use `git add -A` (may stage secrets or unintended files). Stage specific files by name.
+NEVER close a bead when tests are failing.

.claude/commands/plan.md

@@ -4,31 +4,45 @@ Create an implementation plan before writing any code.
 
 ## Instructions
 
-1. **Restate requirements**
-   - Prefer OpenSpec change artifacts (`openspec/changes/...`) when present.
-   - Else use `openspec/specs/...`.
-   - If neither exists, propose creating one first.
-
-2. **Produce a phased plan** with explicit verification and checkpoint gates:
-   ```
-   Phase 1: [Name]
-   - Task -> verify: [how to check]
-   - Checkpoint gate -> user approves before Phase 2
-   ```
-
-3. **Include mandatory sections**
-   - Assumptions
-   - Non-goals
-   - Risks (with mitigations)
-   - Open questions that block coding
-
-4. **Testing strategy (outside-in)**
-   - Acceptance/E2E first
-   - Integration next
-   - Unit tests for complex logic
-
-5. **WAIT FOR CONFIRMATION**
-   Do NOT write code until the user explicitly approves the plan.
+### 1. Locate the spec
+
+Check for OpenSpec artifacts in priority order:
+```bash
+ls openspec/changes/    # preferred for active change work
+ls openspec/specs/      # fallback for simpler features
+```
+
+- **If `openspec/changes/<change-id>/` exists**: read the proposal and acceptance criteria from there.
+- **If `openspec/specs/<feature>.md` exists**: read the spec from there.
+- **If NEITHER exists**: STOP. Do not proceed with planning or coding.
+  - Tell the user: "No OpenSpec artifact found. Run `/brain-dump` to create one first, or create a spec manually at `openspec/specs/<feature>.md` with acceptance criteria before planning."
+  - Do not generate a plan based on `docs/SPEC.md` alone — that file is a summary, not a spec.
+
+### 2. Restate requirements from the spec
+
+Summarize:
+- Goal (what success looks like)
+- Acceptance criteria (verbatim from spec)
+- Explicit non-goals
+- Open questions that must be resolved before coding starts
+
+### 3. Produce a phased plan
+
+Each phase must include verification and a checkpoint gate:
+```
+Phase 1: [Name]
+- Task -> verify: [how to check]
+- Checkpoint gate -> user approves before Phase 2
+```
+
+Include mandatory sections:
+- **Assumptions** — what you're taking as true
+- **Risks** — with mitigations
+- **Testing strategy** — outside-in order: acceptance/E2E first, integration next, unit for complex logic
+
+### 4. WAIT FOR CONFIRMATION
+
+Do NOT write code until the user explicitly approves the plan.
 
 After approval:
 1. `/start-bead`

.claude/commands/start-bead.md

@@ -4,37 +4,66 @@ Start work with minimal manual intervention while preserving traceability.
 
 ## Instructions
 
-1. Check for in-progress issues:
-   ```bash
-   bd list --json
-   ```
-
-2. **If exactly one issue is `in_progress`**: continue it automatically.
-
-3. **If none are `in_progress`**:
-   - Check ready queue:
-     ```bash
-     bd ready --json
-     ```
-   - If ready issues exist: auto-pick the highest-priority unblocked issue and mark in progress.
-     ```bash
-     bd update <id> --status in_progress
-     ```
-   - If no ready issues: create one from user intent and mark in progress.
-     ```bash
-     bd create "[task summary]" -p [priority] --json
-     bd update <id> --status in_progress
-     ```
-
-4. Link the issue to spec context:
-   - Prefer OpenSpec change artifacts (`openspec/changes/*`) when present.
-   - Otherwise use `openspec/specs/*`.
-   - Add notes to issue with the source file path(s):
-     ```bash
-     bd update <id> --notes "Spec source: openspec/..."
-     ```
-
-5. Confirm active issue, objective, and **first checkpoint boundary** (what must be shown before continuing).
+### 1. Check current beads state
+
+```bash
+bd list --json
+```
+
+**If exactly one issue is `in_progress`**: continue it automatically (skip to step 4).
+
+**If multiple issues are `in_progress`**: flag this as unexpected — only one should be active at a time. Ask the user which to continue.
+
+### 2. If none are `in_progress`, find work
+
+```bash
+bd ready --json
+```
+
+- If ready issues exist: auto-pick the highest-priority unblocked issue.
+- If no ready issues: see step 3 before creating anything new.
+
+### 3. Gate on OpenSpec artifact (non-trivial work)
+
+Before marking any issue in-progress — or creating a new one — verify a corresponding OpenSpec artifact exists:
+
+```bash
+ls openspec/changes/   # preferred for active change work
+ls openspec/specs/     # fallback for simpler features
+```
+
+**If OpenSpec artifacts exist** for the work: proceed to step 4.
+
+**If NO OpenSpec artifacts exist** (or the work is non-trivial with no spec):
+- STOP. Do not create a bead and start coding.
+- Tell the user: "No OpenSpec artifact found for this work. Run `/brain-dump` to create specs and a proper task queue first, or point me to an existing spec in `openspec/`."
+- Exception: genuinely trivial work (typo fix, config tweak, single-line change) may proceed without a spec — state the reason explicitly.
+
+### 4. Mark issue in-progress and link to spec
+
+```bash
+bd update <id> --status in_progress
+```
+
+Link the issue to its spec artifact:
+```bash
+bd update <id> --notes "Spec source: openspec/..."
+```
+
+If creating a new issue (for work that already has a spec):
+```bash
+bd create "feat: [feature] (spec: openspec/...)" -p [priority] --json
+bd update <id> --status in_progress
+bd update <id> --notes "Spec source: openspec/..."
+```
+
+### 5. Confirm scope and first checkpoint
+
+State:
+- Active bead ID and title
+- Source spec artifact (path)
+- Objective for this slice
+- First checkpoint boundary (what must be shown before continuing)
 
 ## Human-in-the-loop rule