Beads Task Tracker

Dependency-aware task management integrated with spec workflows. Tasks are stored in .beads/beads.jsonl and persist across sessions via git.

Overview

Beads enforces implementation order through dependency tracking:

• Dependency-driven execution - bd ready surfaces only unblocked tasks

• Bottom-up enforcement - Dependencies ensure Entity → Repository → Service → Router

• Git-backed persistence - .beads/beads.jsonl tracks all tasks and status

• Spec integration - Commands like /spec:plan auto-create epics with ordered tasks

Core Workflow Commands

Command Purpose Example

bd init

Initialize Beads in project bd init

bd create <name>

Create task or epic bd create "Implement UserEntity" -t task -p 2 -l entity,user

bd ready

Find next unblocked task bd ready --label user --json

bd update <id>

Update task status/fields bd update task-123 --status in_progress

bd close <id>

Mark task complete bd close task-123 --reason "Implemented with tests"

bd list

Show all tasks bd list --json or bd list --label feature

Task Types and Priority

Types (-t flag):

• epic

• Feature or change container

• task

• Implementation work (default)

Priority (-p flag):

• 1

• High (epics)

• 2

• Normal (implementation tasks)

• 3

• Low (nice-to-have)

Labels (-l flag):

• Feature name: user , auth , billing

• Layer: entity , repository , service , router

• Type: feature , change , bug

Dependency Management

Dependencies enforce execution order and identify blocking relationships.

Dependency Commands

Command Purpose Example

bd dep add <task> <blocks>

Task blocks another bd dep add task-1 task-2 --type blocks

bd dep list

Show all dependencies bd dep list --json

bd dep list <id>

Show task dependencies bd dep list task-123

bd dep tree

Visualize dependency tree bd dep tree

Dependency Types

• blocks

• Task must complete before dependent can start

• discovered-from

• Task identified during another task

• related-to

• Informational relationship

Finding Blocked Tasks

Show only blocked tasks

bd list --json | jq '.[] | select(.blocked == true)'

Find tasks blocking a specific task

bd dep list task-123

Task Organization

Epic Structure

Epics contain related tasks for a feature or change:

Create epic

bd create "Feature: User Management" -t epic -p 1 -l feature,user

Create tasks in epic

bd create "Implement UserEntity" -t task -p 2 -l entity,user -e epic-1 bd create "Implement UserRepository" -t task -p 2 -l repository,user -e epic-1

Add dependencies (Repository depends on Entity)

bd dep add task-1 task-2 --type blocks

Status Transitions

Tasks flow through these states:

• pending

• Created, not yet started

• in_progress

• Actively being worked

• done

• Completed successfully

Update status explicitly:

bd update task-123 --status in_progress bd close task-123 # Transitions to done

Spec Command Integration

Spec commands automatically manage Beads for workflow enforcement.

/spec:plan [change]

Creates implementation plan with Beads epic and tasks:

Reads:

• docs/spec/<feature>/spec.md

• Technical design

• docs/spec/<feature>/changes/<change>/design.md

• Change design

Creates:

• docs/spec/<feature>/changes/<change>/plan.json

• Task list with dependencies

• docs/spec/<feature>/changes/<change>/delta.md

• ADDED/MODIFIED/REMOVED

• Beads epic with label <feature>

• Beads tasks ordered by layer dependencies

Dependencies:

• Entity tasks have no dependencies (bottom layer)

• Repository tasks depend on Entity tasks

• Service tasks depend on Repository tasks

• Router tasks depend on Service tasks

/spec:work [feature]

Implements next ready task:

Finds ready task:

bd ready --label <feature> --json # If feature specified bd ready --json # Any feature if not specified

Marks in progress:

bd update <task-id> --status in_progress

After implementation:

bd close <task-id> --reason "Implemented with layer boundary tests"

/spec:status [feature]

Reports progress using Beads data:

Queries tasks:

bd list --label <feature> --json # Feature status bd list --json # All features

Calculates metrics:

• Completion percentage: completed / total * 100

• Ready task count: bd ready --label <feature> | wc -l

• Blocked task identification from dependencies

Reports:

• Total/completed/in-progress/blocked/ready counts

• Next ready tasks

• Dependency blockers

• Recommended next action

/spec:complete

Archives completed work:

Verifies all tasks done:

bd list --label <feature> --json

All tasks must have status: done

After merging delta to spec:

• Beads epic remains (git history)

• Beads tracks completion metrics

• Change folder deleted (git preserves history)

Common Patterns

Pattern: Create Epic and Tasks

1. Create epic

bd create "Feature: User Auth" -t epic -p 1 -l feature,auth

2. Create layer tasks in dependency order

bd create "Implement UserEntity" -t task -p 2 -l entity,auth -e epic-1 bd create "Implement UserRepository" -t task -p 2 -l repository,auth -e epic-1 bd create "Implement AuthService" -t task -p 2 -l service,auth -e epic-1 bd create "Implement auth routes" -t task -p 2 -l router,auth -e epic-1

3. Add bottom-up dependencies

bd dep add task-1 task-2 --type blocks # Entity blocks Repository bd dep add task-2 task-3 --type blocks # Repository blocks Service bd dep add task-3 task-4 --type blocks # Service blocks Router

Pattern: Implementation Work Loop

1. Find next ready task

bd ready --label auth --json

2. Start work

bd update task-1 --status in_progress

3. Implement with tests (Stub→Test→Fix)

... code implementation ...

4. Complete task

bd close task-1 --reason "Entity implemented with validation tests"

5. Repeat

bd ready --label auth --json

Pattern: Check Progress

Feature-specific progress

bd list --label auth --json | jq '{ total: length, done: [.[] | select(.status == "done")] | length, in_progress: [.[] | select(.status == "in_progress")] | length, blocked: [.[] | select(.blocked == true)] | length }'

All features overview

bd list --json | jq 'group_by(.labels[] | select(. == "feature")) | map({feature: .[0].labels[1], tasks: length})'

Pattern: Handle Discovered Work

During implementation, create new tasks for edge cases:

Create new task

bd create "Add email validation edge case" -t task -p 2 -l entity,auth

Link to task where discovered

bd dep add task-5 task-1 --type discovered-from

JSON Output

All commands support --json for programmatic access:

Task structure

{ "id": "task-123", "name": "Implement UserEntity", "type": "task", "status": "pending", "priority": 2, "labels": ["entity", "user"], "epic": "epic-1", "created": "2024-01-15T10:30:00Z", "updated": "2024-01-15T10:30:00Z", "blocked": false, "dependencies": [] }

Parse with jq for filtering:

Ready tasks

bd ready --json | jq '.[0].id'

Completed tasks

bd list --json | jq '[.[] | select(.status == "done")] | length'

Tasks by layer

bd list --json | jq 'group_by(.labels[] | select(. == "entity" or . == "repository"))'

Quick Reference

Setup

bd init # Initialize Beads

Task Creation

bd create "Task name" -t task -p 2 -l feature # Create task bd create "Epic name" -t epic -p 1 -l feature # Create epic

Task Management

bd ready # Find next task bd ready --label feature # Feature-specific bd update task-123 --status in_progress # Start work bd close task-123 # Complete work

Progress Tracking

bd list # All tasks bd list --label feature # Feature tasks bd list --json # JSON output

Dependencies

bd dep add task-1 task-2 --type blocks # Add dependency bd dep list task-123 # Show dependencies bd dep tree # Visualize tree

Spec Integration

/spec:plan feature # Create Beads epic /spec:work feature # Start next ready task /spec:status feature # Check progress /spec:complete feature change # Archive work