millerson-overlay.nix/docs/agents/issue-tracker.md

Issue tracker: br (beads_rust)

Issues and specs for this repo live in the beads database at .beads/. The source of truth is .beads/issues.jsonl, managed through the br CLI (v0.7.6). beads state is versioned in the repo and synced with git push; there is no separate Dolt remote.

Note: br is non-invasive and never executes git commands. After br sync --flush-only, you must manually run git add .beads/ && git commit.

The forge remote (git.millerson.name, self-hosted Gitea) is not the issue tracker. Do not open Gitea, GitHub, or GitLab issues for work in this repo.

Core commands

br robot-docs guide    # session context and command reference (run first)
br ready               # open issues with no active blockers
br show <id>           # full issue detail
br list                # list issues
br search "<text>"     # text search
br create "title" -d "description" -p 2 -l label1,label2
br q "quick capture"   # create and print only the id
br update <id> --claim # claim before starting work
br close <id> --reason "..."
br reopen <id>
br comments add <id> "..."          # conversation history
br update <id> --append-notes "..." # append to the issue notes field
br label add <id> <label>
br label remove <id> <label>
br label list <id>
br status              # database overview

Issue ids look like nix-overlay-4g1. New work must be claimed with br update <id> --claim before it starts.

When a skill says "publish to the issue tracker"

Run br create. Use one issue per ticket. Put the full body in --description (markdown is fine). Add labels per triage-labels.md. For a multi-part spec, create a parent issue and link children with --deps.

When a skill says "fetch the relevant ticket"

Run br show <id> and read the description. Use br show <id> --json for machine-readable output, and br comments list <id> for the comment thread. The user normally passes the issue id directly.

Dependencies

br create --deps 'blocked-by:nix-overlay-4g1,discovered-from:nix-overlay-2a3'

Bare ids, blocked-by: and discovered-from: all make the new issue depend on the target. depends-on: is not a valid br dependency type and is rejected. br dep add <issue> <depends-on> adds a dependency after creation, br dep list <issue> shows the graph, and br dep tree <issue> shows it as a tree. br ready already excludes anything with an unresolved blocker, so a ticket is unblocked when every issue that blocks it is closed.

Wayfinding operations

Used by /wayfinder. The map is a parent bead; the children are its sub-issues.

• Map: a bead created for the effort. Its description holds the Notes / Decisions-so-far / Fog body.
• Child ticket: a bead created with --parent <map-id>, which links it to the map as a parent-child dependency (br ids the child <map-id>.1). The question goes in the description. Record the ticket type as a label (research, prototype, grilling, task).
• Blocking: a blocked-by:<id> dependency on the blocking bead.
• Frontier: br ready output, restricted to children of the map (br list --tree groups children under their parent, or filter br ready by label). Lowest priority number, then oldest, wins.
• Claim: br update <id> --claim before any work starts.
• Resolve: append the answer with br update <id> --append-notes "..." or br comments add <id> "...", then br close <id> --reason "<answer gist>", then add a context pointer (gist plus issue id) to the map's Decisions-so-far with br comments add <map-id> "...".

Session end

Work is not complete until pushed. The project workflow requires:

git pull --rebase
br sync --flush-only    # export issue state to .beads/issues.jsonl
git add .beads/
git commit -m "sync beads"
git push
git status              # must show up to date with origin