Beads Work Tracking

Git-synced work items with dependency tracking and session persistence

Why Beads Exists

AI agents have three fundamental problems that Beads solves:

Problem	Without Beads	With Beads
Session Amnesia	Context lost when session ends	Work state persists in git
Manual Tracking	Copy/paste between Jira and AI	Work items live with code
Parallel Collisions	Agents overwrite each other	Dependency-aware coordination

Key Opinion: Let Fulcrum use Beads automatically. The bdcommands are for advanced debugging and manual intervention—not daily workflow. Trust the orchestrator.

Architecture

Beads uses a dual-storage architecture optimized for both git collaboration and fast querying:

.fulcrum/
├── beads/
│   ├── items.jsonl      # Append-only work item log (git-tracked)
│   ├── index.sqlite     # Query cache (git-ignored)
│   └── mail.jsonl       # Agent mail queue (git-tracked)
└── config.json          # Beads configuration

Why JSONL + SQLite?

JSONL: Append-only log is merge-friendly in git (no conflicts)
SQLite: Fast queries for orchestrator without parsing entire log
Rebuild: SQLite cache can always be rebuilt from JSONL source of truth

Git integration: Beads automatically commits work item changes. When you push your branch, teammates see your work breakdown. When you pull, you get their updates. No external tool sync required.

Work Item Lifecycle

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  draft   │ →  │  ready   │ →  │ in_progress │ → │  done    │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │               │               │               │
     │               │               │               │
     ▼               ▼               ▼               ▼
  Planning       Queued for      Being worked    Completed
  phase          execution       on by agent     successfully
                                      │
                                      ▼
                               ┌──────────┐
                               │ blocked  │
                               └──────────┘
                                  Failed or
                                  waiting on
                                  dependency

Essential Commands

These are the commands you might actually need (remember: prefer automatic orchestration):

bd ready

List all work items ready for execution:

$ bd ready

BEAD-001  Add user authentication       @backend    ready
BEAD-002  Create login component        @frontend   ready
BEAD-003  Setup auth database tables    @database   ready
BEAD-004  Write auth integration tests  @qa-backend blocked (BEAD-001)

bd list

List all work items with optional filters:

# All items
$ bd list

# Filter by status
$ bd list --status in_progress

# Filter by agent
$ bd list --agent backend

# Filter by dependency
$ bd list --blocked-by BEAD-001

bd create

Manually create a work item (rare—usually orchestrator creates these):

$ bd create --title "Fix login redirect bug" --agent frontend

Created BEAD-005: Fix login redirect bug
Status: draft
Agent: @frontend

bd close

Mark a work item as complete:

$ bd close BEAD-001 --success
# or
$ bd close BEAD-001 --failure "API rate limit exceeded"

Dependency Types

Beads tracks four types of relationships between work items:

Type	Meaning	Effect on Orchestration
`blocks`	B cannot start until A completes	Hard scheduling constraint
`related`	Items share context or may conflict	Agents notified of relationship
`parent`	Child is a subtask of parent	Parent completes when all children complete
`discovered-from`	Item was found during another's execution	Provenance tracking only

# Example bead with dependencies
{
  "id": "BEAD-005",
  "title": "Implement login form validation",
  "agent": "frontend",
  "status": "ready",
  "blocks": ["BEAD-001"],           // Depends on auth API
  "related": ["BEAD-002"],          // Related to login component
  "parent": "BEAD-epic-auth",       // Part of auth epic
  "discovered-from": null           // Manually created
}

Review State Tracking

Beads tracks code review state for quality gates:

{
  "id": "BEAD-001",
  "review": {
    "state": "changes_requested",
    "reviewer": "@tech-lead",
    "comments": [
      "Add input validation for email field",
      "Missing error handling for network failures"
    ],
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Review States

pending — Awaiting review
approved — Ready to merge
changes_requested — Needs work before approval
dismissed — Review no longer relevant

Conflict Resolution

Because JSONL is append-only, git merge conflicts are rare. When they occur:

# Rebuild SQLite cache from merged JSONL
$ bd rebuild

# Verify integrity
$ bd verify

# Fix any orphaned references
$ bd repair

Don't edit items.jsonl manually. Always use bd commands or let the orchestrator manage state. Manual edits can corrupt the append-only semantics and cause sync issues.

Integration with External Tools

Beads can sync with external project management tools:

# .fulcrum/config.json
{
  "beads": {
    "sync": {
      "jira": {
        "project": "PROJ",
        "bidirectional": false,
        "import_on_start": true
      }
    }
  }
}

Recommended: Use one-way sync (import from Jira, don't export back). Beads has richer dependency tracking than most PM tools, and two-way sync creates state conflicts.

Next Steps

Now that you understand the core concepts, explore the Strategy Agents to learn about PM, Tech Lead, and Work Orchestrator roles in detail.