Skip to main content
Routing decides which session receives an event. The conceptual overview lives in triggers and events; this page collects the production rules that keep routing predictable once a factory grows past its first agent. Rules of thumb, all enforced or exercised in this repo’s config:
  • Bind when the artifact is the unit of work. This repo’s PR reviewer binds every PR lifecycle trigger to github.pull_request with onUnmatched: spawn, so one reviewer session owns a PR across heads and re-reviews fold forward on push instead of spawning a fresh review per push.
  • Only some events can bind. An event routes to a binding only if its payload carries a routing target (a PR, issue, or thread). github.push and github.workflow_run.completed carry none — a bind route can never match them; use spawn or deliver.
  • Suppress your own echoes. Chat deliver triggers routed by attributedSessions must filter "$.auto.authored": false — validation rejects the trigger otherwise, because an agent that hears its own messages loops.
  • Make spawn/deliver pairs mutually exclusive. When the same event should spawn on first contact and deliver on follow-ups, split it on $.auto.attributions: { exists: false } (spawn) versus { exists: true } (deliver). Validation enforces this partition; the chat assistant example is the canonical demonstration.
  • Choose onUnmatched deliberately. drop (the default) is right for optional signals like reactions; warn leaves an audit trail; error records the unmatched event as a failure; spawn guarantees the event is handled even when no session matches. Reserve spawn for events that must never be lost.
See the triggers reference for the complete routing schema and the event catalog for which events carry which bind targets.