AGENTS.md Template: Database Migration Agents

Overview

The AGENTS.md template is a formal operating manual for database migration agents. It governs single-agent and multi-agent workflows, including planning, execution, validation, and handoff across migration steps. It codifies how AI coding agents collaborate to plan schema changes, move data, validate integrity, and rollback when needed. The template emphasizes multi-agent orchestration, tool governance, and human review as needed to maintain auditable, safe migrations.

Direct answer: This AGENTS.md template provides a complete operating context for database migration agents, enabling both single-agent and multi-agent coordination with explicit roles, handoffs, and governance rules.

When to Use This AGENTS.md Template

• Coordinating complex migrations across multiple databases, engines, or versions
• Ensuring data integrity with automated validation and cross-checks
• Orchestrating a multi-agent migration plan with clear handoffs and escalation paths
• Establishing auditable change control and rollback rules for production migrations
• Defining tool access, secrets handling, and production safeguards upfront

Copyable AGENTS.md Template

Paste this into your AGENTS.md file to initialize project-level operating context for database migration agents.

# AGENTS.md

# Project: Database Migration Orchestrator

# Agent roster and responsibilities
- Planner: designs migration strategy and sequencing; defines data movement paths; produces migration plan artifacts.
- Implementer: executes migration steps in target environments; applies schema changes; runs data copy jobs.
- Validator: runs data integrity checks; compares pre/post migration datasets; flags discrepancies.
- Verifier: confirms migration success against acceptance criteria; triggers handoff to production deploy.
- Reviewer: reviews changes for correctness, consistency, and adherence to governance.
- Domain Specialist: provides domain-specific validation (business rules, data semantics).

# Supervisor / Orchestrator behavior
- The Orchestrator maintains a single source of truth, memory of past steps, and a live status board.
- It triggers plan execution, enforces guardrails, and escalates when mismatches or blockers occur.
- All actions are auditable and logged with timestamps, agent IDs, and rationale.

# Handoff rules between agents
- Planner -> Implementer: when plan is fully specified with step-by-step actions and data sources.
- Implementer -> Validator: after executing each critical step or batch, the Validator runs integrity checks.
- Validator -> Verifier: upon passing checks, the Verifier validates overall success criteria.
- Verifier -> Reviewer: if validation flags issues, escalate to Reviewer for remediation.
- Domain Specialist inserts domain-specific checks at any stage and collaborates with Planner for remediation.

# Context, memory, and source-of-truth rules
- All inputs/outputs are versioned; source of truth is the migration plan in the central repository.
- Memory is stored in a structured event log with user/agent identifiers and rationale.
- Data lineage and transformation logic are tracked with metadata for each step.

# Tool access and permission rules
- Tools: DB clients, ETL scripts, schema diff tools, data validation utilities, rollback utilities.
- Access: least privilege; secrets managed by a central vault; credentials rotated on changes.
- Execution gates: each step requires approval from the Planner or a designated gatekeeper before proceeding.

# Architecture rules
- All migrations must have a rollback plan and tested rollback scenario.
- Changes are modular and idempotent where possible.
- Logging, monitoring, and alerting are wired to a central observability platform.

# File structure rules
- Keep all migration plans under /migrations/plans; artifacts under /migrations/artifacts; scripts under /migrations/scripts.
- All environment-specific configs live under /configs with environment tags.

# Data, API, or integration rules
- Data movement must be batched with defined batch sizes; progress tracked in the plan.
- API calls and integration points must be versioned and tested in staging before production.

# Validation rules
- Every migration batch must pass data integrity checks and row-level comparisons.
- Anomaly thresholds must be defined and fail the run if exceeded.

# Security rules
- Secrets only via vault; no plaintext keys in code; access audited.
- Production environments require dual-control approvals.

# Testing rules
- Unit tests for migration scripts; integration tests for end-to-end flow; smoke tests in staging.

# Deployment rules
- Deploy migration plan to a controlled production window; monitor for anomalies; trigger rollback on failure.

# Human review and escalation rules
- Any non-idempotent change or failure triggers human review; escalation path defined in Planner.

# Failure handling and rollback rules
- Rollback plan must be executed if validation fails or anomalies exceed thresholds; rollback steps are tested prior to release.

# Things Agents must not do
- Do not bypass approvals; do not run undetected changes in production; do not access secrets outside vault; do not improvise critical steps without orchestration.

Recommended Agent Operating Model

The agent roles form a controlled interaction pattern: Planner decides, Implementer executes, Validator verifies, Verifier confirms, Reviewer adjudicates, Domain Specialist ensures domain accuracy. Each agent operates within defined decision boundaries and escalation paths. Handoffs enforce single-source truth and auditable history, enabling safe multi-agent orchestration of database migrations.

Recommended Project Structure

database-migration/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── validator/
│   ├── verifier/
│   ├── reviewer/
│   └── domain-specialist/
├── configs/
├── migrations/
│   ├── plans/
│   └── artifacts/
├── checks/
├── orchestrator/
├── docs/
└── tests/

Core Operating Principles

• Operate with auditable, time-stamped decisions.
• Maintain a single source of truth for migration plans and results.
• Protect data integrity with automated validation and rollback capability.
• Enforce least-privilege access and secrets management.
• Use staged environments (staging before production) for all changes.

Agent Handoff and Collaboration Rules

• Planner to Implementer handoffs require a complete migration plan with defined data sources, schemas, and rollback steps.
• Implementer to Validator handoffs occur after each major batch completes and results are reported.
• Validator to Verifier handoffs require passing integrity and performance criteria.
• Domain Specialist can insert domain-specific checks at any state and coordinate remediation with Planner.
• All handoffs must be recorded in the central log with rationale.

Tool Governance and Permission Rules

• Commands and scripts run only through approved tooling with role-based access control.
• All secrets must be accessed through a vault; no plaintext storage in code.
• Production changes require dual approval and staged deployment windows.
• External services and data sources must be versioned and monitored for drift.

Code Construction Rules

• Write idempotent migration steps whenever possible.
• Document every transformation and data movement with metadata.
• Avoid hard-coded environment values; parameterize configs.
• Validate inputs and outputs at every stage; fail fast on anomalies.

Security and Production Rules

• Enforce dual-control approvals for production migrations.
• Maintain strict access controls and rotate credentials regularly.
• Audit logs must be immutable and retained per policy.

Testing Checklist

• Unit tests for migration scripts and helpers.
• Integration tests covering data movement, schema changes, and validation steps.
• End-to-end tests in staging with representative data volumes.
• Rollback tests executing safe recovery procedures.

Common Mistakes to Avoid

• Skipping validation or relying on heuristic checks alone.
• Unclear handoffs leading to drift between plans and execution.
• Executing production changes without approved rollback paths.
• Storing secrets in code or logs; ignoring vault-based access.

FAQ

What is the purpose of this AGENTS.md Template?

It provides a structured, copyable operating manual for database migration agents that supports single-agent and multi-agent orchestration with explicit roles, handoffs, and governance.

How do the agent handoffs ensure data integrity?

Handoffs occur only after validated results, with each step requiring approval by the next role and full logging for traceability.

How are secrets and credentials managed during migrations?

Secrets are retrieved from a central vault; no plaintext storage or hard-coded credentials are allowed, and access is strictly role-based.

What happens on migration failure?

A rollback plan is activated, rollback steps are executed in order, and a human review is triggered to determine remediation and re-run strategy.

How is multi-agent orchestration controlled?

The Orchestrator enforces the single source of truth, enforces gate approvals, and coordinates agent actions with auditable logs and escalation rules.