br · diff
v1.0.0 to git:20260326.7cd40eb
55 added, 264 removed. Audit A to A.
---
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
+ Local-first issue tracker (beads_rust) for AI agents. Use when tracking tasks,
+ managing dependencies, finding ready work, or syncing issues to git via JSONL.
---
- <!-- TOC: Critical Rules | Quick Workflow | Essential Commands | Dependencies | Sync | bv Integration | Agent Mail | Troubleshooting | References -->
+ <!-- TOC: Critical Rules | Quick Workflow | Essential Commands | bv Integration | References -->
- # br -- Beads Rust Issue Tracker (Official Skill)
+ # br — Beads Rust Issue Tracker
> **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` |
+ | **ALWAYS use `--json`** | Structured output for parsing |
+ | **NEVER run bare `bv`** | Blocks session in TUI mode |
+ | **Sync is EXPLICIT** | `br sync --flush-only` after changes |
+ | **Git is YOUR job** | br only touches `.beads/` directory |
| **No cycles allowed** | `br dep cycles` must return empty |
- | **Resolve actor at runtime** | Use `ACTOR="${BR_ACTOR:-assistant}"` and pass `--actor "$ACTOR"` |
## Quick Workflow
```bash
- ACTOR="${BR_ACTOR:-assistant}"
-
# 1. Find work
br ready --json
# 2. Claim it
- br update --actor "$ACTOR" <id> --status in_progress
+ br update bd-abc123 --status in_progress
# 3. Do work...
# 4. Complete
- br close --actor "$ACTOR" <id> --reason "Implemented X"
+ br close bd-abc123 --reason "Implemented X"
# 5. Sync to git (EXPLICIT!)
br sync --flush-only
- git add .beads/ && git commit -m "feat: X (<id>)"
+ git add .beads/ && git commit -m "feat: X (bd-abc123)"
```
## Essential Commands
- ### Issue Lifecycle
-
```bash
- ACTOR="${BR_ACTOR:-assistant}"
-
- br init # Initialize .beads/ workspace
- br create --actor "$ACTOR" "Title" -p 1 -t task # Create issue (priority 0-4)
- br q --actor "$ACTOR" "Quick note" # Quick capture (ID only output)
- br show <id> --json # Show issue details
- br update --actor "$ACTOR" <id> --status in_progress # Update status
- br update --actor "$ACTOR" <id> --priority 0 # Change priority
- br close --actor "$ACTOR" <id> --reason "Done" # Close with reason
- br close --actor "$ACTOR" <id1> <id2> --reason "..." # Close multiple at once
- br reopen --actor "$ACTOR" <id> # Reopen closed issue
- ```
-
- ### Create Options
-
- ```bash
- br create --actor "$ACTOR" "Title" \
- --priority 1 \ # 0-4 scale (0=critical, 4=backlog)
- --type task \ # task, bug, feature, epic, question, docs
- --assignee "user@..." \ # Optional assignee
- --labels backend,auth \ # Comma-separated labels
- --description "..." # Detailed description
- ```
-
- ### Update Options
-
- ```bash
- br update --actor "$ACTOR" <id> \
- --title "New title" \
- --priority 0 \
- --status in_progress \ # open, in_progress, closed
- --assignee "new@..." \
- --add-label reliability \
- --parent <parent-id> \
- --claim # Shorthand for claim-and-start
- ```
-
- Bulk update (batch triage):
- ```bash
- br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json
- ```
-
- ### Querying (always use --json for agents)
+ # Lifecycle
+ br init # Initialize .beads/
+ br create "Title" -p 1 -t task # Create (priority 0-4)
+ br update <id> --status in_progress # Claim work
+ br close <id> --reason "Done" # Complete
+ br reopen <id> # Reopen if needed
- ```bash
- br ready --json # Actionable work (no blockers)
+ # Querying (always use --json for agents)
+ br ready --json # Actionable work (not blocked)
br list --json # All issues
- br list --status open --sort priority --json # Filter and sort
- br list --priority 0-1 --json # Filter by priority range
- br list --assignee alice --json # Filter by assignee
- br blocked --json # Show blocked issues
- br search "keyword" --json # Full-text search
- br show <id> --json # Issue details with dependencies
- br stale --days 30 --json # Stale issues
- br count --by status --json # Count with grouping
- ```
-
- ### Dependencies
+ br blocked --json # What's blocked
+ br search "keyword" # Full-text search
+ br show <id> --json # Issue details
- ```bash
+ # Dependencies
br dep add <child> <parent> # child depends on parent
- br dep add <id> <depends-on> --type blocks # Explicit block type
- br dep remove <child> <parent> # Remove dependency
- br dep list <id> --json # List dependencies for issue
- br dep tree <id> --json # Show dependency tree
- br dep cycles --json # Find circular deps (MUST be empty!)
- ```
-
- **Critical:** `br dep cycles` must return empty. Circular dependencies break the dependency graph and make `br ready` unreliable.
-
- ### Labels
-
- ```bash
- br label add <id> backend auth # Add multiple labels
- br label remove <id> urgent # Remove label
- br label list <id> # List issue's labels
- br label list-all # All labels in project
- ```
-
- ### Comments
-
- ```bash
- ACTOR="${BR_ACTOR:-assistant}"
- br comments add --actor "$ACTOR" <id> --message "Triage note" --json
- br comments list <id> --json
- ```
-
- ### Sync (EXPLICIT -- never automatic)
-
- ```bash
- br sync --flush-only # Export DB to JSONL (before git commit)
- br sync --import-only # Import JSONL to DB (after git pull)
- br sync --status # Check sync status
- ```
-
- Workflow after making changes:
- ```bash
- br sync --flush-only
- git add .beads/ && git commit -m "Update issues"
- ```
-
- Workflow after pulling:
- ```bash
- git pull
- br sync --import-only
- ```
+ br dep cycles # MUST be empty!
+ br dep tree <id> # Visualize dependencies
- ### System and Diagnostics
+ # Sync (EXPLICIT - never automatic)
+ br sync --flush-only # DB → JSONL (before git commit)
+ br sync --import-only # JSONL → DB (after git pull)
- ```bash
- br doctor # Full diagnostics
- br stats --json # Project statistics
- br config --list # Show all configuration
- br config --get id.prefix # Get specific value
- br config --set defaults.priority=1 # Set value
- br where # Show workspace location
- br version # Show version
- br upgrade # Self-update (if enabled)
- br lint --json # Lint issues for problems
+ # System
+ br doctor # Health check
+ br config --list # Show configuration
```
## Priority Scale
- | Priority | Meaning | Use numbers, not words |
- |----------|---------|------------------------|
- | 0 | Critical | Immediate action required |
- | 1 | High | Important, do soon |
- | 2 | Medium (default) | Normal priority |
- | 3 | Low | When time permits |
- | 4 | Backlog | Future consideration |
-
- ## Issue Types
-
- `task`, `bug`, `feature`, `epic`, `question`, `docs`
-
- ## Output Formats
-
- | Flag | Use case |
- |------|----------|
- | `--json` | Default for agents -- full structured data |
- | `--format toon` | Token-optimized alternative for context-window-sensitive agents |
- | (no flag) | Human-readable terminal output with colors |
+ | Priority | Meaning |
+ |----------|---------|
+ | 0 | Critical |
+ | 1 | High |
+ | 2 | Medium (default) |
+ | 3 | Low |
+ | 4 | Backlog |
## bv Integration
- **CRITICAL:** Never run bare `bv` -- it launches interactive TUI and blocks.
+ **CRITICAL:** Never run bare `bv` — it launches interactive TUI and blocks.
```bash
# Always use --robot-* flags:
- bv --robot-next # Single top pick + claim command
- bv --robot-triage # Full triage with recommendations
+ bv --robot-next # Single top pick
+ bv --robot-triage # Full triage
bv --robot-plan # Parallel execution tracks
- bv --robot-insights | jq '.Cycles' # Check graph health (must be empty)
- bv --robot-priority # Priority misalignment detection
- bv --robot-alerts # Stale issues, blocking cascades
+ bv --robot-insights | jq '.Cycles' # Check graph health
```
## Agent Mail Coordination
Use bead ID as thread_id for multi-agent coordination:
- | Concept | Value |
- |---------|-------|
- | Mail `thread_id` | `bd-###` (the issue ID) |
- | Mail subject | `[bd-###] ...` |
- | File reservation `reason` | `bd-###` |
- | Commit messages | Include `bd-###` for traceability |
-
```python
- # 1. Reserve files for bead
file_reservation_paths(..., reason="bd-123")
-
- # 2. Announce work in thread
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
-
- # 3. Do work...
-
- # 4. Close bead and release
+ # Work...
br close bd-123 --reason "Completed"
release_file_reservations(...)
```
## Session Ending Pattern
- Before ending any work session:
-
```bash
git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
- git status # MUST show "up to date with origin"
- ```
-
- ## Standard Agent Workflow (Full)
-
- ```bash
- ACTOR="${BR_ACTOR:-assistant}"
-
- # 1. Verify workspace
- br where
- br ready --json
- br blocked --json
- br list --status open --sort priority --json
-
- # 2. Pick highest-priority ready work
- br show <id> --json
-
- # 3. Claim it
- br update --actor "$ACTOR" <id> --status in_progress --claim
-
- # 4. Do work...
-
- # 5. Close with evidence
- br close --actor "$ACTOR" <id> --reason "Implemented X in commit abc123"
-
- # 6. Check queue impact
- br ready --json
- br blocked --json
-
- # 7. Sync to git
- br sync --flush-only
- git add .beads/ && git commit -m "feat: X (<id>)"
- git push
- ```
-
- ## Triage Decision Matrix
-
- Classify each issue into exactly one category:
-
- | Classification | Action |
- |---------------|--------|
- | `implemented` | Close with evidence (commit/PR/file/behavior) |
- | `out-of-scope` | Close with explicit boundary reason |
- | `needs-clarification` | Comment with specific unanswered questions |
- | `actionable` | Keep open, correct status/priority/labels/deps |
-
- During large triage efforts, checkpoint every few updates:
- ```bash
- br ready --json
- br blocked --json
+ git status # Verify clean
```
## Anti-Patterns
- Running `br sync` without `--flush-only` or `--import-only`
- Forgetting sync before git commit
- Creating circular dependencies
- - Running bare `bv` (blocks session)
- - Assuming auto-commit behavior (br NEVER auto-commits)
- - Inventing evidence for closure -- if unsure, comment instead
- - Modifying unrelated issues during triage
- - Adding speculative dependencies
+ - Running bare `bv`
+ - Assuming auto-commit behavior
- ## Storage Layout
+ ## Storage
```
.beads/
- beads.db # SQLite database (primary storage)
- beads.db-shm # SQLite shared memory (WAL mode)
- beads.db-wal # SQLite write-ahead log
- issues.jsonl # JSONL export (for git)
- config.yaml # Project configuration
- metadata.json # Workspace metadata
+ ├── beads.db # SQLite (primary)
+ ├── issues.jsonl # Git-friendly export
+ └── config.yaml # Optional config
```
## Troubleshooting
```bash
br doctor # Full diagnostics
br dep cycles # Must be empty
br config --list # Check settings
- which br # Verify br is installed
```
- **"Database locked"**: Check for other `br` processes with `pgrep -f "br "`.
-
**Worktree error** (`'main' is already checked out`):
```bash
git branch beads-sync main
br config set sync.branch beads-sync
```
- **Verbose debugging:**
- ```bash
- br -v list # Verbose
- br -vv list # Debug
- RUST_LOG=debug br list # Detailed trace logs
- ```
+ ---
## References
| Topic | File |
|-------|------|
- | Command cookbook | [references/COMMANDS.md](references/COMMANDS.md) |
- | Configuration details | [references/CONFIG.md](references/CONFIG.md) |
- | Troubleshooting guide | [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) |
- | Multi-agent integration | [references/INTEGRATION.md](references/INTEGRATION.md) |
+ | Full command reference | [COMMANDS.md](references/COMMANDS.md) |
+ | Configuration details | [CONFIG.md](references/CONFIG.md) |
+ | Troubleshooting guide | [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) |
+ | Multi-agent patterns | [INTEGRATION.md](references/INTEGRATION.md) |