/output-migrate

name: output-migrate
description: Upgrade a project between versions of the Output framework. Use when the user asks to upgrade, migrate, or move to a newer Output version. Detects the current @outputai/* version in the project, fetches the matching migration guide from docs.output.ai, applies the changes, and verifies the project still type-checks.
allowed-tools: [Bash, Read, Write, Edit, MultiEdit, Grep, WebFetch, TodoWrite]

Migrate an Output Project

Overview

This skill migrates a project from one version of the Output framework to another.

You do not carry migration instructions in your own context. The docs site at `https://docs.output.ai/migrations` is the source of truth — fetch the right page and follow it.

Use the todo tool to track your progress.

When to Use This Skill

• The user wants to upgrade `@outputai/*` packages to a newer version
• The user mentions "migrate", "upgrade", or "move to vX.Y.Z"
• A breaking-change release shipped and the user is still on an older version

URL contract

Migration guides are hand-authored MDX pages linked from a single index:

• Index: `https://docs.output.ai/migrations`
• Per-boundary guide: `https://docs.output.ai/migrations/v{FROM_FULL}-to-v{TO_FULL}` (e.g. `v0.1.12-to-v0.2.0`)

The index lists every available guide with a title and a short description. A release only has a guide if it introduced breaking changes — most releases will not have one.

If the user is jumping multiple boundaries, fetch each applicable guide in order and apply them sequentially.

Instructions

<process_flow>

<step number="0" name="arguments_analysis">

Step 0: Arguments Analysis

If the user passed arguments when invoking this skill, parse them as positional values in this order (all optional):

• `from-version`: The version the project is currently on. If blank, detect it in Step 2.
• `to-version`: The target version. If blank, resolve it in Step 1.
• `additional-instructions`: Free-form guidance from the user (e.g. "skip the http changes, we don't use that package").

</step>

<step number="1" name="detect_to_version">

Step 1: Determine the target (TO) version

If the user provided a `to-version` argument, use it.

Otherwise, run `npm view @outputai/core version` via Bash and use that as the target.

</step>

<step number="2" name="detect_from_version">

Step 2: Detect the current (FROM) version

If the user provided a `from-version` argument, use it and skip the rest of this step.

Otherwise, read `package.json` at the project root and resolve the current framework version from the first entry that exists, in this order: 1. `dependencies["@outputai/core"]` 2. `devDependencies["@outputai/core"]` 3. `dependencies["@outputai/cli"]`

Strip any leading `^` or `~`. If no `@outputai/*` package is present, stop and tell the user: "This project doesn't depend on any @outputai/* packages — nothing to migrate."

**If the version read from `package.json` equals the TO version**, the user may have already edited `package.json` to the new version without running the migration yet. Don't give up — find the pre-bump version by looking in this order:

1. Run `git diff package.json pnpm-lock.yaml package-lock.json yarn.lock 2>/dev/null` and scan the diff for an `@outputai/*` version that was removed (lines starting with `-`). If you find one, that's the FROM version. 2. Run `git log -p -n 20 -- package.json` and find the most recent commit that changed an `@outputai/*` version. The old value on that commit's parent side is the FROM version. 3. If neither locates a prior version, tell the user: "Cannot detect the FROM version — both `package.json` and git history show `vX.Y.Z`. Re-run with `--from <version>` to specify it explicitly."

If FROM and TO still resolve to the same version after this recovery, stop and tell the user: "Already on `vX.Y.Z` — nothing to migrate."

</step>

<step number="3" name="fetch_migration_guide">

Step 3: Fetch migration guides

WebFetch `https://docs.output.ai/migrations`. This is the index page — it links to every hand-authored migration guide with a title keyed on the version boundary.

From the index, identify every guide whose `v{FROM}-to-v{TO}` range falls between the user's FROM and TO versions. Examples:

• User FROM `0.1.12`, TO `0.2.0` → if a `v0.1.12-to-v0.2.0` guide is listed, fetch it.
• User FROM `0.1.12`, TO `0.3.0` → fetch `v0.1.12-to-v0.2.0` first, then (if listed) `v0.2.0-to-v0.3.0`.
• Multiple patch-level guides between the same minor boundaries should all be applied in chronological order.

Fetch each applicable guide by hitting `https://docs.output.ai/migrations/v{FROM_FULL}-to-v{TO_FULL}`.

If the index lists no guides covering the FROM → TO range, stop and tell the user: "No migration guides found for `vFROM` → `vTO`. The releases in this range were additive; just bump your dependencies."

Also WebFetch `https://docs.output.ai/changelog` to cross-reference what shipped in the range — use it to fill in gaps the migration guides may not cover.

</step>

<step number="4" name="plan_changes">

Step 4: Plan the changes

From the fetched guide(s), produce a TodoWrite list of concrete changes, one todo per change. Do not start editing yet.

For each todo, capture:

• Which file(s) are affected (use Grep to find call sites for deprecated APIs the guide mentions).
• What the change is (diff-shaped if possible).
• Which guide section it came from.

If the user passed `additional-instructions`, honor them: skip todos they asked to skip, add todos they asked to add.

Print the plan and ask the user to confirm before proceeding. If they reject, stop.

</step>

<step number="5" name="apply_changes">

Step 5: Apply the changes

Work through each todo. For every todo: 1. Mark it `in_progress` before starting. 2. Apply the change with Edit/MultiEdit. 3. Mark it `completed` when done.

Do not batch completions — update TodoWrite after each one.

</step>

<s