Migrate a library

Use Polygraph to migrate your repos from one version of a library to a newer one.

Major upgrades are rarely mechanical: APIs move, defaults change, and the migration guide never covers your exact usage. And the same migration has to happen in every repo that uses the library, so the work is repetitive on top of being tricky.

Give the agent the library itself

Polygraph can add the library's public repo to the session, so the agent reads what actually changed between the versions instead of guessing from the changelog. See OSS repo integration.

Example prompt

I run polygraph session start and describe the migration:

Add every repo in my account that depends on vitest, and add
vitest-dev/vitest itself for context.

Migrate every repo from vitest 1.x to 2.x. Read the vitest repo first and
summarize the changes between the versions that affect us. Then propose a
per-repo plan before you change anything.

The agent reads the library's source, maps the breaking changes to how each of your repos actually uses it, and proposes a plan you can review before anything moves.

Fan out the migration

Apply the plan repo by repo. Run each repo's tests and report a per-repo
pass/fail. Open a draft PR for every repo that passes; for the rest, report
what's blocking.

Each repo is handled by its own child agent, so the migration proceeds in parallel and a failure in one repo never blocks the others. Repos that pass get a reviewable PR. Repos that don't come back with a concrete blocker instead of a half-applied upgrade.

Reuse the migration

The session becomes the record of how the migration was done. When another team migrates their repos, or the next major version lands, they search for and reference this session and apply the settled approach.