beads-schema

Beads CLI (bd) reference from Beads. Use this when creating, editing, or managing beads issues.

When to Use

Invoke /beads-schema before working with bd commands. Invoke /beads-schema validate to check that bd is initialized and working.

Core Concepts

Beads is a git-backed issue tracker. Issues are stored as JSONL in .beads/ and sync via git. The CLI is bd.

Conversion from Plans

Beads are typically created by /beads-converter from architectural plans (.claude/plans/*-plan.md). The pipeline:

/plan-creator (or /bug-plan-creator, /code-quality-plan-creator)
    ↓ writes
.claude/plans/{slug}-{hash5}-plan.md
    ↓ consumed by
/beads-converter <plan-path>
    ↓ runs
bd create (epic) + bd create (child tasks) + bd dep add
    ↓ stored in
.beads/beads.jsonl
    ↓ executed by
/beads-loop or /beads-swarm or ralph-tui

How plan sections map to bead fields:

Each bead's description must be 100% self-contained — the executor agent receives only the bead description, never the source plan. All code, requirements, and verification commands are copied verbatim from the plan into the bead.

Issue Types (core)

Statuses

Priority (0-4, lower = higher)

Supports both --priority 1 and --priority P1 formats.

Hierarchical IDs

Beads supports parent-child hierarchies via dotted IDs:

• bd-a3f8 (Epic)
• bd-a3f8.1 (Task under epic)
• bd-a3f8.1.1 (Sub-task)

Use --parent <epic-id> when creating to auto-generate child IDs.

Essential Commands

Create

# Create a task (default type)
bd create "Fix login bug" -p 1

# Create with type and parent
bd create "Add toggle switch" --type task --parent bd-a3f8

# Create epic
bd create "User Authentication" --type epic

# Full flags
bd create "Title" \
  --type task \
  --priority 1 \
  --parent bd-a3f8 \
  --description "Detailed description" \
  --acceptance "Criteria for completion" \
  --labels frontend,auth \
  --deps bd-001,bd-002

Create flags:

Update

# Update status
bd update bd-a3f8 --status in_progress

# Update multiple fields
bd update bd-a3f8 --title "New title" --priority 1 --description "Updated desc"

# Append to notes (vs replace)
bd update bd-a3f8 --append-notes "Additional context"

Do NOT use bd edit — it opens an interactive editor. Use bd update with flags instead.

Close

# Close one or more issues
bd close bd-a3f8 --reason "Completed"
bd close bd-001 bd-002 bd-003 --reason "All done"

Show

bd show bd-a3f8          # Human-readable
bd show bd-a3f8 --json   # JSON output

List

bd list                          # All open issues
bd list --type epic              # Only epics
bd list --parent bd-a3f8         # Children of epic
bd list --status open            # Filter by status
bd list --label frontend         # Filter by label
bd list --json                   # JSON output

Ready

bd ready         # Tasks with no open blockers
bd ready --json  # JSON output

Shows tasks that are open, have all dependencies resolved (closed/cancelled), and are not deferred.

Dependencies

# Add dependency: child depends on parent (child blocked until parent closes)
bd dep add bd-child bd-parent

# Dependency types
bd dep add bd-child bd-parent              # Default: "blocks"
bd dep add bd-child bd-parent --type related  # Non-blocking relation

# Remove dependency
bd dep remove bd-child bd-parent

Dependency types that block readiness:

Non-blocking dependency types: related, discovered-from, replies-to, relates-to, duplicates, supersedes

Labels

bd label add bd-a3f8 frontend
bd label remove bd-a3f8 frontend

Sync

bd sync   # Export to JSONL, commit, pull, import, push

Always run bd sync after making changes to persist them.

Task Selection Order

bd ready selects tasks by:

1. Filter to status: open
2. Filter to tasks with all blocking dependencies resolved (closed/cancelled)
3. Filter out deferred tasks (past defer_until)
4. Sort by priority (P0 first)
5. Return matches

Issue Fields Reference

Core fields (used by essentials commands)

Timestamp fields (auto-managed)

Common Workflows

Create epic with tasks

# 1. Create epic
bd create "User Authentication" --type epic --json
# Returns: bd-a3f8

# 2. Add tasks as children
bd create "Login form" --type task --parent bd-a3f8 -p 1
bd create "Auth API" --type task --parent bd-a3f8 -p 1
bd create "Integration tests" --type task --parent bd-a3f8 -p 2

# 3. Add dependency (tests depend on form + API)
bd dep add bd-a3f8.3 bd-a3f8.1
bd dep add bd-a3f8.3 bd-a3f8.2

# 4. Check ready tasks
bd ready --json

Work on a task

bd update bd-a3f8.1 --status in_progress
# ... do work ...
bd close bd-a3f8.1 --reason "Login form implemented with validation"
bd sync

Instructions

Parse $ARGUMENTS to determine mode.

If $ARGUMENTS is validate:

Check beads is set up and working:

# Check bd is installed
bd version

# Check beads is initialized
ls .beads/

# List all issues
bd list --json

# Check for ready tasks
bd ready --json

Report the beads version, issue count, and any issues.

If $ARGUMENTS is empty:

Output the quick reference:

Beads CLI (bd) Quick Reference

Types: task (default), bug, feature, chore, epic
Statuses: open, in_progress, blocked, deferred, closed
Priority: P0 (critical) → P4 (backlog), default P2

Create:   bd create "Title" --type task -p 1 --parent <epic-id>
Update:   bd update <id> --status in_progress
Close:    bd close <id> --reason "Done"
Ready:    bd ready --json
List:     bd list --parent <epic-id> --json
Deps:     bd dep add <child> <parent>
Sync:     bd sync

Do NOT use "bd edit" (interactive). Use "bd update" with flags.