{
  "$schema": "https://promptfoo.tech/schemas/workflow-template.json",
  "name": "Cursor Agent: Monorepo Migration Playbook",
  "slug": "cursor-agent-monorepo-migration",
  "platform": "Cursor",
  "category": "coding",
  "difficulty": "Advanced",
  "tags": [
    "cursor",
    "coding",
    "monorepo",
    "refactor"
  ],
  "summary": "Move a multi-package repo from Yarn workspaces to pnpm + Turborepo using Cursor's Composer agent with plan-file guardrails.",
  "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.",
  "variables": {},
  "steps": [
    {
      "order": 1,
      "name": "Write plan.md",
      "description": "Target: root/packages/*, root/apps/*. Rules: no cross-package deep imports; every package needs a package.json 'exports' map; tsconfig references."
    },
    {
      "order": 2,
      "name": "Phase 1: root config",
      "description": "pnpm-workspace.yaml, turbo.json, root package.json scripts. Ask Composer to generate these against plan.md. Commit."
    },
    {
      "order": 3,
      "name": "Phase 2: convert workspaces",
      "description": "For each package, ask Composer to add exports maps and align tsconfig. Run pnpm install after each. Commit."
    },
    {
      "order": 4,
      "name": "Phase 3: fix imports",
      "description": "Composer scans for deep imports (packages/ui/src/x) and rewrites to package roots. Verify with a full typecheck."
    },
    {
      "order": 5,
      "name": "Phase 4: CI + caching",
      "description": "Update GitHub Actions to use pnpm cache and Turbo remote cache. Composer writes the workflow; you review before merge."
    },
    {
      "order": 6,
      "name": "Phase 5: cleanup",
      "description": "Delete yarn.lock, .yarnrc. Add .cursorrules to codify the new conventions so nothing drifts back."
    }
  ],
  "howItWorks": [
    "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."
  ],
  "useCases": [
    "Yarn workspaces → pnpm + Turborepo (this guide).",
    "npm → bun with workspaces.",
    "Splitting a monolithic app into a monorepo."
  ],
  "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": [
    {
      "q": "Why plan.md?",
      "a": "Agents drift without a north star document. plan.md is that document — and it survives as your migration record."
    },
    {
      "q": "Which model?",
      "a": "Sonnet 4 or Opus 4 for the refactor phases. Autocomplete's default model handles the mechanical rewrites."
    },
    {
      "q": "Can I do this without Cursor?",
      "a": "Yes — with any capable agentic editor. The plan-file discipline matters more than the tool."
    }
  ],
  "source": "https://promptfoo.tech/workflows/cursor-agent-monorepo-migration",
  "updated": "2026-06-25",
  "license": "CC-BY-4.0"
}