AGENTS.md Template for Event Driven Architecture Teams

Overview

The AGENTS.md template for event driven architecture teams provides a formal, copyable operating manual for governing AI coding agents within event-based workflows. It supports both single-agent operation and multi-agent orchestration across producers, brokers, and consumers, with clear handoff rules, tool governance, and human review when needed. Direct answer: this template defines roles, responsibilities, and governance to enable predictable, auditable agent activity in an event-driven system.

What you get in this template: clear role definitions, decision boundaries, and escalation paths that align with event-driven patterns such as event schemas, topic orchestration, and idempotent processing.

When to Use This AGENTS.md Template

• You are designing an event-driven pipeline that uses AI coding agents to publish, route, transform, or react to events.
• You need deterministic handoffs between planner, implementer, tester, reviewer, and domain experts in a live event feed.
• You require tool governance, secrets management, and secure access to the event bus and downstream services.
• You want an auditable, project-level operating context that surfaces failure modes, rollback procedures, and human escalation triggers.
• You are documenting a reusable, template-based workflow for future event-driven projects.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- This file defines the operating model for event driven architecture teams using AI coding agents. It supports single-agent work and multi-agent orchestration across producers, brokers, and consumers.

Agent roster and responsibilities
- Planner Agent: designs event schemas, topics, and flows; validates end-to-end orchestration against business goals.
- Implementer Agent(s): implements producers, transformers, and consumers; writes integration code and adapter logic.
- Tester Agent: creates and executes test plans for event schemas, message formats, and idempotent processing.
- Reviewer Agent: approves changes, checks for policy conformance and security, and signs off on deployments.
- Researcher Agent: gathers domain knowledge, external API capabilities, and data quality checks.
- Domain Specialist Agent: provides subject-matter insights and validates domain-specific event handling rules.

Supervisor or orchestrator behavior
- The Orchestrator ensures events flow through the roster without context drift. It enforces versioned event schemas, topic ownership, and queuing semantics. It triggers handoffs on completion criteria, monitors SLAs, and escalates incidents when automatic recovery fails.

Handoff rules between agents
- Handoff triggers: schema approval, test pass, or deployment gate.
- Handoff data: provide event schema, topic name, transformation details, and validation status.
- Handoff ownership: planner to implementer, implementer to tester, tester to reviewer, reviewer to domain specialist as needed.
- Handoff latency: target under 5 minutes for synchronous steps; non-blocking tasks run in parallel with proper queuing.

Context, memory, and source-of-truth rules
- Source of truth: event catalog, schema registry, and a truth-tracking log.
- Context memory: short-term context kept in the orchestrator with a rolling history; long-term memory stored in an event store and documentation repo.
- Data provenance: every change is traceable to a commit, schema change, or test result.

Tool access and permission rules
- Agents may read event topics and write to allowed topics only.
- Secrets and credentials must be retrieved from a secure vault with short-lived tokens.
- External services require approved adapters and review before production access.

Architecture rules
- Use versioned event schemas; avoid breaking changes without deprecation windows.
- Implement idempotent handlers for at-least-once delivery semantics.
- Maintain a documented event schema registry and topic ownership.

File structure rules
- Keep only workflow-relevant folders; exclude unrelated repos.
- Document adapters and event handlers in a dedicated folder with clear naming.

Data, API, or integration rules
- Validate input/output shapes against the event schema before publishing.
- Respect rate limits and backpressure in consumer integrations.

Validation rules
- All events must be validated against the registry schema before being produced or consumed.
- Tests must cover end-to-end event flow, failure scenarios, and rollback paths.

Security rules
- Least privilege access to topics, secrets, and production endpoints.
- No hard-coded credentials; rotate keys regularly.

Testing rules
- Include unit, integration, and end-to-end tests for event flows.
- Include dead-letter handling and replay testing.

Deployment rules
- Gates require passing tests, security review, and policy conformance.
- Deploy to staging before production; monitor event quality post-deploy.

Human review and escalation rules
- Human review is required for changes affecting schema or business logic.
- Escalate to incident response if events fail validation or cause data loss.

Failure handling and rollback rules
- Use dead-letter queues for failed events; implement compensating actions when needed.
- Rollback via feature flags and canary deployments for event consumers.

Things Agents must not do
- Do not bypass handoffs, modify event schemas without approval, or access production systems without authorization.
- Do not perform unsupervised production changes or bypass rollback procedures.

Recommended Agent Operating Model

Roles and responsibilities are bounded by event-driven decision points. Planner defines the intent and schema; Implementers build adapters and handlers; Reviewers ensure policy and security; Testers validate end-to-end flows; Researchers and Domain Specialists provide context and expert validation. Escalation paths clearly specify when a handoff should wait for human input and when to trigger an incident protocol. This model supports both a single holistic agent and a team of agents coordinating through the orchestrator to guarantee reliability, auditability, and governance in multi-agent orchestration for event-driven systems.

Recommended Project Structure

/agents
  /event-architect
    /planner
    /implementer
    /tester
    /reviewer
    /researcher
    /domain-specialist
  /tools
  /data
  /events
    /schemas
    /topics
  /workflows
    /event-driven-architecture
      /producer
      /consumer
      /broker
      /handoff
  /tests
  /docs

Core Operating Principles

• Maintain a single source of truth for event schemas and topics.
• Enforce strict handoffs with explicit data passed and status signals.
• Use idempotent handlers and robust error handling for at-least-once delivery.
• Limit agent scope to defined event-driven tasks and surfaces responsible ownership.
• Require human review for schema changes and production-impacting steps.

Agent Handoff and Collaboration Rules

• Planner to Implementer: share schema, topic, and mapping; include validation criteria.
• Implementer to Tester: share test cases, data fixtures, and expected outcomes.
• Tester to Reviewer: provide test results, coverage, and risk analysis.
• Researcher to Domain Specialist: supply context, data quality concerns, and external references.
• Domain Specialist to Planner: provide domain constraints and approval for changes.

Tool Governance and Permission Rules

• Commands limited to permitted topics and controlled adapters.
• Edits to code, schemas, and configs require review and approval.
• Secrets stored in vaults; access tokens are short-lived and scoped.
• Production endpoints require approvals and rollback plans.
• All API calls must be logged and auditable in the event store.

Code Construction Rules

• Use versioned event schemas; do not introduce breaking changes without deprecation tracking.
• Validate all payloads against the registry before publishing or consuming.
• Document adapters with clear input/output contracts and error handling paths.
• Write tests that reproduce real-world event flows and failure modes.

Security and Production Rules

• Least privilege access to topics, secrets, and production resources.
• Encrypt sensitive data in transit and at rest; rotate credentials regularly.
• Monitor event quality and enforce alerting on schema validation failures.

Testing Checklist

• Unit tests for each event handler and transformer.
• Integration tests covering end-to-end event flow.
• Deployment checks with canary releases and rollback tests.
• Security and access tests for secrets and adapters.

Common Mistakes to Avoid

• Skipping explicit handoffs and relying on implicit context transfer.
• Editing production configurations without approvals or rollback plans.
• Ignoring event versioning and breaking consumers with schema changes.
• Overloading agents with scope beyond their responsibility.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Ndas and Risk Flagging.

FAQ

What is the purpose of this AGENTS.md Template for event-driven architecture teams?

It defines operating context for AI coding agents involved in event-driven workflows, including roles, handoffs, and governance.

How many agents are typically required in this pattern?

Typically a Planner, one or more Implementers, a Tester, a Reviewer, and optionally Researchers or Domain Specialists depending on domain complexity.

How is memory and source of truth managed in event-driven flows?

Memory is maintained in an orchestrator and event store; source of truth includes the event catalog, schema registry, and a centralized logs/history store.

What are the security and tool governance requirements?

Access is least-privileged and secrets are pulled from a vault; adapters and production access require approvals and auditing.

How are failures and rollbacks handled?

Failed events go to dead-letter queues; rollbacks use canary deployments and feature flags with clear rollback procedures.