AGENTS.md Template for Agentic System Design Reviews | Suhas Bhairav

Overview

The AGENTS.md template for agentic system design reviews defines the operating manual for a team of AI coding agents participating in a design review. It governs both single-agent and multi-agent orchestration, specifying roles, handoffs, governance, and escalation rules to ensure traceability, accountability, and consistent decision-making across design artifacts.

Direct answer: This AGENTS.md template establishes a formal, repeatable workflow for planning, executing, reviewing, and approving agent-driven design reviews, while handling cross-agent coordination and human oversight.

When to Use This AGENTS.md Template

When reviewing complex architecture or API design that benefits from multiple AI agents with specialized expertise.
When you need explicit handoffs and decision boundaries to reduce context drift between agents.
When tool governance and secret/audit controls must be demonstrated in the design process.
When you want a project-level operating context that can be pasted into a new repo for consistency.

Copyable AGENTS.md Template

# AGENTS.md

Agentic System Design Review Template

Project: <PROJECT_NAME> design-review
Version: 1.0

Agent roster and responsibilities
- Planner: defines scope, constraints, and review plan; sequences agent tasks and handoffs.
- Implementer: translates planner output into actionable design artifacts, code scaffolds, and integration notes.
- Reviewer: verifies artifacts against requirements, constraints, and governance rules.
- Researcher: sources relevant docs, standards, APIs, and references to inform decisions.
- Domain Specialist: provides subject-matter expertise (e.g., security, data privacy, regulatory).
- Orchestrator: coordinates multi-agent collaboration, memory, and source-of-truth consistency.
- Security Auditor: validates security controls and risk considerations.

Supervisor or orchestrator behavior
- The Orchestrator maintains a shared memory and a single source of truth for the review (design doc, decisions log, design rationale).
- The Orchestrator approves handoffs, routes outputs to the next agent, and documents decisions.

Handoff rules between agents
- Planner → Implementer: when the design plan, requirements, and acceptance criteria are defined.
- Implementer → Reviewer: once artifacts, prototypes, and evidence are produced.
- Researcher/Domain Specialist → Planner: when new constraints or references modify scope.
- Orchestrator/QA: performs final validation and escalates to human review if ambiguity exists.

Context, memory, and source-of-truth rules
- All conclusions must cite sources (design docs, API specs, standards).
- Memory stores: design decisions log, artifacts, and test results with timestamps.
- Source-of-truth is the Design Docs repository and the Design Decisions Log.

Tool access and permission rules
- Agents may access read-only design docs and public specs; changes require orchestrated PRs or approvals.
- Secrets and credentials are never exposed through agent outputs; use vault-integrated references.
- API calls must use limited scopes, with audit trails.

Architecture rules
- Adhere to defined architectural constraints (e.g., microservices boundaries, layer separation).
- Prefer modular, auditable design blocks with clear interfaces.

File structure rules
- Store design-reviews in docs/design-reviews and evidence in logs/review-logs.
- Keep artifacts under version control with change history.

Data, API, or integration rules
- All external references must be versioned; do not rely on live endpoints without documented fallbacks.

Validation rules
- Acceptance criteria must be defined for each artifact; pass/fail criteria must be objective and testable.

Security rules
- No leakage of secrets; validate inputs; enforce least privilege for all tool calls.

Testing rules
- Include unit checks for design assertions, integration test scaffolds, and reproducible test data.

Deployment rules
- Do not auto-merge; require PR review and approval from the human reviewer when needed.

Human review and escalation rules
- Escalate any uncertainty to a human reviewer with rationale, evidence, and risk assessment.
- Document escalations in the decision log.

Failure handling and rollback rules
- If a design review path deviates from governance, revert to the last approved design and revalidate.
- Maintain an audit trail of rollbacks and rationale.

Things Agents must not do
- Do not modify production configuration directly.
- Do not bypass approval gates.
- Do not hide conflicting evidence or omit sources.
- Do not reveal secrets or credentials in outputs.

Recommended Agent Operating Model

Roles are clearly delineated with decision boundaries and escalation paths. The Planner defines scope; the Implementer creates artifacts; the Reviewer validates; the Researcher and Domain Specialist provide context; the Orchestrator coordinates and ensures a single source of truth; Human reviewers can overrule automated outputs when needed.

Recommended Project Structure

project-root/
  docs/
    design-reviews/
      <project-name>/
        design.md
        decisions.log
        evidence/
  agents/
    planner/
    implementer/
    reviewer/
    researcher/
    domain-specialist/
    orchestrator/
    security-auditor/
  tests/
  logs/

Core Operating Principles

Define explicit agent roles, responsibilities, and decision boundaries.
Maintain a single source of truth (design doc and decisions log).
Ensure auditable traces for all design decisions and outputs.
Enforce tool governance, secrets management, and escalation rules.
Minimize context drift through formal handoffs and versioned artifacts.

Agent Handoff and Collaboration Rules

Planner provides clear scope, constraints, and acceptance criteria to Implementer.
Implementer supplies artifacts with citations and evidence to Reviewer.
Researcher and Domain Specialist supply context to Planner for any scope changes.
Orchestrator coordinates cross-agent outputs and ensures synchronization with the design doc.
Human Review escalates when ambiguous outcomes or risk exceed defined thresholds.

Tool Governance and Permission Rules

All tool actions are logged and auditable; secrets never appear in outputs.
Git operations require orchestrator approval; no direct commits by agents to production branches.
APIs must use scoped tokens and follow least-privilege access.
Changes to design docs require versioning and review gates.

Code Construction Rules

All outputs include citations and references to source materials.
Design decisions must be traceable to requirements and constraints.
Artifacts are modular, testable, and reusable across projects.
Avoid duplicating information; link to the canonical source of truth.

Security and Production Rules

Secrets are stored in a secure vault and never embedded in code or outputs.
Production changes require explicit human approval and secure deployment gates.
Regular security reviews must be part of design reviews for critical systems.

Testing Checklist

Unit tests verify design assertions and constraints.
Integration tests validate interactions with external APIs and services.
End-to-end checks ensure the review workflow completes without handoff gaps.
Regression tests verify that changes do not reintroduce prior issues.

Common Mistakes to Avoid

Overlapping responsibilities among agents leading to duplication.
Skipping citations or omitting design sources.
Bypassing escalation gates for risky changes.
Failing to update the design decisions log after changes.

FAQ

What is the aim of this AGENTS.md template?

To provide a rigorous, copyable operating manual for agentic system design reviews, enabling clear handoffs, governance, and human oversight in multi-agent workflows.

Which roles are required for a design review?

Planner, Implementer, Reviewer, Researcher, Domain Specialist, Orchestrator, and optional Security Auditor and Human Reviewer depending on risk.

How are decisions traced and stored?

All decisions are linked to sources in the Design Docs repository and stored in the Decisions Log with timestamps and rationale.

How do I handle secrets and sensitive data?

Secrets are never output by agents; use a vault for references and ensure all tokens have restricted scopes with audit trails.

What happens if a design decision is uncertain?

The Orchestrator escalates to a human reviewer, and the decision is logged with supporting evidence before proceeding.

Agentic System Design Reviews — AGENTS.md template | AGENTS.md Template for Agentic Workflows

Target User

Use Cases