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

Check ready tasks:

bd ready --json

Pick a task and mark in progress:

bd update <id> --status in_progress

View task details:

bd show <id> --json

During Implementation

Create sub-tasks if needed:

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

Update notes as you go:

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

Completing Work

Close finished tasks:

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

Sync to git:

bd sync

Landing the Plane

When ending a work session, complete ALL steps:

File beads issues for remaining work:

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

Close finished work:

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

Sync and push:

bd sync git push

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

• Use JSON output - Always use --json flag for machine-readable output

• Sync frequently - Run bd sync after making changes

• Include context - Add descriptions and notes for future reference

• Track dependencies - Use bd dep add to show what blocks what

• Close with reasons - Include why tasks were closed

• 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 )