Kit Preamble — 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(bash scripts/kit_update_check.py ), Bash(python3 scripts/), Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm *), Bash(uv *), Bash(pip *), Bash(docker *)

Kit Preamble — migrate

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

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.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

Checkpoint Rules — MANDATORY

Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. If the exit code is not 0, STOP immediately and report the failure. Do NOT proceed to the next phase.

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:

   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 — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill migrate --phase worktree --issue "$SLUG" If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

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 — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill migrate --phase push --issue "$SLUG" If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

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.
• 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.
• Document every breaking change encountered and how it was resolved in the GH Issue body.