bootstrap-beads

A Claude Code skill that installs a complete spec-driven development methodology into any project. One command sets up task tracking, requirements management, guard hooks, quality gates, and a structured implementation workflow.

What This Is

When you work with Claude Code on a real project, you quickly discover that:

• Claude loses track of what it was working on between sessions
• It will manually edit spec files when it should use tooling
• It will merge PRs without code review if you don't stop it
• It has no sense of "what should I work on next?"
• Implementation drifts from requirements with no way to catch it

This skill installs a methodology layer that solves all of these problems. It was battle-tested on a production AI coaching product (2,345+ tests, 25 capability specs, 200+ implemented requirements) and then extracted into this portable package.

What Gets Installed

Running /bootstrap-beads in any repo installs:

1. Beads — Task Tracking

Beads is an AI-native issue tracker. Unlike GitHub Issues or Linear, it's designed to be used by the AI agent during development — not just about the AI's work.

What it provides:

• bd ready — shows the next actionable tasks (no blockers)
• bd create — create tasks with descriptions and dependencies
• bd update <id> --claim — claim a task (assign + set in_progress atomically)
• bd close / bd note — close tasks and record what was done
• bd dep — set task dependencies so bd ready only shows unblocked work

How it's used:

• A session-start hook runs bd ready --limit 10 at the beginning of every Claude session, so the agent always knows what to work on
• When the agent discovers new work during implementation, it creates Beads tasks instead of forgetting or silently changing scope
• When work is done, it closes the task with a note explaining what was accomplished

2. OpenSpec — Requirements Management

OpenSpec is a spec-driven development system. Requirements live in versioned spec files, and all changes go through a structured workflow.

The four-step workflow:

Command	Purpose
/opsx:explore	Think through ideas, investigate problems, clarify requirements. No code writing — pure thinking.
/opsx:propose	Create a change proposal with: proposal.md (what & why), design.md (how), tasks.md (implementation steps). Automatically creates a Beads task.
/opsx:apply	Implement tasks from a change, one by one, with TDD. Pauses on ambiguity.
/opsx:archive	Move completed change to archive, optionally sync delta specs back to main specs. Automatically closes the Beads task.

Spec format:

• ## Purpose section describing the capability
• ### Requirement: headers with SHALL/MUST language
• #### Scenario: blocks required, using WHEN/THEN/AND to describe expected behavior
• No test-prescriptive scenario content (SQL, selectors, assertions, implementation details)

The OpenSpec ↔ Beads bridge:

• /opsx:propose creates a Beads task with summary and definition of done
• /opsx:archive closes the corresponding Beads task
• Both degrade gracefully if bd is not installed

3. Guard Hooks — Automated Safety

Three PreToolUse hooks prevent common agent mistakes:

Hook	Trigger	What It Does
OpenSpec guard	Writing/editing files under openspec/	Warns the agent to use CLI tooling instead of manual edits
Push guard	Running git push	Reminds the agent to request @copilot review + spawn /codex:review
Merge guard	Running gh pr merge	Blocks merge until both Copilot and Codex reviews are confirmed

These hooks are implemented as shell commands in .claude/settings.json and require jq for JSON parsing. They degrade gracefully — if jq is missing, they do nothing rather than block.

4. Quality Gates — Structured Review

Four gates that every OpenSpec change passes through:

Gate	When	What
Architecture Review	Before writing code	Spawn a Plan agent to review the design against existing architecture. Check data flows, isolation, dead code, integration points.
Implementation with Tests	During coding	TDD or test-with. Every module, every endpoint. Run tests after each phase.
Code Review	After implementation	Check for data leaks, dead code, silent failures, SQL injection, missing encryption.
Spec Reconciliation	After archiving	Update spec checkboxes, note new requirements, add "Last reconciled" timestamp.

5. Implementation Workflow — Per-Phase Checklist

A structured workflow for implementing changes:

Before Starting:
  bd ready → bd update <id> --claim → git checkout -b feat/<name> → Gate 1

Per Phase:
  1. Plan (assess complexity, spawn worktree agents for complex tasks)
  2. Implement (TDD: failing test → implement → verify)
  3. CI Gate (build + format + test)
  4. Commit & Push (open or update PR)
  5. Reviews (MANDATORY: @copilot + /codex:review after every push)
  6. Check & Fix Reviews (before starting next phase)

After All Phases:
  Final reviews → fix all findings → full CI → STOP (user merges) →
    after merge: archive OpenSpec change → reconcile specs → bd close

6. CLAUDE.md Methodology Sections

Persistent instructions appended to the project's CLAUDE.md that survive across sessions. Covers:

• Verification Rule (never claim something works without verifying)
• Quality Gates (the four gates described above)
• OpenSpec Workflow (the four-step workflow)
• Spec Governance (format rules, process rules, anti-patterns)
• Worktree and Branch Rules (named branches, cleanup)
• Beads Coordination (daily workflow commands)
• Implementation Workflow (the full per-phase checklist)

Prerequisites

Tool	Required	Install
bd (Beads CLI)	Yes	brew install qwibitai/tap/beads
openspec CLI	Yes	npm install -g openspec
jq	Yes	brew install jq / apt-get install jq
gh (GitHub CLI)	Yes	brew install gh
Codex CLI	Optional	For /codex:review background reviews
Playwright	Optional	For headless UI verification

Installation

As a Global Skill (Recommended)

Copy or symlink this directory to your global Claude Code skills:

# Copy
cp -r bootstrap-beads-skill ~/.claude/skills/bootstrap-beads

# Or symlink
ln -s /path/to/bootstrap-beads-skill ~/.claude/skills/bootstrap-beads

Then in any project:

/bootstrap-beads

As a Project Skill

Copy this directory into a project's .claude/skills/:

cp -r bootstrap-beads-skill my-project/.claude/skills/bootstrap-beads

Manual Installation

If you don't want the interactive skill, you can install each piece manually:

1. bd init --quiet — initialize Beads
2. openspec init — initialize OpenSpec
3. Copy templates/session-start.sh → .claude/hooks/session-start.sh (make executable)
4. Merge hooks from SKILL.md Step 5 into .claude/settings.json
5. Copy templates/commands/opsx/*.md → .claude/commands/opsx/
6. Append templates/methodology.md to your CLAUDE.md

File Manifest

bootstrap-beads-skill/
├── SKILL.md                           # Main orchestration — the interactive installer
├── README.md                          # This file
└── templates/
    ├── session-start.sh               # Beads session-start hook script
    ├── methodology.md                 # CLAUDE.md sections to append
    └── commands/
        └── opsx/
            ├── propose.md             # /opsx:propose slash command
            ├── apply.md               # /opsx:apply slash command
            ├── archive.md             # /opsx:archive slash command
            └── explore.md             # /opsx:explore slash command

What each file does

File	Installed to	Purpose
SKILL.md	.claude/skills/bootstrap-beads/ or ~/.claude/skills/bootstrap-beads/	Interactive installer that orchestrates all steps
templates/session-start.sh	.claude/hooks/session-start.sh	Runs bd ready --limit 10 at session start
templates/methodology.md	Appended to CLAUDE.md	Quality gates, workflow, governance rules
templates/commands/opsx/propose.md	.claude/commands/opsx/propose.md	Creates change proposals with artifacts + Beads task
templates/commands/opsx/apply.md	.claude/commands/opsx/apply.md	Implements tasks from a change (TDD loop)
templates/commands/opsx/archive.md	.claude/commands/opsx/archive.md	Archives completed changes + closes Beads task
templates/commands/opsx/explore.md	.claude/commands/opsx/explore.md	Free-form thinking and investigation mode

The Methodology

This section explains the why behind each piece, for teams evaluating whether to adopt it.

Mental Model

Two systems, one bridge:

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   OpenSpec                          Beads                       │
│   ─────────                         ─────                       │
│   "What should this                 "What should I              │
│    change do?"                       work on next?"             │
│                                                                 │
│   • Specs (requirements)            • Tasks (actionable work)   │
│   • Proposals (what & why)          • Dependencies (ordering)   │
│   • Designs (how)                   • Assignments (who)         │
│   • Tasks (implementation steps)    • Notes (progress)          │
│   • Archive (history)               • Ready queue (priorities)  │
│                                                                 │
│              ┌──────────────────────┐                           │
│              │      Bridge          │                           │
│              │                      │                           │
│              │  propose → bd create │                           │
│              │  archive → bd close  │                           │
│              └──────────────────────┘                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

OpenSpec tracks intent: what the system should do, why a change is being made, how it should be designed. It's the source of truth for requirements.

Beads tracks execution: what needs to happen next, what's blocked, what's done. It's the source of truth for work state.

The bridge connects them: proposing a change creates a task; archiving a change closes the task. Both degrade gracefully if the other system isn't installed.

Why Guard Hooks?

Without guards, Claude Code agents will:

1. Manually edit spec files — breaking the format, introducing test-prescriptive content (SQL queries, implementation details) in scenario blocks, and causing cascading quality problems. The OpenSpec guard catches this.

2. Merge PRs without review — Claude is eager to complete work. Without the merge guard, it will merge the moment CI passes, skipping code review entirely. The merge guard forces confirmation that both automated reviews ran.

3. Push without requesting reviews — The push guard is a reminder, not a blocker. It ensures the agent remembers to spawn reviews after every push, so review feedback arrives while the next phase is in progress.

These hooks were born from real incidents:

• The spec corruption incident (2026-04-08): An agent manually rewrote 25 specs with test-prescriptive WHEN/THEN/AND content, causing another agent to write 37 brute-force tests (none worked on the first try). The OpenSpec guard prevents manual spec editing.
• Silent merges: Multiple PRs were merged without any code review, letting bugs reach main. The merge guard prevents this.

Why Quality Gates?

Gates catch problems at the cheapest point to fix them:

• Gate 1 (Architecture) catches design flaws before any code is written. A 5-minute review saves hours of rework.
• Gate 2 (Tests) catches implementation bugs immediately, not after the full change is integrated.
• Gate 3 (Code Review) catches security issues, dead code, and integration gaps that tests miss.
• Gate 4 (Spec Reconciliation) keeps specs and code in sync, preventing drift that compounds over time.

Why Per-Phase Workflow?

The implementation workflow is structured around phases (not tasks) because:

1. Reviews run in background — spawning reviews after each phase means feedback arrives while you're working on the next phase. Zero time cost.
2. CI catches regressions early — running CI after each phase means you never accumulate a large pile of broken changes.
3. Worktree isolation for complex work — spawning worktree agents for complex tasks keeps the main branch clean and allows parallel work.
4. Named branches prevent orphaned work — requiring named branches (not anonymous worktree-agent-* branches) means work can always be found and continued.

Why Session-Start Hook?

Claude Code sessions start with a blank context. The session-start hook solves this by:

1. Running bd ready --limit 10 to show what needs work
2. Giving the agent immediate context about priorities
3. Preventing the "what should I do?" problem that wastes the first few minutes of every session

Customization

After installation, you can customize any piece:

Adjust the CI command

The methodology template references a generic CI gate. Edit the "CI Gate" section in CLAUDE.md to match your project:

#### 3. CI Gate

After each task, run the full local CI chain:

    npm run build && npm run lint && npm test

Add project-specific development rules

Add your rules above the methodology sections in CLAUDE.md:

## Development Rules

1. TypeScript only
2. Do NOT modify core framework files — add extensions instead
3. camelCase for API responses

## Verification Rule
...

Disable specific guards

Edit .claude/settings.json to remove hooks you don't need. For example, to remove the Codex review requirement from the push guard, edit the command to only mention @copilot.

Change task seeding sources

The interactive seeding step (Step 8 in SKILL.md) can pull from any source. If you use Linear instead of GitHub Issues, modify the detection commands.

Origin

This methodology was developed and refined on CoachClaw, an AI coaching agent with:

• 2,345+ tests
• 25 OpenSpec capability specs
• 200+ implemented requirements
• Full data architecture with PII handling, encryption at rest, per-client isolation
• Production deployment on Fly.io

The methodology emerged from real incidents:

• A spec corruption event where an agent manually edited all 25 specs, introducing test syntax that caused cascading failures
• 47 stale worktrees left behind by agents that didn't follow branch naming conventions
• Silent PR merges that bypassed code review entirely
• Integration gaps where unit tests passed but real code paths were broken

Each piece of the methodology exists because its absence caused a real problem. Nothing is theoretical.

Troubleshooting

"bd: command not found"

Beads isn't installed. Install it:

brew install qwibitai/tap/beads

Or on Linux without Homebrew, see the Beads releases.

"openspec: command not found"

OpenSpec isn't installed. Install it:

npm install -g openspec

Guard hooks not firing

Check that:

1. jq is installed (which jq)
2. .claude/settings.json exists and has valid JSON
3. The hooks are under hooks.PreToolUse (not a different key)

Session-start hook not running

Check that:

1. .claude/hooks/session-start.sh exists and is executable (chmod +x)
2. bd is in PATH (the hook tries Linuxbrew as a fallback)

"I already have a CLAUDE.md"

The installer appends methodology sections — it doesn't overwrite. It checks for ## Quality Gates as a sentinel to avoid duplicating. If you want to re-install, remove the methodology sections first.

License

MIT