AGENTS.md Template for Planner-Executor-Critic Agent Systems

Overview

Direct answer: This AGENTS.md Template provides a complete operating manual for a planner executor critic AI coding agent system, enabling multi agent orchestration with explicit rules for handoffs memory tools and human review. It supports both single agent execution contexts and robust multi agent collaboration.

The AGENTS.md template defines project roles the roster and responsibilities of each agent how supervision and orchestration occur and the criteria for escalation to human review when uncertainty or risk rises. It codifies tool governance and safety constraints so agents act within permitted boundaries.

When to Use This AGENTS.md Template

• When designing an AI coding agents workflow that relies on planner executor and critic roles for end to end automation.
• When you need explicit handoff rules and a single source of truth for multi agent orchestration.
• When tool access memory and data provenance must be governed and auditable.
• When human review and escalation are required for high risk decisions or outputs.
• When you want a copyable AGENTS.md Template that teams can paste into repositories to bootstrap governance.

Copyable AGENTS.md Template

# AGENTS.md
Project: Planner-Executor-Critic Agent System
Agent roster and responsibilities
- Planner: generates a concrete plan of actions from the current objective.
- Executor: carries out planned actions using tools and integrations.
- Critic: reviews outputs for quality, accuracy, and safety.
- Researcher: optional, gathers external facts and sources.
- Domain Specialist: optional, provides domain specific guidance.

Supervisor and orchestration
- Orchestrator: coordinates actors, enforces rules, and maintains shared context.

Handoff rules
- Planner -> Executor: when a concrete action sequence is ready.
- Executor -> Critic: after performing actions to validate results.
- Critic -> Planner: if issues are found or improvements are needed.
- Escalate to Human: when uncertainty crosses a threshold or risk increases.

Context, memory, and source of truth
- Maintain a memory context with a single source of truth for data outputs and decisions.
- Sources of truth include tool results logs and versioned artifacts.

Tool access and permission rules
- Tools: only approved toolsets; access controlled by role; secrets never logged.
- Actions require permission checks and audit trails.

Architecture rules
- Modular components for planner executor critic; clear interfaces.
- Stateless actions with replayable logs for debugging.

File structure rules
- See Recommended Project Structure section for the directory tree.

Data API and integration rules
- Use versioned APIs document inputs and outputs.
- Validate schemas before integration.

Validation rules
- Validate that outputs meet objective criteria before progression.
- Confirm tool results accuracy and consistency.

Security rules
- Never expose secrets; rotate keys; restrict tool calls by role.

Testing rules
- Unit tests for planning logic.
- Integration tests for tool calls.

Deployment rules
- Deploy agents with versioned capabilities; containerized or serverless contexts.

Human review and escalation rules
- Trigger human review for uncertain outputs; log escalations.

Failure handling and rollback rules
- If failure occurs, rollback changes in memory and artifacts; retry with updated plan.

Things Agents must not do
- Do not override safety policies; do not perform unsanctioned external actions.

Recommended Agent Operating Model

Planner proposes actions, Executor implements, Critic validates. Escalation paths to humans exist for high risk. Clear ownership for artifacts produced during the workflow.

Recommended Project Structure

/agents
  /planner
  /executor
  /critic
/memory
/workflows
/tools
/config

Core Operating Principles

• Operate with explicit boundaries and escalation paths.
• Maintain a single source of truth and auditable traces.
• Favor deterministic planning with transparent validation.
• Minimize context drift and ensure reproducible results.
• Prioritize human review for high risk decisions.

Agent Handoff and Collaboration Rules

Planner to Executor handoff occurs after a complete action plan. Executor to Critic handoff occurs after execution. Critic may request planner revision. Domain specialists can be consulted for specific domains.

Tool Governance and Permission Rules

• Executors may access only approved tools with scoped permissions.
• All tool calls must be logged and auditable.
• Secrets must never be written to disk or logs.
• All external calls require explicit approval gates when needed.

Code Construction Rules

• Write modular, testable code with clean interfaces between planner, executor, and critic.
• Document inputs outputs and contracts for each component.
• Avoid duplicating work; reuse memory and facts from the shared store.

Security and Production Rules

• Enforce least privilege for all agents.
• Rotate and manage keys securely; do not log secrets.
• Implement observability and alerting for failures and escalations.

Testing Checklist

• Unit tests for planning logic.
• Integration tests to verify handoffs and tool calls.
• End to end tests to validate the full planner execute critic loop.
• Security and access control tests.

Common Mistakes to Avoid

• Overlooking memory synchronization across agents.
• Skipping explicit handoff rules leading to drift.
• Allowing unsanctioned tool usage or secrets exposure.
• Relying on one agent to perform all tasks without failure handling.

FAQ

What is the Planner-Executor-Critic AGENTS.md Template?

A copyable AGENTS.md template that defines a planner executor and critic loop for AI coding agents with explicit handoffs, tool governance, memory, and escalation rules.

How do agent handoffs work in this workflow?

The planner produces a plan that the executor attempts; the critic then evaluates outputs. If issues arise, control returns to the planner or escalates to a human.

What are the memory and source of truth rules?

All outputs decisions and tool results are stored in a single memory store and versioned source of truth to ensure traceability.

What are the security rules?

Secrets are never logged or exposed. Tool access is restricted by role and audited.

How is failure handled and rolled back?

On failure the system rolls back artifacts resets memory to a prior safe state and retries with updated planning if appropriate.