AGENTS.md Template for AGENTS.md template for Enterprise Architecture Decision Records

Overview

This AGENTS.md template defines an operating manual for Enterprise Architecture Decision Records (EA-EDR) workflows in AI coding agent environments. It governs single-agent execution as well as multi-agent orchestration, ensuring a single source of truth, clearly delineated roles, and governance across agent handoffs. The template explicitly describes how AI coding agents collaborate to produce, review, and publish EA decisions, while maintaining traceability, security, and reproducibility.

Direct answer: Use this AGENTS.md template to codify the EA-EDR workflow for both individual agents and multi-agent orchestration, including who decides, who implements, and how to verify each decision before production usage.

When to Use This AGENTS.md Template

• When establishing a repeatable EA decision process that integrates AI coding agents and domain specialists.
• When you need formal handoffs between planner, implementer, researcher, reviewer, tester, and domain specialist roles.
• When tool governance, security rules, and production deployment gates must be codified in a copyable template.
• When you want to share a consistent operating context across teams creating EA Decision Records.

Copyable AGENTS.md Template

# AGENTS.md

Project: Enterprise Architecture Decision Records (EA-EDR) Governance

# Agent roles
- Planner (EA Strategist): defines problem statement, scope, and success criteria for the EA decision.
- Implementer (EA Architect): builds the decision record, captures rationale, and maps to an EA reference model.
- Researcher (Reference Librarian): gathers evidence, standards, patterns, and external references.
- Reviewer (Governance Reviewer): validates alignment with standards, risk posture, and governance policies.
- Tester (QA Auditor): verifies completeness, traceability, and testable acceptance criteria.
- Domain Specialist: provides security, data, or platform-specific considerations (e.g., security baseline, data sensitivity, integration constraints).

# Supervisor / Orchestrator behavior
- The Orchestrator coordinates task assignment, enforces handoffs, and tracks status via a central decision log.
- It ensures outputs are stored in the EA-EDR repository, and that each agent signs off before moving to the next stage.
- It triggers human review when risk or policy breaches are detected.

# Handoff rules
- Planner → Implementer: deliver problem statement, scope, acceptance criteria, and initial decision draft.
- Implementer → Researcher: fetch supporting evidence, references, and architectural patterns.
- Researcher → Planner: return synthesized evidence and updated decision draft.
- Planner → Reviewer: present the complete EA-EDR for governance validation.
- Reviewer → Implementer: approve changes and prepare for testing.
- Implementer → Tester: provide testable acceptance criteria and verifiable outcomes.
- Tester → Domain Specialist: confirm domain-aligned checks are satisfied.
- Domain Specialist → Planner: finalize decision with domain-specific notes.

# Context, memory, and source-of-truth
- Context is the current EA-EDR record, referenced sources, and decision rationale stored in /docs/edr/
- Memory is limited to the active decision session; long-term history is in the repository and the knowledge base.
- Source of truth is the EA-EDR markdown file and linked artifacts in /docs/edr/; all references must be cited in the document.

# Tool access and permission rules
- Agents may read all EA documentation but may only edit the current EA-EDR file and related artifacts in their authorized folder.
- Secrets must never be stored in AGENTS.md content or artifacts; use secret stores for credentials.
- API calls and tooling must go through approved endpoints with audited tokens.

# Architecture rules
- Align decisions with the enterprise reference architecture, using standard patterns and models.
- Capture decisions with problem, alternatives, rationale, risks, trade-offs, and decision outcome.
- Link architecture decisions to business goals and capabilities.

# File structure rules
- All EA decisions are stored under /docs/edr//decision.md with related artifacts in the same folder.
- Use a single source of truth file named decision.md for each EA decision.

# Data, API, or integration rules
- Record data sources, interfaces, and integration constraints clearly in the decision.
- Do not embed secrets or credentials; reference secure stores where necessary.

# Validation rules
- Ensure all sections exist: Problem, Context, Alternatives, Rationale, Risks, Decision, Trade-offs, Status, Evidence.
- All claims have citations and references.

# Security rules
- Do not publish sensitive data in the EA-EDR; redact sensitive fields.
- Ensure access controls are respected for production-linked artifacts.

# Testing rules
- Define acceptance criteria that are testable (e.g., performance impact, compatibility, compliance).
- Include a lightweight verification checklist in the EA-EDR.

# Deployment rules
- Changes to EA-EDRs go through a PR-based workflow with mandatory reviews before merging.
- Tag the decision with status (Proposed, Approved, Deprecated).

# Human review and escalation rules
- Escalate to Architecture Review Board for high-risk decisions or policy breaches.
- Document escalation path and expected response times in the decision log.

# Failure handling and rollback rules
- If a decision is invalidated, revert the PR, and archive the previous version with an incident note.
- Maintain an audit trail of changes and rationale for all rollbacks.

# Things Agents must not do
- Do not modify production configurations from the EA-EDR workflow.
- Do not conceal risks or omit critical evidence.
- Do not bypass governance gates or skip reviews.
- Do not store secrets in AGENTS.md or decision artifacts.

Recommended Agent Operating Model

The EA-EDR operating model defines clear decision boundaries and escalation paths. The Planner decides scope and success criteria, the Implementer creates the draft decision and artifacts, the Researcher pulls evidence, the Reviewer validates governance compliance, the Tester confirms evidence and acceptance criteria, and Domain Specialists provide specialized input when needed. The Orchestrator handles handoffs, enforces policy, and escalates when risk is detected. Escalation paths point to the Architecture Review Board for high-risk ED decisions. This model supports both single-agent execution and multi-agent orchestration across the EA program.

Recommended Project Structure

apps/edr-manager/docs/edr//
  decision.md
  evidence.md
  acceptance-criteria.md
  risk-assessment.md
  links.md

apps/edr-manager/ai-skills/agents-md-templates/planner/
apps/edr-manager/ai-skills/agents-md-templates/implementer/
apps/edr-manager/ai-skills/agents-md-templates/researcher/
apps/edr-manager/ai-skills/agents-md-templates/reviewer/
apps/edr-manager/ai-skills/agents-md-templates/tester/
apps/edr-manager/ai-skills/agents-md-templates/domain-specialist/

apps/edr-manager/orchestrator/

Core Operating Principles

• Single source of truth for each EA decision record.
• Explicit, auditable handoffs between agents.
• Secure handling of data, secrets, and integrations.
• Governance gates with required reviews before production deployment.
• Traceability from problem statement to decision outcome.

Agent Handoff and Collaboration Rules

Planner hands off to Implementer with a complete scope and acceptance criteria. Implementer collaborates with Researcher for evidence, then hands back for planner validation. Reviewer enforces governance constraints. Tester verifies acceptance criteria. Domain Specialist provides domain inputs where needed. Handoffs occur only via the orchestrator, which maintains the canonical log and ensures no drift between the ED decision and artifacts.

Tool Governance and Permission Rules

• All tool calls require an auditable token; secrets never stored in code or AGENTS.md content.
• Edits to decision.md must go through version control with PRs and reviews.
• Artifacts and evidence must link to sources and be traceable to the decision.
• Production-related edits require Architecture Review Board approval.

Code Construction Rules

Follow consistent documentation patterns for EA decisions: problem, context, alternatives, rationale, risks, decision, and traceability. Use small, testable acceptance criteria and ensure evidence is verifiable. Do not embed hard-coded secrets or credentials in artifacts. Maintain a stable, readable, and versioned history of all decisions.

Security and Production Rules

Protect sensitive data, restrict access to authorized agents, and enforce least-privilege for repository actions. Do not deploy decisions that introduce policy violations or security risks without proper approvals. Maintain an incident log for any production-impacting changes.

Testing Checklist

• Confirm problem, scope, alternatives, and rationale are present.
• Verify evidence citations and references exist and are accessible.
• Check that acceptance criteria are specific, measurable, and testable.
• Validate traceability from decision to architecture patterns and business goals.
• Ensure PRs include reviews from Planner, Implementer, Reviewer, and Domain Specialist if applicable.

Common Mistakes to Avoid

• Omitting rationale or failing to document risk and trade-offs.
• Skipping required governance reviews or rushing handoffs.
• Storing secrets or credentials in artifacts or AGENTS.md content.
• Misaligning the EA decision with the enterprise reference architecture.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is an EA-EDR AGENTS.md Template?

It is a copyable operating manual that codifies how AI coding agents and human experts collaborate to create, validate, and govern Enterprise Architecture Decisions Records (EDR) within a multi-agent workflow.

How does multi-agent orchestration work in this template?

Planner, Implementer, Researcher, Reviewer, Tester, and Domain Specialist coordinate through the Orchestrator, with clearly defined handoffs, shared context, and a central decision log that preserves traceability.

What should be included in the Handoff rules?

Handoffs define what artifacts move, the acceptance criteria, the required approvals, and the expected turnaround times. They prevent drift and ensure governance gates are respected.

How is security enforced in EA-EDR workflows?

Secrets never appear in artifacts; access is controlled via least privilege; production-related changes require governance approval and audit trails.

How do I validate an EA decision before production?

Validate problem statement, evidence, risk analysis, and acceptance criteria; ensure all required reviews are complete; confirm alignment with the enterprise reference architecture.