AGENTS.md Template for Supervisor-Worker Multi-Agent Systems

Overview

Direct answer: This AGENTS.md Template defines the operating manual for a supervisor-worker multi-agent system, enabling AI coding agents to coordinate, hand off tasks, and govern tool usage. It supports both a single-agent scenario and multi-agent orchestration with a supervisory orchestrator guiding worker agents.

• Defines roles, responsibilities, and decision boundaries for supervisor and worker agents.
• Enforces memory, sources of truth, and auditability for all task steps.
• Specifies explicit handoff points and acceptance criteria between agents.
• Governs tool access, secrets, and integration with external services.
• Includes human review paths and escalation for high-risk decisions.

When to Use This AGENTS.md Template

• You are coordinating multiple AI coding agents that need centralized governance.
• You require explicit handoffs and collaboration rules between planner, implementer, tester, reviewer, researcher, and domain specialist agents.
• You must enforce tool governance, secrets handling, and production safeguards.
• You want a reproducible operating context that teams can version and audit.
• You need a clear escalation and rollback path for failures in a multi-agent workflow.

Copyable AGENTS.md Template

# AGENTS.md

Project
- Name: Supervisor-Worker Multi-Agent System for AI coding tasks
- Purpose: Provide a reproducible operating context for single-agent and multi-agent orchestration with explicit handoffs and tool governance

Agent roster and responsibilities
- Supervisor (Orchestrator)
  - Plan the overall workflow, assign tasks, monitor progress, enforce memory/sources of truth, and escalate to human teammates when needed.
  - Maintain task context and ratify agent outputs before handoffs.

- CoderAgent (Worker)
  - Implement code changes, generate patches, and update documentation as required by the task.
  - Produce testable outputs and report progress to Supervisor.

- ValidatorAgent (Worker)
  - Validate code quality, type safety, and basic correctness according to the task’s acceptance criteria.

- TesterAgent (Worker)
  - Run unit/integration tests and report failures with reproducible steps.

- ResearchAgent (Worker)
  - Gather external references, patterns, and official docs relevant to the task.

- DomainAgent (Worker)
  - Apply domain-specific rules and checks (e.g., compliance, industry standards) and flag gaps.

Supervisor or orchestrator behavior
- The Supervisor receives a task, decomposes it into sub-tasks, assigns them to workers, and sequences handoffs.
- It maintains a central memory store of task context, sources, and decisions.
- It requires explicit acceptance from the next agent before proceeding to the next handoff.
- It can trigger human review when risk or quality thresholds are reached.

Handoff rules between agents
- Each handoff must include: task ID, current state, evidence, and acceptance criteria for the next agent.
- The receiving agent must acknowledge and commit to the acceptance criteria before work begins.
- If the next agent cannot proceed, the Supervisor re-routes or notifies a human-in-the-loop.

Context, memory, and source-of-truth rules
- All outputs must reference sources of truth (docs, specs, or tests).
- The memory store must be versioned and queryable for traceability.

Tool access and permission rules
- Access to tools (code repos, CI systems, external APIs) is granted per-agent role with least privilege.
- Secrets must be stored in a dedicated vault and never hard-coded.

Architecture rules
- Separation of concerns: planning, execution, validation, and verification run in distinct components.
- Outputs must be auditable and reproducible.

File structure rules
- Keep a single source of truth per task.
- Organize by task, with subfolders for code, tests, docs, and artifacts.

Data, API, or integration rules
- All external calls must be authenticated and retrievable from logs.
- APIs used must have versioning and deprecation policies.

Validation rules
- Each sub-task must produce deterministic, testable results with traceable inputs.

Security rules
- No production secrets in code or logs.
- All communications must be encrypted in transit.

Testing rules
- Include unit tests for each worker, integration tests for end-to-end flows, and regression tests for handoffs.

Deployment rules
- Deploy only after passing a human-reviewed checklist.

Human review and escalation rules
- Trigger human review on high-risk decisions or tool failures.
- Provide a concise summary and the exact decision points for reviewers.

Failure handling and rollback rules
- If a worker fails, revert to the last known-good state and re-try with updated inputs.
- Maintain an audit trail of retries and rollbacks.

Things Agents must not do
- Do not bypass supervisor decision points.
- Do not access additional tools without authorization.
- Do not leak secrets or expose internal system details.

Recommended Agent Operating Model

Supervisor is the orchestration authority with final say on task sequencing. Workers operate within defined boundaries and must hand off results according to the acceptance criteria. Escalation paths are clearly defined to ensure timely human review for high-risk work.

Recommended Project Structure

ai-workflows/
  supervisor/
  workers/
    coder-agent/
    validator-agent/
    tester-agent/
    research-agent/
    domain-agent/
  memory/
  tools/
  interfaces/
  configs/

Core Operating Principles

• Explicit handoffs with acceptance criteria and traceability
• Least-privilege tool access and secrets management
• Single source of truth for task context and decisions
• Deterministic outputs and auditable decisions
• Human-in-the-loop for high-risk steps

Agent Handoff and Collaboration Rules

• Planner to Implementer: Provide a plan, input requirements, and acceptance criteria; require acknowledgment from the Implementer before work proceeds.
• Implementer to Reviewer: Deliver completed work with evidence and test results; request formal review.
• Researcher to Domain Specialist: Share references and domain constraints; Domain Specialist validates applicability.
• Domain Specialist to Planner: Return constraints and updated acceptance criteria based on domain findings.
• All handoffs must include task ID, state, evidence, and acceptance criteria.

Tool Governance and Permission Rules

• Code repos: read/write only for Coders; CI/CD triggers must go through Supervisor.
• External APIs: access is gated; tokens must be rotated and stored securely.
• Secrets: stored in vault; never in plain text
• Production systems: modifications require supervisor approval
• Audit logs: every tool action is logged and reviewable

Code Construction Rules

• Follow task-specific coding standards and tests.
• All changes must be traceable to the task and sources of truth.
• Write idempotent, well-documented code with clear error handling.
• Do not introduce race conditions or unsafe side effects.

Security and Production Rules

• Do not expose production secrets in logs or outputs.
• Operate within approved environments and use feature flags for risky changes.
• Audit trails for all actions in production

Testing Checklist

• Unit tests for each worker
• Integration tests for handoffs
• End-to-end tests for critical tasks
• Manual tests for human review paths

Common Mistakes to Avoid

• Skipping formal handoffs or acceptance criteria
• Bypassing supervisor for tool access
• Overlooking sources of truth or test coverage
• Ignoring security and production constraints

FAQ

What is AGENTS.md Template for supervisor-worker multi-agent systems?

The AGENTS.md Template provides a formal, copyable operating manual for coordinating a supervisor with worker AI coding agents in a multi-agent workflow.

Who should use this AGENTS.md Template?

Product, engineering, and AI teams implementing supervisor-worker orchestration patterns for AI coding tasks.

What should be included in the handoff between agents?

Task ID, current state, artifacts, evidence, acceptance criteria, and next-step instructions.

How are tool permissions enforced?

Least-privilege access, vault-secured secrets, and supervisor-controlled tool usage with audit logs.

What happens on failure?

Rollback to the last good state, retry with updated inputs, and escalate to human review if needed.

How is security ensured in production?

Encrypted communications, environment controls, and production-change approvals with auditable trails.