Bead-Driven Development

Overview

This skill orchestrates existing skills with beads integration. It provides prompt refinements rather than reimplementing functionality:

writing-plans → create plan + beads for major tasks
executing-plans → use subagents + track via beads
investigation → create blocking beads on failure, update plan

Announce at start: "I'm using the bead-driven-development skill to orchestrate planning and execution with persistent tracking."

Prerequisites

This skill requires beads and superpowers plugins. Install them first:

Install beads

# Install beads CLI
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add beads marketplace and install plugin
/plugin marketplace add steveyegge/beads
/plugin install beads

Install superpowers

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Initialize beads in your repo

bd init

Required skills from superpowers:

writing-plans
executing-plans
investigation (or from ~/.claude/skills/)

Unified Workspace Convention

All phases share one workspace: scratch/{YYYY-MM-DD}-plan-{topic}/

scratch/2026-01-18-plan-auth-system/
├── README.md          ← Plan (Phase 1)
├── scripts/           ← Temp scripts (Phase 2)
└── debug/             ← Investigations (Phase 3)
    └── bd-xxx/

Beads provide the commit history. Plan doesn't need to be committed separately.

Phase 1: Planning with Beads

Invoke writing-plans skill with these additions:

"Create plan in unified workspace following investigation pattern: scratch/{YYYY-MM-DD}-plan-{topic}/README.md Example: scratch/2026-01-18-plan-auth-system/README.md

After finalizing the plan, create a bead for each major task:
bd create 'Task 1: Component name' -t task
bd create 'Task 2: Next component' -t task
bd dep add <task-2-id> <task-1-id> --type blocks
Include bead IDs in the plan file for tracking.

Important: Add a section in the plan noting:

Temp scripts go in: scratch/{date}-plan-{topic}/scripts/

Debug investigations go in: scratch/{date}-plan-{topic}/debug/

Beads provide commit history (plan doesn't need to be committed)

Note: TodoWrite will still be used for fine-grained in-session tracking."

Phase 2: Execution with Beads

Invoke executing-plans skill with these additions:

"Before starting each task:

Run bd ready to find next unblocked task

Mark bead in_progress: bd update <id> --status in_progress

Use TodoWrite as normal for fine-grained step tracking within the task.

Workspace: Put any temporary scripts, test outputs, or debugging artifacts in the plan's scratch directory: scratch/{date}-plan-{topic}/scripts/

After each successful task:

Commit with bead ID: git commit -m 'feat: description (bd-xxx)'

Add commit SHA to bead: bd comment <id> 'Commit: <sha>'

Dispatch code-reviewer subagent (per subagent-driven-development two-stage review)

If review passes: bd close <id> --reason 'Implemented and reviewed'

Sync TodoWrite → bead status when marking task complete

Run bd sync every 2-3 completed tasks to persist to git.

On failure → transition to Phase 3 (Failure Recovery)."

Phase 3: Failure Recovery with Beads

When any task fails, invoke investigation skill with these additions:

Step 1: Create blocking debug bead
bd create 'Debug: <issue description>' -t bug
bd dep add <failed-task-id> <debug-bead-id> --type blocks
Step 2: Investigation in plan's scratch directory Create investigation subfolder: scratch/{date}-plan-{topic}/debug/{bead-id}/README.md

Or if separate investigation needed: scratch/{date}-debug-{bead-id}/README.md

Document findings, hypotheses, and tests in the investigation folder.

Step 3: Resolution Copy key findings summary to debug bead:
bd comment <debug-id> 'Resolution: <summary of fix>'
If plan needs updates: edit scratch/{date}-plan-{topic}/README.md and note changes.

If new tasks discovered:
bd create 'New task from investigation' -t task --discovered-from <debug-id>
Step 4: Resume Close debug bead:
bd close <debug-id> --reason 'Resolved: <summary>'
Original task becomes unblocked. Signal: "Plan updated, resume from Task N with bd ready"

Hybrid Tracking Model

Tool	Purpose	Scope
Beads	Major milestones/tasks	Cross-session persistence
TodoWrite	Fine-grained steps	In-session tracking

Sync rule: When TodoWrite marks task complete → close corresponding bead.

Quick Reference

Command	Purpose
`bd ready`	Find next unblocked task
`bd update <id> --status in_progress`	Mark task started
`bd close <id> --reason '...'`	Mark task complete
`bd comment <id> 'message'`	Add context to bead
`bd dep add <id> <blocker> --type blocks`	Add dependency
`bd sync`	Persist to git (every 2-3 tasks)
`bd show <id>`	Get task context

Workflow Summary

User: "execute this plan with beads"
           ↓
[bead-driven-development loads]
           ↓
Phase 1: Invoke writing-plans + beads prompt
  → Creates unified workspace
  → Plan in README.md
  → Creates beads for major tasks
  → Adds blocks dependencies
           ↓
Phase 2: Invoke executing-plans + beads prompt
  → Uses bd ready to pick next task
  → Updates bead status + TodoWrite
  → Commits with bead ID: (bd-xxx)
  → Two-stage code review
  → Close bead after review
  → bd sync every 2-3 tasks
           ↓
(On failure) Phase 3: Invoke investigation + beads prompt
  → Creates blocking debug bead
  → Investigates in workspace: debug/{bead-id}/
  → Copies findings to bead notes
  → Updates README.md when resolved
  → Resumes with bd ready

bead-driven-development