---
description: How to use the bd (beads) CLI for issue tracking, dependencies, and workflow orchestration
---

# BD Workflow

The `bd` CLI is a git-backed issue tracker with first-class dependency support. Use it for multi-session work, blocking relationships, and persistent memory across conversation compaction.

## When to Use BD vs TodoWrite

| Use BD | Use TodoWrite |
|--------|---------------|
| Work spans multiple sessions | Single-session tasks |
| Dependencies between tasks | Independent subtasks |
| Need audit trail in git | Ephemeral tracking |
| Cross-repo coordination | Local project only |
| Resuming after compaction | Simple task lists |

## Core Commands

### Creating Issues

```bash
bd create "Issue title"                          # Basic task
bd create "Bug title" --type=bug --priority=1    # P1 bug
bd create "Feature" --type=feature -d "Details"  # With description
bd q "Quick capture"                             # Output only ID
```

### Managing Issues

```bash
bd show <id>                    # View issue details
bd show <id> --children         # View children of epic
bd list                         # List open issues (default 50)
bd list --all                   # Include closed
bd list -s in_progress          # Filter by status
bd list -t bug -p 0             # P0 bugs
bd list --pretty                # Tree format
```

### Updating Issues

```bash
bd update <id> --status=in_progress    # Start work
bd update <id> --status=blocked        # Mark blocked
bd update <id> --claim                 # Claim atomically
bd update <id> --add-label=urgent      # Add label
bd update <id> -d "New description"    # Update description
```

### Closing Issues

```bash
bd close <id>                          # Close issue
bd close <id> --continue               # Auto-advance to next step
bd close <id> --suggest-next           # Show newly unblocked
```

## Finding Work

```bash
bd ready                     # Ready issues (no blockers)
bd ready --mol <mol-id>      # Ready steps in molecule
bd ready -n 5                # Limit to 5
bd ready --assignee me       # Assigned to me
bd blocked                   # Show blocked issues
bd blocked --parent <id>     # Blocked within epic
```

## Dependency Management

### Creating Dependencies

```bash
bd dep <blocker> --blocks <blocked>    # A blocks B
bd dep add <blocked> <blocker>         # Same as above
bd dep relate <id1> <id2>              # Bidirectional link
```

### Viewing Dependencies

```bash
bd dep list <id>             # Show dependencies
bd dep tree <id>             # Dependency tree
bd dep cycles                # Detect cycles
```

### Removing Dependencies

```bash
bd dep remove <blocked> <blocker>      # Remove dependency
bd dep unrelate <id1> <id2>            # Remove relation
```

## Sync Workflow

BD syncs issues via git. The daemon handles this automatically, but manual sync is available:

```bash
bd sync                      # Full sync (pull, merge, push)
bd sync --flush-only         # Export to JSONL only
bd sync --import-only        # Import from JSONL only
bd sync --status             # Show sync branch diff
bd sync --squash             # Accumulate without commit
```

## Formula and Molecule Workflow

Formulas are reusable workflow templates. Molecules are instantiated workflows.

### Formulas

```bash
bd formula list                        # List available formulas
bd formula list --type=workflow        # Filter by type
bd formula show <name>                 # Show formula details
bd cook <formula>                      # Compile to proto (stdout)
bd cook <formula> --var name=auth      # With variable substitution
bd cook <formula> --dry-run            # Preview steps
bd cook <formula> --persist            # Save to database
```

### Molecules: Pour vs Wisp

| pour (persistent) | wisp (ephemeral) |
|-------------------|------------------|
| Feature implementations | Release workflows |
| Multi-session work | Patrol cycles |
| Audit trail needed | Health checks |
| Git-synced | Local only |

```bash
# Persistent molecule (liquid phase)
bd mol pour <proto> --var name=auth

# Ephemeral molecule (vapor phase)
bd mol wisp <proto> --var version=1.0
bd mol wisp list                       # List wisps
bd mol wisp gc                         # Garbage collect
```

### Tracking Molecule Progress

```bash
bd mol show <mol-id>                   # Show structure
bd mol show <mol-id> --parallel        # Parallelizable steps
bd mol current                         # Where am I?
bd mol current <mol-id>                # Status for molecule
bd mol progress <mol-id>               # Progress summary + ETA
```

### Molecule Lifecycle

```bash
bd mol squash <mol-id>                 # Condense to digest
bd mol burn <mol-id>                   # Delete wisp
bd mol distill <epic-id>               # Extract formula from epic
```

## Gates and Human Checkpoints

Gates are async wait conditions that block workflow steps:

| Gate Type | Wait Condition |
|-----------|---------------|
| human | Manual `bd close` |
| timer | Timeout expires |
| gh:run | GitHub workflow completes |
| gh:pr | PR merges |
| bead | Cross-rig bead closes |

```bash
bd gate list                           # Show open gates
bd gate list --all                     # Include closed
bd gate check                          # Evaluate all gates
bd gate check --type=bead              # Check bead gates only
bd gate resolve <id>                   # Close manually
```

## Common Patterns

### Starting Work on a Bead

```bash
bd update <id> --status=in_progress
# ... do work ...
bd close <id>
```

### Creating Related Issues

```bash
bd create "Main task" --deps "blocks:<other-id>"
bd dep add <new-id> <blocker-id>
```

### Working Through a Molecule

```bash
bd mol pour my-workflow --var name=feature
bd ready --mol <mol-id>                # Find next step
bd update <step-id> --claim            # Claim step
# ... do work ...
bd close <step-id> --continue          # Close and advance
```

### Quick Status Check

```bash
bd ready -n 3                          # Top 3 ready items
bd list -s in_progress                 # What's in flight?
bd blocked                             # What's stuck?
```

## Useful Flags

| Flag | Effect |
|------|--------|
| `--json` | JSON output for scripting |
| `--quiet` | Suppress non-essential output |
| `--dry-run` | Preview without executing |
| `--pretty` | Tree format display |

## Integration Notes

- BD auto-syncs via daemon (check with `bd info`)
- Issues stored in `.beads/` directory
- JSONL files sync through git
- Use `bd doctor` if something seems wrong
