ensemble AGENTS.md

Agent Instructions

Beads Workflow Integration

This project uses beads_rust (br) for issue tracking and beads_viewer (bv) for graph-aware triage. Issues are stored in .beads/ and tracked in git.

Using bv as an AI sidecar

bv is a graph-aware triage engine for Beads projects (.beads/beads.jsonl). Instead of parsing JSONL or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).

Scope boundary: bv handles what to work on (triage, priority, planning). br handles creating, modifying, and closing beads.

CRITICAL: Use ONLY --robot- flags. Bare bv launches an interactive TUI that blocks your session.*

The Workflow: Start With Triage

bv --robot-triage is your single entry point. It returns everything you need in one call:

• quick_ref: at-a-glance counts + top 3 picks
• recommendations: ranked actionable items with scores, reasons, unblock info
• quick_wins: low-effort high-impact items
• blockers_to_clear: items that unblock the most downstream work
• project_health: status/type/priority distributions, graph metrics
• commands: copy-paste shell commands for next steps

bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick + claim command

# Token-optimized output (TOON) for lower LLM context usage:
bv --robot-triage --format toon

Other bv Commands

Command	Returns
--robot-plan	Parallel execution tracks with unblocks lists
--robot-priority	Priority misalignment detection with confidence
--robot-insights	Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core
--robot-alerts	Stale issues, blocking cascades, priority mismatches
--robot-suggest	Hygiene: duplicates, missing deps, label suggestions, cycle breaks
--robot-diff --diff-since <ref>	Changes since ref: new/closed/modified issues
--robot-graph [--graph-format=json|dot|mermaid]	Dependency graph export