Push Notification Scalability AGENTS.md Template

Overview

Direct answer: This AGENTS.md template defines a scalable push notification workflow using AI coding agents for single-agent and multi-agent orchestration. It provides a complete operating context to manage ingestion, enrichment, routing, delivery, and governance across channels.

The AGENTS.md template articulates who is responsible, how agents hand off, what memories and sources are trusted, and how to validate outcomes before production. It enables rapid onboarding of new workflows while preserving guarantees around reliability, security, and auditability.

When to Use This AGENTS.md Template

• You need a scalable, multi-channel push notification pipeline with clear agent responsibilities.
• You want repeatable operating context for both single-agent and multi-agent orchestration patterns.
• You require governance around tool access, secrets, and production changes.
• You aim to improve reliability via formal handoffs, validation, and human review gates.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Push Notification Scalability Engine (PNSE). Owns end-to-end delivery across mobile and web channels using AI coding agents.

Agent roster and responsibilities:
- Planner: designs top-level workflow, sequencing, and success criteria.
- Implementer: translates design into executable agent prompts and code-generating tasks.
- Reviewer: validates outputs, checks for drift and compliance, approves changes.
- Tester: creates tests, runs regression checks, simulates edge cases.
- Researcher: surfaces domain-specific data (channel capabilities, rate limits, payload formats).
- Domain Specialist: specializes in push channels (APNs, FCM, WebPush) and channel-specific constraints.

Supervisor or orchestrator behavior:
- Maintains the master plan, assigns tasks, monitors progress, and triggers escalations when quality gates fail.
- Enforces memory and source-of-truth rules; reconciles state across agents.
- Orchestrates handoffs with explicit criteria and timing.

Handoff rules between agents:
- Planner -> Implementer: provide the design, constraints, success criteria, and memory sources.
- Implementer -> Reviewer: deliver draft artifacts and rationale for review.
- Reviewer -> Tester: approve test cases and test data; authorize execution.
- Researcher -> Domain Specialist: supply domain data and channel-specific payload spec.
- Domain Specialist -> Planner: update constraints and emerging edge cases from channel behavior.

Context, memory, and source-of-truth rules:
- Central memory store captures all decisions, plans, and outputs.
- All data sources are versioned and attributed; unverified sources are not used for production.
- The single source of truth is the canonical payload schema and channel configuration.

Tool access and permission rules:
- Agents may call push notification provider APIs only through sanctioned adapters.
- Secrets must be retrieved from a vault; never hard-code credentials.
- Production system edits require an approval gate; tests must pass before deployment.

Architecture rules:
- Event-driven, decoupled services with clear topic boundaries.
- Idempotent handling of payloads and retries.
- Observability and tracing across the workflow.

File structure rules:
- Keep all workflow-specific artifacts under workflows/push-notification-scalability/
- Separate planner, implementer, reviewer, tester, researcher, and domain-specialist folders.

Data, API, or integration rules:
- Use standardized payload schemas; validate against schemas before routing.
- Respect rate limits and backoff policies for each channel.
- All API calls should be idempotent and logged.

Validation rules:
- Validate end-to-end success via a canonical delivery event and channel receipt.
- Ensure no duplicate deliveries within a TTL window.

Security rules:
- Secrets must rotate on schedule; tokens must be scoped to the workflow.
- Data in transit and at rest must be encrypted; access is role-based.

Testing rules:
- Unit tests for each agent, integration tests for adapters, end-to-end tests with synthetic events.
- Run failure-mode tests for retries and fallbacks.

Deployment rules:
- Deploy to staging first; run canaries and guardrails before production.
- Monitor health, throughput, and error rates post-deploy.

Human review and escalation rules:
- Escalate any non-deterministic decision, repeated failures, or policy violations to a human reviewer.
- Use a rollback plan if critical thresholds are breached.

Failure handling and rollback rules:
- If delivery fails after N retries, escalate and move to a dead-letter queue; do not retry indefinitely.
- Rollback state to last known-good payload configuration on error.

Things Agents must not do:
- Do not leak secrets or credentials.
- Do not bypass approval gates.
- Do not mutate live production configurations without validation and rollback plans.
- Do not ignore rate limits or channel constraints.

Recommended Agent Operating Model

• Planner defines goals, constraints, and success criteria; coordinates with domain specialists for channel-specific issues.
• Implementer interprets the plan into executable prompts, orchestrations, and adapters; maintains determinism.
• Reviewer ensures compliance, quality, and alignment with architecture rules before tests.
• Tester generates test cases, runs tests, and reports coverage gaps.
• Researcher surfaces data and external signals that affect delivery quality and rate limits.
• Domain Specialist provides channel-specific constraints and best practices; acts as decision boundary for routing decisions.
• Escalation paths exist for non-deterministic outcomes, security concerns, or production risk.

Recommended Project Structure

workflows/
└── push-notification-scalability/
    ├── planner/
    │   └── plan.md
    ├── implementer/
    │   └── agent_prompts.md
    ├── reviewer/
    │   └── review_checklist.md
    ├── tester/
    │   └── test_cases.md
    ├── researcher/
    │   └── data_sources.md
    ├── domain-specialist/
    │   └── channel_specs.md
    ├── data/
    │   └── schemas/
    ├── integrations/
    ├── tests/
    └── deployment/

Core Operating Principles

• Single source of truth for payload schemas, channel configurations, and delivery state.
• Idempotent operations; retries are bounded and auditable.
• Explicit handoffs with criteria, timing, and acceptance conditions.
• Strict secrets management; no hard-coded credentials.
• Human-in-the-loop for critical decisions and security-sensitive actions.

Agent Handoff and Collaboration Rules

• Planner to Implementer: share plan, constraints, success criteria, memory sources.
• Implementer to Reviewer: deliver artifacts, rationale, and testability notes.
• Reviewer to Tester: approve tests; authorize execution.
• Researcher to Domain Specialist: provide data sources and channel-specific payloads.
• Domain Specialist to Planner: update constraints and edge cases from channel behavior.

Tool Governance and Permission Rules

• Commands and file edits must go through approved adapters; no raw shell access to production systems.
• Secrets retrieved from vault; never embedded in prompts or code.
• API calls require rate-limit aware wrappers and circuit breakers.
• Production changes require review, risk assessment, and canary deployment.

Code Construction Rules

• Use deterministic, idempotent delivery logic; avoid side effects in retries.
• Inputs validated against canonical schemas; outputs validated before routing.
• All code changes include tests; maintain a changelog per workflow.
• Use feature flags for new behaviors to enable safe rollouts.

Security and Production Rules

• Data in transit and at rest encrypted; role-based access control enforced.
• Secrets rotation and auditing; exposure minimized across services.
• Observability: dashboards for delivery success, latency, and error rates.
• Production changes require approvals and canary testing.

Testing Checklist

• Unit tests for each agent; integration tests for adapters and channels.
• End-to-end tests using synthetic events across all channels.
• Performance tests to validate throughput and latency under peak load.
• Regression tests to ensure no drift after updates.

Common Mistakes to Avoid

• Assuming a single agent can handle all responsibilities in a scalable way.
• Skipping explicit handoffs and memory management details.
• Relaxing security or production gating during rapid iteration.
• Neglecting channel-specific constraints when routing decisions change.

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template?

It provides a complete operating manual for a push notification scalability workflow, including multi-agent orchestration, handoffs, and governance.

Who should use this AGENTS.md Template?

Engineers, platform teams, and product teams building scalable push delivery pipelines with multi-agent orchestration.

How are handoffs defined between agents?

Handoffs have explicit criteria, timing, and acceptance checks. Each transfer includes memory sources and validation artifacts.

How is security enforced in this workflow?

Secrets are retrieved from a vault, production changes require approvals, and all API calls are audited and rate-limited.

What tests are required before deployment?

Unit tests, integration tests for adapters, end-to-end tests with synthetic events, and canary deployment checks.