tool-br

name	tool-br
description	Use br (beads_rust) as the primary task/issue tracker for this repo. Trigger when planning work, creating or claiming issues, checking what is ready to work on, or preparing a commit that must reference a beads issue id.

tool-br

When To Use

• Before starting non-trivial work: check br ready for actionable issues, or create one.
• When a task has no existing issue: create one first, then reference its id in the commit.
• When checking what is blocked, in progress, or safe to pick up next.
• When preparing any commit message (a beads issue id is required by the commit-msg hook).

Trusted Commands

br init                                   # One-time: initialize .beads/ in a repo
br create "Title" --type task --priority 1 --description "..."
br q "Quick capture title"                # Fast issue creation, id only
br ready                                  # Actionable, unblocked work
br ready --json                           # Machine-readable for agents
br show <id>                              # Issue details
br update <id> --status in_progress --assignee "$(git config user.email)"
br close <id> --reason "What was done"
br delete <id> --hard                     # Delete durably (prunes JSONL; plain delete resurrects)
br dep add <child-id> <parent-id>         # child depends on parent
br dep tree <id>                          # dependency tree rooted at an issue
br dep cycles                             # detect dependency cycles
br list --status open --priority 0-1
br sync --flush-only                      # Idempotent JSONL export check before commit

Harness primitives (what the basicly loop relies on — §12)

# Decomposition & readiness
br ready --json                           # unblocked, actionable work (scheduler input)
br blocked                                # issues waiting on dependencies
br scheduler --json                       # rank ready work; explainable additive score
                                          #   (priority + dependents + stale + fairness + domain)
br scheduler --stale-claim-hours 2        # surface stale/abandoned claims

# Structured fields (Definition-of-Ready / Validate)
br update <id> --acceptance-criteria "Given/When/Then ..."   # alias: --acceptance
br update <id> --design "How it will be built"
br update <id> --notes "Extra context"
br lint                                   # flag issues missing required template sections (DoR)
br lint -t feature -s open                # lint a subset

# Gate ledger (deterministic = required, AI-semantic = advisory)
br gate report <id> --gate ci --provider pytest --status pass   # or: fail, --note "..."
br gate list <id>                         # recorded gate results + required-gate status

# Loop state carried on the issue (no external state file)
br update <id> --external-ref "harness/<name>@<repo>.worktrees/<name>"  # worktree/branch binding
br update <id> --agent-context @design.json   # governing constraints; inherited by child issues
br update <id> --status in_progress --assignee "$(git config user.email)"  # claim

# Retro & multi-agent coordination
br comments add <id> "Retro finding: ..."
br comments list <id>
br coordination                           # diagnose swarm claims (stale-worktree recovery)

# Parallel-branch tracker-state reconciliation (br has NO git merge-driver, unlike bd)
br sync --merge                           # 3-way merge of .beads/issues.jsonl after a branch merge

Safe Defaults

• Always resolve or create an issue before doing the work it represents; never invent an id in a commit message that does not exist in .beads/issues.jsonl.
• Run br sync --flush-only before staging .beads/ so the JSONL export matches the SQLite state (mutating commands auto-flush by default, but this is a cheap final check).
• Prefer br update <id> --status in_progress before starting work. For work done directly in the base checkout, close the issue with br close <id> --reason "..." before making the commit that resolves it, then stage .beads/issues.jsonl together with the code in that same commit — never a separate trailing chore: close <id> commit with no other content. For loop-tracked work the tracker is zero-touch: the loop engine commits tracker state itself at landing and at ship — never git add .beads yourself (see the harness-loop skill).
• Use --json for any programmatic/agent-driven query (br ready --json, br list --json, br show <id> --json).
• Stage .beads/issues.jsonl, .beads/config.yaml, and .beads/metadata.json with the commit that references the issue; .beads/beads.db* is git-ignored by br's own .beads/.gitignore.

Common Pitfalls

• Running bare br sync — it is intentionally refused; choose --flush-only, --import-only, --merge, --status, or --witness explicitly.
• Hand-editing .beads/issues.jsonl instead of using br commands (breaks the SQLite/JSONL sync contract).
• Forgetting the beads id in a commit message — the beads-commit-msg git hook rejects commits without a known issue id referenced in the message.
• Committing with a guessed or pre-assumed issue id — br create assigns a random base (you cannot predict it), so never chain br create and git commit in one command line with an id you invented; the hook rejects the unknown id, and a trailing || true silently swallows that rejection. Run br create alone, read the generated id from its output (✓ Created <id>: ...), then commit separately referencing that exact id.
• Assuming br commits, pushes, or installs hooks automatically — it never does; git add/git commit for .beads/ files is always the user/agent's responsibility.
• Closing an issue in a separate follow-up commit instead of folding the close into the commit that resolves it (base-checkout work only; the loop's closing commit is structurally separate) — creates a no-value trailing commit. If you forgot and the resolving commit isn't pushed yet, git commit --amend it instead of adding a new one; if it's already pushed, amending needs explicit confirmation (history rewrite), so weigh that against just accepting the small trailing commit.
• Bulk-creating issues via a hand-rolled shell loop with conditional flags (${var:+--flag "$var"} word-splits and silently breaks --parent linkage) — use br create --file <markdown> for bulk import, or one explicit br create call per issue, and verify hierarchy afterwards with br epic status/br dep tree.
• br delete <id> alone gets resurrected. Plain delete writes a DB tombstone but leaves the record in .beads/issues.jsonl; the next br command auto-imports that stale line and recreates the issue. Delete durably with br delete <id> --hard (it prunes the record from the JSONL immediately), then confirm with br show <id> (not found) and by grepping .beads/issues.jsonl.
• Probing the live tracker leaves tombstones the loop commits. Investigating br behavior by creating throwaway beads and br delete-ing them leaves tombstone rows in .beads/issues.jsonl; the harness loop's tracker-state commit then captures that junk into project history. Prune every probe bead with br delete <id> --hard (there is no br compact/purge/gc — --hard is the only clean prune), or avoid probing the live tracker at all. --ephemeral is not a workaround: ephemeral beads do not export to JSONL, but br lint also will not lint them (total:0), so any lint probe needs a real bead.
• Trusting a DB-only change. .beads/issues.jsonl is the sync source of truth and br auto-imports it on the next command, so a change made only to the DB can be silently reverted. Make sure the JSONL reflects the change (br sync --flush-only, or --hard for deletes) before you rely on it or stage it.
• Creating ids with br create --slug .... It produces multi-hyphen ids (basicly-my-thing-9li) that the commit-msg hook rejects. Let br generate the default single-hyphen basicly-<hash> id; never pass --slug.
• Staging br's transient sidecars. br writes lock/journal/vacuum artifacts in .beads/ (beads.db-lock-*, .beads.vacuum.<pid>.tmp-*, *.fsqlite-*); they are git-ignored and must never be committed. If any appear as untracked, they are junk — delete them, do not stage them.
• Re-br init with a different --prefix. The prefix is pinned in .beads/config.yaml (authoritative over the local DB); never re-init with another prefix or the team's basicly-<hash> ids diverge across machines.

Output Interpretation

• Statuses are open, in_progress, blocked, deferred, closed — there is no rework status. A rework cycle stays in_progress and is tracked via a failing br gate report result plus a br comments note, not a status change.
• br ready lists only issues that are open (or configured ready statuses), unblocked, and not deferred.
• br list --json returns {"issues": [...], "total": N, "limit": N, "offset": N, "has_more": bool}.
• Issue ids follow <project-prefix>-<short-code> (this repo's prefix is basicly, set during br init).

Why It Matters For Agents

• br is the single source of truth for what work exists, what is blocked, and what is safe to pick up next — always check br ready before assuming there is nothing to do or duplicating an existing issue.
• Referencing the issue id in every commit links code history to tracked intent, which is enforced mechanically (not just by convention) via the beads-commit-msg hook.

Repo Conventions

• Every commit message must reference at least one valid beads issue id (enforced by .basicly/core/hooks/beads-commit-msg.py); conventional commit format is still required separately (enforced by .basicly/core/hooks/commit-msg.py).
• Reference an id as a parenthetical after the conventional commit description, e.g. feat(basicly): add fragment loader (basicly-idr).
• Create an issue (br create or br q) before referencing it; do not fabricate ids.
• Issue prefix is basicly (pinned in .beads/config.yaml, so every clone/init matches); default priority is 2 (Medium) and default type is task.
• Let br generate the id — do NOT pass --slug. Ids must stay single-hyphen basicly-<hash>; a multi-hyphen slug id (e.g. basicly-my-thing-9li) is rejected by the commit-msg hook and breaks the id-parenthetical convention.
• Priority scale (0=Critical, 4=Backlog): use 0/1 sparingly for release-blocking or next-up work; 2 for normal work; 3/4 for low-urgency/backlog items.
• Type taxonomy is br's canonical enum (epic, feature, task, bug, chore, docs, question) — there is no separate "story"/"sub-task" type. Express hierarchy with br create --parent <id> (e.g. epic → feature/task/bug children) instead of inventing a new type.

Trigger Examples

• Should trigger: "What should I work on next in this repo?"
• Should trigger: "Create an issue for the flaky test and start working on it."
• Should trigger: "I'm about to commit — what beads id should I reference?"
• Should not trigger: "Explain how git rebase works."