name	beads-bd
description	Use this skill for ALL task, issue, and todo tracking when the project has a `.beads/` directory or uses `bd` commands. This skill MUST be used instead of TodoWrite for any project with beads initialized.

bd (Beads) - Task Tracking for AI Agents

Distributed, git-backed graph issue tracker. Provides persistent memory for complex, multi-session work with dependency awareness.

Setup Commands

bd prime              # Output workflow context (~1-2k tokens) - run at session start
bd onboard            # Show snippet to add to AGENTS.md for new projects

bd prime provides dynamic workflow context. Use it at session start or after context compaction to refresh bd knowledge.

Core Workflow

Session Start

bd prime              # Get workflow context (optional if using hooks)
bd ready              # Show tasks with no open blockers (sorted by priority)
bd show <id>          # Get full context for a task
bd update <id> --status in_progress  # Claim the task

While Working

bd update <id> --notes "COMPLETED: X. IN PROGRESS: Y. BLOCKED BY: Z"

Write notes as if explaining to a future agent with zero conversation context.

Task Completion

bd close <id> --reason "Summary of what was done"
bd ready              # Check what's now unblocked

End of Session

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

Essential Commands

Command	Purpose
`bd prime`	Output workflow context (session start)
`bd ready`	Tasks with no open blockers
`bd create "Title" -p 1`	Create task (priority 0-4, 0=critical)
`bd show <id>`	Full task details + audit trail
`bd update <id> --status in_progress`	Start working
`bd update <id> --notes "Progress"`	Add notes (appends)
`bd close <id> --reason "Done"`	Complete task
`bd dep add <child> <parent>`	parent blocks child
`bd list`	All tasks (supports filters)
`bd blocked`	Tasks with open blockers
`bd sync`	Git sync (export/commit/pull/push)

Task Creation

# Standalone items (no parent required)
bd create "Fix authentication bug" -p 0 --type bug
bd create "Refactor logging" -p 2 --type chore

# Feature with description
bd create "OAuth Support" -p 1 --type feature --description "Add Google, GitHub OAuth"

# Full hierarchy: epic -> feature -> task
bd create "Auth System" -p 0 --type epic                            # Returns: bd-abc
bd create "OAuth Support" -p 1 --type feature --parent bd-abc       # Returns: bd-abc.1
bd create "Add Google provider" -p 2 --type task --parent bd-abc.1  # Returns: bd-abc.1.1

Types: epic, feature, task, bug, chore

Hierarchy (typical parent -> child):

epic -> feature -> task
bug and chore can optionally have epic or feature as parent
All types can exist standalone without a parent

Priorities: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog

Dependencies

bd dep add <child> <parent>   # parent blocks child
bd dep list <id>              # View blockers and dependents
bd dep tree <id>              # View full dependency tree

Dependency types:

blocks: Parent must close before child is ready
parent-child: Hierarchical (epic/feature/task relationships)
discovered-from: Task A led to discovering task B
related: Related but not blocking

bd prevents circular dependencies automatically.

Filtering & Search

bd list --status open         # Only open tasks
bd list --priority 0          # Only P0 (critical)
bd list --type bug            # Only bugs
bd list --label backend       # Only with label
bd search "authentication"    # Text search
bd stats                      # Project metrics

Git Sync

bd stores issues in .beads/issues.jsonl (one line per issue, git-friendly).

bd sync                       # All-in-one: export, commit, pull, push
bd export -o backup.jsonl     # Export only
bd import -i backup.jsonl     # Import only

Auto-sync: bd exports after changes (30s debounce) and imports after git pull.

ID Format

Hash-based IDs prevent collisions across branches/agents:

bd-a1b2 (4 chars for <500 issues)
bd-a1b2.1 (hierarchical child of epic)

Common Patterns

Blocked Work

bd update <id> --status blocked --notes "API returns 503"
bd create "Fix API 503" -p 0 --type bug   # Returns: bd-blocker
bd dep add <id> bd-blocker                # Link dependency
bd ready                                   # Find other ready work

Resume After Compaction

bd ready                      # Find where you left off
bd show <id>                  # Full context in notes field
# Notes contain: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS

Multi-Agent Coordination

bd update <id> --status in_progress --assignee agent-name
bd ready --assignee agent-name  # Query by assignee
bd sync                         # Push changes for other agents

Error Recovery

Error	Solution
`bd: command not found`	Install: `brew install steveyegge/beads/bd` or `npm install -g @beads/bd`
`No .beads database found`	Run `bd init` in git repo root
`Task not found`	Use `bd list` or `bd search` to find correct ID
`Circular dependency`	Restructure: `bd dep list <id>` to view graph
`Database is locked`	`bd daemon --stop && bd daemon --start`

Reference

Full documentation: https://github.com/steveyegge/beads

beads-bd

Install Skill

SKILL.md