AGENTS.md Template for CAP Theorem Tradeoff Reviews

Overview

Direct answer: This AGENTS.md template defines a structured, copyable operating manual for CAP theorem tradeoff reviews in AI coding agents. It governs both single-agent reviews and multi-agent orchestration, ensuring consistent reasoning about availability, partition tolerance, and consistency tradeoffs across data stores.

The template establishes roles, responsibilities, context propagation, memory, and source-of-truth rules so agents can negotiate CAP tradeoffs deterministically and safely.

When to Use This AGENTS.md Template

• You are performing formal CAP theorem tradeoff reviews for a distributed data store or service architecture.
• You require clear handoffs and governance across Planner, Implementer, Reviewer, Researcher, Domain Expert, and Orchestrator roles.
• You need a repeatable, copyable operating manual that can be versioned and shared across teams.
• You want to enforce tool governance, memory propagation, and escalation rules during multi-agent orchestration.

Copyable AGENTS.md Template

# AGENTS.md

Project role: CAP Review Engine

Agent roster and responsibilities:
- Planner: defines planning goals and success criteria for CAP tradeoff review.
- Implementer: collects data, runs experiments, and composes recommended configurations.
- Researcher: gathers CAP theorem references, failure mode data, and historical tradeoffs.
- DomainExpert: provides domain-specific invariants and architectural constraints.
- Reviewer: assesses outputs for correctness, completeness, and safety.
- Orchestrator: coordinates planning, execution, and handoffs; enforces governance.

Supervisor or orchestrator behavior:
- The Orchestrator maintains the global memory store, triggers handoffs, and collects results.
- Escalates to DomainExpert or Architect when uncertainty exceeds tolerance thresholds.
- Enforces tool governance and permission boundaries.

Handoff rules between agents:
- Planner -> Implementer: pass plan and acceptance criteria.
- Implementer -> Reviewer: pass results and validation evidence.
- Reviewer -> DomainExpert or Orchestrator: if domain issues or escalations arise.

Context, memory, and source-of-truth rules:
- Context is stored in memory.json and versioned.
- Source-of-truth includes CAP theorem references, system constraints, and test results.
- Agents must cite sources for any CAP claim.

Tool access and permission rules:
- Tools allowed: data fetch, code analysis, test runner, version control.
- Secrets must be retrieved from a secure vault; never hard-code credentials.
- All tool actions are auditable and must be traceable to a specific step.

Architecture rules:
- Architecture must be modular to support multi-agent orchestration.
- Agents operate in a sandboxed environment; changes to production systems require orchestrator approval.

File structure rules:
- Use a dedicated cap-tradeoff-review project root.
- Organize by agent role under planners/, implementers/, researchers/, domain-experts/, and orchestrator/.
- Include memory/, docs/, tests/ and pipelines/ folders.

Data, API, or integration rules when relevant:
- Input data: CAP constraints, invariants, failure modes, latency/throughput objectives.
- APIs: cap-tradeoff endpoints must be accessed through orchestrator.
- Integrations: CI, test harness, and metrics collector.

Validation rules:
- All outputs must satisfy predefined acceptance criteria and traceable evidence.
- Validation includes unit, integration, and end-to-end checks where applicable.

Security rules:
- Do not leak secrets; redact PII; follow least-privilege access.
- Audit logs must not contain raw secrets.

Testing rules:
- Include deterministic unit tests and integration checks for CAP scenarios.
- Use synthetic CAP failure injections with rollback verification.

Deployment rules:
- No production changes without orchestrator approval and a green test run.
- Versioned AGENTS.md changes must be reviewable.

Human review and escalation rules:
- If CAP implications are uncertain, escalate to DomainExpert and Architect.
- All escalations must be logged with rationale and evidence.

Failure handling and rollback rules:
- Implement step-level rollback; if a step fails, revert to last successful state.
- Capture failure reason and remediation steps.

Things Agents must not do:
- Do not bypass validation or governance.
- Do not access production data without authorization.
- Do not mutate memory or source-of-truth without traceability.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support CAP tradeoff reviews with clear ownership.

• Planner decides on review scope, data requirements, and success criteria.
• Implementer gathers data, runs experiments, and documents outcomes.
• Researcher providesCAP references and evidence for tradeoffs.
• DomainExpert validates architectural constraints and invariants.
• Reviewer validates the final recommendations and triggers escalations if needed.
• Orchestrator coordinates all steps and ensures governance rules are satisfied.

Recommended Project Structure

cap-tradeoff-review/
├── orchestrator/
├── planner/
├── implementer/
├── researcher/
├── domain-expert/
├── reviewer/
├── memory/
├── docs/
├── tests/
└── pipelines/

Core Operating Principles

• Operate with explicit CAP tradeoff goals and acceptance criteria.
• Maintain traceable memory and source-of-truth for all claims.
• Enforce tool governance and access controls.
• Use multi-agent collaboration patterns for complex tradeoffs.
• Escalate to DomainExperts when domain-specific knowledge is required.

Agent Handoff and Collaboration Rules

• Planner<->Implementer: explicit handoff of plan, data requirements, and constraints.
• Implementer<->Reviewer: share results, evidence, and validation status.
• Reviewer<->DomainExpert: escalate for architectural invariants as needed.
• Orchestrator: monitors progress, enforces decisions, and handles escalations.

Tool Governance and Permission Rules

• Execute commands only through approved interfaces; no direct shell access to production environments.
• Manage secrets through a vault; never hard-code credentials.
• Require supervisor approval for API calls that modify production state.

Code Construction Rules

• Code changes must be traceable to a task and approval chain.
• Follow established linting and security scanning rules.
• All CAP data manipulations must be validated against test data.

Security and Production Rules

• PII is prohibited in CAP tradeoff reviews.
• Production changes require orchestration-layer approval and rollback plan.

Testing Checklist

• Unit tests for each sub-agent’s logic.
• Integration tests that cover planner-implementer-reviewer workflows.
• End-to-end tests with CAP scenario injections.

Common Mistakes to Avoid

• Skipping source-of-truth citations for CAP claims.
• Bypassing handoffs or altering memory without traceability.
• Assuming CAP tradeoffs without domain validation.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Micro-Lenders Using Phone Usage Data Metrics To Evaluate Creditworthiness In Unbanked Regions.

FAQ

What is this AGENTS.md template for CAP theorem tradeoff reviews?

It provides a structured, copyable operating manual for conducting CAP tradeoff reviews across AI coding agents, enabling single-agent and multi-agent orchestration.

Who acts as the supervisor or orchestrator?

The Orchestrator coordinates planning, execution, and handoffs, enforces governance, and escalates when needed.

How are CAP tradeoffs captured and validated?

Tradeoffs are captured with explicit criteria, data requirements, and evidence; validation uses unit, integration, and end-to-end checks.

What are the tool governance rules?

Tools must be accessed via approved interfaces, secrets managed in vaults, and any production-affecting calls require orchestrator approval.

How is memory and source-of-truth managed?

Context is stored in a versioned memory store; CAP sources and validated results form the source of truth.