arn-infra-migrate

Arness Infra Migrate

Handle infrastructure migrations as tracked projects with four scenarios: PaaS-to-IaC graduation, provider-to-provider migration, provider consolidation, and partial migration. Creates a parent issue with migration overview and decomposes into individual task issues with dependencies, verification criteria, and rollback procedures.

This skill manages the full migration lifecycle: planning, IaC generation for the target, incremental deployment to staging, verification, cutover, and cleanup. It warns other skills about in-progress migrations to prevent conflicting changes.

Prerequisites

Read ## Arness from the project's CLAUDE.md. If no ## Arness section exists or Arness Infra fields are missing, inform the user: "Arness Infra is not configured for this project yet. Run /arn-infra-wizard to get started — it will set everything up automatically." Do not proceed without it.

Check the Deferred field. If Deferred: yes, inform the user: "Infrastructure is in deferred mode. Migration is not available until infrastructure is fully configured. Run /arn-infra-assess to un-defer." Stop.

Extract:

• Experience level -- derived from user profile. Read ~/.arness/user-profile.yaml (or .claude/arness-profile.local.md if it exists — project override takes precedence). Apply the experience derivation mapping from ${CLAUDE_PLUGIN_ROOT}/skills/arn-infra-ensure-config/references/experience-derivation.md. If no profile exists, check for legacy Experience level in ## Arness as fallback.
• Providers -- current cloud providers
• Providers config -- path to providers.md
• Default IaC tool -- the target IaC tool for graduation migrations
• Environments -- environment list for staged migration
• Environments config -- path to environments.md
• Issue tracker -- for creating migration project issues (github, jira, none)
• Platform -- for issue management
• Infra plans directory -- for migration plan storage (default: .arness/infra-plans)
• Jira site and Jira project -- if Issue tracker is jira

Workflow

Step 1: Detect Migration Scenario

Ask (using AskUserQuestion):

"What kind of migration are you planning?"

Options:

1. Graduate -- Move from PaaS/platform-native configs to infrastructure-as-code (e.g., fly.toml to OpenTofu, Heroku to AWS)
2. Provider migration -- Move services from one cloud provider to another (e.g., AWS to GCP, Fly.io to AWS)
3. Consolidation -- Reduce the number of providers (e.g., 3 providers to 1-2)
4. Partial migration -- Move specific services while keeping others in place (e.g., move just the database to a managed service)

Read the local override or plugin default for migration-scenarios.md.

Step 2: Check for Active Migrations

Read the provider configuration:

Read <providers-config-path>

Check if any providers have Migration: <id> (in progress):

If active migration detected: Warn: "There is an active migration in progress: [migration-id] affecting [providers/services]. Starting a new migration that overlaps with these services could cause conflicts."

Ask (using AskUserQuestion):

"How would you like to handle the active migration conflict?"

Options:

1. Continue anyway -- Start a new migration (I'll flag potential conflicts)
2. Wait -- Complete the current migration first
3. Cancel current -- Roll back the current migration and start this one

If no active migrations: Continue to Step 3.

Step 3: Assess Source and Target

Based on the chosen scenario:

Graduate:

• Read current PaaS configuration (fly.toml, railway.json, render.yaml, vercel.json, etc.)
• Identify deployed services, databases, and networking
• Determine target provider and IaC tool from ## Arness config
• Map PaaS features to IaC equivalents (auto-scaling, health checks, SSL, custom domains)

Provider migration:

• Read source provider's IaC configs and deployed resources
• Ask for target provider: "Which provider do you want to migrate to?"
• Compare source resources with target provider equivalents
• Identify services that may not have direct equivalents

Consolidation:

• List all configured providers with their scopes
• Ask which providers to consolidate into: "You currently use [list]. Which provider(s) do you want to consolidate into?"
• Identify the scope of each provider being removed
• Map services to the consolidation target

Partial migration:

• Ask which specific services to migrate: "Which services do you want to move?"
• Identify the target provider/service for each
• Check dependencies between migrating and non-migrating services

Step 4: Create Migration Project

4.1: Generate Migration Plan

Invoke the arn-infra-specialist agent via the Task tool, passing the model from .arness/agent-models/infra.md as the model parameter (see plugins/arn-infra/skills/arn-infra-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

--- MIGRATION CONTEXT --- Scenario: [graduate | provider-migration | consolidation | partial] Source: [source provider(s) and current configuration] Target: [target provider(s) and IaC tool] Services affected: [list of services being migrated] Environments: [environment promotion order] --- END MIGRATION CONTEXT ---

--- INSTRUCTIONS --- Generate a migration plan covering:

1. Target infrastructure definition (IaC for the target provider)
2. Data migration steps (database export/import, file transfer)
3. DNS cutover plan (TTL reduction, record updates)
4. Rollback procedure at each step
5. Service dependency order (which services to migrate first)
6. Estimated timeline per step

--- END INSTRUCTIONS ---

4.2: Get Cost Comparison

Invoke the arn-infra-cost-analyst agent via the Task tool, passing the model from .arness/agent-models/infra.md as the model parameter (see plugins/arn-infra/skills/arn-infra-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

--- COST CONTEXT --- Source infrastructure: [current provider resources and costs] Target infrastructure: [proposed target resources] Migration type: [scenario] --- END COST CONTEXT ---

--- INSTRUCTIONS --- Compare monthly costs before and after migration:

1. Current cost breakdown by service and provider
2. Projected cost after migration
3. Migration execution costs (data transfer, parallel running period)
4. Net cost change and payback period (if applicable)

--- END INSTRUCTIONS ---

4.3: Present Migration Plan for Approval

Present the migration plan to the user:

"Here is the migration plan:

Scenario: [type] Source: [provider(s)] Target: [provider(s)] Services affected: [list]

Cost comparison: | | Current | After Migration | Change | |------|---------|-----------------|--------| | Monthly cost | $X | $Y | +/-$Z |

Migration steps: [numbered list of steps with dependencies and estimated duration]

Rollback plan: [summary of rollback strategy]

Risks: [identified risks with mitigation]

Ask (using AskUserQuestion):

"How would you like to proceed with the migration plan?"

Options:

1. Approve and create project -- Create migration issues and start execution
2. Adjust -- Modify the plan before creating issues
3. Cancel -- Abandon this migration

Step 5: Create Migration Issues

Upon approval, create the migration project in the issue tracker.

If Issue tracker is none: Skip issue creation (Steps 5.1, 5.2). Record the migration plan in a file at <infra-plans-dir>/MIGRATION_<name>.md instead. Mark providers as migrating in providers.md (Step 5.3) and proceed to Step 6.

5.1: Create parent issue:

GitHub:

gh issue create \
  --title "Migration: [scenario description]" \
  --label "arn-infra-migration" \
  --body "[migration plan overview: source/target providers, affected services, timeline, risk assessm