# Cursor Agent: Monorepo Migration Playbook

> Move a multi-package repo from Yarn workspaces to pnpm + Turborepo using Cursor's Composer agent with plan-file guardrails.

**Platform:** Cursor  
**Category:** coding  
**Difficulty:** Advanced  
**Tags:** cursor, coding, monorepo, refactor  
**Updated:** 2026-06-25  
**Source:** https://promptfoo.tech/workflows/cursor-agent-monorepo-migration

## 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
1. Author plan.md with target structure, rules, and the migration checklist.
2. Point Cursor's Composer at plan.md and run one phase at a time.
3. Between phases, run typecheck + tests + build.
4. Commit each phase separately so any regression bisects cleanly.
5. 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
### 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.'
```

## FAQs
**Why plan.md?**

Agents drift without a north star document. plan.md is that document — and it survives as your migration record.

**Which model?**

Sonnet 4 or Opus 4 for the refactor phases. Autocomplete's default model handles the mechanical rewrites.

**Can I do this without Cursor?**

Yes — with any capable agentic editor. The plan-file discipline matters more than the tool.

---
Licensed under CC-BY-4.0. Attribution: PromptFoo.tech