bro-herdr — the herdr orchestration playbook
Contract for any agent (bro or otherwise) orchestrating agent sessions
through the herdr CLI. The herdr skill owns command reference; this
playbook owns the five failure modes that silently lose work. Control
commands require HERDR_ENV=1.
1. /goal is a prompt position, not a prompt
Every prompt sent to a herdr agent session begins with /goal —
a kind's native goal-mode fires on the trigger at position zero, and
any leading prose (a greeting, a heading, even Here is your task:)
makes it plain text the session never parses as a goal.
The goal names the completion gate, never a milestone:
/goal `bro review act status` reports exit_gate=OK and the PR is merged
"open a PR" is a step, not a gate — a goal of "PR open" ends the run
before review even starts. The gate is what bro review act status
declares, then the merge.
2. A busy pane queues — nothing delivers until CR
send-keys text to a pane already working lands in the session's
composer queue, not the conversation. It sits there until the
current turn ends. Two send modes, deliberately:
- queue — send the text without Enter; it waits for the running turn (status updates, next-step instructions).
- immediate — send the text followed by
send-keys <pane> C-m(carriage return). The CR commits the queued text now.
Never assume a sent prompt was read. If the pane was busy and you needed it handled, the delivery is the CR, not the text.
3. report-agent binds to a live pane, or it reports nothing
report-agent binds identity to a live pane process. The binding
is process-scoped: a dead pane (exited shell, killed tmux, closed
workspace) silently drops every report — no error, no queue, no
complaint. Verify the pane is live before reporting, or the status
update vanishes.
Valid report states: idle · working · blocked · unknown.
There is no done — completion is asserted from the workspace/PR
gate (rule 1), never claimed as an agent state.
4. Metadata tokens are write-only — the label is the display
report-metadata tokens persist server-side but the UI renders
nothing. Do not rely on them for human-visible status. The visible
status surface is the workspace label — set status there (via the
label mechanism), in addition to the metadata, when a human needs to
see it. Metadata is for programmatic readers; the label is for people.
5. Teardown has one order — close, verify, worktree, branch, remote
- Close the workspace — ends the panes; rule 3's binding dies here.
- Verify the agent is gone — no live pane, no reportable process.
git worktree remove <path>— only after the agent that owned it is dead.git branch -D <branch>— the worktree's branch, now unreferenced.- Remote check —
git ls-remote/gh pr listfor the branch and its PR: a pushed branch or an open PR means the close isn't clean.
Reordering (branch -D before worktree remove, remote check skipped) leaves half-closed state that the next session trips on.