AGENTS.md Template: Multi-Agent Delivery Orchestration

Overview

Direct answer: This AGENTS.md Template defines a repeatable operating manual for AI coding agents that deliver software via multi-agent orchestration. It governs both single-agent execution and multi-agent handoffs, ensuring governance, memory, and auditability across the workflow.

It provides project-level operating context, including agent roles, responsibilities, handoff rules, and validation criteria for software delivery pipelines.

When to Use This AGENTS.md Template

• When you want a reusable operating manual for AI coding agents in software delivery
• When you require explicit handoff rules between planner, implementer, reviewer, tester, and domain experts
• When you need tool governance, secrets handling, and production safeguards
• When you must preserve a single source of truth and auditability across multi-agent workflows

Copyable AGENTS.md Template

# AGENTS.md

Project: Multi-Agent Delivery Orchestration

Roster:
- Planner: defines goals, strategy, and plan
- Implementer: executes tasks from the plan
- Reviewer: reviews artifacts and outputs
- Tester: validates results against requirements
- Researcher: gathers data and signals for decisions
- Domain Specialist: provides context for specialized areas

Supervisor/Orchestrator:
The central orchestrator coordinates agent interactions, enforces constraints, stores context in a canonical memory, and triggers handoffs based on signals.

Handoff rules:
- Planner ➜ Implementer: when a feasible plan is produced
- Implementer ➜ Reviewer/Tester: upon completion of a module or artifact
- Researcher/Domain Specialist ➜ Planner: when new signals require replanning
- Any agent can request escalation to Supervisor if constraints are violated

Context, memory, and source-of-truth:
- All decisions and outputs must be recorded in /data/workflow-trace
- The canonical source of truth is the shared memory store accessible to all agents
- Use immutable artifacts with versioned identifiers

Tool access and permission rules:
- Agents may call only authorized tools with scoped permissions
- Secrets are retrieved from a zero-trust vault and never hard-coded
- Production system calls require Supervisor approval gates

Architecture rules:
- Microservice-like modular tasks with clear boundaries
- Each agent is stateless except for memory carried in the canonical store
- Outputs must be structured, validated, and stored with metadata

File structure rules:
- /workflows/.. contains agents.md-related artifacts
- /tools/ contains tool interfaces
- /data/ contains memory and memory snapshots

Data, API, or integration rules:
- All APIs must be idempotent and logged
- Responses must include provenance and confidence signals

Validation rules:
- All outputs must pass schema validation and unit checks
- Validation results are stored with artifacts

Security rules:
- Do not expose secrets in outputs
- Enforce least privilege for tool access

Testing rules:
- Include unit, contract, and end-to-end tests for workflow steps
- Test for failure modes and rollback paths

Deployment rules:
- Deploy agents together as a single release with rollback triggers
- Feature flags govern new agent behavior

Human review and escalation rules:
- Always escalate high-risk changes to a human reviewer
- Define a SLA for review cycles

Failure handling and rollback rules:
- On failure, revert outputs to last good artifact and notify Supervisor
- Abort on irrecoverable errors and trigger postmortem

Things Agents must not do:
- Do not perform unsanctioned production actions
- Do not hide memory or outputs from the canonical store
- Do not bypass approval gates

Recommended Agent Operating Model

The recommended operating model defines roles, decision boundaries, and escalation paths for effective multi-agent delivery. Planner guides the strategy; Implementer executes; Reviewers validate; Testers verify; Researchers inform; Domain Specialists provide domain-specific signals. If an agent detects a rule violation or workflow risk, escalate to the Supervisor immediately.

Recommended Project Structure

/.workflows/multi-agent-delivery/
  /ai-skills/agents-md-templates/
  /plans/
  /artifacts/
  /tests/
  /docs/
  /config/
  /secrets/

Core Operating Principles

• Operate with a single source of truth and versioned artifacts
• Keep decisions auditable with traceable signals
• Enforce strict handoff criteria and escalation thresholds
• Limit tool access by role and need
• Prefer idempotent, deterministic actions

Agent Handoff and Collaboration Rules

Rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents to coordinate handoffs and maintain context integrity.

Tool Governance and Permission Rules

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

Code Construction Rules

Concrete construction rules tailored to multi-agent software delivery orchestration: deterministic steps; strict validation; explicit artifact contracts; no hidden state; explicit failure paths.

Security and Production Rules

Security rules specific to workflow: secret handling, access control, observability, and least privilege for all agents in production environments.

Testing Checklist

• Unit tests for individual agents
• Integration tests for agent handoffs
• End-to-end tests for the entire orchestration flow
• Deployment tests and smoke checks

Common Mistakes to Avoid

• Assuming agents have implicit capabilities; declare capabilities explicitly
• Skipping handoff validation; allow only well-formed transitions
• Overexposing tool capabilities; use least privilege
• Ignoring memory consistency across agents

FAQ

What is the purpose of this AGENTS.md template?

This AGENTS.md Template defines a reproducible operating manual for AI coding agents to deliver software via multi-agent orchestration, including roles, handoffs, and governance.

How does it support multi-agent orchestration?

It specifies a roaster, supervisor behavior, memory rules, and concrete handoff protocols to coordinate planner, implementer, reviewer, tester, researcher, and domain specialist agents.

What are the handoff rules between agents?

Handoffs occur at defined state boundaries: planner to implementer on plan generation, implementer to reviewer/tester on artifact completion, researchers and domain specialists alert planning when signals require replanning.

How is tool governance enforced?

Access is restricted by role, secrets are fetched from a vault, and production actions require supervisor-approved gates and audit logging.

How do you handle failures and rollback?

On failure, rollback to the last good artifact, isolate failing components, notify the supervisor, and trigger a postmortem to prevent recurrence.

How should security be enforced?

Apply least privilege, secret rotation, audit trails, and secure communication channels between agents and tools.