From 393065ae1d5b941453e5d5a642bde83ce8b6eb9d Mon Sep 17 00:00:00 2001 From: richards-bot Date: Thu, 23 Apr 2026 23:04:04 +0100 Subject: [PATCH 1/2] docs(workflow): enforce spec-first discipline across all commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - brain-dump: make OpenSpec artifacts the mandatory primary output; docs/SPEC.md demoted to human-readable summary; add clarifying questions step before populating docs - start-bead: add step 3 gate — STOP if no OpenSpec artifact exists for non-trivial work; only trivial changes may bypass (must state why) - plan: hard STOP if neither openspec/changes/ nor openspec/specs/ exist; forbid planning from docs/SPEC.md alone - status: list openspec/ artifacts in output; warn if active bead is missing Spec source: linkage in notes - complete-bead: verify spec linkage before closing; add git push to the success path; never close when tests fail - GETTING-STARTED: add clean beads state verification after setup; explicit spec-first section (spec -> beads -> code order); document what brain-dump creates and in what order - README: clarify brain-dump creates OpenSpec artifacts as primary output; add post-setup beads verification; fix manual setup to also remove .beads.bak --- .claude/commands/brain-dump.md | 49 ++++++++++------ .claude/commands/complete-bead.md | 96 ++++++++++++++++++++----------- .claude/commands/plan.md | 64 +++++++++++++-------- .claude/commands/start-bead.md | 91 +++++++++++++++++++---------- .claude/commands/status.md | 33 +++++++++-- GETTING-STARTED.md | 94 ++++++++++++++++++++++-------- README.md | 23 +++++--- 7 files changed, 304 insertions(+), 146 deletions(-) diff --git a/.claude/commands/brain-dump.md b/.claude/commands/brain-dump.md index a14b7f3..8d3fd13 100644 --- a/.claude/commands/brain-dump.md +++ b/.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//` (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//` (proposal, tasks, spec deltas) +- **Simpler/legacy mode:** create/update `openspec/specs/.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 --blocked-by ``` -Store traceability in notes: +Store traceability in notes (mandatory): ```bash bd update --notes "Spec source: openspec/..." ``` @@ -59,14 +68,20 @@ bd update --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 ``` diff --git a/.claude/commands/complete-bead.md b/.claude/commands/complete-bead.md index e4163e7..9213c18 100644 --- a/.claude/commands/complete-bead.md +++ b/.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 --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 sync +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. diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index 07ff4cd..9c94df8 100644 --- a/.claude/commands/plan.md +++ b/.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//` exists**: read the proposal and acceptance criteria from there. +- **If `openspec/specs/.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/.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` diff --git a/.claude/commands/start-bead.md b/.claude/commands/start-bead.md index e5d3495..bb20720 100644 --- a/.claude/commands/start-bead.md +++ b/.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 --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 --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 --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 --status in_progress +``` + +Link the issue to its spec artifact: +```bash +bd update --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 --status in_progress +bd update --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 diff --git a/.claude/commands/status.md b/.claude/commands/status.md index 24238b7..da376d1 100644 --- a/.claude/commands/status.md +++ b/.claude/commands/status.md @@ -4,7 +4,7 @@ Show implementation status with spec ↔ task traceability. ## Instructions -Run these and summarize: +Run these commands and summarize the results: ```bash bd list --json @@ -12,11 +12,32 @@ bd ready --json git status --short git branch --show-current git log --oneline -5 +ls openspec/changes/ 2>/dev/null || echo "(no changes/)" +ls openspec/specs/ 2>/dev/null || echo "(no specs/)" ``` -Also report: -1. Active bead(s) and whether they include spec references in notes. -2. Next checkpoint gate and required evidence. -3. Any blockers or open questions from current spec/change artifacts. +### Report the following -Display: active issues, ready tasks, branch, uncommitted changes, recent commits, and checkpoint readiness. +1. **Beads state** + - Active (in_progress) bead(s): ID, title, spec reference in notes (or flag if missing) + - Ready (unblocked) tasks: count and top priorities + - Blocked tasks: count and what's blocking them + +2. **Spec state** + - OpenSpec changes: list artifacts in `openspec/changes/` (or "none") + - OpenSpec specs: list artifacts in `openspec/specs/` (or "none") + - Flag if active beads exist but have no spec linkage in their notes + +3. **Git state** + - Current branch + - Uncommitted changes (files) + - Last 5 commits + +4. **Checkpoint readiness** + - Next checkpoint gate and required evidence + - Any blockers or open questions from current spec/change artifacts + +### Spec linkage check + +If any in-progress bead is missing a `Spec source:` entry in its notes, surface this as a warning: +> "WARNING: bead bd-XXX has no spec linkage. Update with: `bd update bd-XXX --notes 'Spec source: openspec/...'`" diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index decfc71..3841ca5 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -23,55 +23,95 @@ npm install -g @fission-ai/openspec@latest cd my-project-name ``` -This copies the template, initializes git, and sets up beads tracking in one step. +`setup.sh` copies the template, removes the old `.beads/` database, runs `bd init` and `bd hooks install` to create a clean fresh database, and initializes git. + +### Verify clean state after setup + +After `setup.sh` (or after any `git clone` / copy of an existing project), verify the beads database is clean before starting work: + +```bash +bd list --json # should return empty or only expected issues +bd ready --json # should return only issues you intend to work on +``` + +If you see unexpected issues (e.g. leftover issues from a previous project), your `.beads/` was not reset. Fix it: + +```bash +rm -rf .beads +bd init +bd hooks install +``` + +Do NOT trust `.beads.bak` or backup files — delete them along with `.beads/` when resetting. ### Manual setup ```bash cp -r project-template my-project-name cd my-project-name -rm -rf .git +rm -rf .git .beads git init bd init bd hooks install # Auto-syncs JSONL on commit/pull cp .env.example .env # Edit with your values ``` -### Then start Claude Code +--- + +## The Spec-First Workflow + +OpenSpec artifacts in `openspec/` are the **authoritative source of truth** for what to build. Beads issues are the execution queue derived from those specs. `docs/SPEC.md` is a human-readable summary, not the spec itself. + +The correct order is: -```bash -claude -> /brain-dump ``` +1. Spec (openspec/specs/ or openspec/changes/) +2. Beads issues linked to spec artifacts +3. Code implementation +``` + +If you find yourself creating beads issues or writing code without a corresponding OpenSpec artifact, stop and create the spec first. -Share your project idea. Claude will populate `openspec/project.md`, create feature specs in `openspec/specs/`, fill out project docs, and create beads issues linked to each spec. +--- -## Daily Workflow +## Session Start: Daily Workflow ``` 1. CHECK bd list --json / bd ready --json -2. START bd create "feat: description" -p 1 --json - bd update --status in_progress -3. WORK claude (AI-assisted development) -4. CHECKPOINT git add [files] && git commit -m "checkpoint: msg (bd-xxx)" - bd sync -5. TEST npm test -6. FINISH bd close --reason "Completed" --json +2. SPEC ls openspec/changes/ openspec/specs/ (must exist before step 3) +3. START bd update --status in_progress + bd update --notes "Spec source: openspec/..." +4. WORK claude (AI-assisted development) +5. CHECKPOINT git add [files] && git commit -m "type(scope): msg (bd-xxx)" + git push && bd sync +6. TEST npm test +7. FINISH bd close --reason "Completed" --json bd sync && git push ``` +--- + ## Slash Commands (in Claude Code) | Command | Purpose | |---------|---------| -| `/start-bead` | Create/pick a beads issue and start work | -| `/complete-bead` | Run tests, commit, close issue, sync | -| `/checkpoint` | Stage, commit, sync current progress | -| `/status` | Show issues, git state, ready tasks | -| `/plan` | Plan before implementing (waits for approval) | +| `/brain-dump` | Turn unstructured ideas into OpenSpec artifacts, docs, and beads issues | +| `/start-bead` | Create/pick a beads issue (gates on existing OpenSpec artifact for non-trivial work) | +| `/complete-bead` | Run tests, verify spec linkage, commit, close issue, sync, push | +| `/checkpoint` | Stage, commit, push, sync current progress | +| `/status` | Show beads state, git state, OpenSpec artifacts, and spec linkage | +| `/plan` | Plan before implementing — requires spec artifact; waits for approval | | `/tdd` | Test-driven development cycle | | `/code-review` | Security and quality review | -| `/brain-dump` | Turn unstructured ideas into docs | + +### Brain dump: what it creates + +`/brain-dump` produces: +1. **OpenSpec artifacts** (primary): `openspec/changes//` or `openspec/specs/.md` — these are the authoritative spec +2. **Docs summary** (secondary): `docs/SPEC.md`, `docs/DECISIONS.md`, updated `CLAUDE.md` and `README.md` +3. **Beads issues**: linked to spec artifacts with `Spec source:` notes + +--- ## Beads Commands Reference @@ -86,7 +126,9 @@ Share your project idea. Claude will populate `openspec/project.md`, create feat | `bd update --notes "msg"` | Add notes to issue | | `bd show --json` | Show issue details | -**Never use `bd edit`** — it opens an interactive editor. Use `bd update` with flags. +**Never use `bd edit`** — it opens an interactive editor. Use `bd update` with flags instead. + +--- ## Token Efficiency Tips @@ -95,9 +137,13 @@ Share your project idea. Claude will populate `openspec/project.md`, create feat - Break large tasks into steps - Use `@file` syntax in Claude Code to reference files +--- + ## Documentation - `CLAUDE.md` — Agent instructions (auto-loaded) -- `docs/SPEC.md` — Project specification +- `docs/SPEC.md` — Human-readable project summary (not the implementation spec) - `docs/DECISIONS.md` — Architecture decisions -- `openspec/specs/` — Feature specifications +- `openspec/specs/` — Feature specifications (authoritative) +- `openspec/changes/` — Change proposals (authoritative for active changes) +- `openspec/AGENTS.md` — How AI agents should work with OpenSpec + Beads diff --git a/README.md b/README.md index 6934e70..5d45b51 100644 --- a/README.md +++ b/README.md @@ -36,9 +36,7 @@ claude > /brain-dump ``` -The `/brain-dump` command walks you through describing your project. Claude will populate `openspec/project.md`, create feature specs, fill out docs, and create beads issues for each piece of work. - -> Optional: if you prefer the native OpenSpec workflow, run `openspec update` and use `/opsx:propose` for spec-first change proposals. +The `/brain-dump` command walks you through describing your project. Claude will create OpenSpec artifacts in `openspec/specs/` or `openspec/changes/` (the authoritative spec), fill out summary docs, and create beads issues linked to each spec artifact. ### 3. Start building @@ -102,11 +100,18 @@ Hooks automatically warn you if you try to edit code or commit without an active ## Customising the Template -After running `setup.sh`, make it yours: +After running `setup.sh`, verify clean beads state first: + +```bash +bd list --json # should be empty +bd ready --json # should be empty +``` + +Then make it yours: - **CLAUDE.md** -- Update the project overview, stack, and commands sections -- **docs/SPEC.md** -- Fill in your project specification (or let `/brain-dump` do it) -- **openspec/project.md** -- Set your project identity, tech stack, and constraints +- **openspec/specs/** -- Create your feature specs here (authoritative source for implementation) +- **docs/SPEC.md** -- High-level human-readable summary (not the implementation spec) - **.claude/rules/** -- Adjust coding style, security, or testing rules to match your preferences - **.env.example** -- Add your project's environment variables @@ -117,8 +122,10 @@ If you prefer not to use `setup.sh`: ```bash cp -r project-template my-project cd my-project -rm -rf .git .beads setup.sh +rm -rf .git .beads .beads.bak setup.sh git init bd init && bd hooks install cp .env.example .env -``` \ No newline at end of file +``` + +Always remove `.beads/` and any backup files when starting from a copy — they contain state from the source project, not yours. \ No newline at end of file From 81944074bb8acd2c019005c4e14fc1da8b3a2f20 Mon Sep 17 00:00:00 2001 From: richards-bot Date: Thu, 23 Apr 2026 23:07:26 +0100 Subject: [PATCH 2/2] docs(workflow): remove stale bd sync guidance --- .claude/commands/checkpoint.md | 4 ++-- .claude/commands/complete-bead.md | 2 +- .claude/hooks.json | 6 +++--- .claude/rules/agent-behavior.md | 6 +++--- AGENTS.md | 2 +- CLAUDE.md | 12 ++++++------ GETTING-STARTED.md | 11 ++++++----- README.md | 2 +- 8 files changed, 23 insertions(+), 22 deletions(-) diff --git a/.claude/commands/checkpoint.md b/.claude/commands/checkpoint.md index eb22edc..b5d7c60 100644 --- a/.claude/commands/checkpoint.md +++ b/.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. diff --git a/.claude/commands/complete-bead.md b/.claude/commands/complete-bead.md index 9213c18..90f8c69 100644 --- a/.claude/commands/complete-bead.md +++ b/.claude/commands/complete-bead.md @@ -49,7 +49,7 @@ Stage specific files (NOT `git add -A`): git add [specific files] git commit -m "type(scope): description (bd-xxx)" bd close [id] --reason "Completed" --json -bd sync +bd list --json --all git push ``` diff --git a/.claude/hooks.json b/.claude/hooks.json index 2fcfe2f..3043564 100644 --- a/.claude/hooks.json +++ b/.claude/hooks.json @@ -27,7 +27,7 @@ "hooks": [ { "type": "command", - "command": "echo '[Hook] Reminder: Run bd sync before pushing. Run /code-review if needed.'" + "command": "echo '[Hook] Reminder: beads auto-syncs via Dolt. Before pushing, verify issue state with bd list --json --all if you touched tracker data. Run /code-review if needed.'" } ], "description": "Reminder to sync beads before push" @@ -61,10 +61,10 @@ "hooks": [ { "type": "command", - "command": "if command -v bd >/dev/null 2>&1 && [ -d .beads ]; then echo '[Hook] Reminder: Run bd sync if you made issue changes this session.' >&2; fi" + "command": "if command -v bd >/dev/null 2>&1 && [ -d .beads ]; then echo '[Hook] Reminder: beads auto-syncs via Dolt. If you changed issues, verify with bd list --json --all or bd vc status.' >&2; fi" } ], - "description": "Remind to bd sync at session end" + "description": "Remind to verify beads state at session end" } ] } diff --git a/.claude/rules/agent-behavior.md b/.claude/rules/agent-behavior.md index f7d8c00..92e436d 100644 --- a/.claude/rules/agent-behavior.md +++ b/.claude/rules/agent-behavior.md @@ -54,14 +54,14 @@ Every code change requires a tracked beads issue. ### During work - **Commit AND push after every meaningful change** — a completed function, a passing test, a config update. Small, frequent commits beat one large commit at the end. - Commit with issue ID: `git commit -m "type(scope): description (bd-xxx)"` then immediately `git push` -- `bd sync` after issue changes +- Beads auto-syncs via Dolt; use `bd list --json --all` or `bd vc status` when you need confirmation after issue changes - Use `bd update --notes "context"` to record decisions - If you've edited 3+ files without committing and pushing, stop and do it now. ### Session end 1. `bd close --reason "Completed" --json` (if done) -2. `bd sync` -3. `git push` (work is NOT done until pushed) +2. `git push` (work is NOT done until pushed) +3. If you touched tracker state and want confirmation, run `bd list --json --all` or `bd vc status` ### Forbidden - NEVER use `bd edit` (interactive editor — agents cannot use it) diff --git a/AGENTS.md b/AGENTS.md index 7241a59..253b9db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ This file exists for compatibility with tools that look for AGENTS.md. 4. **PUSH TO REMOTE** - This is MANDATORY: ```bash git pull --rebase - bd sync + bd list --json --all git push git status # MUST show "up to date with origin" ``` diff --git a/CLAUDE.md b/CLAUDE.md index 9205282..ed80e21 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,20 +59,20 @@ openspec/specs/ # Feature specifications - **Commit after every meaningful change** — don't batch all changes into one commit at the end - Commit with issue ID: `git commit -m "type(scope): description (bd-xxx)"` -- Sync periodically: `bd sync` +- Verify issue state when needed: `bd list --json --all` ### When done 1. Close the issue: `bd close --reason "Completed" --json` -2. Sync: `bd sync` -3. Run tests before finishing +2. Run tests before finishing +3. Verify tracker state if needed: `bd list --json --all` ### Critical rules - NEVER use `bd edit` (interactive — agents cannot use it) - Use `bd update --title/--description/--notes` instead - Always use `--json` flag when creating/querying for structured output -- Run `bd sync` after making issue changes +- Beads auto-syncs via Dolt; verify with `bd list --json --all` or `bd vc status` when you need confirmation - Include issue ID `(bd-xxx)` in commit messages Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` @@ -84,7 +84,7 @@ Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` 3. Implement one thin vertical slice with outside-in tests 4. Run verification (`test`, `lint`, `typecheck` where available) 5. Checkpoint summary for human approval at phase boundary -6. Commit with `(bd-xxx)`, sync beads, continue or close +6. Commit with `(bd-xxx)`, verify tracker state if needed, continue or close ## Git @@ -103,7 +103,7 @@ Branch naming: `feature/*`, `fix/*` from `main` - Run tests before marking work complete - Update `docs/DECISIONS.md` for architectural changes - Keep bead notes linked to spec paths (`Spec source: openspec/...`) -- Run `bd sync` before ending a session +- Prefer `bd list --json --all` / `bd vc status` if you need to confirm tracker state before ending a session ## Context Files diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index 3841ca5..cb57ab9 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -83,10 +83,10 @@ If you find yourself creating beads issues or writing code without a correspondi bd update --notes "Spec source: openspec/..." 4. WORK claude (AI-assisted development) 5. CHECKPOINT git add [files] && git commit -m "type(scope): msg (bd-xxx)" - git push && bd sync + git push 6. TEST npm test 7. FINISH bd close --reason "Completed" --json - bd sync && git push + bd list --json --all && git push ``` --- @@ -97,8 +97,8 @@ If you find yourself creating beads issues or writing code without a correspondi |---------|---------| | `/brain-dump` | Turn unstructured ideas into OpenSpec artifacts, docs, and beads issues | | `/start-bead` | Create/pick a beads issue (gates on existing OpenSpec artifact for non-trivial work) | -| `/complete-bead` | Run tests, verify spec linkage, commit, close issue, sync, push | -| `/checkpoint` | Stage, commit, push, sync current progress | +| `/complete-bead` | Run tests, verify spec linkage, commit, close issue, verify tracker state, push | +| `/checkpoint` | Stage, commit, push, optionally verify tracker state | | `/status` | Show beads state, git state, OpenSpec artifacts, and spec linkage | | `/plan` | Plan before implementing — requires spec artifact; waits for approval | | `/tdd` | Test-driven development cycle | @@ -122,7 +122,8 @@ If you find yourself creating beads issues or writing code without a correspondi | `bd close --reason "msg" --json` | Close issue | | `bd list --json` | List all issues | | `bd ready --json` | Show unblocked issues | -| `bd sync` | Sync database with git | +| `bd list --json --all` | Verify tracker state including closed issues | +| `bd vc status` | Show Dolt/beads working state when you need confirmation | | `bd update --notes "msg"` | Add notes to issue | | `bd show --json` | Show issue details | diff --git a/README.md b/README.md index 5d45b51..8e83878 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ The template enforces a simple loop: 1. **Pick work** -- `bd ready` shows unblocked issues, or create one with `bd create` 2. **Start** -- `bd update --status in_progress` 3. **Build** -- Write code with Claude. Commit frequently with `(bd-xxx)` in the message. -4. **Finish** -- `bd close `, run tests, `bd sync`, `git push` +4. **Finish** -- `bd close `, run tests, optionally verify with `bd list --json --all`, then `git push` Hooks automatically warn you if you try to edit code or commit without an active issue.