Overview
Migrations are exactly the class of change Cursor's agent mode is built for — mechanical, repetitive across dozens of files, and dangerous if you drift. This playbook uses a plan.md file to constrain the agent, a phased rollout across packages, and CI checks between each phase to make a monorepo migration boring instead of career-limiting.
How it works
- Author plan.md with target structure, rules, and the migration checklist.
- Point Cursor's Composer at plan.md and run one phase at a time.
- Between phases, run typecheck + tests + build.
- Commit each phase separately so any regression bisects cleanly.
- Use Cursor's rules file to lock in new conventions permanently.
Benefits
- Turns a 5-day painful migration into 1-2 focused sessions.
- Plan.md becomes the migration doc your team reviews.
- Each phase is a discrete PR — easy to revert or roll forward.
Use cases
- Yarn workspaces → pnpm + Turborepo (this guide).
- npm → bun with workspaces.
- Splitting a monolithic app into a monorepo.
Step-by-step guide
Step 1: Write plan.md
Target: root/packages/*, root/apps/*. Rules: no cross-package deep imports; every package needs a package.json 'exports' map; tsconfig references.
Step 2: Phase 1: root config
pnpm-workspace.yaml, turbo.json, root package.json scripts. Ask Composer to generate these against plan.md. Commit.
Step 3: Phase 2: convert workspaces
For each package, ask Composer to add exports maps and align tsconfig. Run pnpm install after each. Commit.
Step 4: Phase 3: fix imports
Composer scans for deep imports (packages/ui/src/x) and rewrites to package roots. Verify with a full typecheck.
Step 5: Phase 4: CI + caching
Update GitHub Actions to use pnpm cache and Turbo remote cache. Composer writes the workflow; you review before merge.
Step 6: Phase 5: cleanup
Delete yarn.lock, .yarnrc. Add .cursorrules to codify the new conventions so nothing drifts back.
Example
plan.md excerpt: '- Every package must define "exports" as { ".": "./src/index.ts" }.\n- Deep imports (packages/x/src/y) are forbidden; add a named export instead.\n- tsconfig.json uses references, not paths.'