{
  "$schema": "https://promptfoo.tech/schemas/workflow-template.json",
  "name": "Cursor: Plan-File API Refactor Playbook",
  "slug": "cursor-plan-file-api-refactor",
  "platform": "Cursor",
  "category": "coding",
  "difficulty": "Advanced",
  "tags": [
    "cursor",
    "refactor",
    "typescript",
    "coding"
  ],
  "summary": "Extract a monolithic Express app into route modules and typed services using Cursor's Composer with an explicit plan.md contract.",
  "overview": "A 3,000-line index.js is not a codebase, it's a hostage situation. This playbook uses Cursor's Composer with a plan.md file to extract routes into modules, introduce a services layer, and add zod-validated request schemas — while running tests between each phase.",
  "variables": {},
  "steps": [
    {
      "order": 1,
      "name": "Write plan.md",
      "description": "Target: src/routes/{group}/index.ts, src/services/{name}.ts. Every route validates input with zod. No inline SQL."
    },
    {
      "order": 2,
      "name": "Phase 1: skeleton",
      "description": "Create empty folders/files. Composer generates the barrel exports and app.ts wiring. Commit."
    },
    {
      "order": 3,
      "name": "Phase 2: extract routes group by group",
      "description": "Auth first (highest risk). Move handlers into the new file, keep tests green, delete the old code. Commit per group."
    },
    {
      "order": 4,
      "name": "Phase 3: services layer",
      "description": "Extract business logic into src/services. Route handlers become 5-10 lines: validate → call service → shape response."
    },
    {
      "order": 5,
      "name": "Phase 4: zod validation",
      "description": "Add request schemas per route. Fail fast on invalid input. Update tests to expect 400s for missing fields."
    },
    {
      "order": 6,
      "name": "Phase 5: enforce with lint",
      "description": "ESLint rule to ban route files > 80 lines and services with unvalidated input. Locks in the pattern."
    }
  ],
  "howItWorks": [
    "Author plan.md with target file structure, naming rules, and validation contract.",
    "Composer processes one route group per phase (auth, users, orders, admin).",
    "Between phases: typecheck + integration tests must pass before continuing.",
    "Each phase becomes a commit; the plan file is the north star and doc."
  ],
  "benefits": [
    "Refactors ship in days, not months.",
    "Plan.md is the review artifact reviewers actually engage with.",
    "Type safety introduced without stopping the world."
  ],
  "useCases": [
    "Legacy Express/Koa APIs with growing complexity.",
    "Consolidating microservices back into a modular monolith.",
    "Preparing a codebase for a new team to inherit."
  ],
  "example": "plan.md rule: 'Every route file must export default a router. Handlers must be < 15 lines and call at most one service method.'",
  "faqs": [
    {
      "q": "How long?",
      "a": "1-2 days for a 3-5K LOC monolith with tests. Longer if tests are thin (add them first)."
    },
    {
      "q": "Framework agnostic?",
      "a": "Same plan structure works for Fastify, Hono, or NestJS. Only the wiring differs."
    },
    {
      "q": "Which model?",
      "a": "Sonnet 4 for all phases. Opus for edge cases where the model gets stuck."
    }
  ],
  "source": "https://promptfoo.tech/workflows/cursor-plan-file-api-refactor",
  "updated": "2026-06-04",
  "license": "CC-BY-4.0"
}