Output Migrate

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/output"]
4. 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">