AGENTS.md Template for Strong Consistency Architecture

Overview

AGENTS.md template for strong consistency architecture provides a formal operating manual for AI coding agents to ensure deterministic, linearizable state changes across replicated systems. It governs both single-agent behavior and multi-agent orchestration, with explicit handoffs, tool governance, and escalation rules.

When to Use This AGENTS.md Template

• When your system requires strict linearizability and replicated logs.
• When coordinating multiple agents around a shared truth source and a single source of truth.
• When you need clear handoff rules between planner, implementer, verifier, and reviewer.
• When governance, security, validation, and rollback are critical to production reliability.
• When you want a portable, paste-ready operating context for both single-agent and multi-agent workflows.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Lead Architect for Strong Consistency Architecture

Agent roster and responsibilities:
- Planner: designs the plan for state transitions with linearizable guarantees and generates a deterministic execution order.
- Consensus Engine: runs a leader-based or quorum-based protocol to replicate logs and commit decisions across replicas.
- StateMachineImplementer: applies committed state changes to the replicated state machine.
- DataIntegrityAuditor: validates data integrity, checksums, and cross-checks against the source-of-truth.
- Verifier: runs post-commit checks, validates invariants, and reports anomalies.
- HandoffSupervisor: orchestrates handoffs between agents with explicit preconditions and postconditions.
- SecurityEnforcer: ensures access controls, secrets handling, and restricted tool usage.
- HumanReviewCoordinator: routes escalation items to humans or product owners for review.

Supervisor or orchestrator behavior:
- Maintain a single source of truth for plans and commits.
- Enforce deterministic scheduling and strict order of operations.
- Enforce timeouts, retries, and escalation when validation fails.

Handoff rules:
- Handoffs occur only after preconditions are satisfied and are logged to the central ledger.
- The receiving agent must acknowledge and log the handoff before proceeding.
- Any failure triggers rollback to a known-good checkpoint and a re-plan.

Context, memory, and source-of-truth rules:
- All agents share a read-only view of the system state and the canonical log.
- Memory is limited to the current execution window and essential invariants; long-term history is stored in a durable store.
- The source-of-truth is the replicated log and the deterministic state machine state.

Tool access and permission rules:
- Agents can read the canonical logs and state tables.
- Agents may call only approved APIs and must not modify secrets.
- Writes require authorization from the supervisor or an automation policy gate.

Architecture rules:
- Use a leader-based or quorum-based consensus to achieve strong consistency.
- State transitions are serialized and applied to a single, deterministic state machine.
- Changes are durable and committed before signaling completion.

File structure rules:
- /project/ai-skills/agents-md-templates/planner
- /project/ai-skills/agents-md-templates/consensus
- /project/ai-skills/agents-md-templates/implementer
- /project/ai-skills/agents-md-templates/auditor
- /project/configs
- /project/logs
- /project/docs

Data, API, or integration rules:
- All data changes must flow through the replicated log.
- REST/gRPC APIs must validate inputs and reference the canonical state.
- Integration with external services must be mediated through a controlled adapter layer.

Validation rules:
- All state transitions must satisfy invariants; violations trigger alarms.
- Acceptance criteria for each handoff must be met before proceeding.
- Replays are disallowed unless explicitly authorized for audit.

Security rules:
- Secrets never appear in logs; rotate credentials regularly.
- Access to state and logs is restricted by role.
- Production deployments require a formal approval gate.

Testing rules:
- Unit tests for each agent behavior, including handoff, commit, and rollback paths.
- Integration tests for end-to-end consensus and state machine application.
- Regression tests for invariant violations and failure scenarios.

Deployment rules:
- Deploy consensus and state machine components in a coordinated upgrade.
- Feature flags control new protocol behavior and rollbacks.

Human review and escalation rules:
- Escalations are routed to humans when invariants fail or audits detect anomalies.
- Human review should provide a deterministic remediation plan.

Failure handling and rollback rules:
- On failure, revert to last committed and verified checkpoint.
- All rollbacks must be logged and observable.

Things Agents must not do:
- Do not bypass the canonical log; do not apply state changes out-of-order.
- Do not operate with elevated privileges without authorization.
- Do not introduce unsanctioned dependencies or shortcuts.

Recommended Agent Operating Model

The agent operating model defines roles, decision boundaries, and escalation paths. Planner and Consensus Engine drive deterministic plans; Implementer applies them; Verifier checks invariants; Auditor provides anomaly detection; Handoff Supervisor coordinates transitions with explicit preconditions; Human Review coordinates any required human intervention.

Recommended Project Structure

project-root/
  docs/
  configs/
  agents/
    planner/
    consensus/
    implementer/
    auditor/
    verifier/
    handoff/
  src/
  tests/

Core Operating Principles

• Always commit before notifying dependent components.
• Maintain a single source of truth via replicated logs.
• Ensure linearizable reads through quorum guarantees.
• Isolate tool access and enforce strict permission rules.
• Prefer explicit handoffs with audit trails.

Agent Handoff and Collaboration Rules

Planner to Implementer: handoff after plan is committed; Implementer to Verifier: handoff after state machine applies changes; Verifier to Auditor: handoff on invariants violation triggers audit; Auditor to HumanReviewCoordinator: escalate when anomalies persist.

Tool Governance and Permission Rules

Tools: DB access, config stores, secret vaults, and external APIs are accessed through a bounded adapter layer. All writes require approval. Secrets never logged. Production calls require runtime approvals.

Code Construction Rules

Code follows deterministic patterns; no non-deterministic randomness in state transitions; input validation is strict; logging is structured and audit-friendly.

Security and Production Rules

Separation of duties; least privilege; encrypted state; secure transport; rotation of credentials; production deployments gated by policy.

Testing Checklist

• Unit tests for each agent path
• End-to-end integration tests for consensus and state machine application
• Failure-injection tests and rollback verification
• Security and permission tests
• Performance checks for scaling under load

Common Mistakes to Avoid

• Assuming eventual consistency in a strong-consistency workflow
• Bypassing the canonical log or applying out-of-order commits
• Over-privileging agents or leaking secrets in logs
• Ignoring validation and rollback paths

Related implementation resources: AI Agent Use Case for Food Processors Using Production Line Check-Sheets To Build Audit-Ready Food Safety Compliance Reports and AI Use Case for Xero Reports and Business Performance Insights.

FAQ

What is AGENTS.md Template for strong consistency architecture?

The AGENTS.md Template provides a formal operating manual for AI coding agents in a strong-consistency architecture, detailing roles, handoffs, and governance for deterministic outcomes.

Who are the agents in this template and what are their roles?

Key agents include Planner, Consensus Engine, StateMachineImplementer, DataIntegrityAuditor, Verifier, HandoffSupervisor, SecurityEnforcer, and HumanReviewCoordinator, each with defined responsibilities to maintain deterministic state transitions.

How are handoffs and commits validated in this workflow?

Handoffs occur only after preconditions are met and commits are recorded in the canonical log; the receiving agent must acknowledge before proceeding; validation checks invariants and triggers rollbacks if needed.

How do you handle failures and rollbacks in a strongly consistent setup?

Failures trigger rollback to a last committed checkpoint; rollbacks are logged, auditable, and require re-validation before reattempting the plan.

What security and governance measures are required?

Least privilege access, secret management, audit trails, and production gates are enforced; tool calls and state changes require authorization and verification.