theplenkov/bro

Use when an ACP client (Zed, JetBrains, Neovim, or any * acp agent binary) should sit behind bro's hook seam instead of talking to the agent directly — bro acp proxy -- <agent cmd> is the cascading edge: verbatim forwarding plus session context on the first prompt. Thin wrapper over the bro CLI — mechanics live in the CLI.

Use when the user invokes /act on an open PR or a 'bro: PR #N ...' status ping arrives — the review-fix loop. Thin wrapper over the bro CLI: bro review act status is the exit gate as code; resolve/reply are mutations. Requires bro (npx -y @broject/bro@0) and gh.

Use when supervising bro-managed agents — respawn a lost worker, stop one, or check the agent plane across orchestrator connectors. Thin wrapper over bro fleet agents — mechanics live in the CLI.

Use when driving herdr agent sessions — sending a session a prompt, reading agent status, reporting agent state, or tearing a worktree down. The orchestration playbook: /goal-first prompts, composer-queue delivery, live-pane report binding, invisible metadata tokens, and the five-step teardown order.

Use when the repo has a sverka workflow (sverka.config.ts) or the user asks to run checks/scans through bro. Thin wrapper over bro check — mechanics live in the CLI; this skill carries policy only.

Use when the user invokes /convoy or asks to run a beads workflow — a molecule's DAG of steps executed inside the agent. Thin wrapper over the bro CLI: bro flow convoy next is the scheduler as code; bro flow convoy done advances it. Requires bro (npx -y @broject/bro@0) and bd.

Use when the project needs a supervisor that outlives the session — 'run the review loop forever', 'keep the fleet owned', bro fleet daemon up. The daemon is the long-lived process owner; bro review watch is the bounded observer that watches it; bro fleet serve is the UI surface. Thin wrapper over the bro CLI — mechanics live in packages/cli/src/commands/daemon.ts and drive.ts. Requires bro (npx -y @broject/bro@0) and the configured review-host CLI.

Use when the user invokes /debt or asks about review debt on merged PRs. Thin wrapper over the bro CLI — all mechanics live in bro review debt * commands; this skill carries policy only. Requires bro (npx -y @broject/bro@0) and gh.

Use when an agent needs another agent — ask a question synchronously or hand off real work. bro fleet delegate is the one contract: --wait is a pooled ACP turn for short asks, --detach a registry spawn for real work. Thin wrapper over the bro CLI — mechanics live in the CLI.

Use when reading or mutating bro documents directly — tasks (beads) and stores — through the verb-first bro <verb> <noun|ref> surface. Also covers the user-level global task store. Thin wrapper — mechanics live in the CLI.

Use when running bro's scenario-driven e2e self-test — a committed markdown runbook executed by a fresh registry agent in a scratch repo, then judged by a second agent that writes verdict.md. Thin wrapper over the bro CLI: bro self dogfood run|status|report|scenarios does the work. Requires bro (npx -y @broject/bro@0) and a configured agents.* backend for the runner/analyst spawns.

Use when the user invokes /drill or /unwind, or when a task needs scoped descent — narrower investigation frames with mandatory result+prevention memos. Thin wrapper over the bro CLI: drill frames are beads; bd owns storage, bro work drill owns the invariants. Requires bro (npx -y @broject/bro@0) and bd.

Use when orphaned PRs need an owner — 'drive the review loop', 'watch the PRs and fix them', a post-PR supervisor. Thin wrapper over the bro CLI: bro review drive polls act exit gates, spawns fixer agents through the facade, and merges on green. Requires bro (npx -y @broject/bro@0), bd, and the configured review-host CLI (for example, gh or glab).

Use when a shell command's result must reach the session that launched it — long builds, test runs, delayed jobs the agent should hear land. Thin wrapper over the bro CLI: bro exec <cmd> runs the command under sh -c and fires taskFinish connector probes on exit; the herdr connector's report-back prompts the pane for agent kinds without a native task-exit wake.

Use when the session needs a persistent completion condition it keeps working toward across turns — /goal <condition> sets it, the stop hook reminds (or judge-verdicts) whether it was reached. bro work goal is the scriptable, cross-host surface (CI, spawned workers, hosts without a native command). Requires bro (npx -y @broject/bro@0).

Use when a declarative prompt contribution should fire on a hook event — a nudge conditioned on worktree state, session markers, or a judge verdict. Thin wrapper over the bro CLI: bro self guard list inspects what's armed, bro self guard test dry-runs a def against live state. Requires bro (npx -y @broject/bro@0).

Use when an agent orchestrates worker agents through Herdr — spawn an isolated worktree workspace per task, start any supported agent kind in it, brief it, wait on semantic state, verify the gate, tear down. Provider-agnostic: the mechanics are herdr CLI + git worktrees; any supported agent kind is an interchangeable worker. Covers the spawn sequence, blocking waits, label-vs-state semantics, sequential budget, and teardown order. In a bro-managed repo, spawn through bro fleet agents/bro flow convoy instead — this recipe is for herdr-only environments and herdr plugin internals.

Use when judging calibrated decisions for agent loops — act triage annotation, fallback escalation. Thin wrapper over the bro CLI: bro self judge decide smokes the connector; the systemone → llm-judge chain lives in packages/judge. Requires bro (npx -y @broject/bro@0); the default systemone backend needs a TypeSafe API key, llm-judge needs its own judge.llm config.

Use when a lesson should outlive the session — 'remember this for next time', capturing a drill/retro/review finding, or asking whether the store already knows the answer. Thin wrapper over the bro CLI: bro self learn is the lesson store; the learn connector injects matched lessons at session-start, prompt-submit, and post-tool. Requires bro (npx -y @broject/bro@0) and bd.

Use when the user wants the backlog worked autonomously end-to-end — 'run the backlog', 'bro flow loop', a hands-off /goal over open beads. Unlike /next (one scheduling step), bro flow loop IS the loop: bro claims each ready bead, spawns the configured agent in a fresh worktree, drives the act gate, closes the bead, repeats. Requires bro and bd; the agent is a providers.<name> entry (loop.provider/--provider, acp = headless) or a raw loop.agent template.

Use when an MCP-capable client (Windsurf, Zed, Goose, Gemini CLI, Copilot, Claude Desktop) should read bro orchestration state as tools instead of shelling bro and parsing text — bro fleet mcp is the stdio server over the read planes. Thin wrapper over the bro CLI — mechanics live in the CLI.

Use when federating work between bro rigs — mesh:// identity, peer bindings over local checkouts or beads-remote dolt replicas, the request → claim → done → accept/reject lifecycle, and bro mesh inbox|wait. Thin wrapper over bro mesh — mechanics live in the CLI (spec: specs/mesh/spec.md).

Use when the user says 'work the backlog', 'clean the queue', invokes /next, or sets a /goal over open beads — the autonomous backlog loop. Thin wrapper over the bro CLI: bro flow next is the scheduler as code — it claims the top ready bead and emits the work order. Requires bro (npx -y @broject/bro@0) and bd.

Use when a background worker, watcher, or fixer must reach live sessions mid-turn — 'notify me when done', mailbox events, child→parent signaling. Thin wrapper over the bro CLI: bro comms notify <text> drops an atomic event; the notify connector's postTool probe delivers unseen drops into session context. Requires bro (npx -y @broject/bro@0).

Use when enabling, inspecting, or debugging bro's hook-first telemetry — 'which hooks fire in this repo', 'send hook events to an OTLP collector', per-hook payload allowlists, sampling, or reading the file sink. Thin wrapper over the bro CLI: bro otel status|test|on|off — mechanics live in @broject/otel emitHook on the bro hooks dispatch path (spec specs/bro-xgejl.md). Requires bro (npx -y @broject/bro@0).

Use when Claude Code should run ON bro — bro provider serve is the host-level Messages-API listener (ANTHROPIC_BASE_URL target), bro provider ensure self-starts it, and bro provider url|token|env are the one-time wiring helpers. Thin wrapper over the bro CLI — mechanics live in the CLI.

Use when configuring or debugging bro's provider registry — providers in bro.config.json, provider kinds (api/acp/cli), model wire selection, judge.provider / agents.<backend>.provider references, or bro doctor provider rows. Mechanics live in the CLI + @broject/providers; this skill carries the contract and policy only.

Use when a session needs its own watchdog cadence — 'arm the pulse', 'wake me every N', keeping an eye on long-running fleet/loop/convoy work without blind infinite waits. Thin wrapper over the bro CLI: bro pulse <S> is the session-owned metronome — every S seconds it ticks and drops the beat into the mailbox, which is what actually reaches the session mid-turn. Requires bro (npx -y @broject/bro@0).

Use when writing or running a kind = "query" plan — cross-provider GraphQL fan-out over bro connectors (github/gitlab/atlassian), one merged JSON answer. Thin wrapper over bro plan query — mechanics live in the CLI (spec: specs/bro-14h8.1.md).

Use after a host/session restart to recover the rig — dead watches, a recorded-but-dead daemon, loop residue, lost agents, dirty worktrees. bro fleet resume is the post-reboot runbook as one pass. Thin wrapper over the bro CLI — mechanics live in the CLI. Requires bro (npx -y @broject/bro@0).

Use at session end — before the final answer or when the retro-on-stop guard fires. A short self-review checklist: uncommitted work, hand-rolled scripts that could become bro commands or beads, token/call economy, lesson capture, review-debt sweep, state assertions. Requires bro (npx -y @broject/bro@0) and bd.

Use when the rig's own bro install must stay current — 'keep the checkout fresh', a staleness check, the fetch→ff-pull→rebuild poll. Thin wrapper over the bro CLI: bro fleet rig sync is the pass, bro fleet rig install arms the session pulse. Requires bro (npx -y @broject/bro@0).

Use when the repo enables spec-driven development (sdd section in bro.config.json) or asks why bro nudges about missing specs. Thin wrapper over bro spec — mechanics live in the CLI; this skill carries policy only.

Use when a thin client (TUI, webui, IDE) needs the bro facade over HTTP — bro fleet serve hosts the agents/fleet/snapshot planes as JSON on 127.0.0.1. Thin wrapper over the bro CLI — mechanics live in the CLI.

Use when the repo declares agent-skill dependencies (skills.install in bro.config.json) or asks how vendored skills land in .agents/skills/. Thin wrapper over bro skills — mechanics live in the CLI; this skill carries policy only.

Use when work should land as a stacked bead→worktree→PR chain (gh-stack analogue) — bro flow stack push a bead onto a named stack, bro flow stack list the chain, bro flow stack publish registers the PRs as the host's stack, bro flow stack sync after a member merges, bro flow stack merge to land it, bro flow loop --stack to drive it. Thin wrapper over the bro CLI — mechanics live in the CLI.

Use when a thin client (pi extension, TUI, dashboard) needs bro's live project board in one read — active beads, fleet workers, drill frame, PR gate. bro fleet status --json is the contract; --deep adds the act gate (network). Requires bro (npx -y @broject/bro@0).

Use when the user invokes /sweep or asks to prune/dispose of closed beads, archive bead history, or run the harvest pipeline. Thin wrapper over bro work sweep — mechanics live in the CLI (spec: specs/bro-pj2g.1.md).

Use when the user invokes /sync or asks to publish/restore bro artifacts (review-debt ledger, evidence packs) across machines or agents. Thin wrapper over bro work sync — mechanics live in the CLI.

Use when an operator wants the session trace journals in an OTel backend — 'send traces to Langfuse/Phoenix', cost attribution per bead/molecule, or debugging a missing OTLP export. Thin wrapper over the bro CLI: bro trace export pushes unexported journal lines as OTLP/HTTP-JSON spans. Requires bro (npx -y @broject/bro@0).

Build AI-powered software with TypeSafe: small units of AI intelligence you can use like programming primitives. Its System One models, including Jev, turn natural language and application state into typed judgments and probabilities that code can combine. Use when a feature needs programmable common sense, when brainstorming what AI could make possible in an app, or when an LLM prompt-and-parse step could become a structured decision. Applications include routing, ranking, extraction, verification, and interactive experiences; these are starting points, not the limits. Read live docs and cookbooks to find useful patterns and discover new combinations.

Use when supervising parallel convoys/agents — 'watch the fleet', 'what needs attention', a monitor loop over mols/PRs. Thin wrapper over the bro CLI: bro review watch is the deterministic heartbeat — one snapshot of molecules, PR exit gates, and the fleet. Requires bro (npx -y @broject/bro@0) and bd.

Use when starting work in a shared repo, when parallel agent sessions fight over one checkout, or to clean up git worktrees. Thin wrapper over bro work — mechanics live in the CLI.

Use when the user invokes /wtf or vents sharp frustration at the agent's own work. Thin wrapper over the bro CLI — bro wtf captures the complaint as a bead, bro self retrospect record stores a TOML retro plan and fans prevention actions out to beads. Requires bro (npx -y @broject/bro@0) and bd.