beads - SKILL.md Agent Skill

name: beads alt_names: beads_rust, br, bd description: Track tasks and issues using the br CLI. Use for task management, sprint planning, dependency tracking, and project organization. Replaces TodoWrite. url: https://github.com/Dicklesworthstone/beads_rust

Beads Workflow Integration

This project uses beads_rust (br/bd) for issue tracking. Issues are stored in .beads/ and tracked in git.

Prerequisites

Install beads:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash

Initialize in a project:

br init

Essential Commands

# View ready issues (unblocked, not deferred)
br ready              # or: bd ready

# List and search
br list --status=open # All open issues
br show <id>          # Full issue details with dependencies
br search "keyword"   # Full-text search

# Create and update
br create --title="..." --description="..." --type=task --priority=2
br update <id> --status=in_progress
br close <id> --reason="Completed"
br close <id1> <id2>  # Close multiple issues at once

# Sync with git
br sync --flush-only  # Export DB to JSONL
br sync --status      # Check sync status

Workflow Pattern

Start: Run br ready to find actionable work
Claim: Use br update <id> --status=in_progress
Work: Implement the task
Complete: Use br close <id>
Sync: Always run br sync --flush-only at session end

Key Concepts

Dependencies: Issues can block other issues. br ready shows only unblocked work.
Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
Types: task, bug, feature, epic, chore, docs, question
Blocking: br dep add <issue> <depends-on> to add dependencies

Session Protocol

Before ending any session, run this checklist:

git status              # Check what changed
git add <files>         # Stage code changes
br sync --flush-only    # Export beads changes to JSONL
git commit -m "..."     # Commit everything
git push                # Push to remote

Best Practices

Check br ready at session start to find available work
Update status as you work (in_progress → closed)
Create new issues with br create when you discover tasks
Use descriptive titles and set appropriate priority/type
Always sync before ending session