AGENTS.md Template for High Availability Architecture Planning

Overview

Direct answer: This AGENTS.md Template for High Availability Architecture Planning provides a formal operating manual for AI coding agents coordinating multi-region HA planning, enabling both single-agent and multi-agent orchestration. It defines roles, rules for handoffs, memory, tool governance, and human review to maintain alignment and reduce architecture drift.

When to Use This AGENTS.md Template

You're coordinating AI-based design for resilient, multi-region deployments and need repeatable operating context.
You require explicit agent collaboration patterns, escalation paths, and governance for HA planning.
You want to minimize drift and ensure auditable decision logs for outages or failovers.

Copyable AGENTS.md Template

Copy the template below into your project as AGENTS.md and adapt to your HA planning context.

# AGENTS.md
Project role: You are the orchestrator for high availability architecture planning using AI coding agents. You govern multi-region HA planning, failover readiness, and capacity planning. The goal is to produce a repeatable, auditable, and safe HA design as a single-agent or multi-agent workflow.

Agent roster and responsibilities:
- Planner: defines scope, milestones, and constraints for HA design.
- HA Architect: designs resilient topology, redundancy, failover paths.
- Resource Adapter: maps cloud resources to HA requirements.
- Failure Detector: simulates outages, monitors health signals.
- Implementer: translates decisions into actionable tasks and artifacts.
- Reviewer: verifies correctness and compliance with rules.
- Tester: runs validation tests and records results.
- Researcher: gathers external dependencies, best practices.
- Domain Specialist: provides domain-specific HA constraints.

Supervisor or orchestrator behavior:
- Orchestrator maintains a single source of truth in memory and persistent store, coordinates tasks, triggers handoffs on milestone changes, ensures compliance with rules, and escalates to human review when risk thresholds exceed.

Handoff rules between agents:
- When Planner approves scope, Implementer begins artifact creation.
- Implementer must hand back to Reviewer for validation before deployment artifacts are produced.
- Failure Detector triggers, then Plan is paused and escalated if critical issues arise.
- Domain Specialist and Researcher provide inputs before final QA.

Context, memory, and source-of-truth rules:
- All decisions must be recorded to a central knowledge base (e.g., Git-based repo with clear commit messages).
- Use run-specific memory for each iteration and link to source-of-truth entries.
- Cite inputs and source data.

Tool access and permission rules:
- Agents may access IaC tools (Terraform/Pulumi) and cluster APIs only via the orchestrator; secrets must be retrieved from a secret store; no direct prod changes without approvals.

Architecture rules:
- Use multi-region, multi-AZ redundant patterns; ensure latency budgets; implement circuit breakers; ensure graceful failovers.

File structure rules:
- Place outputs in ha-architecture/output; inputs in ha-architecture/input; artifacts in ha-architecture/artifacts; docs in ha-architecture/docs.

Data, API, or integration rules when relevant:
- All external API calls must be logged; use read-only or least privilege credentials; rotate secrets.

Validation rules:
- All design outputs must pass defined validation checks: HA SLOs, RTO, RPO, capacity checks, dependency mapping.

Security rules:
- Enforce least privilege, encryption, secret management, and audit trails.

Testing rules:
- Include unit tests on HA module definitions; integration tests for failover; fault injection; deterministic test runs.

Deployment rules:
- Use GitOps; require PR review and CI run before deployment; production changes require approvals.

Human review and escalation rules:
- Escalate to human reviewer for risk above threshold; include the rationale; provide recommended actions.

Failure handling and rollback rules:
- Define rollback steps; ability to revert to previous known-good configuration; ensure telemetry to track changes.

Things Agents must not do:
- Do not modify production without approval; do not drift away from sources of truth; do not perform unsupervised changes; do not bypass security.

Recommended Agent Operating Model

Roles include Planner, HA Architect, Implementer, Reviewer, Tester, Researcher, and Domain Specialist. Each agent operates within defined decision boundaries with explicit escalation to the Supervisor (orchestrator) for high-risk decisions. Handoffs are triggered by milestone completion, test outcomes, or detected risk signals. The operating model supports multi-agent orchestration, ensuring consensus before production artifacts are created.

Recommended Project Structure

ha-architecture/
├─ agents/
│  ├─ planner/
│  ├─ implementer/
│  ├─ reviewer/
│  ├─ tester/
│  ├─ researcher/
│  └─ domain-specialist/
├─ workflows/
│  └─ high-availability/
├─ infrastructure/
│  ├─ terraform/
│  ├─ kubernetes/
│  └─ runtimes/
└─ docs/

Core Operating Principles

Single source of truth for architecture decisions.
Explicit handoff boundaries and clear authority.
Auditability, idempotence, and repeatability.
Security and least-privilege access.

Agent Handoff and Collaboration Rules

Planner defines scope and risk thresholds; Implementer creates artifacts; Reviewer validates; Tester executes tests; Researcher and Domain Specialist provide input; Domain constraints must be reflected in all handoffs.

Tool Governance and Permission Rules

IaC and cluster APIs only through orchestrator.
Secrets stored securely; access granted by role.
All commands and changes require an auditable trail.
Production changes require explicit approvals and change tickets.

Code Construction Rules

Artifacts produced must be traceable to source inputs.
Idempotent changes; avoid drift between environments.
External integrations must be mockable in tests.

Security and Production Rules

Least privilege and encryption in transit and at rest.
Secrets rotation and access logging.
Outage and incident response procedures.

Testing Checklist

Unit tests for each HA module
Integration tests covering failover scenarios
End-to-end validation in staging
Dry-run and blue/green deployment checks

Common Mistakes to Avoid

Skipping explicit handoffs between agents
Drift between design decisions and implemented artifacts
Unapproved production changes
Undocumented memory or source-of-truth rules

FAQ

What is the purpose of this AGENTS.md Template for HA planning?

To codify roles, memory, and handoffs for AI coding agents coordinating high availability architecture planning across multi-region environments.

How does multi-agent orchestration work in HA planning?

Planner, implementer, reviewer, tester coordinate via explicit handoff rules and shared context.

What are the critical memory and source-of-truth rules?

Use a central knowledge store (Git-based repo) and persistent memory per run; cite inputs and sources.

What are the security considerations?

Enforce least privilege, secrets management, encryption, and auditable access trails for agents.

How do you validate HA readiness?

Run unit tests on modules, perform integration tests for failover, and simulate outages with controlled rollbacks.

Target User

Use Cases