Prerequisites

Step 1 — Detect br:

Always check for br before doing anything else:

command -v br >/dev/null 2>&1

If the command succeeds, br is available — skip straight to the workflow sections below.

Step 2 — If br is not found:

Tell the user:

br (beads_rust) is required but was not detected on this system.

Then offer to install it via the recommended curl command. Ask clearly and wait for explicit approval — do not run the installer without consent.

Recommended install command (run only after user approves):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash

After the install completes, verify success:

command -v br >/dev/null 2>&1

If verification fails, report the failure and stop.

Step 3 — If the user declines the install:

Show the manual alternatives below and stop — do not proceed without br.

Manual install via cargo:

cargo install --git https://github.com/Dicklesworthstone/beads_rust.git

Manual install from source:

git clone https://github.com/Dicklesworthstone/beads_rust.git
cd beads_rust
cargo build --release
cargo install --path .

Beads Rust

Use br as the source of truth for issue state. Prefer machine-readable output (--json) for analysis and deterministic updates.

Use this skill when the request involves issue operations in a repo that uses .beads, including:

• •creating issues
• •triaging backlog
• •updating priority/status/labels/parent
• •linking or removing dependencies
• •closing/reopening with evidence
• •summarizing ready/blocked queue impact

Core Rules

1. •Read first, mutate second. Use br show <id> --json to inspect before updating.
2. •Prefer --json whenever available.
3. •Resolve actor at runtime and pass it via --actor; do not ask the user to edit files.
4. •Keep changes minimal and scoped to requested issues.
5. •Recompute queues after bulk changes.
6. •Make closure reasons concrete and auditable.
7. •--format toon is a token-optimized alternative to --json for context-window-sensitive agents. Use --json as the safer default.

Actor Resolution

The agent should choose actor automatically for each mutation batch:

• •if BR_ACTOR is set, use it
• •otherwise use a stable assistant identity (for example model/agent name)
• •fallback to assistant

Example runtime setup (agent-executed, not user-edited):

ACTOR="${BR_ACTOR:-assistant}"

Use "$ACTOR" in mutating commands.

Verify Workspace

Before any update:

br where
br ready --json
br blocked --json
br list --status open --sort priority --json

If workspace context is wrong or unclear, stop before mutating.

Standard Workflow

For triage batches:

1. •Capture baseline (ready, blocked, open list).
2. •Classify each targeted issue.
3. •Apply scoped updates.
4. •Recompute queues.
5. •Report IDs changed and queue deltas.

For single-issue tasks:

1. •Verify workspace.
2. •Inspect the issue: br show <id> --json.
3. •Apply requested mutation.
4. •Read back state (--json) to confirm.
5. •Report exact change and rationale.

Triage Decision Matrix

Use one classification per issue:

• •implemented
  • •close with implementation evidence (commit/PR/file/observable behavior)
• •out-of-scope
  • •close with explicit boundary reason
• •needs-clarification
  • •comment with specific unanswered questions
• •actionable
  • •keep open and correct status/priority/labels/dependencies

During large triage efforts, checkpoint every few updates:

br ready --json
br blocked --json

Create High-Quality Issues

Bug issues should include:

• •concise summary
• •reproduction steps
• •expected vs actual
• •environment/context
• •logs or crash pointers

Task/feature issues should include:

• •objective
• •acceptance criteria
• •constraints and non-goals
• •dependencies or parent linkage

For rapid capture when only a title is needed, use br q "<title>" to get an ID quickly.

Reference command templates:

• •references/command-cookbook.md

Update Patterns

Use small idempotent mutations:

ACTOR="${BR_ACTOR:-assistant}"
br update --actor "$ACTOR" <id> --priority 2 --status in_progress --json
br update --actor "$ACTOR" <id> --add-label reliability --json
br update --actor "$ACTOR" <id> --parent <parent-id> --json
br comments add --actor "$ACTOR" <id> --message "<triage note / evidence>" --json

Multiple IDs can be passed to br update for batch triage:

br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json

Prefer comment-first when facts are incomplete.

Dependency Hygiene

Use explicit dependencies to keep ready/blocked accurate.

Rules:

• •add blocks only for real execution ordering constraints
• •remove stale dependency links promptly
• •verify dependency effects after changes

Commands:

br dep add <issue-id> <depends-on-id> --type blocks
br dep rm <issue-id> <depends-on-id>
br dep list <issue-id> --json
br blocked --json

Closure Standard

Before closing an issue:

1. •provide evidence artifact (commit/PR/path/observed behavior)
2. •state what was verified
3. •use precise --reason

Close/reopen patterns:

ACTOR="${BR_ACTOR:-assistant}"
br close --actor "$ACTOR" <id> --reason "<specific reason with evidence>" --json
br reopen --actor "$ACTOR" <id> --reason "<reason for reopening>" --json

If confidence is low, add clarification comments instead of closing.

For milestone issues, summarize unmet criteria in a comment before closure decisions.

Reporting Format

When reporting work, include:

1. •changed issue IDs and exact mutations
2. •reason for each meaningful change
3. •queue impact (ready, blocked)
4. •explicit follow-ups needed

Preferred response shape:

Updated:
- <id>: <change>

Closed:
- <id>: <reason + evidence>

Queue impact:
- ready: <summary>
- blocked: <summary>

Needs input:
- <id>: <question>

Safety Guardrails

• •Do not modify unrelated issues.
• •Do not invent evidence for closure.
• •Do not add speculative dependencies.
• •Re-run reads with --json when output is ambiguous.
• •Prefer reversible updates over broad, risky edits.

Quick Command Reference

Use references/command-cookbook.md for concise copy/paste command patterns.