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

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

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:

1. pending – Created, not yet started
2. in_progress – Actively being worked
3. 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