AGENTS.md Template: Human-in-the-Loop Approval Agents (AGENTS.md template)

Overview

AGENTS.md template for human-in-the-loop approval agents provides a formal operating manual for governance of HITL decision workflows in AI coding agents. It covers both single-agent and multi-agent orchestration and defines how planners, approvers, reviewers, and auditors collaborate with clear handoff and memory rules.

Direct answer: This template prescribes a repeatable HITL HIT workflow with explicit roles, authorities, and escalation paths to ensure safe, auditable decisions.

When to Use This AGENTS.md Template

• When critical AI actions require explicit human sign-off.
• When you need auditable decisions with traceable rationale.
• When memory and a single source of truth must be maintained across agents.
• When multi-agent orchestration is required with well-defined handoffs.
• When enforcing tool governance and secret management is essential.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Human-in-the-Loop Approval (HITL) Orchestrator for AI coding agents

Agent Roster and Responsibilities:
- Orchestrator: coordinates all interactions, enforces memory, context, and gating; triggers escalations.
- Requestor Agent: gathers inputs, validates requirements, surfaces missing information.
- Context Collector / Memory Keeper: maintains a single source of truth for task context and stores artifacts, decisions, and rationales.
- Approver Agent: domain expert who issues or routes approvals.
- Reviewer / QA Agent: performs quality checks and ensures policy compliance.
- Auditor: ensures traceability and auditability across the workflow.
- Logger: writes audit logs to persistent storage.

Supervisor or Orchestrator Behavior:
- Enforce explicit human approvals for high-risk decisions.
- Manage tool access, secrets, and data handling policies.
- Maintain memory isolation between concurrent tasks.
- Escalate when inputs are incomplete or when variance in decisions is detected.

Handoff Rules Between Agents:
- If input is incomplete, handoff from Requestor to Context Collector to enrich context.
- When approval is required, handoff to Approver Agent; after approval, handoff to Reviewer for QA checks; after QA, handoff to Orchestrator for final decision.
- Final decision and memory update occur in the Orchestrator, which then communicates outcomes to downstream systems.

Context, Memory, and Source-of-Truth Rules:
- Use a single, versioned memory store; context is timestamped and tied to a task ID.
- All artifacts and rationales are stored with the task context; do not duplicate context across agents.
- Source-of-truth is the memory store; agents should fetch context from there.

Tool Access and Permission Rules:
- Tools: data fetchers, code execution sandboxes, search, and policy-check services.
- Access granted via a secrets vault; secrets must not be written to logs.
- Approvals and surface results must be auditable in the memory store.

Architecture Rules:
- Stateless agents with a central orchestrator; memory store persists context.
- Clear interfaces between agents; avoid tight coupling.
- All decisions and outputs should be formatted to persist in the memory store.

File Structure Rules:
- Use a conventional structure: tasks/, memory/, logs/, tools/, policies/, tests/, docs/

Data, API, or Integration Rules:
- Read-only data unless necessary; all API usage must be logged; tokens rotated.
- Respect rate limits; surface errors clearly.

Validation Rules:
- Every decision must include a rationale and a record of checks performed.
- Validate input completeness before handoffs.

Security Rules:
- PII must not be logged; secrets never appear in outputs; access restricted by roles.
- Audit trails preserved for all critical actions.

Testing Rules:
- Unit tests for decision logic branches; integration tests for handoffs between HITL roles.
- End-to-end tests on deployment pipelines with feature flags.

Deployment Rules:
- Canaries and feature flags for changes to HITL flows; monitor approvals after deployment.

Human Review and Escalation Rules:
- Escalate to human reviewers for ambiguous or high-risk cases; document escalation rationale.

Failure Handling and Rollback Rules:
- If a step fails, revert to the last known good memory state; preserve logs; re-run from the last green state.

Things Agents Must Not Do:
- Do not bypass human approvals, expose secrets, or alter history without an auditable trail.

Recommended Agent Operating Model

The HITL approval model defines distinct roles and decision boundaries:

• Orchestrator: coordinates all steps, enforces memory, and ensures policy compliance; makes final gating decisions where allowed by policy.
• Requestor Agent: gathers input, validates requirements, and surfaces missing information to the Orchestrator.
• Approver Agent: domain expert responsible for sign-off at decision points with risk beyond defined thresholds.
• Reviewer: performs QA checks and ensures policy and compliance alignment.
• Auditor: ensures traceability and reproducibility of decisions.
• Memory Keeper: maintains a versioned, single source of truth for context and artifacts.

Escalation paths: if approval cannot be granted within policy, escalate to a human supervisor or governance board; capture rationale and route to remediation.

Recommended Project Structure

project/
├── agents/
│   ├── orchestrator/
│   │   └── main.py
│   ├── requester/
│   │   └── collect.py
│   ├── context/
│   │   └── memory.py
│   ├── approver/
│   │   └── approve.py
│   ├── reviewer/
│   │   └── review.py
│   └── auditor/
│       └── audit.py
├── data/
│   └── sources/
├── logs/
├── tests/
├── docs/
├── templates/
└── README.md

Core Operating Principles

• Clear, auditable decisions with explicit rationales.
• Single source of truth and versioned context per task.
• Strict human-in-the-loop gating for high-risk actions.
• Memory isolation between concurrent tasks; no cross-task leakage.
• Deterministic handoffs and predictable behavior.
• Security-first: secrets managed centrally; no sensitive data in logs.

Agent Handoff and Collaboration Rules

• Planner -> Implementer: plan how to fulfill the task and surface required data to HITL.
• Implementer -> Reviewer: hand off completed checks and proofs; include rationale and evidence.
• Reviewer -> Planner: return feedback or escalate.
• Domain Specialist -> Approver: provide specialized justification for policy-based decisions.

Tool Governance and Permission Rules

• Only approved tools may be invoked; log all tool use in the memory store.
• Secrets are never written to outputs or logs; use a vault for secrets management.
• APIs must require explicit user or supervisor consent for sensitive actions.

Code Construction Rules

• Follow modular design; avoid side effects in read operations; ensure idempotence.
• Inputs validated; outputs include evidence artifacts.

Security and Production Rules

• Restrict access by role; maintain audit trails; rotate credentials.
• Enforce least privilege for all agents; monitor suspicious patterns.

Testing Checklist

• Unit tests for decision branches.
• Integration tests for handoffs between HITL roles.
• End-to-end tests on deployment pipelines with feature flags.

Common Mistakes to Avoid

• Skipping human review for high-risk tasks.
• Forgetting to log rationales or decisions.
• Allowing data leakage across tasks; not isolating memory.

FAQ

What is the HITL approval AGENTS.md template?

The template defines roles, handoffs, and governance for human-in-the-loop approval workflows in AI coding agent projects.

How is memory managed across agents?

Context is stored in a versioned memory store tied to a task ID; all agents read from and write to the same source-of-truth.

What constitutes a successful handoff?

A handoff is successful when the next agent has all required inputs, rationales, and artifacts to proceed without asking for more data.

How do I escalate when approval is blocked?

Escalate to a human supervisor or governance board; document rationale and trigger remediation steps.

Are there things agents must not do?

Never bypass human approvals, leak secrets, or modify history without an auditable trail.