Why bro
The problem bro solves — agent workflows are mechanics, not prompts.
Agents are good at judgment and bad at bookkeeping. Prompts try to carry both — and the bookkeeping parts ("remember to check for unresolved threads", "don't stop while a drill frame is open", "sweep merged PRs") rot the moment the conversation drifts.
bro's bet: mechanics belong in a CLI, policy belongs in a skill, and neither belongs inline in a prompt.
bro is not a plugin — it's a system. The CLI is the mechanics; the client plugins are transport; hooks put the state back in front of the agent at every lifecycle boundary; skills carry the policy; connectors swap the backends (review host, task store, agent plane, events); the judge and guards decide and nudge. Remove any layer and the prompt has to carry it again — that's the rot bro exists to prevent.
And bro is developed by bro itself: a bead becomes a convoy becomes a
PR, act gates the merge, debt sweeps what reviewers left behind,
learn keeps the lesson. The dogfood is the design review.
The shape of every capability
Each feature ships the same four parts:
- a CLI subcommand — the mechanics, testable and deterministic
- an agent skill — the policy, readable markdown the agent follows
- a config section — the knobs, validated and defaulted
- a plan schema — structured input, validated before it runs
Why beads is a default store
bro review debt collect creates .beads/ in a repo that doesn't have one —
on purpose. The jsonl ledger is evidence; beads is the work queue
(bd ready -l debt, drill frames, bro flow next). An opt-in default would
fill the ledger and starve the queue until the user found a config key —
and bd is required by the task commands anyway, so opting out only
defers the dependency to a later, less predictable failure.
The init is stealth: .beads is written to .git/info/exclude, nothing
lands in git, no hooks or AGENTS.md edits, and rm -rf .beads reverses
it — the same machine-local contract as .agents/review-debt/ and the
gitignored bro.config.local.json. It announces itself on stderr; a tool
that wants adoption doesn't get to be silent about writing to your repo.
Opt out once: "stores": ["jsonl"] in the local layer —
bro.config.local.json, or bro.config.local.ts where one exists (it
shadows the JSON).
What it doesn't do
bro doesn't fix your code. bro doesn't write essays in your PRs. bro collects what's owed, keeps the books clean, and waits.
bro got you.