notification-routing

## Context When a Squad grows beyond a few agents, notifications flood a single channel — failure alerts drown in daily briefings, tech news buries security findings, and everything gets ignored. This is the pub-sub problem: a single message queue for everything is a recipe for missed alerts. The fix is **topic-based routing**: agents tag notifications with a channel type, and a routing function sends them to the appropriate destination. **Trigger symptoms:** - Important alerts missed because they're buried in routine notifications - Team members turning off notifications entirely (signal overwhelm) - Onboarding friction: "where do I look for X?" ## Patterns ### Channel Config Schema Define a `.squad/teams-channels.json` (or equivalent) mapping notification types to channel identifiers: ```json { "teamId": "your-team-id", "channels": { "notifications": "squad-alerts", "tech-news": "tech-news", "security": "security-findings", "releases": "release-announcements", "daily-digest": "daily-digest" } } ``` Place this in `.squad/` (git-tracked, shared across the team). For platforms that use channel IDs instead of names (Teams, Slack), store the resolved ID alongside the name to avoid name-collision bugs: ```json { "channels": { "notifications": { "name": "squad-alerts", "id": "channel-id-opaque-string" } } } ``` ### CHANNEL: Tag Convention Agents prefix their output with `CHANNEL:<type>` to signal where the notification should go: ``` CHANNEL:security Worf found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5 ``` ### Routing Dispatcher (shell pseudocode) ```bash dispatch_notification() { local raw_output="$1" local channel="notifications" # default if echo "$raw_output" | grep -qE '^CHANNEL:[a-z][a-z0-9-]*'; then channel=$(echo "$raw_output" | head -1 | cut -d: -f2) raw_output=$(echo "$raw_output" | tail -n +2) fi send_notification --channel "$channel" --message "$raw_output" } ``` ### Provider-Agnostic Adapter The routing layer is provider-agnostic. Plug in your platform adapter: ``` .squad/notify-adapter.sh # Teams / Slack / Discord / webhook -- swappable ``` The routing config and CHANNEL: tags never change. Only the adapter changes per deployment. ## Anti-Patterns **Never send all notification types to one channel:** ``` send_notification --channel "general" --message "$anything" ``` **Never use display names as identifiers (name collision risk):** ``` send_to_team --name "Squad" --channel "notifications" ``` Resolve channel IDs once at setup. Use IDs at runtime. ## Distributed Systems Pattern This is **pub-sub with topic routing** -- the same principle as Kafka topics, RabbitMQ routing keys, and AWS SNS topic filtering. Route by type. Each consumer subscribes to the topics it cares about.