Migration Ops

On first invocation, read `references/orchestrator.md` and follow its welcome protocol.

The "change the engine mid-flight" skill. Fills the gap between oc-reverse-spec ("what I have") and oc-app-architect ("what I want") when the answer is "transform one into the other" — without downtime, without data loss, and with a rollback at every step.

This is inherently multi-session work. A database migration plan might span 3–4 conversations. Checkpoint protocol adoption is critical from day one.

/oc-migrate — Command Reference

MIGRATION OPS COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  PLAN
  /oc-migrate              Show this menu
  /oc-migrate assess       Inventory current state + classify migration type
  /oc-migrate plan         Generate incremental migration plan with rollback points
  /oc-migrate impact       Blast radius analysis — what breaks during each step

  EXECUTE
  /oc-migrate execute      Start or resume execution from migration plan
  /oc-migrate step [N]     Execute a specific step (with pre/post verification)
  /oc-migrate verify       Run verification suite against current state
  /oc-migrate rollback     Revert to last verified checkpoint

  OBSERVE
  /oc-migrate status       Current migration state from checkpoint
  /oc-migrate diff         Compare current state vs. target state
  /oc-migrate history      Show completed steps with pass/fail and timing

  UTILITIES
  /oc-migrate dry-run      Simulate the next step without applying changes
  /oc-migrate ecosystem    Bulk-update opchain skills (format, protocol, oc-orchestrator)
  /oc-migrate abandon      Abandon an in-progress migration (archive checkpoint)
  /checkpoint           Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command, or describe what you want to migrate.

How This Skill Fits the Pipeline

EXISTING SYSTEM (documented or not)
       │
       ├──► oc-reverse-spec (if undocumented → produces baseline specs)
       │
       ▼
┌──────────────┐
│ MIGRATION-OPS│  current state → migration plan → incremental execution → target state
│              │  Reads: oc-reverse-spec, oc-stack-forge, oc-app-architect, oc-code-auditor
│              │  Chains to: oc-code-auditor (post-migration verify), oc-deploy-ops (cutover)
└──────┬───────┘
       │
       ├──► oc-code-auditor /oc-audit (post-migration quality gate)
       ├──► oc-deploy-ops /oc-deploy (cutover deployment)
       └──► oc-app-architect (if migration reveals spec updates needed)

Migration-ops sits between "what exists" and "what should exist" — it's the transformation engine. It does NOT build new features (oc-app-architect) or document existing code (oc-reverse-spec). It transforms running systems from state A to state B.

Migration Types

Every migration request is classified into one of these types. The type determines which reference playbook to load and which verification strategy to use.

Auto-Detection

When the user describes a migration without explicitly classifying it, infer the type:

• "Move from D1 to Postgres" → Database
• "Migrate the warehouse" / "BigQuery to Snowflake" → Database
• "Upgrade Hono to v4" → Framework
• "Switch auth to Supabase" → Auth
• "Move off Cloudflare to Vercel" → Platform
• "Split the monorepo" → Structural
• "Replace Axios with fetch" → Dependency
• "Update all skills to the new format" → Ecosystem
• "Upgrade checkpoint protocol to v2" → Ecosystem
• "Add a new field to every SKILL.md" → Ecosystem

If ambiguous, ask ONE clarifying question.

Structural vs oc-modularize-ops. Structural stays the home for repo/package reorgs whose behaviour is git-diffable. A decomposition of a live monolith carrying real traffic, where no functionality or data loss has to be proven against real input/output, goes to oc-modularize-ops first. It decides whether to split, captures golden fixtures, and plans the seams, then hands the move back here as modularization/module-map.json (see Cross-Skill Reads). The two skills never both plan the same split: if that file exists, plan from it.

Phase 0: Assessment (/oc-migrate assess)

Before planning anything, understand the current state and the target state. This is the most important phase — a bad assessment produces a bad plan.

Step 1: Gather Current State

Check for existing documentation in this order:

1. CLAUDE.md / project config — if a CLAUDE.md exists in the project root, read it

first. For Cloudflare Workers apps, also read wrangler.jsonc (or wrangler.toml) for bindings (D1, KV, secrets), routes, and compatibility dates.

1. Reverse-spec checkpoint — if it exists, the current state is already documented.

Read context_primer.key_decisions and generated_files for architecture, schema, and stack info. Skip redundant scanning.

1. App-architect checkpoint — read spec files (01-tech-stack.md, 02-architecture.md)

for the documented architecture.

1. Stack-forge checkpoint — read stack decisions for current platform/framework choices.
2. Module map — if modularization/module-map.json exists, oc-modularize-ops has

already decided the split and planned the seams. Classify as Structural, take the module list, seams, and data ownership from the file (format under Cross-Skill Reads), and do not re-derive them.

1. Code scan — if no upstream checkpoints exist, run a targeted scan of the specific

layer being migrated (not a full oc-reverse-spec).

Step 2: Define Target State

The user describes where they want to end up. Capture:

• Target technology — specific framework, database, platform, auth provider
• Target version — exact version number, not "latest"
• Constraints — zero downtime required? Data migration needed? Backward compat?
• Timeline — "this session" vs. "planned over multiple sessions"
• Success criteria — what proves the migration worked?

Step 3: Gap Analysis

Compare current state → target state. For each gap:

Step 4: Risk Classification

Rate the overall migration:

Critical migration rule: If the assessment reveals a CRITICAL-risk migration, recommend breaking it into 2-3 sequential migrations (e.g., migrate database first, then swap auth, then move platform). Each sequential migration gets its own plan. Never execute multiple HIGH-risk changes simultaneously.

Output: Assessment Report

# Migration Assessment — [project]

## Classification
- **Type:** [Database | Framework | Auth | Platform | Structural | Dependency | Ecosystem]
- **Risk:** [LOW | MEDIUM | HIGH | CRITICAL]
- **Estimated steps:** [N]
- **Estimated sessions:** [N]

## Current State
[Dense summary from checkpoint reads or code scan]

## Target State
[What the user wants to achieve]

## Gap Analysis
| Gap | Current | Target | Effort | Risk |
|---|---|---|---|---|

## Dependencies
[What must be true before migration starts — tests passing, backups, etc.]

## Recommendation
[Proceed with single migration plan | Break into sequential migrations | Defer — prerequisites missing]

Write checkpoint: phase "assessed".

Phase 1: Migration Plan (/oc-migrate plan)

Generate an incremental migration plan. Every step has a verification gate and a rollback procedure. The plan follows the expand-migrate-contract pattern where applicable.

Pre-Planning: Web Search

Before generating any plan, web search for the migration path. Frameworks publish migration guides, databases have export/import docs, and platforms document cutover procedures. Search for [source] to [target] migration guide [year] and read the official docs before writing a single step. The official guide overrides generic patterns — if Hono v5 has a codemod, use it instead of manual find-and-replace.

Expand-Migrate-Contract Pattern

For most non-trivial migrations, the safest approach is:

1. Expand — Add the new capability alongside the old one (dual-write, feature flag,

new column alongside old). Both systems work simultaneously.

1. Migrate — Move data/traffic/users from old to new. Verify at each batch.
2. Contract — Remove the old capability once new is verified. This is the point

of no return — keep rollback available until this step.

Not every migration needs this pattern. Dependency swaps and minor framework upgrades can often be done in-place. The assessment's risk level determines the approach:

Migration Step Template

Every step in the plan follows this structure:

## Step [N]: [Short title]

### Owner
CLAUDE | USER | CLAUDE+USER
(CLAUDE = autonomous execution. USER = only a human can do this — create accounts,
fill .env, DNS changes. CLAUDE+USER = Claude drafts, user reviews/confirms.)

### What Changes
[Specific files, configs, schemas, or infrastructure being modified]

### Pre-Conditions
[What must be true before this step runs — prior steps passed, tests green, etc.]

### Procedure
[Numbered instructions. Concrete commands, not vague descriptions.]

### Verification
[How to prove this step succeeded. Specific checks:]
- [ ] [Testable condition — command to run, expected output]
- [ ] [Another condition]

### Rollback
[How to undo this step if verification fails. Specific commands.]
- [ ] [Rollback step 1]
- [ ] [Rollback step 2]
- [ ] [Verify rollback succeeded]

### Point of No Return?
[YES/NO. If YES, explain why and what must be confirmed before proceeding.]

### Estimated Time
CLAUDE: [time] | USER: [time]

Standard Step Ordering by Migration Type

Read references/migration-playbooks.md for type-specific step templates. General ordering principles:

Database migrations:

1. Backup current database
2. Create target database + apply schema
3. Set up dual-write (if live migration)
4. Migrate data in batches with verification
5. Switch reads to new database
6. Verify all reads correct
7. Stop writes to old database
8. Remove dual-write code
9. Archive old database

Framework upgrades:

1. Pin current version in lockfile
2. Web search [framework] [version] migration guide — read breaking changes
3. Create upgrade branch
4. Bump version
5. Fix breaking changes (compiler/linter-guided, referencing migration guide)
6. Run full test suite
7. Manual smoke test
8. Merge

Auth provider swaps:

1. Set up new auth provider (sandbox/dev)
2. Implement new auth flow alongside old (feature-flagged)
3. Migrate user credentials / sessions
4. Route new signups to new provider
5. Migrate existing users in batches
6. Verify all users can authenticate via new provider
7. Remove old auth code
8. Decommission old provider

Platform moves:

1. Set up target platform account + project
2. Adapt code for target runtime (bindings, env vars, API differences)
3. Deploy to target (staging)
4. Run full smoke test suite on target
5. Set up DNS for cutover (low TTL)
6. Cutover DNS
7. Monitor for 24-48h
8. Decommission old platform

★ Plan Approval Gate

Present the complete plan. User reviews every step, rollback procedure, and point of no return. Do NOT proceed until explicitly approved.

Write checkpoint: phase "planned".

Phase 2: Execution (/oc-migrate execute)

Execute the migration plan step by step. Each step is a mini-cycle: pre-check (block on missing preconditions) → execute (rollback on error) → verify (retry / manual fix / rollback on fail) → checkpoint (save progress + verification).

Execution Rules

1. One step at a time. Never batch-execute steps. Each step gets individual

verification before the next begins.

1. Verify before advancing. A step is not "done" because the commands ran

without errors. It's done when the verification checks pass.

1. Checkpoint after every step. If the session ends mid-migration, the next

session knows exactly where to resume.

1. Rollback is always available — until a "point of no return" step, at which

point the user must explicitly confirm they want to proceed.

1. Dry run first when the step modifies production data. Show what would

change without applying it.

Step Execution Report

After each step:

## Step [N] — Execution Report

### Status: PASSED | FAILED | ROLLED BACK

### Procedure Output
[Key output from the commands run]

### Verification Results
- [x] [Check 1] — PASSED [evidence]
- [ ] [Check 2] — FAILED [what went wrong]

### Duration
CLAUDE: [X min] | USER: [Y min]

### Next
[What happens next — next step, or remediation needed]

Phase 3: Verification (/oc-migrate verify)

Run the full verification suite against the current state. This can be invoked:

• After completing all steps (final verification)
• Mid-migration (progress check)
• After a rollback (confirm clean state)

Verification Layers

Final Verification Report

# Migration Verification — [project]

## Migration: [description]
## Steps Completed: [X] of [Y]

## Verification Results
| Layer | Status | Evidence | Notes |
|---|---|---|---|
| Schema | ✅ PASS | 12 tables, all indexes present | — |
| Data | ✅ PASS | Row counts match ±0, checksums verified | — |
| API | ⚠️ PARTIAL | 18/20 endpoints pass, 2 timeout | See findings |
| Auth | ✅ PASS | Both users authenticated successfully | — |
| Performance | ✅ PASS | p95 42ms (baseline: 45ms) | Slight improvement |

## Open Issues
1. [Issue with details and remediation plan]

## Verdict: MIGRATION COMPLETE | ISSUES REMAINING

Rollback (/oc-migrate rollback)

Revert to the last verified state. Rollback granularity depends on migration progress:

Rollback Strategies

Rollback Verification

After rollback, run the same verification suite against the original state:

• Schema matches pre-migration state
• Data intact (compare against backup checksums)
• All endpoints respond as before
• Auth works as before

Handling Multi-Session Migrations

Migrations are the most checkpoint-dependent skill in the ecosystem. A database migration might span 4+ sessions:

• Session 1: Assessment + plan generation
• Session 2: Steps 1-3 (backup, create target, dual-write setup)
• Session 3: Steps 4-6 (data migration, read switchover)
• Session 4: Steps 7-9 (cleanup, decommission, final verification)

Session Handoff Protocol

At the end of each session (or when context is getting long):

1. Write a detailed checkpoint with:

• Which steps are complete (with verification results)
• Which step is next
• Any manual steps the user needs to do before next session
• Current system state (dual-write active? which database is primary?)

1. Tell the user: "Migration paused at step [N]. Before next session, please [manual tasks]. Next session will resume with [step N+1]."

Session Resume

On resume, oc-migration-ops:

1. Reads its checkpoint
2. Displays migration progress and current system state
3. Checks if manual tasks are complete
4. Re-runs verification on the last completed step (detect drift)
5. Proceeds with next step

Impact Analysis (/oc-migrate impact)

Before executing, analyze blast radius — what could break at each step and who's affected.

Impact Report

## Impact Analysis — [migration description]

### Service Dependencies
[Which services/users/integrations depend on the system being migrated]

### Per-Step Impact
| Step | What Changes | Who's Affected | Downtime | Rollback Time |
|---|---|---|---|---|
| 1. Backup | Nothing visible | Nobody | 0 | N/A |
| 2. Schema | Nothing visible | Nobody | 0 | < 1 min |
| 3. Dual-write | Write latency +10ms | All users | 0 | < 5 min |
| 4. Data migration | Read latency +20ms | All users | 0 | 30 min (restore backup) |
| 5. Read switchover | ★ CRITICAL — brief read gap | All users | ~30s | < 5 min |

### Risk Mitigation
| Risk | Likelihood | Mitigation |
|---|---|---|
| Data loss during migration | LOW | Backup verified at step 1, checksums per batch |
| Auth gap during switchover | MEDIUM | Feature flag, gradual rollout (10% → 50% → 100%) |
| Performance regression | LOW | Baseline metrics captured, alert if p95 > 2x |

### Recommended Timing
[When to run this migration — low-traffic window, maintenance window, or safe anytime]

Cross-Skill Integration

Active Chaining

Session Persistence (Checkpoint Protocol)

The shared checkpoint schema, write rules and resume protocol live in references/checkpoint-protocol.md, bundled with this skill. This section adds only what is specific to oc-migration-ops.

Checkpoint: {project-dir}/.checkpoints/oc-migration-ops.checkpoint.json

Resume on Start

When any /oc-migrate command is invoked:

1. Check for checkpoint
2. If exists: show migration type, current step, verification status, next action
3. Ask: "Continue from step [N], restart, or show full checkpoint?"

Concurrent Migration Guard

One active migration per project. If a checkpoint exists with status: in_progress, block any new /oc-migrate assess or /oc-migrate plan until the current migration is completed, rolled back, or explicitly abandoned via /oc-migrate abandon. This prevents half-finished migrations from being orphaned by a new one starting on top.

/oc-migrate abandon archives the checkpoint to .checkpoints/history/ and warns: "Abandoning mid-migration may leave the system in a partial state. Run /oc-migrate verify to check current health."

progress_table

[
  { "id": "assessment",    "label": "Assessment + classification",    "status": "not_started" },
  { "id": "plan",          "label": "Migration plan generation",      "status": "not_started" },
  { "id": "plan-gate",     "label": "★ Plan approval",                "status": "not_started" },
  { "id": "step-1",        "label": "Step 1: [title]",                "status": "not_started" },
  { "id": "step-2",        "label": "Step 2: [title]",                "status": "not_started" },
  { "id": "step-3",        "label": "Step 3: [title]",                "status": "not_started" },
  { "id": "verification",  "label": "Final verification",             "status": "not_started" },
  { "id": "cleanup",       "label": "Cleanup + decommission",         "status": "not_started" }
]

skill_state

The skill_state shape varies by migration type. Common fields are always present; type-specific fields are included only when relevant.

{
  "migration_type": "database",
  "risk_level": "HIGH",
  "source": "D1 (SQLite)",
  "target": "Supabase Postgres",
  "total_steps": 9,
  "current_step": 4,
  "steps_verified": [1, 2, 3],
  "step_failures": [
    { "step": 4, "attempt": 1, "error": "brief description", "rollback": "succeeded" }
  ],
  "rollback_available": true,
  "point_of_no_return_reached": false,

  "_type_specific_fields_below": "shape depends on migration_type",

  "backup_location": "d1-backup-20260423.sql",
  "dual_write_active": true,
  "primary_database": "d1"
}

Type-specific fields by migration type:

When to Write

Cross-Skill Reads

`modularization/module-map.json` is a file, not a checkpoint read (another skill's skill_state stays private). oc-modularize-ops writes it; this skill and oc-fleet-ops read it. It holds a modules array, one object per module:

{ "modules": [
  { "id": "billing", "seam_contract": "modularization/seams/billing.md",
    "owns_data": ["invoices", "charges"], "image_hint": "billing",
    "equivalence_verified": true }
] }

The code-move plan covers every module in the map — oc-modularize-ops hands a module over for the move before its equivalence proof runs. The live cutover (traffic shift, decommission) for a module waits until oc-modularize-ops sets its equivalence_verified to true. owns_data marks where the dual-write boundaries sit.

No other skill reads this checkpoint. When handing cutover to oc-deploy-ops, state the cutover readiness (steps verified, point of no return reached or not) in the handoff itself — oc-deploy-ops does not gate on migration state.

Diff View (/oc-migrate diff) and History (/oc-migrate history)

/oc-migrate diff compares current system state against target state, showing per-area progress (Schema / Data / API / Auth / Config) with completion percentages, current dual-write posture, and the next step.

/oc-migrate history reads steps_verified and step_failures from the checkpoint and lists each completed step with outcome (✅/❌→✅ retry/❌ failed), plus the duration recorded in that step's migrations/steps/step-NN-report.md. Both views are read-only summaries — execution happens via /oc-migrate execute.

File Structure

project-dir/
├── .checkpoints/
│   └── oc-migration-ops.checkpoint.json
├── migrations/
│   ├── assessment.md              # Assessment report
│   ├── migration-plan.md          # Full plan with all steps
│   ├── impact-analysis.md         # Blast radius report
│   ├── steps/
│   │   ├── step-01-report.md      # Execution report per step
│   │   ├── step-02-report.md
│   │   └── ...
│   └── verification/
│       ├── pre-migration.md       # Baseline state snapshot
│       ├── step-03-verify.md      # Per-step verification
│       └── final-verify.md        # Final verification report

PM-Tool MCP Integration (v1.2+)

Migrations are multi-week, multi-step, multi-engineer. They are also genuinely scary — the kind of work where everyone in the org wants to know the current state. v1.2 makes that state legible in the PM tool the team already lives in. See oc-integrations-engineer for the canonical PM-MCP patterns and oc-integrations-engineer/references/pm-mcp-protocol.md for the runtime contract (tool names, markers, retry, deferred-action queue).

Parent + step-child mirror

When /oc-migrate plan produces the migration plan:

1. Create a parent ticket:

• title: Migration: {from-engine} → {to-engine}
• type: the epic (or chore) mapping from .opchain/pm.yaml

issue_types when the project defines one — migrations are exactly the kind of work epics exist for. The canonical pm.yaml defines only feature/bug/deploy/incident, so with neither key present use issue_types.feature.

• body: full migration spec summary + estimated calendar

duration + abort criteria + the rollback strategy.

• labels: migration, area:<from-engine>, area:<to-engine>,

risk:<low/med/high>.

1. For each plan step, create a child ticket parent-linked:

• title: Step {NN}: {step-name}
• body: step procedure + rollback + verification criteria.
• state: Todo initially.

1. Record the ids in oc-migration-ops.checkpoint.json pm_refs:

the parent as role: source, each step ticket as role: child, created_by_skill: oc-migration-ops. Keep the step ↔ ticket map in skill_state so the executor knows which ticket to update at each step.

Per-step state machine

The plan is the source of truth; the PM tool reflects it.

plan-pending      Step is in the plan, not yet started
in_progress       /oc-migrate execute picked it up
verified          /oc-migrate verify passed
blocked           Verification failed; rollback in progress
rolled-back       Step was undone; back to plan-pending or aborted
done              Verified + signed off; safe to advance

State transitions on the PM ticket happen at the same instants the checkpoint is updated. The PM comment thread carries the verifier output; the checkpoint carries the canonical machine-readable record.

Per-step comment shape

Every state transition emits a comment on the step ticket:

{state-from} → {state-to} at {timestamp}
Verifier: {pass-summary OR failure-detail}
Next: {next-action OR blocker}
Checkpoint: .checkpoints/oc-migration-ops.checkpoint.json

If the step touches a separately-tracked feature ticket (e.g. the migration is happening to unblock PLAT-4471), comment back on that ticket too: Migration step N completed; PLAT-4471 unblocked.

Aborts + rollbacks

Aborts are big enough that they get their own visibility:

• Abort triggered → comment on the parent ticket:

MIGRATION ABORTED at step {N}. Rollback in progress.

• Each rollback step gets its own comment on its step ticket.
• Final state on parent: rolled-back with the abort reason.

Communication discipline

For long-running migrations (multi-week), the parent ticket becomes the project homepage. oc-deploy-ops and oc-monitoring-ops do not look the migration parent up on their own: when a cutover deploy or an incident is traced to a migration step, link it to the parent yourself (the parent id is in this checkpoint's pm_refs).

Failure modes

• PM provider down at a step transition → the intended write goes

to the checkpoint's pm_deferred_actions[] (pm-mcp-protocol.md §4); the migration proceeds, and the user flushes the queue with --retry-pm on the next /oc-migrate execute, step or verify.

• Migration spans 50+ steps → use a phase-grouping pattern:

parent → phase tickets (≤6) → step tickets per phase. Avoids a flat list of 50 children that nobody can navigate.

• Cross-team migration → mention the team's owner in each step

ticket using the PM tool's @mentions (or labelled assignment if mentions aren't available).

Principles

1. Assess before planning, plan before executing. Skip assessment and you'll

discover blockers mid-migration. Skip planning and you'll have no rollback.

1. One step at a time. Every step gets individual verification. No batch execution.
2. Rollback is not optional. Every step documents how to undo it. If a step

can't be undone, it's a point of no return that requires explicit user confirmation.

1. Data integrity over speed. Checksums, row counts, and spot-checks at every

data migration step. Fast migrations that lose data are failures.

1. Dual-write beats big-bang. For database and auth migrations, run both systems

simultaneously before cutting over. The expand-migrate-contract pattern exists because big-bang cutovers fail.

1. Checkpoint obsessively. This is the most session-spanning skill in the ecosystem.

Every completed step, every verification result, every manual task — checkpoint it.

1. Never combine HIGH-risk migrations. Database change + auth swap + platform move

at the same time is how outages happen. Sequential, not simultaneous.

1. Web search the migration guide. Frameworks publish migration guides for major

versions. Read them before planning — the breaking changes are documented.

1. Inventory before transforming. For ecosystem migrations, count every affected

file before changing any of them. The file you forgot to update is the one that breaks trigger routing next Tuesday.