docs: notification routing guide by diberry · Pull Request #646 · bradygaster/squad

diberry · 2026-03-27T01:52:32Z

Concise docs page for multi-channel notification routing — pub-sub architecture, provider-agnostic design, severity-based routing rules.

Closes diberry#50

@bradygaster — new docs page for notification routing (142 lines, concise per your preference). 3 files: doc, nav entry, test entry.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

…er#650) * feat: REPL UX polish — figlet banner, proper-case names, keyword emoji, 80-col wrap, activity hints - Add figlet ASCII art SQUAD banner in header (App.tsx) - Fix agent name casing: SessionRegistry uses case-insensitive keys, preserves display names (sessions.ts) - Add keyword-based role emoji fallback matching in getRoleEmoji (lifecycle.ts) - Add extractAgentHint() to parse coordinator text for specific task descriptions (index.ts) - Cap content width at 80 columns across App.tsx, MessageStream.tsx, AgentPanel.tsx - Remove [system] prefix from system messages in MessageStream - Add slash command passthrough while processing (InputPrompt.tsx) - Pin header to top via Ink Static block, simplified header content - Register agents with proper case names, use display names in activity hints - Update tests: 192 passing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: wire REPL telemetry — EventBus bridge, StreamingPipeline, agent metrics, model display Wire all defined OTel instrumentation into the REPL code path: - Pass EventBus to initSquadTelemetry() so EventBus→OTel bridge activates (bradygaster#645) - Instantiate StreamingPipeline and feed message_delta/usage events for token and response latency metrics (TTFT, duration, tokens/sec) (bradygaster#646) - Call recordAgentSpawn/Duration/Error/Destroy from dispatch handlers (bradygaster#647) - Add model field to AgentSession, display model name in AgentPanel (bradygaster#648) - Enable shell metrics when OTel endpoint is configured (no longer requires SQUAD_TELEMETRY=1) (bradygaster#649) - Export RuntimeEventBus from SDK barrel for REPL consumption - Listen for usage events to capture model name and feed to StreamingPipeline - Update tests: replace stale [WORK]/[STREAM] assertions, update banner/header checks for figlet art, update source-code parsing tests for simplified header Closes bradygaster#644, bradygaster#645, bradygaster#646, bradygaster#647, bradygaster#648, bradygaster#649 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds a new docs page describing notification routing and wires it into the docs site navigation and build validation.

Changes:

Added notification-routing feature doc page.
Linked the new page in the docs navigation.
Updated docs build test to expect the new generated page.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
`docs/src/content/docs/features/notification-routing.md`	New documentation page for notification routing concepts and configuration examples.
`docs/src/navigation.ts`	Adds “Notification Routing” to the Features nav list.
`test/docs-build.test.ts`	Ensures the docs build output includes the new `notification-routing` page.

Copilot · 2026-03-27T21:53:08Z

+Routing rules are defined in `.squad/notification-routes.yaml`:
+
+```yaml


This page documents a built-in routing config file (.squad/notification-routes.yaml) and rule engine, but there’s no corresponding config/implementation anywhere in the repo (search shows the only occurrences are in this new doc). As written, this will mislead users into thinking notification routing is a shipped feature; either align the doc with the current MCP-based notifications architecture (routing handled by the user’s MCP notification server / external system), or add the actual config + parser + runtime support.

Suggested change

Routing rules are defined in `.squad/notification-routes.yaml`:

```yaml

Squad does **not** currently ship a built-in routing engine or a `.squad/notification-routes.yaml` file.

Instead, Squad agents emit structured notification events (via MCP) to your own notification/alerting stack

(for example, a Slack bot, PagerDuty bridge, or custom MCP notification server), and **that external system**

is responsible for routing messages to the right channels.

Below is an example of how a **custom notification server** that consumes Squad events might model routing

rules. This configuration lives in your notification infrastructure, not in Squad itself:

```yaml

# squad-notifications.yaml (example for your notification server)

Fixed — Reframed config framing to clarify that Squad emits MCP events, not built-in YAML routing. Updated to reflect that notification routing is handled by the user's MCP notification server/external system.

Copilot · 2026-03-27T21:53:09Z

+Use the CLI to test a routing configuration:
+
+```bash
+squad notification-routes validate
+squad notification-routes test --agent ralph --severity critical
+```


The CLI commands squad notification-routes validate/test don’t appear to exist in the codebase (no matches under packages/ or existing docs). Please remove/replace these with the actual way to test notifications (e.g., validating your MCP server / sending a sample notification) or implement the documented CLI surface.

Suggested change

Use the CLI to test a routing configuration:

```bash

squad notification-routes validate

squad notification-routes test --agent ralph --severity critical

```

After defining your routing rules and destinations, test them by triggering sample notifications from your agents (or MCP servers) and verifying where they land.

- Start a staging or test environment.

- Trigger notifications with different severities, agents, and topics (for example, from Ralph or another agent).

- Confirm that each notification is delivered to the expected channels (Slack, Teams, webhooks, etc.) based on your routing rules.

Fixed — Removed non-existent CLI commands (squad notification-routes validate/test). Updated to reflect how users actually test notifications through their MCP server configuration.

Copilot · 2026-03-27T21:53:09Z

+**Match operators:**
+- **Exact match:** `severity: critical`
+- **List match (OR):** `severity: [critical, warning]`
+- **Wildcard:** `agent: ralph*` (matches ralph-1, ralph-staging, etc.)
+- **Negation:** `NOT severity: debug`


The match syntax described here (wildcards like agent: ralph* and especially NOT severity: debug) isn’t valid YAML as shown and isn’t implemented anywhere. If routing is intended to be user-implemented (MCP server), consider reframing this section as conceptual examples (or remove it) so it doesn’t imply a supported DSL/config format.

Suggested change

**Match operators:**

- **Exact match:** `severity: critical`

- **List match (OR):** `severity: [critical, warning]`

- **Wildcard:** `agent: ralph*` (matches ralph-1, ralph-staging, etc.)

- **Negation:** `NOT severity: debug`

**Match operators (conceptual):**

- **Exact match:** `severity: critical`

- **List match (OR):** `severity: [critical, warning]`

- **Wildcard (conceptual):** pattern-based matches, for example treating `"ralph*"` as matching `ralph-1`, `ralph-staging`, etc.

- **Negation (conceptual):** rules that match when a field does **not** have a given value, for example severity is anything except `debug`.

Fixed — Reframed wildcard syntax as conceptual examples. Clarified that the match syntax shown are examples for users implementing their own MCP notification server, not a built-in DSL.

Copilot · 2026-03-27T21:53:09Z

+- [Notifications](/docs/features/notifications/) — Message templates and formatting
+- [Ralph](/docs/features/ralph/) — Load testing agent


These internal links use an absolute /docs/.../ path, but the rest of the docs use relative .md links (e.g., ../features/notifications.md). To avoid broken links depending on Astro base path, update these to the repo’s standard relative link style (e.g., notifications.md, ralph.md).

Suggested change

- [Notifications](/docs/features/notifications/) — Message templates and formatting

- [Ralph](/docs/features/ralph/) — Load testing agent

- [Notifications](notifications.md) — Message templates and formatting

- [Ralph](ralph.md) — Load testing agent

Fixed — Changed absolute links to relative links (e.g., notifications.md, ralph.md) to match the repo's standard relative link style and avoid broken links from Astro base path issues.

bradygaster · 2026-03-27T22:44:35Z

@diberry going to let you handle these items from copilot

Concise docs page for multi-channel notification routing. Covers pub-sub routing, supported providers (Slack, Teams, Discord, webhooks), routing rules configuration, and real-world severity-based routing example. - Added notification-routing.md with ~140 lines - Updated navigation.ts to include new feature page - Updated test/docs-build.test.ts with 'notification-routing' in EXPECTED_FEATURES Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

diberry · 2026-03-28T14:44:55Z

Closing -- will re-open via fork-first pipeline when fully polished.

This was referenced Mar 27, 2026

docs: notification routing guide diberry/squad#57

Closed

content: Taming Agent Alert Fatigue: Multi-Channel Notification Routing diberry/squad#50

Closed

bradygaster requested a review from Copilot March 27, 2026 21:49

Copilot started reviewing on behalf of bradygaster March 27, 2026 21:50 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

diberry marked this pull request as draft March 28, 2026 14:13

diberry force-pushed the squad/50-notification-routing-docs branch from 1bef5e0 to a086eba Compare March 28, 2026 14:17

diberry force-pushed the squad/50-notification-routing-docs branch from a086eba to fa8c86f Compare March 28, 2026 14:20

diberry closed this Mar 28, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: notification routing guide#646

docs: notification routing guide#646
diberry wants to merge 1 commit intobradygaster:devfrom
diberry:squad/50-notification-routing-docs

diberry commented Mar 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

diberry Mar 28, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

diberry Mar 28, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

diberry Mar 28, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

diberry Mar 28, 2026

Uh oh!

bradygaster commented Mar 27, 2026

Uh oh!

diberry commented Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		Routing rules are defined in `.squad/notification-routes.yaml`:

		```yaml

-Routing rules are defined in `.squad/notification-routes.yaml`:
-```yaml
+Squad does **not** currently ship a built-in routing engine or a `.squad/notification-routes.yaml` file.
+Instead, Squad agents emit structured notification events (via MCP) to your own notification/alerting stack
+(for example, a Slack bot, PagerDuty bridge, or custom MCP notification server), and **that external system**
+is responsible for routing messages to the right channels.
+Below is an example of how a **custom notification server** that consumes Squad events might model routing
+rules. This configuration lives in your notification infrastructure, not in Squad itself:
+```yaml
+# squad-notifications.yaml (example for your notification server)

-Use the CLI to test a routing configuration:
-```bash
-squad notification-routes validate
-squad notification-routes test --agent ralph --severity critical
-```
+After defining your routing rules and destinations, test them by triggering sample notifications from your agents (or MCP servers) and verifying where they land.
+- Start a staging or test environment.
+- Trigger notifications with different severities, agents, and topics (for example, from Ralph or another agent).
+- Confirm that each notification is delivered to the expected channels (Slack, Teams, webhooks, etc.) based on your routing rules.

		- [Notifications](/docs/features/notifications/) — Message templates and formatting
		- [Ralph](/docs/features/ralph/) — Load testing agent

Conversation

diberry commented Mar 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

diberry Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

diberry Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

diberry Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

diberry Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

bradygaster commented Mar 27, 2026

Uh oh!

diberry commented Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants