Blue-Green Deployment AGENTS.md Template

Overview

Direct answer: This AGENTS.md template defines roles, guardrails, and handoff rules to coordinate AI coding agents during a blue-green deployment, enabling both single-agent and multi-agent orchestration with a clear memory and source-of-truth.

The AGENTS.md Template for blue-green deployment design governs the workflow of traffic switchover between blue and green environments, health checks, canaries, and rollback procedures. It prescribes agent roles, decision boundaries, escalation paths, and audit trails to ensure safe production changes with human review where necessary.

When to Use This AGENTS.md Template

• Launching or updating a production service with a blue-green strategy where risk must be minimized.
• Coordinating multiple AI coding agents across planning, implementation, testing, and review stages.
• Ensuring strict handoff protocols and a single source of truth for deployment state and metrics.
• Documenting tool governance, permission rules, and roll-back criteria in a reproducible format.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- You are an AI coding agent orchestrating a blue-green deployment design using a planner, orchestrator, implementer, tester, reviewer, researcher, and domain specialist to safely switch traffic between blue and green environments.

Agent roster and responsibilities
- Planner: designs rollout plan, constraints, canary strategy, and gate conditions; outputs a plan artifact.
- Orchestrator: coordinates tasks, maintains memory of environment state, tracks current color, and triggers transitions.
- Implementer: applies deployment updates to the target color; interacts with CI/CD and manifests.
- Tester: runs health checks, synthetic transactions, canary tests; reports metrics.
- Reviewer: validates plan and results against acceptance criteria; approves or requests changes.
- Researcher: gathers external dependencies, docs, known issues, and compliance considerations.
- Domain Specialist: validates network, security, database migrations in the blue-green context.

Supervisor or orchestrator behavior
- The orchestrator enforces plan execution with strict sequencing, records decisions to a central memory store, enforces canary and health gate checks, and raises escalation if a step fails.

Handoff rules between agents
- Planner hands off rollout tasks to Implementer with the plan artifact and runbook.
- Implementer informs Orchestrator of progress; if blockers, handoff to Reviewer or Domain Specialist.
- Researcher and Domain Specialist consulted for blockers; results appended to memory and source of truth.

Context, memory, and source-of-truth rules
- Central memory store holds environment state, plan versions, metrics, manifests, and run logs; all agents read from and write to canonical sources.
- Memory is append-only; source of truth includes deployment manifests, CI/CD logs, and telemetry data.

Tool access and permission rules
- Implementer can modify deployment manifests; Orchestrator can trigger pipelines; Planner can propose changes but not execute; Secrets are accessed via a Secrets Manager with scoped tokens.

Architecture rules
- Use blue-green separation; idempotent steps; deterministic planning; reversible changes.

File structure rules
- Place blue_green_deploy artifacts under blue_green_deploy/, with manifests in manifests/, config in config/, and canary/pipeline definitions in pipelines/.

Data, API, or integration rules when relevant
- Interactions go through a central message bus; API calls are versioned; use stable contracts.

Validation rules
- Preconditions: plan exists; canary window specified; all required artifacts exist.
- Postconditions: correct traffic routing, health checks pass, memory updated.

Security rules
- Secrets never hard-coded; access controlled; encryption at rest; audit trails.

Testing rules
- Unit tests for agents; integration tests for orchestrator flow; end-to-end tests in staging.

Deployment rules
- Deploy to blue or green as per plan; perform canary, then traffic shift; rollback if health fails.

Human review and escalation rules
- If health shows degradation beyond threshold or policy breach, escalate to human reviewer.

Failure handling and rollback rules
- Switch traffic back to previous color; ensure memory and manifests are consistent; notify stakeholders.

Things Agents must not do
- Do not bypass approvals; do not mutate production data; do not mutate shared memory without appending a new event; do not perform irreversible actions without guardrails.

Recommended Agent Operating Model

The operator roles in this blue-green deployment design collaborate as a disciplined team. Planner defines the rollout strategy and exit criteria; Orchestrator enforces sequence and records decisions; Implementer converts the plan into production changes; Tester validates health and canary signals; Reviewer provides a human-in-the-loop checkpoint; Researcher and Domain Specialist supply context and domain validation; Escalation paths route issues to humans when automation cannot resolve them within policy constraints.

Recommended Project Structure

project-root/
  blue_green_deploy/
    config/
      rollout.yaml
    manifests/
      deployment.yaml
    pipelines/
      blue_green_plan.yaml
  agents/
    planner/
    orchestrator/
    implementer/
    tester/
    reviewer/
    researcher/
    domain_expert/
  tests/
    end_to_end/
      test_blue_green.py
  docs/

Core Operating Principles

• Single source of truth for deployment state and artifacts
• Clear separation of planning, execution, testing, and review
• Idempotent and auditable steps across all agents
• Deterministic decision making with guardrails
• Observability through shared metrics, logs, and run artifacts
• Human-in-the-loop for high-risk changes
• Explicit escalation when automation cannot resolve issues
• Strict tool governance and access controls

Agent Handoff and Collaboration Rules

• Planner to Implementer: deliver plan artifact, runbook, and canary criteria
• Implementer to Orchestrator: report progress, success, or blockers
• Orchestrator to Reviewer: request validation when gates fail or risk exceeds threshold
• Researcher/Domain Specialist consulted for blockers; results appended to memory
• All handoffs include context, links to source artifacts, and versioned identifiers

Tool Governance and Permission Rules

• CI/CD pipeline triggers are controlled by Orchestrator with audit trails
• Deployment manifest edits are restricted to Implementer with Planner approvals
• Secrets access is mediated by a central Secrets Manager with scoped tokens
• Production traffic switchover requires explicit canary health and human approval
• All external API calls must conform to versioned contracts

Code Construction Rules

• Code must be idempotent and reproducible
• Avoid hard-coded secrets; use environment-driven configuration
• All changes are logged to the central memory with a timestamp
• Follow a strict commit and review process for production changes
• Include validation hooks before promoting changes to production

Security and Production Rules

• RBAC: role-based access control for all agents
• Secrets stored in a dedicated secret store with encryption at rest
• Audit trails for all deployment actions and escalations
• Network segmentation between blue and green environments
• Automatic rollback on critical health signal

Testing Checklist

• Unit tests for each agent
• Integration tests for orchestrator flow
• Canary tests and health checks in staging
• End-to-end tests covering color switch and rollback
• Manual review for high-risk changes

Common Mistakes to Avoid

• Bypassing approvals or gate checks
• Mutating production state outside source of truth
• Untracked changes or ambiguous artifacts
• Insufficient canary coverage or metric thresholds
• Overlapping artifact versions across environments

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts.

FAQ

What is the purpose of this AGENTS.md Template for blue-green deployment?

This template documents roles, rules, and handoffs to coordinate AI coding agents through blue-green deployment cycles, including traffic switchover and rollback criteria.

How does agent handoff work in this workflow?

Planner creates the rollout plan, Implementer executes changes, Orchestrator coordinates and records state, Reviewer approves or requests changes, with Researcher and Domain Specialist consulted as needed.

How are secrets and tool access governed?

Secrets are managed by a centralized secret store with scoped tokens; agents modify manifests and trigger pipelines only within defined permissions.

What happens if health checks fail during switchover?

Traffic is rolled back to the previous color; the Orchestrator logs the failure and escalates if policy requires human review.

What are the validation criteria before deployment?

Canary health checks pass, metrics meet thresholds, and all required artifacts exist; high-risk changes may require manual validation.