AGENTS.md Template for Agentic Workflow Simulation Agents

Overview

Direct answer: This AGENTS.md Template defines an agent roster, orchestrator rules, and governance for simulating agentic workflows with AI coding agents. It supports both single-agent execution and multi-agent orchestration with explicit handoffs, memory rules, tool access controls, and escalation paths.

The template is designed for engineering teams building AI coding agents that operate in a simulated environment, enabling rigorous planning, execution, validation, and review cycles across a defined agent roster and a central orchestrator.

When to Use This AGENTS.md Template

• You need a repeatable operating manual for agentic workflow simulations involving multiple agent roles.
• You require explicit handoffs, governance, and memory/Source-of-Truth rules for reproducible experiments.
• You want a shareable blueprint to onboard new agents and auditors into a simulated workflow.
• You need to enforce tool governance and security constraints in a controlled, testable environment.

Copyable AGENTS.md Template

# AGENTS.md

Project: Agentic Workflow Simulation

1) Project role
- Owner: Tech Lead / AI Architect
- Objective: Define and run agentic workflow simulations with a clear roster, orchestration rules, and governance

2) Agent roster and responsibilities
- Planner Agent: creates high level plan, defines tasks, prioritizes work
- Implementer Agent: translates plan into executable artifacts
- Researcher Agent: gathers data, APIs, docs needed for tasks
- Domain Specialist Agent: provides domain-specific validation and constraints
- Evaluator Agent: validates outputs against acceptance criteria
- Tester Agent: runs unit and integration tests in the simulation
- Reviewer Agent: performs final review before handoff to orchestrator
- Domain Orchestrator (Supervisor): coordinates all agents, enforces rules, triggers handoffs

3) Supervisor or orchestrator behavior
- Maintains a living plan and timeline
- Triggers agent handoffs when criteria are met or blockers are encountered
- Logs decisions to a central memory store
- Escalates to human review when risk exceeds thresholds

4) Handoff rules between agents
- Planner → Implementer: handoff plan and acceptance criteria
- Implementer → Evaluator: handoff artifacts for validation
- Researcher/Domain Specialist → Planner: return findings with recommended actions
- Any agent → Orchestrator: escalate on blocker or policy breach

5) Context, memory, and source-of-truth rules
- All decisions are logged in a central memory store with timestamps
- Source of Truth: centralized knowledge base, code repository, and test results
- Agents must reference only the Source-of-Truth for validation and avoid external drift

6) Tool access and permission rules
- Tools: code sandbox, file system operations, API clients, data fetchers
- Permissions: read in memory/knowledge base; write only to designated artifacts per role
- Secrets: never print secrets; secret access granted through orchestrator with ephemeral tokens

7) Architecture rules
- Central orchestrator coordinates a fixed roster of agents
- Each agent has a scoped API surface and clear input/output contracts
- All artifacts stored under a version-controlled directory structure

8) File structure rules
- /agents
  - planner/
  - implementer/
  - researcher/
  - domain-specialist/
  - evaluator/
  - tester/
  - reviewer/
  - orchestrator/
- /tools
- /workflows
- /docs
- /tests
- AGENTS.md (this template)

9) Data, API, or integration rules when relevant
- All API calls must be gated by the orchestrator
- Data reads/writes go through a central memory layer with audit trails
- Mock services used in simulation must be clearly labeled

10) Validation rules
- Acceptance criteria must be defined in the Planner output
- Validation results must be attached to each handoff
- No handoff occurs without a passing validation record

11) Security rules
- Secrets never exposed in logs or messages
- All external calls are sandboxed
- Access tokens rotated per run

12) Testing rules
- Unit tests for each agent contract
- Integration tests for end-to-end handoffs
- Rollback scripts exist for failed runs

13) Deployment rules
- Simulation runs are versioned and reproducible
- Rollback to last good state if a run fails

14) Human review and escalation rules
- Escalate to humans on security risk or high-impact design decisions
- Review notes must be attached to the run

15) Failure handling and rollback rules
- If any agent fails, trigger rollback of artifacts and revert memory state
- Re-run with updated plan after root-cause analysis

16) Things Agents must not do
- Do not bypass orchestrator rules
- Do not access secrets directly
- Do not mutate shared sources without trace
- Do not perform production deployments from simulation

Recommended Agent Operating Model

The recommended operating model assigns explicit roles with clear decision boundaries and escalation paths. The Orchestrator maintains global context, enforces policies, and coordinates handoffs. Planners create plans that are executed by Implementers, while Researchers and Domain Specialists feed domain data. Evaluators and Testers verify outputs before handoffs. Reviewers provide final sign-off. Escalation paths to humans exist for security, policy, or risk events.

Recommended Project Structure

project-root/
  agents/
    planner/
    implementer/
    researcher/
    domain-specialist/
    evaluator/
    tester/
    reviewer/
  orchestrator/
  tools/
  workflows/
  docs/
  tests/
  README.md
  AGENTS.md

Core Operating Principles

• Single source of truth for all decisions and results
• Deterministic, idempotent actions with clear contracts
• Explicit handoffs with traceable context
• Human-in-the-loop for risk-prone decisions
• Auditable logs and artifact versioning
• Security-first and secret-minimizing by default

Agent Handoff and Collaboration Rules

• Planner hands off plan to Implementer with criteria and acceptance tests
• Implementer passes artifacts to Evaluator for validation
• Researcher and Domain Specialist provide inputs when requested by Planner
• Orchestrator mediates any conflict between agents and enforces governance
• All handoffs require a successful validation record

Tool Governance and Permission Rules

• Execute commands only via approved tool sandbox
• Writes to artifacts are restricted by role
• Secrets are accessed through orchestrator and never logged
• External API calls require review and approval gates

Code Construction Rules

• Write clean, typed interfaces for agent contracts
• Keep logic modular and idempotent
• Avoid global state and side effects without trace
• Document assumptions and data shapes explicitly
• Include extensive in-code validation

Security and Production Rules

• Isolate simulation environments from production endpoints
• Rotate tokens between runs and enforce least privilege
• Audit all data access and export paths
• Impose rate limits and input validation to protect services

Testing Checklist

• Unit tests for each agent contract
• End-to-end integration tests for handoffs
• Security tests for secret handling
• Regression tests after rule changes

Common Mistakes to Avoid

• Skipping explicit handoffs leading to context drift
• Violating tool governance or security rules
• Overfitting to a single agent, reducing resilience
• Ignoring audit trails and versioning

FAQ

What is the purpose of this AGENTS.md Template?

To provide a copyable, running AGENTS.md template that defines roles, governance, and orchestration for simulating agentic workflows with AI coding agents.

Which agents are involved in the workflow?

Planner, Implementer, Researcher, Domain Specialist, Evaluator, Tester, Reviewer, and a central Orchestrator coordinate the workflow.

How are handoffs enforced between agents?

Handoffs occur only after successful validation, with explicit artifacts and acceptance criteria recorded in memory.

How is tool governance enforced in the simulation?

All tool usage is regulated by the orchestrator with role-based permissions and audited through logs and run records.

What happens on failure or rollback?

Failures trigger rollback of artifacts, restoration of prior memory state, and a replan with root-cause analysis before re-run.

Where should I store and reference sources of truth?

In a central knowledge base and versioned code/tests; agents reference these sources for validation and decisions.