AGENTS.md Template for Notification System Architecture

Overview

Direct answer: This AGENTS.md template provides a practical operating manual for coordinating AI coding agents in a notification system architecture. It governs single-agent and multi-agent workflows, clarifying roles, handoffs, memory, tool access, and governance to minimize context drift and ensure predictable outcomes.

In this template you’ll find a complete operating context that enables both autonomous agent work and human-in-the-loop oversight for alerting, delivery routing, and channel-specific formatting across email, SMS, and push notifications.

When to Use This AGENTS.md Template

When designing a notification system that relies on AI coding agents to compose, schedule, and deliver messages across channels.
When you require explicit agent roles, handoff rules, and governance to support multi-agent orchestration.
When you need a copyable project-level operating context that teams can paste into an AGENTS.md file.
When ensuring security, secrets, and production discipline is required from the outset.
When you want clear escalation paths and human review touchpoints for quality and compliance.

Copyable AGENTS.md Template

# AGENTS.md

Project: Notification System Architecture using AI coding agents

Agent roster and responsibilities:
- PlannerAgent: designs event flow, channel mapping, queueing, and orchestration.
- ImplementerAgent: implements tasks, integrates with delivery services (Email, SMS, Push), and executes actions.
- ReviewerAgent: validates content, formatting, and channel constraints before delivery.
- ResearcherAgent: checks compliance, rate limits, and policy constraints for each channel.
- DomainSpecialistAgent: handles domain-specific content and channel nuances.

Supervisor or orchestrator behavior:
- OrchestratorAgent coordinates all agents, maintains the global memory map, and enforces the source of truth.
- It triggers retries, backoffs, or escalates to human review on failures or policy violations.

Handoff rules between agents:
- Planner -> Implementer: pass task definitions, channel mapping, and content constraints.
- Implementer -> Reviewer: hand off content payloads for validation.
- Reviewer -> Orchestrator: approve or reject; on rejection, loop back to Planner with feedback.
- Orchestrator -> Planner/DomainSpecialist: adjust strategy based on feedback or failures.

Context, memory and source-of-truth rules:
- Use a centralized NotificationStore as the single source of truth.
- Each agent maintains a scoped memory with a per-run correlation ID; avoid leaking data between runs.
- Log all decisions to an immutable audit log for traceability.

Tool access and permission rules:
- ImplementerAgent may call channel adapters (email, SMS, push) with tokens stored in a secret manager; never log secrets.
- Only the Orchestrator may trigger production sends or write to delivery endpoints without explicit approval.
- All tool calls must be auditable and idempotent.

Architecture rules:
- Event-driven microservice architecture with per-channel adapters and a central orchestrator.
- All messages must be validated against channel schemas before delivery.

File structure rules:
- notifications/
  ├─ agents/
  │  ├─ planner/
  │  ├─ implementer/
  │  ├─ reviewer/
  │  ├─ researcher/
  │  └─ domain-specialist/
  ├─ workflows/
  │  └─ notification-pipeline.yaml
  ├─ adapters/
  │  ├─ email/
  │  ├─ sms/
  │  └─ push/
  ├─ configs/
  ├─ tests/
  └─ docs/

Data, API, or integration rules:
- Use idempotent APIs and include a correlation ID for end-to-end traceability.
- Do not send duplicate notifications; deduplicate at the orchestrator level.

Validation rules:
- Validate payloads against channel schemas; ensure required fields like recipient, content, and channel exist.
- Validate rate limits and delivery windows prior to dispatch.

Security rules:
- Secrets must be stored in a secrets manager; rotate tokens; apply least privilege.
- Avoid leaking PII; mask data in logs.

Testing rules:
- Unit tests per agent; integration tests for end-to-end delivery; contract tests for channel adapters.

Deployment rules:
- Deploy using CI/CD with feature flags for new channels; support canary rolls and rollback.

Human review and escalation rules:
- Critical failures route to on-call; non-critical gating may be resolved through Planner feedback.

Failure handling and rollback rules:
- Retry with exponential backoff; if still failing, rollback to last-good configuration and alert operators for manual intervention.

Things Agents must not do:
- Do not bypass security controls; do not access production data beyond required fields; do not modify infrastructure without approval.

Recommended Agent Operating Model

PlannerAgent leads the design and strategy, while ImplementerAgent executes actions with channel adapters. ReviewerAgent provides quality gates. ResearcherAgent and Domain SpecialistAgent inject policy, compliance, and content domain knowledge. The OrchestratorAgent coordinates, enforces memory rules, and triggers escalations when thresholds are breached. Escalation paths require human review for high-risk changes or policy violations.

Recommended Project Structure

notifications/
├─ agents/
│  ├─ planner/
│  ├─ implementer/
│  ├─ reviewer/
│  ├─ researcher/
│  └─ domain-specialist/
├─ workflows/
│  └─ notification-pipeline.yaml
├─ adapters/
│  ├─ email/
│  ├─ sms/
│  └─ push/
├─ configs/
├─ tests/
└─ docs/

Core Operating Principles

Single source of truth and traceable decisions.
Deterministic outputs with deterministic memory scoping per run.
Explicit and documented agent handoffs.
Observability, auditability, and reproducible tests.
Security-by-default and least-privilege access.
Idempotent operations and safe retries.
Respect privacy and compliance constraints across channels.

Agent Handoff and Collaboration Rules

Define explicit handoffs between Planner, Implementer, Reviewer, Researcher, and Domain Specialist agents. Use correlation IDs for cross-agent context, and ensure the Orchestrator enforces state transitions and rollback points. Reviewers formalize acceptance criteria; Researchers validate policy constraints; Domain Specialists adapt to channel nuances.

Tool Governance and Permission Rules

Describe tool access, secret management, and approval gates for channel adapters and production endpoints. Enforce role-based access control, audit logging, and strict boundaries on what agents can modify in production.

Code Construction Rules

Implement adapters and orchestrator logic with explicit interfaces, deterministic behavior, and strict input validation. Do not hard-code secrets; prefer configuration-driven behavior with feature flags.

Security and Production Rules

Use secret stores for credentials, enforce TLS, rotate keys, and restrict cross-zone access. Production changes require approval and validated test results.

Testing Checklist

Unit tests per agent; integration tests for end-to-end notification pipeline across channels.
Contract tests for adapters against channel APIs.
End-to-end performance and reliability tests under load.

Common Mistakes to Avoid

Over-optimistic assumptions about agent autonomy without governance.
Context drift due to missing memory scoping.
Bypassing validation or secret management steps.
Unclear handoffs causing duplication or gaps in delivery.
Ignoring security and data minimization in logs.

FAQ

What is the purpose of this AGENTS.md template for notification system architecture?

This AGENTS.md template provides a practical operating manual for coordinating AI coding agents to design and run a notification system, with clear roles, handoffs, memory, and governance for reliable multi-agent delivery.

How does multi-agent orchestration handle channel diversity (email, SMS, push) in this workflow?

Orchestrator coordinates per-channel adapters, validates channel schemas, and ensures channel-specific formatting and rate limits are respected before dispatch.

What are the handoff rules between planners, implementers, reviewers, and testers?

Planner -> Implementer passes task definitions and constraints; Implementer -> Reviewer passes payloads for validation; Reviewer -> Orchestrator approves or requests changes; Escalation paths trigger human review when needed.

How are secrets, tool access, and production actions governed in this template?

Secrets live in a secret manager; agents use least privilege and logs never include tokens. Only the orchestrator can trigger production actions with explicit approvals and auditable traces.

How do we handle failures and rollback in the notification pipeline?

Use exponential backoff retries; if all retries fail, rollback to the last good configuration and alert operators for manual intervention.

Target User

Use Cases