AGENTS.md Template: Event Sourcing Architecture

Overview

Direct answer: This AGENTS.md template defines the operating manual for event-sourced AI coding agents and supports both single-agent and multi-agent orchestration around an event store as the single source of truth.

In this template, you describe project roles, agent roster and responsibilities, supervisor/orchestrator behavior, explicit handoffs, memory and source-of-truth rules, tool governance, architecture constraints, and detailed rules that keep the system auditable and safe while enabling scalable automation of event-driven workflows.

When to Use This AGENTS.md Template

• When building AI coding agents around an Event Sourcing architecture with a central Event Store.
• When you need clear agent roles (planner, event handler, projector, auditor, etc.) and explicit handoff rules.
• When governance, compliance, and rollback capabilities are required in a multi-agent workflow.
• When you want a copyable, project-level operating context that can be shared across teams.

Copyable AGENTS.md Template

# AGENTS.md

# Project Role
- Title: Event Sourcing Architect
- Primary goal: Guarantee correct, auditable processing of domain events with a single source of truth (Event Store) and reliable multi-agent coordination.

# Agent roster and responsibilities
- PlannerAgent: designs aggregates, event schemas, and event types; defines the orchestration plan.
- EventStoreManager: writes/appends events, manages streams, snapshots, and idempotency checks.
- ProjectionAgent: updates read models and projections from domain events.
- ReadModelTester: validates read models against event history and invariants.
- DomainEventResearcher: clarifies domain semantics and event semantics; contributes to event contracts.
- AuditorAgent: enforces compliance, privacy, and audit logging.
- OrchestratorAgent: coordinates all agents, enforces handoffs, and tracks progress.
- SecurityAgent: manages secrets and access restrictions.

# Supervisor or orchestrator behavior
- The OrchestratorAgent maintains the authoritative plan, assigns tasks, and enforces timeouts.
- Execution is deterministic and idempotent; replays are allowed to recover state.
- All actions are logged and traceable to a specific event in the Event Store.

# Handoff rules between agents
- After PlannerAgent defines a plan, EventStoreManager locks streams and accepts new events.
- ProjectionAgent consumes events after write success, then ReadModelTester validates projections.
- AuditorAgent reviews any schema drift or anomalous events before deployment to production.

# Context, memory, and source-of-truth rules
- The Event Store is the single source of truth; agents maintain lightweight, ephemeral memory for current job context.
- Do not rely on external memory for long-term state; replay and replay checkpoints derive state from events.

# Tool access and permission rules
- Agents access events, projections, and configs via a controlled API layer; secrets live in a vault.
- Production actions require Orchestrator approval; no direct write to production systems by agents without guardrails.

# Architecture rules
- Use Event Sourcing with CQRS; snapshots and projection pipelines are allowed.
- Ensure idempotent event handlers and deterministic replays.

# File structure rules
- events/: domain events and aggregates
- projections/: read models
- handlers/: event handlers
- snapshots/: snapshot storage
- tests/: tests for handlers and projections
- docs/: its own docs
- infra/: deployment scripts and config

# Data, API, or integration rules
- Schema-versioned events; backward-compatible projections; explicit contract tests.
- Use standard HTTP/gRPC APIs provided by the platform with proper auth.

# Validation rules
- Validate event schema on write; reject incompatible events.
- Use contract tests for event formats.

# Security rules
- Enforce least privilege; secrets are not embedded in code.
- All actions are auditable; logs are immutable when possible.

# Testing rules
- Unit tests for each event handler; integration tests against in-memory event store; end-to-end tests for read models.

# Deployment rules
- CI/CD with feature flags; canary deployments for projection pipelines; rollbacks supported via event replay.

# Human review and escalation rules
- Any schema drift or security concern triggers human review; critical events require manual approval before reaching production.

# Failure handling and rollback rules
- Use idempotent handlers; on failure, replay events from last checkpoint; use compensating events when needed.

# Things Agents must not do
- Do not modify historical events; do not bypass the event store; do not access secrets outside vault; avoid context drift.

Recommended Agent Operating Model

Roles, decision boundaries, and escalation paths for event-sourced multi-agent orchestration are defined here to ensure predictable outcomes and auditable handoffs.

Recommended Project Structure

project-root/
  events/
    aggregates/
      order.py
      payment.py
    schemas/
    streams/
  projections/
    read-models/
  handlers/
  snapshots/
  tests/
  docs/
  infra/
  configs/

Core Operating Principles

• The Event Store is the single source of truth for all domain events.
• All handlers are idempotent and replayable.
• Explicit, documented handoffs between agents reduce drift.
• Access is restricted; secrets are vault-backed and audited.
• Observability is built-in: tracing, metrics, and audit logs.

Agent Handoff and Collaboration Rules

• Planner → EventStoreManager: define event contracts and streams; validate schema.
• EventStoreManager → ProjectionAgent: publish validated events to projections after write success.
• ProjectionAgent → ReadModelTester: validate projections against event history.
• AuditorAgent: reviews for drift, security, and compliance before production merge.
• OrchestratorAgent: enforces timeouts, retries, and ensures end-to-end traceability.
• DomainEventResearcher: resolves domain ambiguities to refine event contracts.

Tool Governance and Permission Rules

• All command execution, file edits, and API calls go through a governance layer with role checks.
• Secrets must be accessed via a secure vault; never hard-coded.
• Production changes require multi-agent approvals and audit trails.

Code Construction Rules

• Use deterministic handlers; avoid side effects in event handlers.
• Versioned events; support migration strategies.
• Contracts must be tested with unit and integration tests.

Security and Production Rules

• Least privilege for all agents; rotate credentials regularly.
• Audit logging for all event writes and projections.
• Shield production systems from direct agent access; use an API gateway.

Testing Checklist

• Unit tests for all event handlers and projections.
• Integration tests with in-memory event store; end-to-end tests for read models.
• Replay tests to verify deterministic recovery.

Common Mistakes to Avoid

• Skipping schema versioning and contracts.
• Unbounded memory in agents; neglecting replay safety.
• Bypassing the Event Store for read models.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Agent Use Case for Defense Subcontractors Using Compliance Databases To Verify It Infrastructure Alignment with Cybersecurity Rules.

FAQ

What is this AGENTS.md Template used for in event sourcing?

It codifies agent roles, orchestrator behavior, and governance for single-agent and multi-agent workflows centered on an event store.

Can I use this AGENTS.md Template for both single-agent and multi-agent orchestration?

Yes. It describes an agent roster, handoff rules, and supervision patterns that support both modes.

How are handoffs between agents defined in this template?

Handoffs are explicit via orchestrator rules, with context passed between agents and a clear source of truth at each transition.

What are the key security considerations for event-sourced AGENTS.md templates?

Enforce least privilege, vault-backed secrets, auditable actions, and protected access to the Event Store and production systems.

How do I validate events and projections in this workflow?

Use versioned event schemas, contract tests, and deterministic replay checks to ensure projections remain correct over time.