AI Agent Application Architecture — AGENTS.md Template

Overview

This AGENTS.md template is for AI agent application architecture and governs both single-agent and multi-agent orchestration within an AI coding agents workflow. It defines the operating model, handoff rules, tool governance, and human-in-the-loop review needed to keep agent outputs trustworthy in production. It serves as a copyable, project-level operating context that agents can reference during planning, execution, validation, and deployment.

Direct answer: Use this AGENTS.md Template to establish a formal, repeatable runtime for AI coding agents that coordinate via an orchestrator, respect memory and source-of-truth constraints, and enforce security and escalation paths.

When to Use This AGENTS.md Template

• Starting a new AI coding agents project with a multi-agent orchestration pattern.
• Defining clear handoffs between planner, implementer, reviewer, tester, researcher, and domain specialist agents.
• Establishing a governance and security model for tool access, secrets, and production deployments.
• Documenting project structure, memory rules, and validation criteria for repeatable audits.

Copyable AGENTS.md Template

Paste this block into a file named AGENTS.md at the root of your AI coding agents project. It contains all required sections for a complete operating manual.

# AGENTS.md

# Project: AI Agent Application Architecture
# Version: 1.0

Overview:
- Project role: Build a robust AI coding agents platform that enables single-agent and multi-agent orchestration with clear handoffs, tool governance, and human review.
- Agent roster and responsibilities:
  - Planner: defines tasks, scope, and plan boundaries.
  - Implementer: executes assigned tasks and builds artifacts.
  - Reviewer: validates outputs, checks safety, and ensures quality.
  - Tester: runs unit/integration tests and validates end-to-end scenarios.
  - Researcher: gathers domain knowledge and sources truth.
  - Domain Specialist: provides domain-specific constraints and guidance.
- Supervisor/Orchestrator behavior:
  - Maintains a centralized plan, routes work, and enforces memory, source-of-truth, and security policies.
  - Triggers handoffs when outputs require rework or escalation.
- Handoff rules between agents:
  - Planner -> Implementer: hand off tasks with acceptance criteria and context.
  - Implementer -> Reviewer: hand off artifacts for validation with evidence and logs.
  - Reviewer -> Implementer: return for fixes or approve with notes.
  - Researcher/Domain Specialist -> Planner/Orchestrator: provide constraints or new inputs when needed.
- Context, memory, and source-of-truth rules:
  - All decisions are logged with timestamps and provenance links.
  - Memory: limited to task context, results, and relevant references; no leakage of secrets.
  - Source-of-truth: primary data sources are declared with URLs, versions, and access controls.
- Tool access and permission rules:
  - Agents may invoke only whitelisted tools; every API call must be authenticated and auditable.
  - Secrets are injected via a secure vault; logs do not contain secret values.
- Architecture rules:
  - Central orchestrator coordinates task flows and enforces constraints.
  - Stateless agent runs with ephemeral memory; persistent state stored in a protected store.
- File structure rules:
  - Root: AGENTS.md
  - folders: orchestrator/, agents/, memory/, integrations/, configs/, tests/, docs/
- Data, API, or integration rules:
  - All external calls are logged; data minimization applies.
  - Validate API responses against schemas; handle retries with backoff.

Validation rules:
- Outputs must include provenance, citations, and evidence for decisions.
- Outputs pass domain-specific validation criteria before progression.
- All changes are reviewed by a human when high-risk operations are involved.

Security rules:
- Secrets must be accessed only through vaults; no hard-coded credentials.
- Production actions require approval gates and audit logging.
- Do not expose internal endpoints to public networks.

Testing rules:
- Unit tests for each agent role; integration tests for multi-agent flows.
- Regression tests for memory and memory-eviction behavior.
- End-to-end tests for critical workflows.

Deployment rules:
- Deploy orchestrator and agents in a controlled environment with canary steps.
- Rollback on failure with automated rollback procedures.

Human review and escalation rules:
- All high-risk changes require human approval.
- Escalate to domain expert when unknown constraints are encountered.

Failure handling and rollback rules:
- If a step fails, revert to last known good state and replan.
- Preserve audit logs for post-mortem analysis.

Things Agents must not do:
- Do not perform unsupervised production changes.
- Do not skip validation or security checks.
- Do not bypass escalation rules or memory constraints.

Notes:
- Update this document with changes in workflow, tool permissions, and governance.

Recommended Agent Operating Model

The recommended operating model assigns specific responsibilities to each agent role and defines decision boundaries and escalation paths. The orchestrator maintains the authoritative plan; planners generate tasks; implementers execute; reviewers validate; testers verify; researchers and domain specialists supply constraints. Escalations route to human review when automatic validation fails or when risks exceed defined thresholds.

Recommended Project Structure

Workflow-specific directory tree:

ai-agent-architecture/
  ├── orchestrator/
  │   ├── planner.js
  │   ├── orchestrator.go
  │   └── policies/
  ├── agents/
  │   ├── planner/
  │   │   └── tasks/
  │   ├── implementer/
  │   │   └── artifacts/
  │   ├── reviewer/
  │   │   └── validation/
  │   ├── tester/
  │   │   └── tests/
  │   ├── researcher/
  │   │   └── sources/
  │   └── domain-specialist/
  │       └── constraints/
  ├── memory/
  │   ├── cache/
  │   └── provenance/
  ├── integrations/
  │   ├── tools/
  │   └── external-services/
  ├── configs/
  │   ├── memory.json
  │   └── access- policies.yaml
  ├── tests/
  │   ├── unit/
  │   └── e2e/
  ├── docs/
  │   └── AGENTS.md
  └── deployments/
      └── canary/

Core Operating Principles

• Explicit scope and boundary conditions for each agent role.
• Single source of truth for data and decisions, with auditable provenance.
• Handoffs are explicit, with acceptance criteria and evidence required.
• Security and privacy by default; secrets never leaked to logs.
• Human review is required for high-risk or irreversible actions.

Agent Handoff and Collaboration Rules

Clear handoff guidelines between planner, implementer, reviewer, tester, researcher, and domain specialist. - Planner to Implementer: share task scope, acceptance criteria, and relevant context. - Implementer to Reviewer: attach artifacts, validation data, and evidence. - Reviewer to Implementer: provide fixes or approve with notes. - Researcher/Domain Specialist to Planner/Orchestrator: add constraints, sources, and boundary changes.

Tool Governance and Permission Rules

• Only whitelisted tools may be invoked; all calls are logged with context.
• Secrets stored in a secure vault; never embedded in code or logs.
• Production systems require approval gates and rollback capabilities.
• Access must be role-based and time-limited where possible.

Code Construction Rules

• Code must be reproducible, with versioned dependencies and deterministic builds.
• Inputs are validated; outputs include traceability and provenance.
• Do not hard-code secrets or long-lived tokens; use vaults and refresh as needed.
• Modules must be modular and testable; avoid tight coupling with the orchestrator.

Security and Production Rules

• All production deployments are gated with reviews and automated checks.
• Data minimization and least privilege principles apply to all integrations.
• Audit logs must be tamper-evident and retained for a defined period.

Testing Checklist

• Unit tests for each agent role and function.
• Integration tests for multi-agent handoffs and orchestrator patterns.
• End-to-end tests of critical workflows with simulated data.
• Security tests for credential handling and secret leakage.

Common Mistakes to Avoid

• Skipping validation or producing outputs without provenance.
• Overlapping responsibilities between agents without clear handoff criteria.
• Bypassing escalation or security gates for convenience.

FAQ

What is the purpose of this AGENTS.md Template for AI agent application architecture?

It provides a formal operating manual to govern single-agent and multi-agent workflows, including handoffs, tool governance, memory, and review processes.

How does multi-agent orchestration work in this template?

The orchestrator coordinates planners, implementers, reviewers, testers, researchers, and domain specialists, enforcing memory, provenance, and gate checks before progression.

What are the handoff rules between core roles?

Plan -> Implement: scope and criteria; Implement -> Reviewer: artifacts and evidence; Reviewer -> Implementer: fixes or approval; Researcher/Domain Specialist -> Planner/Orchestrator: constraints and inputs.

What security and production rules apply?

Secrets in vaults, auditable actions, strict access controls, and gated production deployments with rollback support.

How do you validate and test this architecture?

Include unit, integration, and end-to-end tests, with explicit validation criteria and provenance for all outputs.