AGENTS.md Template for Consistency Model Analysis

Overview

Use this AGENTS.md Template for Consistency Model Analysis to govern how AI coding agents analyze and validate model consistency across distributed components. It defines an operating model for single-agent and multi-agent orchestration, detailing roles, memory strategies, tool access, and handoffs to keep analyses reproducible and auditable.

When to Use This AGENTS.md Template

When performing analytical validation of consistency models in distributed systems or ML pipelines.
When coordinating multiple agents to ensure reproducible CMA results.
When requiring an auditable trail of decisions, data, and actions.
When enforcing tool governance and security in CMA workflows.
When documenting an operating model that can be reused across CMA projects.

Copyable AGENTS.md Template

# AGENTS.md
Project: Consistency Model Analysis (CMA)
Purpose: Define roles, rules, and workflow for analyzing consistency models using AI coding agents in single-agent and multi-agent orchestration.

Agent roster
- OrchestratorAgent (Coordinator)
- AnalystAgent
- DataAgent
- ValidatorAgent
- ResearchAgent
- ReviewerAgent
- DomainSpecialistAgent

Supervisor / Orchestrator behavior
- The Orchestrator maintains plan, provides context, issues task assignments, enforces memory and SOPs, triggers handoffs, and handles escalation.

Handoff rules
- Handoff from Analyst to Validator when analysis is complete
- Handoff from Validator to Reviewer for QA
- Handoff from Researcher to Analyst for updated references
- Handoff from DomainSpecialist to Reviewer for domain validation

Context memory and source of truth
- CMA-DataStore is the canonical source of truth
- All agents attach to and log actions with timestamps
- Context is scoped to CMA analysis session

Tool access and permission rules
- Tools: Python execution sandbox, API client, data store, Git
- Access is granted by the Orchestrator
- Secrets must be stored in CMA secrets vault and accessed via tokens

Architecture rules
- Agents communicate via simple JSON messages
- Planner is stateless; memory is stored in CMA-DataStore
- Changes are auditable and replayable

File structure rules
- Keep all CMA files under CMA-Agents at the repository root
- Subfolders per agent exist under CMA-Agents
- Use a shared data directory for inputs, outputs, and results

Data API and integration rules
- Inputs must be validated against CMA input schema
- Outputs must conform to CMA result schema
- Integrations log events to CMA-Logs

Validation rules
- All results must be reproducible
- Cross-check with ResearchAgent findings
- Validate against trusted baselines

Security rules
- Secrets vault; least privilege; no plaintext secrets in code
- Access audits and rolling keys

Testing rules
- Unit tests for each agent
- End-to-end CMA workflow tests
- Page-level regression checks

Deployment rules
- Staged rollout to CMA environment
- Feature flag controlled
- Audit trail retained post deployment

Human review and escalation rules
- Analysts escalate to CMA Supervisor when uncertain
- Human-in-the-loop validation for critical decisions

Failure handling and rollback rules
- Rollback CMA-DataStore to last good state on failure
- Retry up to 3 times with backoff
- If persistent, raise to human operator

Things Agents must not do
- Do not bypass orchestrator
- Do not mutate canonical CMA data without validation
- Do not perform production changes without approval

Recommended Agent Operating Model

In CMA agent orchestration, the Orchestrator plans and coordinates, while specialized agents perform analysis, data gathering, validation, and review. Clear decision boundaries and escalation paths ensure accountability and reproducibility across single-agent and multi-agent runs.

Recommended Project Structure

consistency-model-analysis/
├── agents/
│   ├── orchestrator/
│   │   └── orchestrator.py
│   ├── analyst/
│   │   └── analyst.py
│   ├── data/
│   │   └── data_gatherer.py
│   ├── validator/
│   │   └── validator.py
│   ├── researcher/
│   │   └── researcher.py
│   ├── reviewer/
│   │   └── reviewer.py
│   └── domain-specialist/
│       └── domain_specialist.py
├── workflows/
│   └── CMA-workflow.yaml
├── data/
│   └── inputs/
├── results/
└── logs/

Core Operating Principles

Single source of truth is the CMA data repository. All outputs are traceable to this source.
Handoffs are explicit with preserved context and memory continuity.
Agents operate with least privilege and strict access control.

Agent Handoff and Collaboration Rules

Planner (Orchestrator) assigns tasks and enforces sequencing.
Analyst implements analytical steps and prepares inputs for validation.
DataGatherer collects and standardizes inputs for CMA analysis.
Validator checks outputs against baselines and external references.
Researcher provides literature references and alternative baselines as needed.
Domain Specialist ensures domain constraints are respected and flags edge cases.
Reviewer validates results before final publication or deployment.

Tool Governance and Permission Rules

Execution tools require orchestrator approval.
Code edits require review and version control checks.
APIs and data stores require scoped tokens with rotation policies.
Production changes require human sign-off when CMA results influence live systems.

Code Construction Rules

All CMA logic must be modular and testable.
Inputs have strict schemas; outputs validated against CMA schemas.
Logging includes provenance and timestamps for auditability.

Security and Production Rules

Secrets stored in a secure vault; never hard-coded.
Access control enforced at every agent boundary.
Audit trails maintained for all CMA actions in production.

Testing Checklist

Unit tests for each CMA agent.
End-to-end CMA workflow tests with representative data.
Regression tests for changes in the CMA data model.

Common Mistakes to Avoid

Skipping memory and source-of-truth alignment during handoffs.
Bypassing orchestrator or causing architecture drift.
Uncontrolled production changes based on unverified CMA outputs.

FAQ

What is the purpose of this AGENTS.md Template for CMA?

The template codifies roles, rules, and workflows to support consistent CMA analysis across single-agent and multi-agent orchestration.

Who are the primary agents in CMA analysis?

Orchestrator, Analyst, DataAgent, Validator, Researcher, Reviewer, and Domain Specialist roles coordinate via handoffs and memory rules.

How are memory and source of truth managed?

A CMA-DataStore is the canonical source of truth; all agents attach to and log actions with timestamps.

What happens on failure or when human review is required?

On failure, rollback to the last consistent CMA state and escalate to human reviewer when uncertainty arises.

Can this template be adapted to other workflows?

Yes, the AGENTS.md template pattern can be adapted while preserving the core operating manual structure.

Target User

Use Cases