beads

name	beads
description	Manage plan tasks using the beads distributed, git-backed graph issue tracker. Supports creating, updating, closing tasks, managing dependencies, and syncing with git.

Beads Task Management

This skill enables AI-powered task management using the beads (bd) distributed issue tracker. Beads provides persistent, structured memory for coding agents with dependency-aware task graphs.

When to Use This Skill

Use this skill when you need to:

• Create or manage tasks for a development plan
• Track work items with priorities and dependencies
• View ready tasks (tasks with no open blockers)
• Update task status during implementation
• Close completed tasks
• Create epics with sub-tasks
• Sync task state with git

Prerequisites

• beads CLI (bd) must be installed globally
• Project must be initialized with bd init
• Git repository (beads uses git as its database backend)

Core Commands

Viewing Tasks

# List tasks ready to work on (no open blockers)
bd ready --json

# List all open tasks
bd list --json

# Show task details
bd show <id> --json

# Search tasks by text
bd search "keyword" --json

# View database status and statistics
bd status --json

Creating Tasks

# Create a P0 (highest priority) task
bd create "Task title" -p 0 --json

# Create with priority and type
bd create "Bug fix" -p 1 -t bug --json

# Create with detailed description
bd create "Feature name" -p 2 -t feature --json

# Quick capture (returns only ID)
bd q "Quick task" -p 1

Updating Tasks

IMPORTANT: DO NOT use bd edit - it opens an interactive editor which AI agents cannot use.

# Update task description
bd update <id> --description "new description"

# Update task title
bd update <id> --title "new title"

# Update design notes
bd update <id> --design "design notes"

# Add notes
bd update <id> --notes "additional notes"

# Set acceptance criteria
bd update <id> --acceptance "acceptance criteria"

# Set status to in progress
bd update <id> --status in_progress

Managing Dependencies

# Add dependency (child is blocked by parent)
bd dep add <child> <parent>

# Remove dependency
bd dep rm <child> <parent>

# List dependencies for a task
bd dep list <id> --json

Closing Tasks

# Close a single task
bd close <id> --reason "Completed" --json

# Close multiple tasks
bd close <id1> <id2> --reason "Completed" --json

# Reopen a closed task
bd reopen <id>

Hierarchical Tasks (Epics)

Beads supports hierarchical IDs for epics:

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

# List children of a parent task
bd children <parent-id> --json

# Create epic structure
bd create "Epic: Major feature" -p 1 -t epic --json

Syncing with Git

# Force immediate sync (export, commit, pull, push)
bd sync

# Check for issues with bd doctor
bd doctor --json

Task Workflow

Starting a Work Session

1. Check ready tasks:

   bd ready --json
   

2. Pick a task and mark in progress:

   bd update <id> --status in_progress
   

3. View task details:

   bd show <id> --json
   

During Implementation

1. Create sub-tasks if needed:

   bd create "Sub-task description" -p 1 --json
   bd dep add <child> <parent>
   

2. Update notes as you go:

   bd update <id> --notes "Implementation notes..."
   

Completing Work

1. Close finished tasks:

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

2. Sync to git:

   bd sync
   

Landing the Plane

When ending a work session, complete ALL steps:

1. File beads issues for remaining work:

   bd create "Follow-up task" -p 2 --json
   

2. Close finished work:

   bd close <finished-ids> --reason "Completed" --json
   

3. Sync and push:

   bd sync
   git push
   

4. Choose next work:

   bd ready --json
   

Priority Levels

• P0: Critical - must be done immediately
• P1: High - should be done soon
• P2: Medium - normal priority
• P3: Low - nice to have
• P4: Backlog - future consideration

Task Types

Common types: task, bug, feature, epic, chore, documentation

Best Practices

1. Use JSON output - Always use --json flag for machine-readable output
2. Sync frequently - Run bd sync after making changes
3. Include context - Add descriptions and notes for future reference
4. Track dependencies - Use bd dep add to show what blocks what
5. Close with reasons - Include why tasks were closed
6. Commit message convention - Include issue ID: git commit -m "Fix bug (bd-abc)"

Commit Message Convention

When committing work for an issue, include the issue ID in parentheses:

git commit -m "Add retry logic for database locks (bd-xyz)"

This enables bd doctor to detect orphaned issues.

Common Patterns

Pattern: Create and Track a Bug Fix

# Create bug task
bd create "Fix login validation error" -p 1 -t bug --json

# Mark in progress
bd update bd-xxx --status in_progress

# ... do the work ...

# Close when done
bd close bd-xxx --reason "Fixed validation logic" --json
bd sync

Pattern: Create Epic with Sub-tasks

# Create epic
bd create "Epic: User profile redesign" -p 2 -t epic --json

# Create sub-tasks
bd create "Design new profile layout" -p 2 -t task --json
bd create "Implement profile header" -p 2 -t task --json

# Link dependencies
bd dep add <subtask1> <epic>
bd dep add <subtask2> <epic>

Pattern: Check What's Ready

# See tasks ready to work on
bd ready --json

# Get count of open issues
bd count --json

Limitations

• bd edit opens an interactive editor - use bd update with flags instead
• Beads requires git for persistence
• Task IDs are hash-based (e.g., bd-a1b2)