AGENTS.md Template for Multi-Agent Workflow Systems

Overview

Direct answer: This AGENTS.md Template defines a repeatable multi-agent workflow system and governs how AI coding agents collaborate, with explicit roles, memory, tool access, and handoff rules to support both single-agent and multi-agent orchestration.

The template provides a concrete operating manual for AI coding agents to work together in a controlled, observable, and auditable manner. It covers the full lifecycle from task planning to execution, verification, and escalation, and it defines how agents share context, trigger handoffs, access tools, and maintain a single source of truth. Used at project level, it scales from a single agent to an orchestration pattern across multiple agents while preserving governance and human review where needed.

When to Use This AGENTS.md Template

• When you design AI coding agents that must operate in a coordinated, multi-agent workflow
• When planning handoffs between planner, implementer, verifier, researcher, and domain specialist agents
• When you require tool governance, secret handling, and production-safe decision making
• When you need a project-level operating context that both individuals and teams can refer to for compliance and reproducibility

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Orchestrator and coordinator for a multi-agent workflow system to ensure reliable AI coding outcomes with governance and human review.

Agent roster and responsibilities:
- Planner: defines tasks, sequencing, and success criteria; generates a task plan for implementer and verifier.
- Implementer: executes tasks, generates artifacts, and interfaces with tools and APIs as defined by the plan.
- Verifier: validates outputs against acceptance criteria, runs checks, and flags deviations.
- Researcher: collects external data, domain references, and context to inform decisions.
- Domain Specialist: provides domain-specific reasoning and constraints; ensures compliance with domain norms.
- Orchestrator: coordinates task assignment, monitors progress, and enforces schedules and escalation paths.
- Logger: records decisions, tool usage, and outputs for auditability.

Supervisor or orchestrator behavior:
- Maintain an up-to-date task queue and task state ledger.
- Assign tasks to agents based on role, capability, and workload.
- Enforce memory and source-of-truth rules; refresh or prune context to prevent drift.
- Trigger hands-offs when acceptance criteria are met or when risk is detected.
- Halt execution and escalate when unsafe or uncertain conditions arise.

Handoff rules between agents:
- Planner -> Implementer: pass task plan, acceptance criteria, and required data.
- Implementer -> Verifier: pass artifacts and execution evidence.
- Researcher/Domain Specialist -> Planner/Orchestrator: inject new constraints or updated context.
- Verifier -> Planner/Orchestrator: approve, request rework, or escalate.

Context, memory, and source-of-truth rules:
- All decisions must reference a single source of truth (SOT) stored in a persistent context store.
- Memory window should be bounded; avoid unbounded accumulation of stale data.
- Use citation IDs for external data sources; verify authenticity where possible.

Tool access and permission rules:
- Only authorized agents can call restricted tools; tokens are scoped and rotated regularly.
- Secrets are never logged or exposed in outputs.
- Tool usage requires an audit trail and approval by the Orchestrator for production actions.

Architecture rules:
- Use modular components with clear interface contracts between Planner, Implementer, Verifier, Researcher, and Domain Specialist.
- All API calls must be rate-limited and logged.
- Outputs must be validated against schemas before storage.

File structure rules:
- Keep all AGENTS.md related files under the agents-md-template scope.
- Store task plans in plans/; artifacts in artifacts/; and logs in logs/.

Data, API, or integration rules when relevant:
- Define data schemas and API contracts in a shared schema directory.
- Validate external data with strict type checks; reject unknown fields.

Validation rules:
- Every important action must be accepted by the Verifier before proceeding.
- Acceptance criteria must be explicit and testable.

Security rules:
- Encrypt secrets at rest and in transit.
- Do not reveal keys or credentials in outputs or logs.
- Follow least-privilege access for all tools and endpoints.

Testing rules:
- Run unit tests for each agent, integration tests for handoffs, and end-to-end tests for the workflow.
- Include test data and mocks for external dependencies.

Deployment rules:
- Promote changes via review and approval gates; avoid hot deployment without validation.
- Monitor for regressions post-deploy and rollback if needed.

Human review and escalation rules:
- Trigger human review when uncertainty or risk exceeds predefined thresholds.
- Escalate to the product owner for business-logic decisions.

Failure handling and rollback rules:
- If an artifact fails validation, revert to the last known good state and re-run the plan with adjusted parameters.
- Do not continue on critical failures without explicit approval.

Things Agents must not do:
- Do not operate outside approved tool scopes or permissions.
- Do not perform unsupervised production changes.
- Do not bypass the Verifier for acceptance.
- Do not reuse stale context for critical decisions.

Recommended Agent Operating Model

The multi-agent operating model defines clear responsibilities for Planner, Implementer, Verifier, Researcher, Domain Specialist, and Orchestrator. Decision boundaries are explicit; escalation paths are defined for uncertain outcomes and security concerns.

• Planner crafts a defensible task plan with success criteria and data requirements.
• Implementer executes tasks with traceable outputs and tool interactions.
• Verifier validates results against criteria and prevents drift or incorrect outputs.
• Researcher and Domain Specialist provide context, constraints, and evidence for decisions.
• Orchestrator coordinates work, enforces memory rules, and handles handoffs and escalation.

Recommended Project Structure

Workflow-specific directory tree:

agents-md-template/
├── plans/
├── artifacts/
├── logs/
├── tools/
├── data/
├── configs/
├── policies/
├── src/
│   ├── planner/
│   ├── implementer/
│   ├── verifier/
│   ├── researcher/
│   ├── domain-specialist/
│   └── orchestrator/

Core Operating Principles

• Operate with explicit goals, measurable criteria, and auditable decisions.
• Maintain a bounded memory window and a single source of truth.
• Use least-privilege access and never leak secrets in outputs.
• Prefer deterministic, idempotent operations; handle non-determinism with explicit reasoning traces.
• Respect tool governance and escalation policies; do not bypass reviews.

Agent Handoff and Collaboration Rules

Define how planners, implementers, verifiers, researchers, and domain experts collaborate, including when to hand off and how to communicate state changes.

Tool Governance and Permission Rules

Rules for command execution, file edits, API calls, secrets, production systems, external services, and approval gates.

Code Construction Rules

Concrete implementation constraints for this workflow; avoid vague statements.

Security and Production Rules

Workflow-specific security guidance for data handling, secrets, access control, and production deployments.

Testing Checklist

• Unit tests for each agent behavior
• Integration tests for handoffs
• End-to-end tests of the multi-agent workflow
• Security and input validation tests

Common Mistakes to Avoid

• Overlooking memory management and source-of-truth drift
• Skipping explicit handoff criteria and acceptance checks
• Neglecting tool governance and secret handling

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Visa Consultants Using Government Portals To Check Application Documents for Missing Requirements.

FAQ

What is this AGENTS.md Template for?

It provides a copyable operating manual for multi-agent workflows that govern AI coding agents across planning, implementation, verification, and governance.

Which agent roles are required for multi-agent orchestration?

Planner, Implementer, Verifier, Researcher, Domain Specialist, and Orchestrator are defined with explicit handoff rules and responsibilities.

How are handoffs defined?

Handoffs are explicit between Planner, Implementer, Verifier, Researcher, Domain Specialist, and Orchestrator with criteria and data requirements.

What about security and approvals?

Secrets and tool access are restricted, rotated, and audited; production actions require governance approvals.

How is memory managed?

A bounded memory window and single source of truth keep context fresh and auditable.

Can this template be customized?

Yes; replace domain content, tools, and contracts to fit your workflow while preserving core governance.