OpenParable
Skip to content
← Back to skills

Beads Br

Productivity
beads-br

Beads Br is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/productivity/beads-br/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/beads-br, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

beads-br — Beads Rust Issue Tracker

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

Critical Rules for Agents

RuleWhy
ALWAYS use --jsonStructured output for parsing
NEVER run bare bvBlocks session in TUI mode
Sync is EXPLICITbr sync --flush-only after changes
Git is YOUR jobbr only touches .beads/ directory
No cycles allowedbr dep cycles must return empty

Private-ledger repos — the persist_intent port contract

Some repos declare a private bead ledger separated from the public source tree. The agentops repo is the canonical case; an agent that loads only this skill (without the repo CLAUDE.md) must still honor these invariants:

InvariantRule
IndirectionInvoke as BEADS_DIR=$PWD/_beads br <cmd> — the ledger lives at _beads/, not .beads/ (legacy .beads/ holds retired tracker config; br init there would clobber it).
Private repo_beads/ is its own git repository (separate remote). Sync = git -C _beads push.
Never leaknever run git add _beads in the host repo — bead bodies carry private context; the host repo is public and gitignores the ledger.
bd is retiredbecause the bd/Dolt remote-server lane was retired (2026-06-11) — do not run bd in a br repo; it appears only in explicitly-marked legacy notes.
Prefix filterto prevent cross-project leakage in shared DBs, filter queries by the repo's issue prefix (e.g. ag-) before trusting br ready output.

This section is the persist_intent port contract: the skill that persists intent owns the rules that keep that intent private and uncorrupted.

Quick Workflow

# 1. Find work
br ready --json

# 2. Claim it
br update bd-abc123 --status in_progress

# 3. Do work...

# 4. Complete
br close bd-abc123 --reason "Implemented X"

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

Essential Commands

# 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

# 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

# Dependencies
br dep add <child> <parent>          # child depends on parent
br dep cycles                        # MUST be empty!
br dep tree <id>                     # Visualize dependencies

# Sync (EXPLICIT - never automatic)
br sync --flush-only                 # DB → JSONL (before git commit)
br sync --import-only                # JSONL → DB (after git pull)

# System
br doctor                            # Health check
br config --list                     # Show configuration

Priority Scale

PriorityMeaning
0Critical
1High
2Medium (default)
3Low
4Backlog

bv Integration

CRITICAL: Never run bare bv — it launches interactive TUI and blocks.

# 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

Agent Mail Coordination

Use bead ID as thread_id for multi-agent coordination:

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(...)

Session Ending Pattern

git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
git status  # Verify clean

Issue-Lifecycle Discipline

Folded from the retired beads umbrella (ag-ez7y6) — operating doctrine, not the command surface above. These keep the tracker graph honest across sessions:

  • Live reads are authoritative. Treat live br show / br ready / br list output as the source of truth for current tracker state. Do NOT treat the exported issues.jsonl as the primary decision source when live br data is available — the JSONL is a git-friendly export artifact, refreshed on br sync --flush-only.
  • Scoped closure proof on every close. br close <id> --reason must name the touched files (or explicit no-file evidence artifact), the validation command(s) run, and the parent-reconciliation outcome. Never close a child bead with a generic reason like "done" or "implemented".
  • Reconcile the parent in the same session. After closing or materially updating a child bead, reconcile the open parent: update stale "remaining gap" notes immediately, and close the parent when the child resolved its last real gap.
  • Narrow the umbrella issue before implementing. If br ready surfaces a broad umbrella bead, do not implement against vague parent wording — first narrow the remaining gap into an execution-ready child bead, land the child, then reconcile the parent.
  • Normalize stale queue items instead of skipping them. Rewrite broad or partially-absorbed beads to the actual remaining gap rather than silently passing over them.

Anti-Patterns

  • Running br sync without --flush-only or --import-only
  • Forgetting sync before git commit
  • Creating circular dependencies
  • Running bare bv
  • Assuming auto-commit behavior

Storage

.beads/
├── beads.db        # SQLite (primary)
├── issues.jsonl    # Git-friendly export
└── config.yaml     # Optional config

Troubleshooting

br doctor                    # Full diagnostics
br dep cycles                # Must be empty
br config --list             # Check settings

Worktree error ('main' is already checked out):

git branch beads-sync main
br config set sync.branch beads-sync

References

TopicFile
Full command referenceCOMMANDS.md
Configuration detailsCONFIG.md
Troubleshooting guideTROUBLESHOOTING.md
Multi-agent patternsINTEGRATION.md