Migrate away from a deprecated library

Library migrations are the perfect work for AI agents. They are mechanical, well-defined, and tedious - exactly the combination that burns out humans and produces inconsistent results. This guide walks you through the full playbook for migrating a deprecated library off a real codebase using Sprint Chains. Expect this to run over several days. That is normal and good.

1. Map the migration before you start

Before involving an agent, write the migration in human-readable form. Specifically, you need a one-page document that lists every source API and its target equivalent, edge cases that need manual handling, and a smoke test for each migrated module.

This document becomes the source of truth for every agent run. Without it, the agent will improvise - and improvisation across 200 files is how you ship subtle behavioural regressions.

2. Discover the surface area

Run a single discovery Issue Session with a Researcher persona pointed at the codebase. Its job is read-only: emit a structured report of every file that imports the deprecated library, grouped by how the library is used.

task: Survey usage of `legacy-http` across this monorepo.
output:
  - Group files by usage pattern (basic GET, streaming, auth-wrapped, etc.).
  - For each pattern, count occurrences and list a representative file.
  - Flag any unusual or one-off usage.

Save this report. It is the input to your Sprint Chain.

3. Build a migration persona

Clone the Senior Engineer template and write a persona whose entire job is this one migration. The system prompt embeds your mapping document verbatim. Bind it to a Coder toolset with pnpm test available so it can validate as it goes.

Set a tight Judge: every PR must match the mapping document exactly; deviations are rejected. Mechanical work demands mechanical review.

4. Compose the Sprint Chain

A Sprint Chain runs a sequence of Issue Sessions in order, optionally in parallel, sharing context across runs. For this migration you want one session per usage pattern from the discovery report. Group small files into one session; isolate complex usage into its own.

• Session 1: migrate basic GET usage across all files in that group. Single PR.
• Session 2: migrate streaming usage. Single PR.
• Session 3: migrate auth-wrapped usage. Single PR.
• Session N: handle the long tail one-by-one.

One PR per pattern. Not one PR per file, not one PR for the whole migration. Pattern-sized PRs are reviewable; the other sizes are not.

5. Run the chain on the smallest repo first

Find your smallest repo and run the full chain there. Treat it as a rehearsal. Watch every PR, merge or revise each one yourself, and only declare the chain ready when the smallest repo is fully migrated and CI is green on main.

Most teams discover one or two edge cases here. Update the mapping document, re-run the affected sessions, and only then move to the next repo.

6. Fan out to the rest of the fleet

Once the chain is stable, run it across remaining repos in parallel - CodeCourier handles the concurrency, your CI handles the load. You will get a wave of pull requests. Review them in batches grouped by repo, not by chronological order; reviewing by repo keeps your mental model of each codebase intact.

7. Track the deprecation deadline

Add a recurring task that runs a grep for the deprecated library every Monday morning and emits a count by repo. When the count reaches zero across the fleet, archive the persona and the chain with a clear filename like legacy-http-deprecation-2026-q2-complete. Migrations are only done when you have proof they are done.

8. Next steps

Operate CodeCourier in production is the natural next read - the operations handbook covers RBAC, budgets, and alerting that matter when you are running multi-day chains unattended.