beads

What this skill does

# Beads - Distributed Git-Backed Issue Tracker

This skill activates when working with Beads (`bd`) for task management, dependency tracking, and AI agent workflows.

## When to Use This Skill

Activate when:
- Managing tasks with dependencies in a git repository
- Working with AI agents that need task queue access
- Running multi-branch parallel development workflows
- Needing collision-resistant task IDs across distributed teams
- Tracking task hierarchies and dependency graphs
- Integrating issue tracking directly into version control

## What is Beads?

Beads is a distributed git-backed graph issue tracker designed for AI agents and modern development workflows:

- **Hash-based IDs**: Collision-resistant task identifiers (8+ hex characters)
- **Git-native storage**: Tasks stored as JSONL in `.beads/` directory
- **Dependency-aware**: Query ready tasks with `bd ready`
- **JSON output**: Machine-readable format for AI agent integration
- **SQLite cache**: Fast local queries with git sync

## Installation

### npm (Recommended)

```bash
npm install -g @anthropic/beads
```

### Homebrew (macOS)

```bash
brew install anthropic/tap/beads
```

### Go Install

```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

### mise (Multi-Architecture)

Add to your `mise.toml`:

```toml
[tools."github:steveyegge/beads"]
version = "latest"

[tools."github:steveyegge/beads".platforms]
linux-x64 = { asset_pattern = "beads_*_linux_amd64.tar.gz" }
macos-arm64 = { asset_pattern = "beads_*_darwin_arm64.tar.gz" }
```

See `templates/multi-arch.md` for platform-specific patterns.

## Getting Started

### Initialize Beads

```bash
# Full mode - syncs to remote (shared with team)
bd init

# Stealth mode - local only, no commits
bd init --stealth

# Contributor mode - pull only, no push
bd init --contributor
```

### Create Tasks

```bash
# Create a task with title
bd create "Implement user authentication"

# Create with description
bd create "Fix login bug" --description "Users cannot log in with special characters"

# Create with labels
bd create "Add dark mode" --labels "feature,ui"

# Create with assignee
bd create "Review PR" --assignee "alice"
```

### List Tasks

```bash
# List all open tasks
bd list

# List ready tasks (no blockers)
bd ready

# JSON output for agents
bd list --json
bd ready --json

# Filter by status
bd list --status open
bd list --status closed

# Filter by label
bd list --labels "bug"

# Filter by assignee
bd list --assignee "bob"
```

### Show Task Details

```bash
# Show task by ID (use first 4+ characters)
bd show abc1

# Full JSON output
bd show abc1 --json

# Show with comments
bd show abc1 --comments
```

### Manage Dependencies

```bash
# Add dependency (task2 depends on task1)
bd dep add task2 task1

# Remove dependency
bd dep remove task2 task1

# View dependency graph
bd dep graph

# List blockers for a task
bd dep blockers task2

# List tasks blocked by a task
bd dep blocking task1
```

### Update Tasks

```bash
# Close a task
bd close abc1

# Reopen a task
bd reopen abc1

# Add a comment
bd comment abc1 "Working on this now"

# Update labels
bd label abc1 --add "priority:high"
bd label abc1 --remove "wip"

# Assign task
bd assign abc1 alice

# Unassign
bd unassign abc1
```

### Sync with Git

```bash
# Sync changes to remote
bd sync

# Pull changes from remote
bd pull

# Check sync status
bd status
```

## JSON Output for AI Agents

All commands support `--json` for machine-readable output:

### List Ready Tasks (JSON)

```bash
bd ready --json
```

Output:
```json
[
  {
    "id": "abc12345",
    "title": "Implement login form",
    "status": "open",
    "labels": ["feature", "frontend"],
    "created": "2024-01-15T10:30:00Z",
    "dependencies": [],
    "blocking": ["def67890"]
  }
]
```

### Show Task Details (JSON)

```bash
bd show abc1 --json
```

Output:
```json
{
  "id": "abc12345",
  "title": "Implement login form",
  "description": "Create a login form with email and password fields",
  "status": "open",
  "labels": ["feature", "frontend"],
  "assignee": "alice",
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:20:00Z",
  "dependencies": [],
  "blocking": ["def67890"],
  "comments": [
    {
      "author": "bob",
      "body": "Should we add OAuth support?",
      "created": "2024-01-15T11:00:00Z"
    }
  ]
}
```

### Parse JSON in Scripts

```bash
# Get first ready task ID
TASK_ID=$(bd ready --json | jq -r '.[0].id')

# Count open tasks
bd list --json | jq 'length'

# Get task titles
bd list --json | jq -r '.[].title'
```

## Task Hierarchies

### Parent-Child Relationships

```bash
# Create parent task
bd create "Authentication system"
# Returns: Created task auth123

# Create child tasks
bd create "Login form" --parent auth123
bd create "Password reset" --parent auth123
bd create "Session management" --parent auth123

# List children
bd list --parent auth123

# View hierarchy
bd tree auth123
```

### Epic/Story/Task Pattern

```bash
# Create epic
bd create "User Management Epic" --labels "epic"

# Create stories under epic
bd create "User registration story" --parent epic123 --labels "story"
bd create "User profile story" --parent epic123 --labels "story"

# Create tasks under stories
bd create "Design registration form" --parent story456 --labels "task"
bd create "Implement validation" --parent story456 --labels "task"
```

## Dependency Management

### Dependency Types

```bash
# Task A blocks Task B (B depends on A)
bd dep add taskB taskA

# View what blocks a task
bd dep blockers taskB

# View what a task blocks
bd dep blocking taskA

# Circular dependency detection
bd dep add taskA taskB  # Error if creates cycle
```

### Ready Tasks Query

The `bd ready` command shows tasks with no unresolved dependencies:

```bash
# All ready tasks
bd ready

# Ready tasks with label
bd ready --labels "priority:high"

# Ready tasks for assignee
bd ready --assignee "alice"
```

## Storage and Sync

### File Structure

```
.beads/
├── tasks.jsonl     # Task data (append-only)
├── comments.jsonl  # Comments (append-only)
└── deps.jsonl      # Dependencies (append-only)

.beads.sqlite       # Local cache (not committed)
```

### Sync Modes

| Mode | `bd init` Flag | Commits | Pushes | Use Case |
|------|----------------|---------|--------|----------|
| Full | (default) | Yes | Yes | Team shared |
| Stealth | `--stealth` | No | No | Local only |
| Contributor | `--contributor` | Yes | No | Pull-only |

### Conflict Resolution

Beads uses append-only JSONL and hash-based IDs to minimize conflicts:

```bash
# Pull remote changes
bd pull

# Resolve conflicts in .beads/ files
git mergetool .beads/tasks.jsonl

# Rebuild cache after conflict resolution
bd rebuild
```

## Workflow Examples

### PR-Based Development Workflow

The recommended workflow for git repositories integrates beads with feature branches and pull requests:

#### Session Start

```bash
git checkout main && git pull    # Start fresh
bd ready                         # Find available tasks
bd show <id>                     # Read task requirements
```

#### Task Execution

```bash
git checkout -b feature/<name>   # Create feature branch
bd update <id> --status in_progress  # Claim task

# Do the work:
# - Read existing code to understand patterns
# - Implement following TDD (tests first when practical)
# - Run quality gates (tests, linters, formatters)

git add <files>                  # Stage changes
git commit -m "type(scope): description"  # Commit
```

#### PR Creation

```bash
git push -u origin <branch>
gh pr create --title "type(scope): description" --body "- Change one
- Change two"

# Notify user: "PR created: <url>"
```

#### Watch CI & Close Tasks

Watch CI until it passes, then close tasks:

```bash
gh pr checks --watch             # Wait for CI to complete
bd close <id>                    # Close completed task
git add .beads/ && git commit -m "chore(beads): close <id>"
git push                         # Push closure to branch
```

Notify us