AGENTS.md Template: Cloud Migration Agent Teams

Overview

This AGENTS.md Template for Cloud Migration Agent Teams provides a concrete, executable operating manual that governs the workflow for migrating workloads to the cloud using AI coding agents. It covers both single-agent execution and multi-agent orchestration, including clear handoffs, memory rules, and source-of-truth governance.

When to Use This AGENTS.md Template

• You are planning a cloud migration with multiple teams or automated agents.
• You need explicit handoff rules between planning, implementation, validation, and review.
• You require tool governance, secrets management, and security constraints baked into the workflow.
• You want a project-level operating context that any agent can reference for consistent decisions.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Cloud Migration Program Manager
Agent roster and responsibilities:
- Planner: defines migration scope, risk matrix, timeline, resource plan.
- Implementer: writes migration scripts, executes steps, handles rollback.
- Reviewer: validates artifacts, security checks, compliance.
- Tester: runs migration tests, validates data integrity, monitors metrics.
- Researcher: investigates environment, dependencies, vendors, and constraints.
- Domain Specialist: cloud provider expert focusing on AWS/GCP/Azure features and limits.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates all agents, enforces memory of context, and triggers handoffs when criteria are met.
- Enforces tool governance and approves escalations for human review when needed.

Handoff rules between agents:
- Planner → Implementer: share migration plan, environment map, risk-based acceptance criteria.
- Implementer → Tester: share code, deployment changes, test results, and rollback steps.
- Researcher/Domain Specialist → Implementer: supply provider-specific steps, configs, and constraints.
- Reviewer → Implementer or Tester: approve artifacts or request changes before promotion.

Context, memory, and source-of-truth rules:
- Use a central MigrationContext document stored in the repo (docs/migration_context.md).
- All agents read from and write to the MigrationContext; source-of-truth is the MigrationPlan, EnvironmentMap, and ValidationResults.

Tool access and permission rules:
- Only approved tools (cloud CLI, code runner, and CI task runners).
- Secrets stored in a vault/KMS with role-based access control; avoid hard-coding credentials.
- Edit permissions restricted to authorized agents; production changes require a supervisor sign-off.

Architecture rules:
- Use provider-agnostic abstractions where possible; capture provider-specific steps as configuration.
- Prefer IaC (infrastructure as code) with versioned templates.

File structure rules:
- /cloud-migration/
  - /ai-skills/agents-md-templates/
    - planner/
    - implementer/
    - tester/
    - researcher/
    - domain-specialist/
  - /configs/
  - /scripts/
  - /validations/
  - /docs/

Data, API, or integration rules when relevant:
- Interact with cloud APIs using the provider SDKs; respect rate limits and retries.
- Centralize environment data in the MigrationContext; avoid duplication across agents.

Validation rules:
- All migrations must pass unit, integration, and end-to-end tests before promotion.
- Data integrity checks and schema validation are mandatory.

Security rules:
- Enforce least privilege for all agents; rotate credentials and audit access.
- Encrypt data in transit and at rest; segregate duties for sensitive steps.

Testing rules:
- Unit tests for scripts, integration tests for API calls, end-to-end tests in staging.
- Tests must be deterministic and have defined rollback procedures.

Deployment rules:
- Use canaries or blue/green deployment where applicable; require approval gates for production migrations.

Human review and escalation rules:
- Any anomaly or failure above a threshold triggers human review by SRE and product engineering.

Failure handling and rollback rules:
- Have a rollback plan to revert to the last known-good environment.
- Preserve logs and artifacts for audit.

Things Agents must not do:
- Do not deploy to production without explicit approval.
- Do not bypass validation or skip tests.
- Do not modify shared artifacts without updating the MigrationContext.

Recommended Agent Operating Model

Roles and decision boundaries: Planner defines the migration strategy and acceptance criteria; Implementer executes with guidelines from the planner; Reviewer ensures compliance; Tester validates outcomes; Researcher and Domain Specialist provide environment-specific inputs; Escalation to the Orchestrator occurs for uncertainties or policy violations. Handoffs are explicit, and decisions require sign-off from the supervisor when thresholds are crossed.

Recommended Project Structure

/cloud-migration
  /agents
    /planner
    /implementer
    /tester
    /researcher
    /domain-specialist
  /configs
  /scripts
  /validations
  /docs

Core Operating Principles

• Single source of truth: all decisions anchor to the MigrationContext.
• Explicit handoffs: no implicit state transfers between agents.
• Least privilege: agents operate with minimal necessary permissions.
• Auditable changes: every action is logged and versioned.
• Bias-free automation: algorithms do not override human review when policy requires it.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide migration plan, environment map, risk criteria, data schema, and rollback plan.
• Implementer to Tester: provide deployment changes, test results, and validation criteria.
• Researcher/Domain Specialist to Implementer: deliver provider-specific configuration and constraints.
• Reviewer to Implementer or Tester: approve or request changes before promotion to production-ready state.

Tool Governance and Permission Rules

• Commands must pass policy checks before execution.
• Edits to critical configs require two-person consent or supervisor sign-off.
• Secrets must never be exposed in logs or code; use secure storage and access controls.
• Production access is gated; deploys require approval gates and post-deploy monitoring.

Code Construction Rules

• Follow provider-agnostic patterns; vendor-specific steps are configuration-driven.
• Avoid hard-coded values; pull configuration from MigrationContext and configs.
• Scripts must be idempotent and include explicit rollback steps.
• All changes require unit and integration tests with deterministic outcomes.

Security and Production Rules

• Enforce encryption at rest and in transit for all sensitive data.
• Apply least privilege IAM roles and rotate secrets regularly.
• Audit logs retained for compliance; monitor anomalies with alerting.

Testing Checklist

• Unit tests for scripts and functions.
• Integration tests for API calls and data flows.
• End-to-end tests in staging with migration simulations.
• Rollback tests to verify restoration paths.

Common Mistakes to Avoid

• Skipping validation or shortcuts that bypass tests.
• Over-privileged tool access or secret leakage.
• Unclear handoffs or missing source-of-truth artifacts.
• Architectural drift between plan and implementation.

FAQ

How does AGENTS.md Template support cloud migration with multi-agent orchestration?

It defines roles, handoffs, and governance to coordinate planning, execution, validation, and review across agents, ensuring traceability and controlled risk.

Who makes up the agent roster for cloud migration?

The roster typically includes Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist, with a supervising Orchestrator coordinating them.

How are handoffs between planners, implementers, and testers managed?

Handoffs are explicit and documented in the MigrationContext. Each handoff includes context, criteria, and artifacts required to continue with the next phase.

What are the security and governance rules for tool access and secrets?

Secrets must be stored securely, access is role-based, and all tool actions are auditable. Production changes require approval gates and monitoring.

How are validation, rollback, and risk mitigation handled?

Validation uses defined success criteria; if criteria fail, rollback plans are executed, logs preserved, and human review triggered if thresholds are exceeded.