Beads

Beads Task Tracker

You are an expert at using beads for persistent, git-backed task management with dependency tracking.

When To Use

• User says "beads", "ready tasks", "what's next", "next task"
• User needs cross-session task persistence
• User wants dependency tracking between tasks
• Multi-agent coordination is needed
• Before/after handoffs to sync persistent state
• User says "blockers", "blocked by", "dependencies"

Inputs

• Task descriptions and priorities
• Dependency relationships between tasks
• Status updates (open, in_progress, closed)

Outputs

• Persisted tasks in .beads/ directory
• Ready task lists (unblocked work)
• Dependency graphs
• Synced state with git

Why Beads (Not Just TODO.md)

Rule: Use TODO.md for immediate visibility. Use beads for persistent state.

Workflow

1. Session Start

# Pull latest state
bd sync

# See what's ready (no blockers)
bd ready --json

# Pick highest priority task
bd update <id> --status in_progress --json

Update TODO.md with current task for visibility.

2. During Work

Create new tasks discovered during work:

bd create "Task title" -p 1 -t task --json

Add dependencies when tasks block each other:

bd dep add <child-id> <parent-id> --type blocks

Complete tasks:

bd close <id> --reason "Completed" --json

3. Session End

# CRITICAL: Push all changes before ending
bd sync

Create handoff if needed - beads state persists regardless.

Core Commands

Check Ready Tasks

bd ready --json

Returns tasks with no open blockers. Start here each session.

Create Tasks

bd create "Task title" -p 1 -t task --json
bd create "Bug description" -p 0 -t bug --json
bd create "Feature request" -p 2 -t feature --json
bd create "Epic name" -t epic --json

Priority: 0=critical, 1=high, 2=normal, 3=low, 4=backlog

Manage Dependencies

# Child blocked until parent closes
bd dep add <child-id> <parent-id> --type blocks

# View dependency tree
bd dep tree <id>

Update Status

bd update <id> --status in_progress --json
bd update <id> --status open --json
bd close <id> --reason "Completed" --json

View Tasks

bd show <id> --json
bd list --status open --json
bd list --status in_progress --json

Sync (Critical!)

bd sync

Forces immediate export/commit/push. ALWAYS run before session end.

Integration with TODO.md

Keep TODO.md in sync for immediate visibility:

# TODO

## From Beads (bd ready)
- [ ] bd-a1b2: Implement auth endpoint (p1)
- [ ] bd-f4c3: Add login tests (p2)

## Session Tasks
- [ ] Current step: Write login handler

Multi-Agent Coordination

Beads prevents conflicts via hash-based IDs (bd-xxxx format).

Task Claiming

# Agent claims a task
bd update <id> --status in_progress --json
bd sync  # Others see the claim immediately

Parallel Work

# Agent A creates bd-a1b2
# Agent B creates bd-f4c3
# No collision - different hash IDs

Discovery Pattern

# Found sub-task during implementation
bd create "Sub-task" --deps parent:<parent-id> -p 2 --json
bd sync

Agent Handover

# Agent A ending
bd close <id> --reason "Completed auth endpoint"
bd sync

# Agent B starting
bd sync
bd ready --json

Handoff Integration

Before create-handoff

bd sync  # Push all changes

Include in handoff document:

• In-progress tasks
• Ready tasks
• Blocked tasks with blockers

After resume-handoff

bd sync  # Pull latest
bd ready --json  # See available work

Background Agent Tracking

Beads can track background agents across sessions for result retrieval.

New Fields for Background Tasks

When creating tasks that spawn background agents:

# Create task with agent tracking
bd create "Run security audit" -t agent_task --json --meta '{"agent_id": "abc123", "agent_type": "security-auditor", "poll_status": "running"}'

Meta fields for agent tasks:

• agent_id: Background agent/task ID (from Task tool response)
• agent_type: Type of agent spawned (security-auditor, background-worker, etc.)
• poll_status: pending | running | completed | failed
• started_at: ISO timestamp when spawned
• completed_at: ISO timestamp when finished

Agent Task Workflow

# 1. Spawn background agent and record in beads
bd create "Security audit before PR" -t agent_task --json \
  --meta '{"agent_id": "sec_xyz", "agent_type": "security-auditor", "poll_status": "running"}'
# Returns bd-f1a2

# 2. Check agent status (updates poll_status)
bd poll bd-f1a2
# Uses TaskOutput internally, returns: "running" or "completed: [summary]"

# 3. Get full results
bd results bd-f1a2
# Returns full agent output, updates poll_status to "completed"

# 4. Close task with findings
bd close bd-f1a2 --reason "Security audit passed, no issues"

Polling Multiple Agents

# List all running agent tasks
bd list --type agent_task --meta-filter 'poll_status=running' --json

# Poll all running agents
bd poll-all --json
# Returns: [{"id": "bd-f1a2", "status": "completed"}, {"id": "bd-g3h4", "status": "running"}]

Cross-Session Agent Resumption

Agent IDs persist across sessions:

# Session 1: Start long security audit
bd create "Deep security scan" -t agent_task --meta '{"agent_id": "deep_sec_123"}'
bd sync
# Session ends

# Session 2: Check on agent
bd sync
bd poll bd-f1a2  # Agent still running or completed
bd results bd-f1a2  # Get findings

Common Patterns

Breaking Down Work

# Create epic
bd create "User Authentication" -t epic --json
# Returns bd-a1b2

# Create child tasks
bd create "Login endpoint" --deps parent:bd-a1b2 -p 1 --json
bd create "Logout endpoint" --deps parent:bd-a1b2 -p 1 --json
bd create "Password reset" --deps parent:bd-a1b2 -p 2 --json

Tracking Blockers

# Found a blocker
bd create "Need API key from user" -t blocker -p 0 --json
# Returns bd-x1y2

# Link current task as blocked
bd dep add <current-task> bd-x1y2 --type blocks

Initialize in New Project

bd init --stealth  # Keeps .beads/ local to you

Aggressive Persistence (Disconnect-Proof)

NEW in v7.4: Sync state aggressively to survive terminal disconnection.

Sync Triggers (ALWAYS sync on these)

Resilient Workflow

# Start task (sync immediately)
bd update $ID --status in_progress --json
bd sync

# Do work...

# Complete task (sync immediately)
bd close $ID --reason "commit: xyz" --json
bd sync  # Don't wait, sync now!

# If error occurs
bd sync  # Save state before handling error

Recovery After Disconnect

# 1. Pull latest state
bd sync

# 2. See where we left off
bd list --status in_progress --json  # What was in progress?
bd ready --json                       # What's next?

# 3. Check what was completed
bd list --status closed --json | tail -5

# 4. Resume
# If task was in_progress but not complete, continue it
# If task was closed, move to next ready task

Background Auto-Sync

When running in resilient mode, beads syncs automatically:

# Add to your session (done automatically by resilient-executor)
( while true; do sleep 300; bd sync 2>/dev/null || true; done ) &

Anti-Patterns

• Creating beads issues for trivial tasks (use TODO.md instead)
• Forgetting bd sync before session end
• Not using --json flag for structured output
• Creating dependencies on closed issues
• Over-engineering dependency graphs for simple work
• NEW: Waiting to batch syncs (sync immediately after each action)
• NEW: Assuming terminal will stay connected (always use resilient mode)

Beads vs Handoffs

Installation

Beads is optional but required for persistent features:

npm install -g @beads/bd
# or
brew install steveyegge/beads/bd
# or
go install github.com/steveyegge/beads/cmd/bd@latest

Skill Testing Framework

NEW: Test ONE_SHOT skills with scenarios to verify they work correctly.

Test Commands

# Test a specific skill
bd test <skill-name>

# Test all skills
bd test --all

# Run tests with coverage report
bd test --coverage

# List test scenarios
bd test --list

# Run specific test scenario
bd test <skill-name> --scenario <scenario-name>

Test Scenario Format

Each skill can have test scenarios in .claude/skills/<skill-name>/TESTS.md:

# Test Scenarios: <skill-name>

## Scenario 1: Basic Functionality
**Input:** User says "test message"
**Expected:** Skill loads correctly, provides expected output
**Steps:**
1. Verify skill loads from disk
2. Parse frontmatter metadata
3. Return correct triggers
**Status:** PASS | FAIL

## Test Scenarios

```bash
# Test a specific skill
bd test <skill-name>

# Test coverage report
bd test --coverage

# Health score
bd test --health

4. Run bd test --coverage to ensure overall health

Keywords

beads, tasks, ready, dependencies, blockers, persistent, cross-session, bd ready, bd create, bd sync, bd close, bd update, bd dep, multi-agent, bd test, skill testing, test coverage