AGENTS.md Template: Immutable Event Store Design

Overview

AGENTS.md Template for immutable event store design governs the workflow of AI coding agents that manage an immutable event store design. It supports both single-agent operation and multi-agent orchestration, detailing roles, memory rules, and handoffs to ensure a reliable, auditable event history.

Direct answer: This AGENTS.md template provides everything needed to set up project-level operating context for immutable event store design, including agent roster, supervisor behavior, handoffs, and governance for safe, repeatable execution.

When to Use This AGENTS.md Template

• When implementing an immutable, append-only event store and requiring multi-agent orchestration for ingestion, validation, projection, and audit.
• When you need a reusable operating manual that can be copied into each project’s AGENTS.md file and customized per domain.
• When enforcing tool governance, memory rules, and strict escalation paths to human reviewers.
• When documenting handoffs and failure handling to avoid context drift across agents.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Immutable Event Store Orchestration Lead

Agent Roster & Responsibilities:
- IngestAgent: responsible for ingesting events and ensuring idempotency
- ValidatorAgent: validates event schemas and enforces versioning
- ProjectionAgent: builds materialized views from events
- OrchestratorAgent: planner & coordinator of handoffs
- AuditorAgent: ensures traceability and compliance

Supervisor / Orchestrator Behavior:
The Orchestrator coordinates inter-agent handoffs, enforces memory and source-of-truth rules, and initiates human review when escalation criteria are met.

Handoff Rules Between Agents:
Ingest > Validator > Projection; Escalate if validation fails; Projections are updated after successful validation and commit to store.

Context, Memory, and Source-of-Truth Rules:
All agents share a single canonical event store as source of truth. Use event IDs and shards for deterministic replay.
- Memory: keep event history, latest checkpoint, and projection offsets.
- Source of Truth: immutable append-only store; proofs of delivery.

Tool Access and Permission Rules:
- IngestAgent: write-only to the event stream; read-only to schemas catalog.
- ValidatorAgent: read from store; write validations and schema registry updates.
- ProjectionAgent: read from store; write projections.
- Orchestrator: orchestrates across agents; CI-protected.

Architecture Rules:
- Event schemas are versioned; backward-compatible changes only via adapters.
- Each event must include event_id, timestamp, type, version, source.

File Structure Rules:
- events/schemas/
- events/store/
- orchestrator/
- projections/
- validators/
- ingestion/

Data, API, or Integration Rules:
- All events must pass schema validation before persisting.
- Secrets are never stored in code; use secret manager.

Validation Rules:
- Idempotency checks on ingest; idempotent handlers; deterministic projections.

Security Rules:
- Encrypt at rest; audit logs; restricted access by role; rotate keys.

Testing Rules:
- Unit tests per handler; integration tests for end-to-end ingestion and projection; replay tests.

Deployment Rules:
- Migrate schemas with zero-downtime adapters; CI gates; rollback plan.

Human Review and Escalation Rules:
- All governance decisions require human review if risk score exceeds threshold.

Failure Handling and Rollback Rules:
- On failure, no events lost; write compensating events and replay validations.

Things Agents Must Not Do:
- Mutate persisted events; bypass validation; leak secrets; bypass orchestrator controls.

Recommended Agent Operating Model

The model enforces clear roles, decision boundaries, and escalation paths to coordinate AI coding agents around an immutable event store design. Each agent operates within a defined scope and hands off work at well-defined boundaries. If a decision requires context beyond an individual agent’s scope, escalate to the Orchestrator or Human Review.

Recommended Project Structure

project-root/
  events/
    schemas/
    store/
  orchestrator/
    planner/
    workers/
  projections/
  validators/
  ingestion/
  tests/
  docs/

Core Operating Principles

• Deterministic and idempotent event handlers to guarantee replayability.
• Single source of truth: immutable event store as the canonical log.
• Versioned event schemas with backward-compatible migrations.
• Traceability with end-to-end auditability and playback capability.
• Explicit handoffs with preconditions and validation gates.

Agent Handoff and Collaboration Rules

• Planner-to-Implementer: pass concrete event types, latest schemas, and replay offsets. Validate before execution.
• Implementer-to-Reviewer: commit changes to handler logic and projections with unit test results.
• Reviewer-to-Tester: approve test coverage including end-to-end replay tests.
• Researcher-to-Domain Specialist: provide domain-specific event semantics and constraints.

Tool Governance and Permission Rules

• Commands to mutate the event store require orchestrator approval and audit logging.
• Code edits to projection or validator paths require pull request review and secret scoping.
• API calls to external services follow least-privilege access and secret rotation policies.
• Production deployments require canary testing and rollback plans.
• All actions must be logged for traceability in audit trails.

Code Construction Rules

• Use strongly typed event schemas and a shared registry.
• Write tests that cover idempotency and replay of events.
• Avoid hard-coding environment-specific values in code; use config/secret managers.
• Do not bypass the orchestrator; never run side effects without explicit gating.

Security and Production Rules

• Encrypt event data at rest and in transit; enforce access control on read/write per agent.
• Rotate credentials; store secrets in a vault; log secret access events.
• Maintain immutable logs; prohibit in-place edits to historical events.

Testing Checklist

• Unit tests for every handler with deterministic input/output.
• Integration tests for ingestion, validation, and projection with replay.
• End-to-end tests simulating multi-agent handoffs and failure scenarios.
• Security tests for access controls and secret handling.
• Deployment tests including canary and rollback verification.

Common Mistakes to Avoid

• Mutating historical events or bypassing the event store’s immutability.
• Unclear handoffs leading to context drift between agents.
• Ignoring schema versioning and backward compatibility.
• Storing secrets in code or logs.

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 Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is AGENTS.md Template for immutable event store design?

This template defines the operating manual, agent roster, handoffs, and governance needed to implement an immutable event store with reliable multi-agent orchestration.

How does multi-agent orchestration work in this template?

Agents operate in stages (ingest, validate, project) with a central orchestrator coordinating handoffs, memory, and source-of-truth rules.

What are the key agent roles and handoffs?

IngestAgent → ValidatorAgent → ProjectionAgent; Escalation to AuditorAgent or Human Review when risk signals are raised.

What security considerations are included?

Immutability, access control, secret management, encrypted storage, and auditable action logs across agents.

How should failure and rollback be handled?

Propagate compensating events, replay validations, and maintain a rollback plan with explicit human approval.