Migrate

---
name: migrate
description: Plan and execute a migration, then create a GH Issue + PR.
argument-hint: '[migration target, e.g. "Django 5.0" or "Python 3.12"]'
disable-model-invocation: false
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_setup.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(python3 scripts/*), Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm *), Bash(uv *), Bash(pip *), Bash(docker *), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*)
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — migrate

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.
## Checkpoint Rules — MANDATORY
Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. Blocking gates exit non-zero on failure: STOP immediately, report, do NOT proceed. Advisory gates always exit 0 and print an `ADVISORY:` line on failure: report the gap, self-correct, then continue (ISSUE-031). Never skip running either tier.

**Slug convention**: After creating the worktree, store the branch slug (e.g., `migrate/django-5.0`) for use in checkpoint commands.

## Argument Validation (run before anything else)
1) If `$ARGUMENTS` is empty or blank, ask the user: "Please specify the migration target (e.g., 'Django 5.0', 'Python 3.12', 'PostgreSQL 16')."
2) Do NOT proceed until the user provides a migration target.

Steps:
1) Ensure `gh` authenticated (`gh auth status`).
2) Identify the migration target from $ARGUMENTS (library version, DB schema, runtime, etc.).
3) Read the current project configuration (pyproject.toml, requirements, Dockerfile, etc.).
4) Scan the codebase for affected files, deprecated APIs, and breaking changes.
5) Generate a step-by-step migration plan with rollback instructions.
6) Present the plan to the user for approval.
7) Create worktree + auto-freeze in one step:
   ```bash
   WT="$(bash scripts/wt_setup.sh migrate/<slug>)"
   ```
   `wt_setup.sh` creates the worktree and writes the freeze marker inside
   `.claude-kit/freeze-dir.txt` atomically. All subsequent file operations
   happen inside `$WT/`.

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill migrate --phase worktree --issue "$SLUG"`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

8) Execute changes incrementally inside `$WT/`, running tests after each step.
9) Run the full test suite to confirm no regressions.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill migrate --phase test --issue "$SLUG"`
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

10) Update relevant documentation (README, CHANGELOG, architecture notes) inside `$WT/`.
11) Create GH Issue:
    - `gh issue create --title "migrate: <target description>" --body "<body>"`
    - Body must include: migration scope, affected files/APIs, step-by-step plan, and rollback instructions.
12) Commit + push (from `$WT/`).

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill migrate --phase push --issue "$SLUG"`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

13) Create PR:
    - `gh pr create --title "migrate: <target description>" --body "Closes #<issue_number>\n\n<details>"`
14) Report the PR URL to the user — continue with `/review` and `/ship`.

## Error Handling
- If `gh auth status` fails: stop and instruct the user to run `gh auth login`.
- If the migration target is ambiguous: ask the user to clarify the exact version or scope.
- If tests fail after a step: stop, report the failure, and suggest a rollback or fix. Do NOT push or create PR.

## Rollback
- Use `bash scripts/wt_cleanup.sh <branch>` for safe worktree removal —
  the wrapper cd's to main root and removes the worktree in a single subshell.
- If failure occurs after worktree creation but before PR:
  1. `bash scripts/wt_cleanup.sh <branch>`
  2. `git push origin --delete <branch>` (remote cleanup, if pushed)
- If failure occurs after PR creation: `gh pr close <pr_number>` then clean up worktree and branch as above.

## Shared Registry Files
**IMPORTANT**: Never commit `issues.md`, `STATUS.md`, or `CHANGELOG.md` to the feature branch.
These are registry files managed only on main. Always use `bash scripts/registry_edit.sh <file> -- bash -c '<update command>'` — the wrapper resolves the main repo root internally.

## Guidelines
- Always create a rollback plan before making changes — per step, not just for the migration overall.
- Apply changes in small, reversible increments: dependency bump → fix breaking changes → update config → update tests.
- Read the official changelog and migration guide BEFORE writing any code.
- One major version bump per PR — do not bundle multiple major upgrades.
- Verify breaking changes explicitly — never assume backward compatibility. Document every breaking change encountered and how it was resolved in the GH Issue body.
- Clean up deprecated API usage encountered during the migration, or file follow-up issues for it — do not leave it silently in place.