AGENTS.md Template for AI Agent Orchestration Architecture

Overview

Direct answer: This AGENTS.md Template provides a concrete operating manual for designing and running AI coding agents, including multi-agent orchestration, handoffs, tool governance, and human review.

The AGENTS.md template defines the project-level operating context for both single-agent and multi-agent work. It clarifies roles, responsibilities, memory strategies, tool access, and governance to ensure safe, auditable agent execution.

When to Use This AGENTS.md Template

Architecting both single-agent and multi-agent workflows in AI coding projects.
Establishing clear handoff points between planners, implementers, reviewers, and testers.
Setting tool governance, memory rules, and source-of-truth references for reproducible agent behavior.
Providing an auditable, deployable operating manual for engineering teams and governance bodies.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Lead AI Architect and Orchestration Steward

Agent roster and responsibilities:
- Planner: designs plan for tasks and sequencing
- Implementer: executes plan, writes code and integrates tools
- Reviewer: validates outputs, ensures quality and compliance
- Tester: runs tests, records results
- Researcher: fetches data, sources, and domain knowledge
- Domain Specialist: handles domain-specific constraints and approvals

Supervisor or orchestrator behavior:
- The Orchestrator coordinates all agents, maintains memory, enforces memory and source-of-truth rules, and triggers handoffs when criteria are met.
- It logs decisions and surfaces escalation when confidence is low.

Handoff rules between agents:
- Planner outputs a structured plan with milestones and success criteria.
- Implementer begins work, referencing plan and memory.
- Reviewer validates outputs against acceptance criteria; if fails, return to Implementer with feedback.
- Tester runs tests; if pass, hand to Domain Specialist or deploy; if fail, loop back to Implementer.
- Researcher updates memory with new sources; Branches for specializations as needed.
- Domain Specialist signs off on domain-specific constraints before final deployment.

Context, memory, and source-of-truth rules:
- Memory is stored in a shared vector store and tied to a workspace ID.
- All critical decisions reference a single source of truth: repository docs, design specs, and external data sources listed in the memory store.
- Agents must cite sources and update memory when relevant.

Tool access and permission rules:
- Agents may call allowed tools only via the Orchestrator; credentials are stored in a secure vault and never hard-coded.
- Prohibited: direct production system edits by non-approved agents.

Architecture rules:
- Modular microservices for planner, orchestrator, and execution components; clear API contracts between modules.
- Idempotent operations; stateless plan execution with a persistent workflow log.

File structure rules:
- Top-level AGENTS.md at repository root.
- src/planner/, src/implementer/, src/reviewer/, src/tester/, src/researcher/, src/domain-specialist/, orchestrator/, configs/

Data, API, or integration rules:
- Standardized data contracts for inputs and outputs; versioned APIs; audit trails for data access.

Validation rules:
- Acceptance criteria must be verifiable; tests cover unit, integration, and end-to-end validations.

Security rules:
- Secrets in vault; avoid logging secrets; rotate keys; enforce least privilege.

Testing rules:
- Unit tests per agent; integration tests for cross-agent flows; end-to-end tests for orchestration patterns.

Deployment rules:
- Deploy via CI/CD; require code review; run tests; require approver sign-off before production.

Human review and escalation rules:
- Any high-risk changes require human review; escalate to security/legal if needed.

Failure handling and rollback rules:
- If a critical step fails, rollback to last known-good state; notify stakeholders; preserve audit trails.

Things Agents must not do:
- Do not bypass memory sources; do not modify production configurations without approval; do not fabricate data.

Recommended Agent Operating Model

The operating model defines roles, decision boundaries, and escalation paths for AI coding agents. Planner frames the objective; Implementer executes; Reviewer checks quality; Tester validates; Researcher provides domain data; Domain Specialist ensures domain constraints. The Orchestrator enforces governance, coordinates handoffs, and provides memory and traceability for all actions.

Recommended Project Structure

agents-md-template-root/
  orchestrator/
  planner/
  implementer/
  reviewer/
  tester/
  researcher/
  domain-specialist/
  memory/
  configs/
  workflows/
  docs/

Core Operating Principles

Clear responsibility boundaries and auditable decisions.
Idempotent operations and deterministic planning.
Always expose source-of-truth references and memory for decisions.
Least-privilege tool access with enforced approval gates.
Visible, testable, and revertible deployment paths.

Agent Handoff and Collaboration Rules

Planner to Implementer: ensure executable, traceable plan with acceptance criteria.
Implementer to Reviewer: provide artifacts and evidence of compliance.
Reviewer to Tester: attach test coverage and results.
Tester to Orchestrator: if failures occur, trigger remediation loop or escalation.
Researcher to Domain Specialist: align domain data with domain constraints.

Tool Governance and Permission Rules

All tool calls must go through the orchestrator with access controls and audit logging.
Secrets must be retrieved from a vault; never hard-coded.
Production edits require approval gates and staging validation.
External service calls must be rate-limited and logged.

Code Construction Rules

Follow modular, testable patterns with clear interfaces between agents.
Ensure idempotence and deterministic outputs for reproducibility.
Document all non-obvious decisions and data sources in memory.
Avoid hard-coded constants; fetch configuration from central configs.

Security and Production Rules

Encrypt secrets at rest and in transit; rotate keys regularly.
Enforce least privilege across all agents and services.
Implement robust audit trails for all changes and deployments.

Testing Checklist

Unit tests for each agent under normal and edge cases.
Integration tests for cross-agent handoffs and data flows.
End-to-end tests of the full orchestration pattern in a staging environment.
Security and vulnerability checks for secrets handling.
Performance tests to confirm latency budgets for handoffs.

Common Mistakes to Avoid

Skipping memory and source-of-truth discipline during handoffs.
Bypassing approval gates or deploying unsafe changes.
Over-engineering handoffs or creating unnecessary agents.
Ignoring audit trails and test coverage in production changes.
Assuming all tools are always available; plan for outages.

FAQ

What is this AGENTS.md Template used for?

This AGENTS.md Template provides a formal operating manual for AI coding agents and multi-agent orchestration, including roles, handoffs, tool governance, and validation rules.

Can I adapt this template for single-agent workflows?

Yes. The template describes both individual agent flows and multi-agent orchestration, with explicit handoff and escalation rules.

What are the key guardrails in this template?

Tool access controls, memory and source-of-truth rules, security requirements, and escalation paths are defined to prevent context drift and unsafe operations.

How do agents hand off work in this template?

Handoffs follow a defined sequence: Planner -> Implementer -> Reviewer -> Tester -> Researcher/Domain Specialist, with checks before each transition.

Where should I place this AGENTS.md file in a project?

Place a single AGENTS.md at the root of the project/workspace to govern the entire agent orchestration pattern. Include a per-workflow subfolder if needed.

Target User

Use Cases