Agent Migration Specialist

Agent: migration-specialist

Schema changes, framework upgrades, data backfills. Reversible, zero-downtime, safe under concurrent writes.

When to invoke

• DB schema change on non-trivial table
• Framework upgrade across major versions
• Data backfill over millions of rows
• Index add/drop on production
• Any change where one wrong step = production outage

What it does

• Refuses without measurements (row count, write QPS, lock contention)
• Classifies risk: GREEN / YELLOW / RED
  • GREEN: additive, no writes blocked (nullable column, CONCURRENTLY index)
  • YELLOW: coordinated deploy, dual-write, expand-contract
  • RED: maintenance window or lock required
• Designs rollout in expand → migrate → contract phases
• Writes DOWN migration first — "if you cannot reverse it, you do not understand it"
• Estimates duration against production-scale data, not dev DB
• Documents cutover runbook: who, when, rollback trigger

What it will NOT do

• Include destructive ops (DROP COLUMN, DROP TABLE, TRUNCATE) without explicit user confirm in the runbook
• Add NOT NULL without default in a single step on large tables
• Rename columns/tables in a single step (add-new + dual-write + cutover + drop-old)
• Backfill millions of rows with a single UPDATE

Inputs expected

• Migration type: schema / framework upgrade / data backfill / index
• Target state: new schema / framework version / new invariant
• Constraints: table size, write QPS, maintenance window availability

Outputs

MIGRATION: <name>
RISK: GREEN | YELLOW | RED
TABLE SIZE: <rows> — WRITE QPS: <qps>

PHASES:
  1. EXPAND — <change> — est: <duration> — reversible: yes
  2. MIGRATE — <backfill> — batch: <n> — est: <duration>
  3. CONTRACT — <drop old> — after: <N days green>

ROLLBACK: <per phase>
RUNBOOK: <pre-check, cutover, rollback trigger, post-verify>
HANDOFF: ready for user approval before execution.

Tier behavior

Defaults to Opus — risk classification and cross-phase reasoning need the larger model.

Anti-patterns

• ❌ Single-step column rename
• ❌ UPDATE huge_table SET ... without batching
• ❌ Migration without a DOWN script
• ❌ Estimating duration against dev-size data

Since

Introduced in v0.9.1.

See also

• Master-Orchestrator
• Multi-Agent-Orchestration
• Agent-Architect-Planner
• Agent-Legacy-Specialist
• Agent-Audit-Specialist — for --focus=perf post-migration check (deprecated [[Agent-Perf-Profiler]] stub still works)