AGENTS.md Template for CQRS System Design

Overview

Direct answer: This AGENTS.md template defines a CQRS oriented workflow for AI coding agents. It governs a write model using commands and a read model via queries, with an event store and projections, enabling both a single agent and multi-agent orchestration with explicit handoffs and governance.

The CQRS oriented AGENTS.md template helps teams codify operating context, roles, and rules so agents collaborate with clarity and accountability.

When to Use This AGENTS.md Template

Use when designing a system with separate write and read models, event sourcing, and multi-agent coordination
When the workflow requires explicit handoffs and governance between planner, command handler, and read model teams
When eventual consistency is acceptable and tracing via correlation identifiers is required

Copyable AGENTS.md Template

Paste this AGENTS.md block into your project to establish the project-level operating context for CQRS oriented AI coding agents.

# AGENTS.md

Project role: CQRS System Designer for AI coding agents

Agent roster and responsibilities
- Planner Agent: designs commands and queries, defines orchestration strategy
- CommandHandler Agent: validates and applies domain logic for write commands, emits events
- EventStore Agent: persists events and maintains sequence integrity
- ReadModelUpdater Agent: builds and updates read models from the event stream
- QueryHandler Agent: serves read model queries to downstream tasks
- DomainModelAgent: enforces domain invariants and aggregates across commands
- SupervisorAgent: coordinates all agents, enforces handoffs, retries, and escalation

Supervisor or orchestrator behavior
- Maintain a per-workflow correlationId; track progress across stages; escalate on persistent failure
- Enforce idempotency and guard against duplicate commands
- Trigger compensating actions for failed workflows when possible

Handoff rules between agents
- Planner -> CommandHandler: pass command payload, correlationId, version
- CommandHandler -> EventStore: emit one or more events based on command results
- EventStore -> ReadModelUpdater: publish event stream for projection updates
- ReadModelUpdater -> QueryHandler: ensure read models reflect latest events before serving queries
- If any step fails, escalate to Supervisor and halt further progression until resolved

Context, memory, and source-of-truth rules
- System of record: EventStore
- Domain models live in memory during processing but are reconstructed from events
- Read models are derived from events and used for fast reads
- Do not rely on global long-term memory for workflow state

Tool access and permission rules
- Commands to repositories and external services require approved credentials
- Secrets stored in a vault; avoid hard-coded secrets
- Production system edits require supervisor approval

Architecture rules
- Enforce CQRS with strict boundaries between write and read paths
- Events are the source of truth; projections are eventually consistent
- All commands must be idempotent and auditable

File structure rules
- Use CQRS-focused folders only; exclude unrelated tech stacks

Data, API, or integration rules
- Commands include id, timestamp, correlationId, userId; events carry payloads and metadata
- All external API calls are versioned and logged

Validation rules
- Validate input at planner stage; enforce domain invariants at command handling
- Projections validated against the event stream

Security rules
- Least privilege; secrets in vault; audit logs for critical actions
- Production changes require operator approval and human review when warranted

Testing rules
- Unit tests for each command handler and projection
- Integration tests for event bus and event store
- End-to-end tests for the full CQRS workflow

Deployment rules
- CI/CD with migrations; canary deployments for projections
- Rollback by replaying events or reprojecting read models

Human review and escalation rules
- Trigger manual review for critical domain changes or failed reconciliations
- Domain experts can approve exception paths

Failure handling and rollback rules
- Prefer compensating events for failures
- If rollback is not possible, isolate failed components and replay from a known good state

Things Agents must not do
- Do not bypass domain invariants
- Do not mutate past events
- Do not perform unsupervised production changes

Recommended Agent Operating Model

The agent operating model defines roles, decision boundaries, and escalation paths for CQRS driven AI agents. Each agent has a clear responsibility with explicit handoffs and a single source of truth. Escalation paths lead to the SupervisorAgent for coordination and review.

Planner: designs commands and queries, sets success criteria, and schedules handoffs
CommandHandler: enforces domain rules and writes to the event store
EventStore: maintains event chronology and preserves system state
ReadModelUpdater: materializes read models from events
QueryHandler: serves read model data to consumers
DomainModelAgent: guards invariants and business rules
SupervisorAgent: orchestrates, retries, and escalates as needed

Recommended Project Structure

Workflow-specific directory tree

ai-cqr s-workflow
  commands/
    handlers/
    models/
  queries/
    handlers/
    models/
  events/
    store/
  projections/
  domain/
  infra/
  tests/
  docs/

Core Operating Principles

Single source of truth is the EventStore
Explicit handoffs with correlation identifiers
Idempotent commands and compensating actions
Separation of write and read models
Auditable, versioned and reproducible workflows
Security by design and least privilege

Agent Handoff and Collaboration Rules

Define cooperation between planner, implementer, reviewer, tester, researcher and domain specialist as follows

Planner -> Implementer: provide concrete command and query specs
Implementer -> Reviewer: share implementation details and validation evidence
Reviewer -> Tester: pass test plans and acceptance criteria
Researcher -> Domain Specialist: verify domain rules and invariants
Domain Specialist -> Planner: provide policy constraints for design

Tool Governance and Permission Rules

Execute commands within approved repositories and scopes
Write edits require code review and approvals
APIs and secrets accessed via secure vaults
Production commands require gating and human approval
Audit trails for all tool usage

Code Construction Rules

Follow CQRS patterns strictly: separate write and read paths
Commands carry correlationId, userId, and timestamp
Events are durable and append-only
Projections are derived from event streams only
All code is tested in isolation and integrated via CI

Security and Production Rules

Least privilege on all services
Secrets in vaults, rotated regularly
Production deployments require automated and manual checks
Monitoring and alerting for failure modes

Testing Checklist

Unit tests for planners, handlers and domain rules
Integration tests for event bus and projections
Contract tests for API and external services
End-to-end tests for full CQRS workflow
Regression tests for schema compatibility

Common Mistakes to Avoid

Bypassing domain invariants
Unbounded memory in agents
Untracked handoffs causing drift
Mutable shared state across agents
Overexposing secrets or credentials

FAQ

What is the purpose of this AGENTS.md Template for CQRS system design?

Provides a complete, copyable AGENTS.md template that governs a CQRS driven workflow with dedicated command and query agents, event store, and read models.

How do agents hand off work in CQRS patterns?

Handoffs are explicit and tracked by a correlationId; planner creates commands, command handler emits events, events update read models, and the planner validates completion before next steps.

Where is the system of record and how is memory handled?

The EventStore is the system of record; read models are derived; agent memory is per workflow via correlationId and not shared across workflows.

How are failures and rollback addressed?

Use compensating events and idempotent commands; if a step fails, escalate to supervisor, pause, and retry with backoff, ensuring eventual consistency.

What security and governance rules are included?

Least privilege access, secrets in a vault, audited actions, and production gate checks with human review for critical changes.

Target User

Use Cases