AGENTS.md Template for Operational Transformation Architecture

Overview

Direct answer: The AGENTS.md template for operational transformation architecture provides a precise operating manual to coordinate AI coding agents across single-agent and multi-agent workflows, including agent roles, handoffs, memory rules, tool governance, and security constraints.

It defines an explicit orchestration model to enable reliable transformation of operational inputs into outputs, while preserving sources of truth and enabling human review where needed.

When to Use This AGENTS.md Template

• You are designing a multi-agent workflow to transform operational data and decisions.
• You need a formal roster of agents with clear responsibilities and escalation paths.
• You require explicit handoff rules, memory governance, and tool access controls.
• You want a reusable operating manual that can be adapted to new transformation patterns.
• You must enforce security, auditing, and production deployment constraints.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Operational Transformation Architect

Agent roster and responsibilities:
- Planner: defines workflow goals, success criteria, and high-level plan.
- Implementer(s): execute plan steps, coordinate tool calls, and generate artifacts.
- Researcher: gathers external data sources, validates assumptions, and surfaces risk.
- Reviewer: inspects outputs for quality, integrity, and alignment with goals; approves or requests changes.
- Domain Specialist: provides domain-specific rules, constraints, and validations.
- Monitor / Orchestrator: maintains state, enforces constraints, and triggers handoffs.

Supervisor or orchestrator behavior:
- The Orchestrator maintains the authoritative plan, ensures idempotence, and coordinates handoffs between agents.
- It enforces tool governance, secrets handling, and production gating; it never performs user-facing actions without approval.

Handoff rules between agents:
- Planner -> Implementer: passes plan, context, and success criteria.
- Implementer -> Reviewer: passes artifacts and validation results.
- Researcher/Domain Specialist -> Planner: passes updated constraints and risk signals.
- Any agent may escalate to Monitor if a failure or policy violation is detected.

Context, memory, and source-of-truth rules:
- Memory Store: a persistent vector or event store containing agent state, decisions, and artifacts.
- Source of Truth: the system of record (event store, database) used for validation and rollback.
- Each handoff includes a snapshot of context tokens and the latest source-of-truth pointers.

Tool access and permission rules:
- Agents may access only approved tools via the orchestrator.
- Secrets are never embedded in code; use a secure secrets service with rotation.
- Production systems require explicit approval gates and sandboxed environments.

Architecture rules:
- Modular, event-driven architecture with clear boundaries between components.
- All steps are idempotent; operations can be retried safely.
- Interfaces are versioned and contract-tested.

File structure rules:
- No irrelevant folders; only folders related to the orchestration pattern.
- Maintain a single source of truth per artifact; avoid duplicative copies.

Data, API, or integration rules when relevant:
- Data contracts, schemas, and endpoints must be versioned.
- Use retriable API calls with exponential backoff and circuit breakers.

Validation rules:
- Each agent must produce machine-readable validation outcomes.
- All artifacts pass a final validation before promotion to production.

Security rules:
- Principle of least privilege for all agents.
- Secrets are rotated, and access is logged.

Testing rules:
- Unit tests for each agent
- Integration tests for handoffs and orchestration
- End-to-end tests in a staging environment

Deployment rules:
- Feature flags control rollout; production changes require approvals.
- All changes are auditable and reversible.

Human review and escalation rules:
- If risk is detected, escalate to a human operator with context.
- Reviewers can trigger a rollback or pause the workflow.

Failure handling and rollback rules:
- On failure, revert to the last known good state in the source of truth.
- Use compensating actions to undo changes; ensure idempotency.

Things Agents must not do:
- Do not bypass the orchestrator or modify the source of truth directly.
- Do not leak secrets or credentials.
- Do not perform unsanctioned changes in production.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support both single-agent execution and multi-agent coordination. The Planner defines the strategy, while Implementers perform execution with oversight from Reviewers and Domain Specialists. The Monitor enforces governance and triggers escalations when policy violations occur.

Recommended Project Structure

operational-transformation-architecture/
  docs/
  orchestrator/
  agents/
    planner/
    implementer/
    researcher/
    reviewer/
    domain-specialist/
  memory/
  data-schemas/
  integrations/
  tests/
  artifacts/

Core Operating Principles

• Opt-in collaboration: agents share context and decisions via the source of truth.
• Idempotence: all actions are safe to retry without side effects.
• Least privilege: access is restricted to necessary tools and data.
• Traceability: every decision and handoff is auditable.
• Human-in-the-loop when risk or ambiguity exceeds thresholds.

Agent Handoff and Collaboration Rules

• Planner-to-Implementer handoffs carry plan, success criteria, and constraints.
• Implementer-to-Reviewer passes artifacts, results, and validation outcomes.
• Researcher and Domain Specialist provide updates to the Planner when new data or constraints emerge.
• Handoffs require explicit state updates to the source of truth and memory.

Tool Governance and Permission Rules

• All tool calls go through the orchestrator with audit logging.
• Secrets must be sourced from a secrets manager; never hard-coded.
• APIs must be rate-limited, authenticated, and contract-tested.

Code Construction Rules

• Write modular, well-documented components; avoid global mutable state.
• Use versioned interfaces; changes require backward compatibility.
• All artifacts must be produced in well-defined formats (JSON, YAML, etc.).

Security and Production Rules

• Enforce least privilege; rotate credentials; monitor for anomalies.
• Deploy behind feature flags; enable observability; require approval for production changes.

Testing Checklist

• Unit tests for each agent behavior
• Integration tests for handoffs
• End-to-end tests in staging with synthetic data

Common Mistakes to Avoid

• Skipping explicit handoffs and relying on implicit context transfers.
• Mutating the source of truth outside the orchestrator.
• Overprivileging agents or leaking secrets.

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 Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is this AGENTS.md Template for Operational Transformation Architecture?

This template defines the operating model, agent roles, and collaboration rules to execute a multi-agent transformational workflow within an operational transformation architecture.

How are agent handoffs defined in this template?

Handoffs are defined by explicit transitions, memory passes, and source-of-truth updates, orchestrated by the Planner agent and validated by the Reviewer before Implementer proceeds.

What are the security and production constraints?

Exposed credentials are never shared. All actions require least privilege access, secrets management, and production safeguards, with alarms for anomalies.

How do you validate multi-agent workflows?

Validation includes unit tests per agent, integration tests for the handoff paths, and end-to-end scenario tests in a staging environment.

Where can I extend or customize this template?

Clone the AGENTS.md Templates collection and create a new template for the target orchestration pattern; ensure alignment with the core operating principles.