br · diff
git:20260329.e53e29d to v1.0.0
251 added, 171 removed. Audit A to A.
---
name: br
description: >-
- 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.
+ 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
---
- <!-- TOC: Critical Rules | Quick Workflow | Essential Commands | bv Integration | Redirect/Worktree | Troubleshooting | References -->
+ <!-- TOC: Critical Rules | Quick Workflow | Essential Commands | Dependencies | Sync | bv Integration | Agent Mail | Troubleshooting | References -->
- # br — Beads Rust Issue Tracker
+ # 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 |
|------|-----|
- | **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 |
+ | **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
```bash
+ ACTOR="${BR_ACTOR:-assistant}"
+
# 1. Find work
br ready --json
# 2. Claim it
- br update bd-abc123 --status in_progress
+ br update --actor "$ACTOR" <id> --status in_progress
# 3. Do work...
# 4. Complete
- br close bd-abc123 --reason "Implemented X"
+ 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 (bd-abc123)"
+ git add .beads/ && git commit -m "feat: X (<id>)"
```
## Essential Commands
+ ### Issue Lifecycle
+
```bash
- # 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
+ ACTOR="${BR_ACTOR:-assistant}"
- # Querying (always use --json for agents)
- br ready --json # Actionable work (not blocked)
- br list --json # All issues
- br blocked --json # What's blocked
- br search "keyword" # Full-text search
- br show <id> --json # Issue details
+ 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
+ ```
- # Dependencies
- br dep add <child> <parent> # child depends on parent
- br dep cycles # MUST be empty!
- br dep tree <id> # Visualize dependencies
+ ### Create Options
- # Sync (EXPLICIT - never automatic)
- br sync --flush-only # DB → JSONL (before git commit)
- br sync --import-only # JSONL → DB (after git pull)
+ ```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
+ ```
- # System
- br doctor # Health check
- br config --list # Show configuration
+ ### 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
```
- ## Priority Scale
+ Bulk update (batch triage):
+ ```bash
+ br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json
+ ```
- | Priority | Meaning |
- |----------|---------|
- | 0 | Critical |
- | 1 | High |
- | 2 | Medium (default) |
- | 3 | Low |
- | 4 | Backlog |
+ ### Querying (always use --json for agents)
- ## bv Integration
+ ```bash
+ br ready --json # Actionable work (no blockers)
+ 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
+ ```
- **CRITICAL:** Never run bare `bv` — it launches interactive TUI and blocks.
+ ### Dependencies
```bash
- # Always use --robot-* flags:
- 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
+ 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!)
```
- ## Agent Mail Coordination
+ **Critical:** `br dep cycles` must return empty. Circular dependencies break the dependency graph and make `br ready` unreliable.
- Use bead ID as thread_id for multi-agent coordination:
+ ### Labels
- ```python
- file_reservation_paths(..., reason="bd-123")
- send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
- # Work...
- br close bd-123 --reason "Completed"
- release_file_reservations(...)
+ ```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
```
- ## Session Ending Pattern
+ ### Comments
```bash
- git pull --rebase
- br sync --flush-only
- git add .beads/ && git commit -m "Update issues"
- git push
- git status # Verify clean
+ ACTOR="${BR_ACTOR:-assistant}"
+ br comments add --actor "$ACTOR" <id> --message "Triage note" --json
+ br comments list <id> --json
```
- ## Anti-Patterns
+ ### Sync (EXPLICIT -- never automatic)
- - Running `br sync` without `--flush-only` or `--import-only`
- - Forgetting sync before git commit
- - Creating circular dependencies
- - Running bare `bv`
- - Assuming auto-commit behavior
+ ```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
+ ```
- ## Storage
+ 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
```
- .beads/
- ├── beads.db # SQLite (primary)
- ├── issues.jsonl # Git-friendly export
- └── config.yaml # Optional config
+
+ ### System and Diagnostics
+
+ ```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
```
- ## Redirect / Worktree Workflow
+ ## Priority Scale
- ### What Redirects Are
+ | 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 |
- A `.beads/redirect` file is a plain text file containing a single path that
- points to another `.beads/` (or `_beads/`) directory. When br discovers a
- redirect, it follows the chain until it reaches a terminal beads directory.
- All reads and writes (SQLite DB, JSONL) happen in the **target** directory,
- not the one containing the redirect file.
+ ## Issue Types
- This lets multiple working trees share one beads store so issues, history,
- and dependencies stay unified.
+ `task`, `bug`, `feature`, `epic`, `question`, `docs`
- ### When to Use
+ ## Output Formats
- - **Git worktrees** -- the primary use case. Each worktree gets its own
- `.beads/` from git, but you want all of them to operate on the same
- underlying database.
- - **PR-only workflows** -- temporary feature branches that should not
- maintain their own beads state.
- - **Ephemeral checkouts** -- CI or review checkouts that need read access
- to issues without duplicating the store.
+ | 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 |
- ### Setup
+ ## bv Integration
- Create a `redirect` file inside the worktree's `.beads/` directory. The
- path is resolved **relative to the `.beads/` directory itself**, not the
- project root.
+ **CRITICAL:** Never run bare `bv` -- it launches interactive TUI and blocks.
```bash
- # Example: main repo at /code/myproject, worktree at /code/myproject/.worktrees/feat
- # The worktree's .beads/ is at .worktrees/feat/.beads/
- # From there, ../../../.beads reaches the main repo's .beads/
-
- echo "../../../.beads" > /code/myproject/.worktrees/feat/.beads/redirect
+ # Always use --robot-* flags:
+ bv --robot-next # Single top pick + claim command
+ bv --robot-triage # Full triage with recommendations
+ 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
```
- Absolute paths also work:
+ ## Agent Mail Coordination
- ```bash
- echo "/code/myproject/.beads" > /code/myproject/.worktrees/feat/.beads/redirect
+ 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
+ br close bd-123 --reason "Completed"
+ release_file_reservations(...)
```
- Verify with `br where`:
+ ## Session Ending Pattern
- ```bash
- cd /code/myproject/.worktrees/feat
- br where
- # Output shows the target path and "(via redirect from ...)"
+ Before ending any work session:
- br where --json
- # { "path": "/code/myproject/.beads", "redirected_from": ".../feat/.beads", ... }
+ ```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"
```
- ### Path Resolution Rules
+ ## Standard Agent Workflow (Full)
- | Aspect | Behavior |
- |--------|----------|
- | Relative paths | Resolved from the `.beads/` dir containing the redirect file |
- | Absolute paths | Used as-is |
- | Target validation | Must be a `.beads` or `_beads` directory that exists on disk |
- | Chain following | Redirects can chain (A -> B -> C) up to 10 hops |
- | Loop detection | Paths are canonicalized; revisiting any path in the chain is an error |
- | Self-redirect (`.`) | Legal -- resolves to the current `.beads/` dir and stops |
+ ```bash
+ ACTOR="${BR_ACTOR:-assistant}"
- ### Effect on Commands
+ # 1. Verify workspace
+ br where
+ br ready --json
+ br blocked --json
+ br list --status open --sort priority --json
- With a redirect active, **all br commands** operate on the target directory:
+ # 2. Pick highest-priority ready work
+ br show <id> --json
- - `br create`, `br update`, `br close` -- write to the target DB and JSONL
- - `br sync --flush-only` -- flushes inline (writes already landed in the
- target); typically reports "nothing to export"
- - `br list`, `br ready`, `br show` -- read from the target
- - `br doctor` -- checks the target store
+ # 3. Claim it
+ br update --actor "$ACTOR" <id> --status in_progress --claim
- ### JSONL Commits in PR-Gated Repos
+ # 4. Do work...
- Because writes land in the **main repo's** `.beads/` directory, JSONL changes
- only appear in `git status` from the main repo, not from the worktree. This
- creates a commit-path question for projects that require PRs to merge to `main`.
+ # 5. Close with evidence
+ br close --actor "$ACTOR" <id> --reason "Implemented X in commit abc123"
- Recommended approaches:
+ # 6. Check queue impact
+ br ready --json
+ br blocked --json
- 1. **Treat JSONL as infrastructure** -- commit `.beads/` changes directly to
- `main` from the main repo working tree, outside the PR flow. JSONL updates
- are mechanical bookkeeping, not feature code, so many teams exempt them
- from PR review.
+ # 7. Sync to git
+ br sync --flush-only
+ git add .beads/ && git commit -m "feat: X (<id>)"
+ git push
+ ```
- 2. **Periodic sync from main** -- after merging a feature PR, run
- `br sync --flush-only` from the main repo on `main` and commit the
- resulting JSONL changes as a separate housekeeping commit.
+ ## Triage Decision Matrix
- 3. **Dedicated beads-sync branch** -- configure `br config set sync.branch
- beads-sync` and commit JSONL to that branch, then merge it to `main`
- through your normal PR process.
+ Classify each issue into exactly one category:
- ### Quick Setup Recipe
+ | 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
- # 1. Create worktree
- git worktree add .worktrees/feat -b feat/my-feature
+ br ready --json
+ br blocked --json
+ ```
- # 2. Add redirect (count "../" hops from .worktrees/feat/.beads/ to project root)
- echo "../../../.beads" > .worktrees/feat/.beads/redirect
+ ## Anti-Patterns
- # 3. Verify
- cd .worktrees/feat && br where && cd -
+ - 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
- # 4. Work normally from the worktree
- cd .worktrees/feat
- br create "New task" -p 1 -t task
- br ready --json
+ ## Storage Layout
- # 5. Commit JSONL from the main repo
- cd /code/myproject
- br sync --flush-only
- git add .beads/ && git commit -m "chore: update beads JSONL"
```
+ .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
+ ```
## Troubleshooting
```bash
br doctor # Full diagnostics
br dep cycles # Must be empty
- br config --list # Check settings
+ 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
```
- **Redirect target not found**: The path in `.beads/redirect` does not resolve
- to an existing directory. Check that relative paths are counted from the
- `.beads/` directory, not the project root.
-
- **Redirect loop detected**: Two or more redirect files point at each other.
- Run `br where` from each location to trace the chain, then fix the cycle.
-
- **Redirect chain exceeds max depth**: More than 10 redirect hops. Simplify
- the chain -- most setups need exactly one hop.
-
- ---
+ **Verbose debugging:**
+ ```bash
+ br -v list # Verbose
+ br -vv list # Debug
+ RUST_LOG=debug br list # Detailed trace logs
+ ```
## References
| Topic | File |
|-------|------|
- | 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) |
+ | 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) |