Upgrade & Migration Engineer

What it does

Upgrade & Migration Engineer is a Cursor agent playbook named migration-engineer. AgenticKit installs it so a session can adopt this role instead of acting as a generic coding assistant.

The migration-engineer agent upgrades the stack without mixing in features. It reads upstream changelogs, bumps lockfiles, fixes breaking APIs, and keeps the test suite green. tech-lead plans new work; this role keeps the floor from rotting.

Bumps Next, React, Node, ORMs. Tests stay green. Plans and executes dependency upgrades and stack migrations with a changelog read, breaking-API fixes, and a rollback note.

Why it exists

A pile of agent files is not a team. migration-engineer exists so one job, upgrade & migration engineer, has a written brief, required skills, and a stop condition.

It ships in the Engineering Kit. Skills it must read: Dependency & Framework Upgrades; Vitest Unit & Integration Testing; Strict TypeScript Standards & Type Safety. Commands that adopt this role: /upgrade: Dependency and Framework Upgrade; /ci-pipeline: GitHub Actions CI/CD Pipeline Generator; /fix: Automated Bug & Exception Debugger.

When to use it

• Next 15 to 16 without a weekend fire
• Prisma to Drizzle with data intact
• Node LTS bump that broke CI

When not to use it

• Do not ask migration-engineer to do a different role's job. If you need a launch post, switch agents.
• Do not keep the same chat after this agent has finished its artifact. Start a reviewer in a new thread.
• Do not invoke every agent in the kit for a small change.

Example workflow

1. Install the Engineering Kit so .cursor/agents/migration-engineer is on disk.
2. Run /upgrade: Dependency and Framework Upgrade, or start a chat and tell Cursor to adopt the migration-engineer role.
3. The agent should read: Dependency & Framework Upgrades; Vitest Unit & Integration Testing; Strict TypeScript Standards & Type Safety.
4. It produces the artifact for this role only, then stops.
5. A different agent or you review. Same-chat self-review is not a review.

Example usage

Example: "You are migration-engineer. Next 15 to 16 without a weekend fire. Read dependency-upgrades before you edit."

Or let the pipeline invoke it: /upgrade: Dependency and Framework Upgrade.

Capabilities you should actually see: Major/minor dependency bumps with lockfile discipline

Example output

• migration-engineer should leave files or a written verdict, not a vibe check. Major/minor dependency bumps with lockfile discipline Framework migrations (Pages → App Router, ORM swaps)
• Engineering agents should touch the slice they were given (schema, route, test, or review note) and nothing else.

Best practices

• Major/minor dependency bumps with lockfile discipline
• Framework migrations (Pages → App Router, ORM swaps)
• Rollback notes and skip flags
• CI green as the done definition
• One role per chat unless a command is explicitly orchestrating a sequence.

Common mistakes

• Using migration-engineer as a synonym for 'the Cursor agent'. It is a brief, not the product.
• Skipping the required skills and hoping the role name is enough.
• Letting the writer approve its own PR.
• Invoking this agent and three unrelated ones in the same prompt.