br

name	br
description	Official skill for beads_rust (`br`), a local-first, dependency-aware issue tracker for AI agents. Use when creating issues, triaging backlogs, managing dependencies, finding ready work, updating status, or syncing to git via JSONL.
license	MIT
domain	project-management
role	specialist
scope	operations
output-format	commands
triggers	["br","beads","beads_rust","issue tracker","issue triage","backlog","dependencies","ready work"]
metadata	{"author":"Dicklesworthstone","version":"1.0.0"}

br -- Beads Rust Issue Tracker (Official Skill)

Non-invasive: br NEVER runs git commands. Sync and commit are YOUR responsibility.

Critical Rules for Agents

Rule	Why
Binary is br	NEVER bd (that is the old Go version)
ALWAYS use --json	Structured output for parsing; --format toon for reduced tokens
NEVER run bare bv	Blocks session in interactive TUI mode
Sync is EXPLICIT	br sync --flush-only exports DB to JSONL only
Git is YOUR job	br only touches .beads/ -- you must git add .beads/ && git commit
No cycles allowed	br dep cycles must return empty
Resolve actor at runtime	Use ACTOR="${BR_ACTOR:-assistant}" and pass --actor "$ACTOR"

Quick Workflow

ACTOR="${BR_ACTOR:-assistant}"

# 1. Find work
br ready --json

# 2. Claim it
br update --actor "$ACTOR" <id> --status in_progress

# 3. Do work...

# 4. Complete
br close --actor "$ACTOR" <id> --reason "Implemented X"

# 5. Sync to git (EXPLICIT!)
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"

Essential Commands

Issue Lifecycle

ACTOR=""

br init                                              
br create --actor   -p 1 -t task      
br q --actor                     
br show <> --json                                  
br update --actor  <> --status in_progress 
br update --actor  <> --priority 0         
br close --actor  <> --reason        
br close --actor  <id1> <id2> --reason   
br reopen --actor  <>