Migrate

Migrate

Overview

All subagent dispatches use disk-mediated dispatch. See shared/dispatch-convention.md for the full protocol.

Autonomous migration planning and execution: analyzes a migration target, maps blast radius, decomposes into safe phases with compatibility layers, groups consumers into waves, then executes through build's refactor/feature mode with verification at each phase boundary.

Announce at start: "Running migrate on [migration target description]."

Skill type: Rigid -- follow exactly, no shortcuts.

Purpose: Bridge between prospector discovery ("you should modernize X") and build execution ("here is the plan, execute it"). Today that bridge is manual. /migrate makes it autonomous.

Two modes:

• Plan + Execute (default) -- produces a phased migration plan, then executes each phase through build
• Plan only -- produces the plan and saves it without executing

Invocation

/migrate "upgrade lodash from v3 to v4"                    # plan + execute
/migrate --plan-only "upgrade React Router v5 to v6"       # plan only, no execution
/migrate --execute docs/plans/2026-03-23-lodash-migration-plan.md  # execute existing plan
/migrate --orgs org1,org2 "upgrade shared-auth v2 to v3"   # cross-repo

Communication Requirement (Non-Negotiable)

Between every agent dispatch and every agent completion, output a status update to the user. This is NOT optional -- the user cannot see agent activity without your narration.

Every status update must include:

1. Current phase -- Which pipeline phase you're in
2. What just completed -- What the last agent reported
3. What's being dispatched next -- What you're about to do and why
4. Phase progress -- Which phases are done, in progress, or pending

After compaction: If you just experienced context compaction, follow the Compaction Recovery procedure, re-read state from the scratch directory, and output current status before continuing. Do NOT proceed silently.

Examples of GOOD narration: > "Phase 2 complete. Blast radius mapper found 14 direct consumers across 3 modules. Dispatching Phase Planner to decompose into migration phases."

> "Phase 7, Wave 2 complete. 8/14 consumers migrated. Build reported all tests passing after Phase 3b. Proceeding to Wave 3 (4 consumers)."

This requirement exists because: Migrations are long-running and high-stakes. The user needs visibility into progress, blast radius, and phase outcomes to decide whether to continue or intervene.

Pipeline Status

Write a status file to ~/.claude/projects//memory/pipeline-status.md at every narration point. This file is overwritten (not appended) and provides ambient awareness for the user in a second terminal.

Write Triggers

Write the status file at every point where the Communication Requirement mandates narration: before dispatch, after completion, phase transitions, health changes, escalations, and after compaction recovery.

Status File Format

The status file uses this structure (overwritten in full each time):

# Pipeline Status
**Updated:** 
**Started:** 
**Skill:** migrate
**Phase:** 
**Health:** 
**Suggested Action:** 
**Elapsed:** 

## Recent Events
- [HH:MM] 
- [HH:MM] 
(last 5 events, newest first)

Skill-Specific Body

Append after the shared header:

## Migration Progress
| Phase | Description | Status |
|-------|-------------|--------|
| 0 | Pre-flight | DONE |
| 1 | Analyze target | DONE |
| 2 | Map blast radius | IN PROGRESS |
| 3 | Decompose phases | PENDING |
| 4 | Compatibility layer | PENDING |
| 5 | Plan waves | PENDING |
| G | User gate | PENDING |
| 6 | Rollback points | PENDING |
| 7 | Execute | PENDING |
| 8 | Cleanup | PENDING |

## Blast Radius
- Direct consumers: 14
- Cross-repo: 3 repos (if applicable)

## Execution (Phase 7)
- Wave 1: 4/4 consumers DONE
- Wave 2: 2/6 consumers IN PROGRESS
- Phase test suite: PASSING

Health State Machine

Health transitions are one-directional within a phase: GREEN -> YELLOW -> RED. Phase boundaries reset to GREEN.

• Phase boundaries (reset to GREEN): each new phase
• YELLOW: quality gate round 3+ on any phase, phase retry in progress, medium-confidence decision
• RED: phase execution failure, test suite failure unresolved, stagnation in quality gate, compatibility layer test failure

When health is YELLOW or RED, include **Suggested Action:** with a concrete, context-specific sentence.

Inline CLI Format

Output concise inline status alongside the status file write:

• Minor transitions (dispatch, completion): one-liner, e.g. Phase 2 [blast radius] 14 consumers found | GREEN | 12m
• Phase changes and escalations: expanded block with --- separators
• Health transitions: always expanded with old -> new health

Compaction Recovery

After compaction, before re-writing the status file:

1. Read the existing pipeline-status.md to recover Started timestamp and Recent Events buffer
2. Reconstruct phase, health, and skill-specific body from scratch directory state files
3. Write the updated status file
4. Output inline status to CLI

Model Allocation

| Agent | Model | Dispatch Method | |-------|-------|-----------------| | Orchestrator | Opus | -- | | Migration Analyzer | Opus | Agent tool (Explore) | | Blast Radius Mapper | Sonnet | Agent tool (general-purpose) | | Phase Planner | Opus | Task tool | | Compatibility Layer Designer | Opus | Task tool | | Consumer Wave Grouper | Sonnet | Task tool |

Scratch Directory

Canonical path: ~/.claude/projects//memory/migrate/scratch//

Files:

• invocation.md -- migration target, mode (plan-only/full), orgs scope
• migration-analysis.md -- Phase 1 output (API delta, breaking changes, complexity)
• blast-radius.md -- Phase 2 output (impact manifest + consumer registry)
• phase-plan.md -- Phase 3 output (ordered phases with safe stopping points)
• compatibility-spec.md -- Phase 4 output (shim/adapter design)
• wave-plan.md -- Phase 5 output (consumer wave assignments)
• migration-plan.md -- consolidated plan (presented at user gate)
• rollback-points.md -- Phase 6 output (per-phase rollback definitions)
• execution-status.json -- Phase 7 tracking (per-phase execution status)
• phase-N/ -- per-phase build execution scratch (delegated to build's scratch)

Stale cleanup: Delete scratch directories older than 48 hours (migrations run longer than most skills). Preserve directories where execution-status.json shows any phase in executing or failed status.

Context Management

Follow spec's context budget management pattern:

• Preemptive context checkpoint between phases: Before starting a new phase, write current state to scratch directory so compaction recovery can resume
• Per-phase context lifecycle: Load only current phase's inputs. Do not carry forward raw outputs from completed phases -- use the structured scratch files instead
• Complex migrations (10+ phases): Use aggressive summarization of completed phases. Carry forward only the phase-plan.md and execution-status.json, not individual phase outputs

Compaction Recovery

Recovery procedure:

1. Read invocation.md -- recover migration target, mode, scope
2. Read execution-status.json -- determine which phases are complete/in-progress/pending
3. Read migration-plan.md -- recover the approved plan
4. For any phase in executing status: restart that phase from the beginning (safe because build's refactor mode has its own rollback)
5. Resume processing from the next pending phase

---

Pipeline-Active Marker

Before any dispatch work, check for a crashed prior migration session:

1. Check /.pipeline-active (where ` is ~/.claude/projects//memory/`)
2. Not found: Write the pipeline-active marker (JSON with pipeline_id set to current session ID, skill set to "migrate", phase set to "0", start_time set to current ISO-8601 timestamp, scratch_dir and dispatch_dir paths, branch from git branch --show-current, baseline_sha from git rev-parse HEAD). Proceed to Phase 0.
3. Found, same pipeline_id: Compaction recovery (existing behavior). Do not re-write the marker.
4. Found, different pipeline_id: Previous migration session crashed. Check marker's branch against current branch — if mismatched, warn the user which branch the crashed session was on. Present to user:

> "Previous migration session on branch [marker.branch] crashed. Start fresh? [yes]" Delete the stale marker. Write a fresh marker. Proceed to Phase 0. (Full replay orchestration for migrate is deferred -- detection and cleanup only for now.)

Marker cleanup: Delete .pipeline-active after Phase 8 (Cleanup) completes successfully.

Phase 0: Pre-flight

Before any agent dispatch:

1. Consult cartographer (consult mode) -- load known module boundaries for blast radius mapping
2. Consult forge (feed-forward) -- check past lessons, especially prior migration outcomes
3. Handle --execute -- if specified, read the existing plan file, validate it has the expected structure (phases, consumer registry, rollback points), and skip to Phase 7.
4. Dispatch recon with consumer-registry module:

`` /recon task: "Map structure and consumers for migration: " context: { target: "" } modules: ["consumer-registry"] ``

Write recon's Investigation Brief to scratch//recon-brief.md. Write recon's Consumer Registry section to scratch//consumer-registry-from-recon.md.

On recon failure: "Recon failed: [reason]. Blast Radius Mapper will discover consumers from scratch." Proceed without recon context -- Phase 2 falls back to full consumer discovery (existing behavior).

1. Write invocation.md to scratch directory with migration target, mode, and scope.

---

Phase 1: Analyze Migration Target

Dispatch the Migration Analyzer (Opus, Agent tool, Explore subagent) using ./migration-analyzer-prompt.md.

Input:

• Migration description from user
• Cartographer data (if available)
• Framework context from dependency manifests (following prospector's Phase 0.5 pattern: read package.json, *.csproj, requirements.txt, go.mod, Cargo.toml, etc.)

The analyzer investigates:

• Changelog / migration guide (CHANGELOG.md, MIGRATION.md, UPGRADING.md in repo or dependency)
• API diff between versions (old vs new type definitions, function signatures, endpoint contracts)
• Breaking changes (backward-incompatible removals or signature changes)
• Deprecation notices (what the new version removes that the old warned about)
• New capabilities (additions consumers may want to adopt during migration)

Output: Structured migration analysis written to scratch//migration-analysis.md.

Complexity classification:

• Low: /blast-radius.md`.

Consumer registry entry format:

- consumer: 
  usage_pattern: "calls TargetClass.method(args)"
  migration_complexity: low|medium|high
  independent: true|false
  reason_if_dependent: "shares state with "

---

Phase 3: Decompose into Phases

Dispatch the Phase Planner (Opus, Task tool) using ./phase-planner-prompt.md.

Input: Migration analysis + blast radius + consumer registry.

The planner produces an ordered list of migration phases. Each phase must satisfy the safe stopping point invariant: after completing the phase, the codebase compiles, all tests pass, and both old and new code paths function correctly.

Standard phase template (adapted by planner based on migration type):

| Phase | Description | Build Mode | Typical Content | |-------|-------------|------------|-----------------| | 1 | Introduce new version | Feature | Add new dependency alongside old | | 2 | Add compatibility layer | Feature | Create shims/adapters | | 3a-3N | Migrate consumer waves | Refactor | Update consumers wave-by-wave | | 4 | Remove compatibility layer | Refactor | Delete shims once all consumers migrated | | 5 | Remove old version | Refactor | Delete old dependency |

Each phase entry includes:

• Phase number and description
• Affected files/repos
• Build mode (feature or refactor)
• Estimated effort (Low/Medium/High)
• Safe stopping point verification criteria
• Dependencies on prior phases

Legacy Migration Patterns

The planner must verify the phase plan against these operational patterns. These address the human and organizational side of migration that the technical decomposition doesn't cover.

1. Map the territory first — Understand what the legacy system actually does, not what it was designed to do. Hidden workflows, tribal knowledge in column headers, undocumented behaviors ARE the requirements spec. If /recon with consumer-registry was run, the technical mapping exists — but the planner should flag operational unknowns (manual processes, workarounds, tribal knowledge) as risks requiring user confirmation before cutover phases.

1. Build alongside, not on top of — The new system must run in parallel with the old. Both are live during migration. Users try the new while the old is a safety net. The phase plan must include a coexistence period — never require a hard cutover without one. If Phase 2 (compatibility layer) was skipped, the planner must justify why parallel operation is unnecessary.

1. Cut over by group, not by system — Migration happens one team/department at a time, not all at once. The phase plan should identify rollout groups (who moves when) in addition to technical phases. Wave 3a-3N should map to user groups, not just code modules.

1. Don't migrate data unless you must — Historical data in the old system is fine where it is. The new system starts capturing from day one. If historical queries are needed, build a read-only bridge. The planner should flag any data migration phases as high-risk and verify that data migration is genuinely required (not just assumed).

1. Kill the old system explicitly — The phase plan must include an explicit decommission step: archive the old system and remove access. "Still available just in case" systems never die. This should be the final phase, with clear criteria for when it triggers (last user migrated, parallel period complete, no fallback queries in N days).

Output: scratch//phase-plan.md

---

Phase 4: Design Compatibility Layer

Dispatch the Compatibility Layer Designer (Opus, Task tool) using ./compatibility-designer-prompt.md.

Input: Migration analysis (API delta) + phase plan (which phases need coexistence).

Skip condition: If Phase 3 determined no coexistence period is needed (e.g., simple in-place rename with no external consumers), skip this phase. Write "Compatibility layer: SKIPPED (no coexistence period required)" to scratch.

Output: Compatibility specification written to scratch//compatibility-spec.md:

• Shim inventory -- list of adapters/facades with their interfaces
• Mapping -- old API call -> shim -> new API call (for each shim)
• Direction -- strangler fig (old-to-new) or facade (new-to-old)
• Tests -- what tests the shim needs (bidirectional correctness)
• Removal criteria -- when each shim can be safely deleted

---

Phase 5: Plan Consumer Waves

Dispatch the Consumer Wave Grouper (Sonnet, Task tool) using ./wave-grouper-prompt.md.

Input: Consumer registry from Phase 2 + phase plan from Phase 3.

Algorithm:

1. Build dependency graph among consumers (consumer A depends on consumer B if A imports/calls B)
2. Topological sort: consumers with no dependencies on other consumers go in Wave 1
3. Consumers depending only on Wave 1 consumers go in Wave 2
4. Continue until all consumers assigned
5. Within each wave, verify independence (no consumer in the wave depends on another in the same wave)

Output: Wave assignments written to scratch//wave-plan.md.

For cross-repo migrations: each wave entry includes repo name

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: raddue
• Source: raddue/crucible
• License: MIT

Install and usage instructions live in the source repository linked above.