oc-migration-ops

# 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.

| Type | Examples | Risk | Key Concern |
|---|---|---|---|
| **Database** | D1 → Postgres, schema overhaul, ORM swap | HIGH | Data integrity, zero data loss |
| **Framework** | Hono v3→v4, React 18→19, Next.js pages→app router | MEDIUM | Breaking API changes, dependency conflicts |
| **Auth** | Passkeys → Supabase Auth, Auth0 → Clerk, session → JWT | HIGH | Auth gap = security gap, user lockout |
| **Platform** | Workers → Vercel, Supabase → raw Postgres, Heroku → Fly.io | HIGH | DNS cutover, cold start behavior, binding changes |
| **Structural** | Monorepo restructure, module extraction, package split | MEDIUM | Import path breakage, CI pipeline updates |
| **Dependency** | Major version bumps, library swap (Axios → fetch, Moment → date-fns) | LOW-MED | API surface changes, bundle impact |
| **Ecosystem** | Opchain skill format changes, checkpoint protocol upgrades, oc-orchestrator rewrites, bulk SKILL.md updates | LOW-MED | Consistency across N skills, no skill left behind |

### Auto-Detection

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

- "Move from D1 to Postgres" → 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 using `ask_user_input`.

---

## 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 aidops-core apps, also read `wrangler.toml` for bindings (D1, KV, secrets),
   routes, and compatibility dates.
2. **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.
3. **App-architect checkpoint** — read spec files (01-tech-stack.md, 02-architecture.md)
   for the documented architecture.
4. **Stack-forge checkpoint** — read stack decisions for current platform/framework choices.
5. **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"
- **Succ