notify

/notify (bro)

All mechanics live in the bro CLI. This skill is policy only.

Prereq: bro on PATH or npx -y @broject/bro@0.

What it is

The session mailbox — <git-common-dir>/bro/notify/ inside a repo (shared across linked worktrees via the common git dir), the XDG state dir ($XDG_STATE_HOME, default ~/.local/state) outside one. bro comms notify <text> writes one atomic drop (tmp+rename); the notify connector's postTool probe delivers it into session context — real-time child→parent events with no tokens spent in a wait loop.

Command	What it does
bro comms notify <text>	Drop an event into the mailbox — delivered to every session's next postTool probe
bro comms notify -- <text>	Same, with the text taken verbatim — needed when it contains option-looking words like --help

Policy

• Delivery is pull-based. A drop never wakes a sleeping session — it lands in context on the session's next tool call (the postTool probe). Reaching an idle parent needs its own tool cadence (a bare-sleep holder), not a louder drop.
• Write, don't wait. A worker that finished early, a watcher that saw a transition, a fixer that needs attention — bro comms notify the event and get on with it; never poll the parent for attention.
• Events, not streams. Each drop should be self-contained — the drain renders it verbatim into context. A dropped bro review watch snapshot is one event; so is a one-line step X merged.
• Once per session, not once total. The mailbox is broadcast: a drop reaches every live session exactly once (per-session .seen cursor) and expires after ~1h. Writing an event your own session ends up seeing is normal — the echo is delivery confirmation, not a lost message.
• Fire-and-forget is honest. If the event needs an answer, say what you need in the drop — the mailbox has no reply channel.

Sinks — the human edge

The mailbox reaches agents; notify.sinks webhooks reach PEOPLE. Config routes by event type (topic or topic:kind, * globs), secrets come from env (urlEnv/tokenEnv/chatIdEnv name the variable — values never enter config), delivery never blocks the agent (bounded timeout, failures are silent rows). Slack posts {text}, telegram sendMessage, webhook the raw event JSON.

Emissions built in: convoy HUMAN GATE (convoy:gate), drive stuck-PR and silent-reviewer alerts (drive:alert), act wait settles (act:block / act:result), wtf/retro captures (wtf:note / retro:result).

Command	What it does
bro sinks list	Resolved sinks — type, route patterns, secret env set/unset (never values)
bro sinks test	Deliver a probe event, report per-sink ok/err — verify a webhook before a real event needs it