Turn a PRD into a plan and tasks in Cursor

The PRD workflow in Cursor turns a product requirements document into committed work: spec.md with numbered acceptance criteria, plan.md drafted in Plan Mode with a task list, and one commit per task with test evidence. Each task runs in a fresh chat that reads plan.md, so the work survives closed chats and stays checkable against the criteria.

Documentation freshness

Covers: the Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor’s release notes). Cursor’s help says Shift+Tab cycles through the agent modes (Agent, Ask, Plan and Debug), and Cursor’s agent overview says checkpoints are stored locally, separate from Git, and restoring one reverts files only (both checked 2026-10-12). Plan Mode and Bugbot were first verified against cursor.com on 28 August 2026. This page uses git for every rollback.

Your product manager posts a two-page PRD for a notification system: email and push, per-type preferences, delivery tracking. You ask Cursor’s agent to build it, and after an afternoon you have half an email service, a schema nobody agreed to, and no way to say which requirement each change serves. This page is for developers who have project rules in place and now face a feature too big for one chat, and for tech leads who want the plan reviewed before the code exists.

What you get from the PRD workflow in Cursor

• A prompt that reads the PRD for gaps and writes spec.md with numbered, testable acceptance criteria.
• A Plan Mode prompt that produces a task list in which every task names its files, its criteria, and the command that proves it.
• A per-task prompt that runs one task in a clean chat, so long conversations stop drifting away from the plan.
• A traceability check that proves each criterion has a test that can fail, which replaces reading the whole diff.
• A way to change the plan halfway through without losing the record of why.

When is a PRD worth its own workflow?

Use this page when the feature is too big to hold in one chat. For a feature you can describe in five acceptance criteria and finish in one sitting, the shorter loop in build your first AI-assisted feature is enough.

Signal	One-chat loop	PRD workflow
Acceptance criteria	Up to about five, written by you	More than you can hold in your head, or written by someone else
Sessions	One sitting	Several days, or several people
Plan lives in	The chat	plan.md, committed and reviewed
Who signs off the plan	You	You, plus the product owner for the criteria and a tech lead for higher-risk changes

The file names follow the site’s artifact chain: the PRD plays the role of intent.md, the acceptance criteria become spec.md, and the plan with its tasks becomes plan.md. You do not need the whole chain to use this page. You need the last two files.

Prepare the repository before you paste the PRD

1. Start from a clean tree on a feature branch, with one folder for the feature’s documents. In a terminal:

   git status --short                      # must print nothing
   git switch -c feat/notifications
   mkdir -p docs/features/notifications

2. Save the PRD as docs/features/notifications/prd.md. If the PRD lives in a GitHub issue, the agent can read it through the GitHub MCP server instead. Add it to ~/.cursor/mcp.json, the user-level file that you never commit, keep the token in an environment variable, and set it to read-only, because reading the PRD needs no write tools:

   {
     "mcpServers": {
       "github": {
         "url": "https://api.githubcopilot.com/mcp/",
         "headers": {
           "Authorization": "Bearer ${env:GITHUB_PAT}",
           "X-MCP-Toolsets": "context,repos,issues",
           "X-MCP-Readonly": "true"
         }
       }
     }
   }

   If your Cursor version does not expand ${env:GITHUB_PAT} (this page checked that interpolation only against a docs excerpt), paste the token instead and keep ~/.cursor/mcp.json out of any repository.

   The GitHub MCP server guide covers token scopes and read-only settings, and MCP setup in Cursor covers the other servers.

3. Confirm that tests, type checks, and lint each run from one command. This example uses npm test, npm run typecheck, and npm run lint. Every task in the plan ends with one of these commands, so a missing one blocks the whole workflow; see making a codebase agent-ready.

Phase 1: Turn the PRD into acceptance criteria

A PRD describes what the product owner wants. An agent needs statements it can test. The first prompt converts one into the other and lists what the PRD leaves open, instead of letting the agent guess. Run it in a new, normal agent chat rather than Plan Mode, so the agent writes spec.md directly.

Copy-paste prompt: read the PRD for gaps and write spec.md

Read @docs/features/notifications/prd.md. Do not write any code.

1. Ask me up to five clarifying questions about anything ambiguous or
   missing: failure behaviour, limits, permissions, data retention,
   and what is explicitly out of scope. Wait for my answers.
2. Then write docs/features/notifications/spec.md with these sections:
   - Acceptance criteria: numbered AC1, AC2, ... Each one is a single
     observable behaviour that an automated test can check.
   - Non-functional requirements, each with a number (latency, volume,
     retry limits).
   - Out of scope.
   - Open questions: anything I could not answer. Do not invent answers.
3. After each criterion, name the PRD section it comes from.
Create or edit no other file.

Read spec.md closely. It is the one document in this workflow that you read line by line, because every later check is measured against it. Look for three defects:

• Vague criteria. “Users manage preferences” cannot fail a test. “A user can turn email off for the comment type, and no email of that type is queued afterwards” can.
• Missing error paths. The PRD rarely says what happens when the email provider times out. Add a criterion for it or list it under Open questions.
• Criteria with no PRD source. The agent added a requirement nobody asked for. Delete it or get the product owner to accept it.

Send the product owner spec.md, not the chat. Their acceptance of the criteria is the first sign-off. Then commit it:

git add docs/features/notifications && git commit -m "docs: notifications spec (AC1-AC9)"

Writing acceptance criteria an agent cannot misread has the full method.

Phase 2: Draft the plan in Plan Mode

Start a new chat and switch the agent to Plan Mode (Shift+Tab cycles through the modes), which creates an implementation plan before it writes any code. A new chat matters: the Phase 1 conversation holds your answers as chat history, and spec.md holds them as a file. Plan from the file.

Copy-paste prompt: plan the feature against the spec

Plan the notification feature described in
@docs/features/notifications/spec.md. Do not write code yet.

Before planning, find how this codebase already handles database
migrations, background jobs, outbound HTTP calls, and configuration.
List the files you read.

The plan must contain:
- A task list with checkboxes. Each task fits in one reviewable commit.
- For each task: the files it creates or changes, the acceptance
  criteria it satisfies (AC numbers), the test that proves it, and the
  command that runs that test.
- The order of tasks, with each dependency stated ("T4 needs T2").
- Any new dependency, marked NEW DEPENDENCY with a reason. Prefer none.
- A final "Proof" section: the commands that must pass before the PR.

Every AC must appear in at least one task. If an AC cannot be planned
without answering an open question, stop and tell me which one.

Review the plan against this checklist before you accept it:

• Every criterion from spec.md maps to at least one task and one named test. A criterion with no task is a requirement that will not ship.
• Each task names its files. A task that says “update the relevant services” has no scope you can check with git diff --stat.
• The first task produces something testable on its own, such as a migration and its test, not a skeleton of every layer.
• New files follow patterns the agent says it read. A new queue library or a second HTTP client is a question to answer now, not after it is installed.

Correct the plan in the same chat (“Use the existing jobs/ runner, not a new queue”) until the checklist passes. A correction here costs one sentence. The same correction after three tasks costs a rewrite.

Save the plan where reviewers and later chats can read it

A plan that exists only in a chat, or only on your machine, is gone for the next session and invisible to the reviewer. Once you accept the plan, ask the agent to write the final version as docs/features/notifications/plan.md, next to spec.md, before you switch modes: switching starts a fresh context window (Cursor’s help, checked 2026-10-12), so a plan that lives only in the chat does not follow you. Then commit it. The committed file should look like this:

# Plan: notifications (spec: ./spec.md)

## Tasks
- [ ] T1 Migration: notification_preferences table.
      Files: db/migrations/0042_notification_prefs.sql, db/prefs.test.ts
      Covers: AC2 · Proof: npm test -- db/prefs.test.ts
- [ ] T2 Preferences API: GET/PUT /api/notification-preferences.
      Files: src/api/preferences.ts, src/api/preferences.test.ts
      Covers: AC1, AC2 · Needs: T1 · Proof: npm test -- src/api/preferences.test.ts

## Proof
npm test && npm run typecheck && npm run lint

For a higher-risk feature, open a draft pull request that contains only spec.md and plan.md and ask a tech lead to review it. A reviewer who accepts the plan before the code exists reviews against an agreed list later, not against their own guess of what you meant.

Phase 3: Build one task per chat

Run the tasks in order, outside Plan Mode. Each task gets a new chat that starts from plan.md, so the agent works from the agreed plan instead of the tail of a long conversation.

Copy-paste prompt: run the next task from plan.md

Read @docs/features/notifications/plan.md and
@docs/features/notifications/spec.md.
Implement the first unchecked task only. Change only the files that
task lists. If you need another file, a new dependency, or a different
design, stop and explain why instead of doing it.

Write or update the test the task names, then run its Proof command
and show me the output. If a test fails twice for the same reason,
stop and tell me what you observed.
When the Proof command passes, tick that task's checkbox in plan.md.
Do not start the next task.

After each task, check the scope and commit before the next chat:

git diff --stat                    # only the files the task lists, plus plan.md
git add -A && git commit -m "feat(notifications): T2 preferences API (AC1, AC2)"

The commit is your restore point. If the agent strays, run git restore . and git clean -fd to return to it, then repeat the prompt with the file list spelled out. When tasks do not share files, you can run them in parallel on separate worktrees. Do that only after the one-task loop feels routine.

Prove the feature meets the spec without reading every line

Passing tests the agent wrote prove only that the code agrees with those tests. Before you open the pull request, make the agent show that each criterion has a test that fails when the behaviour breaks.

Copy-paste prompt: audit criterion-to-test coverage

Using @docs/features/notifications/spec.md and the commits on this
branch, build a table: AC number | test file and test name | task.

Then, for each AC, one at a time:
1. Break the implementation in the smallest way that violates it.
2. Run the named test and confirm it fails.
3. Restore the implementation exactly and confirm the suite passes.

Do not edit any test file during this task. Add a column
"failed when broken" (yes/no). List any AC with no test, and any test
that maps to no AC. Finish with `git status --short`, which must be empty.

A no in that column is a real finding: the criterion has no test that can fail. Ask for one and rerun the audit. Then collect the rest of the evidence yourself:

1. Run the plan’s Proof section in a terminal and confirm it passes on a clean checkout:

   npm test && npm run typecheck && npm run lint

2. Compare the scope with the plan. Every file in this list should appear in some task:

   git diff --stat main...HEAD

3. Check that no test was weakened on the way:

   git diff main...HEAD -- '*.test.ts' | grep -E '^-.*expect\(|^\+.*\.(skip|only)\('

   An empty result is what you want. Protect the test oracle shows how to enforce this in CI instead of by hand.

4. Open the pull request with spec.md, plan.md, and the coverage table linked in the description. If your team runs Bugbot, it reviews the pull request for bugs, security issues, and code quality problems; treat its findings as input for the reviewer, not as the gate.

Who signs off: the product owner accepted the criteria in Phase 1, and the reviewer accepts three things now: every criterion has a test that failed when broken, the scope matches the plan, and the gates pass. Code reading is kept for what the evidence cannot cover, such as authorisation checks on the preferences API. Reading evidence instead of diffs explains where that line sits.

Change the plan when the PRD changes mid-build

Product owners change their minds after T3. Do not patch the code first. Change the spec, then the plan, then the code, so the record stays true.

Copy-paste prompt: apply a requirement change to spec and plan

The product owner changed a requirement: push notifications are out
of scope for this release; email only.

1. Update @docs/features/notifications/spec.md: move the affected
   ACs to Out of scope and note the date and reason.
2. Update @docs/features/notifications/plan.md: list every task,
   done or not, that the change affects, and say for each one whether
   to remove it, change it, or add a follow-up task to undo work already
   committed.
Show me both diffs. Do not change any code until I approve them.

Commit the spec and plan change on its own, with the reason in the message. Then continue with the per-task prompt. A reviewer can now see why T5 disappeared, which a code diff alone never shows. For a longer treatment of keeping the spec authoritative, see spec-driven development.

What breaks in the PRD workflow, and how to recover

Symptom	Likely cause	Recovery
The plan is generic: “set up the service layer”, “add tests”	spec.md has vague criteria, or the plan prompt did not demand files and proof per task	Tighten the criteria in spec.md, then rerun the plan prompt in a new chat
The agent works on two tasks at once	The prompt did not say “first unchecked task only”, or the chat is long	git restore . to the last commit, open a new chat, and use the per-task prompt as written
The plan invents a queue, client, or table you already have	The agent did not read your code, or your rules do not state the convention	Ask it to list the files it read; correct the plan; add the convention to a project rule
Checkboxes in plan.md say done, but the Proof command fails	The agent ticked the box before the test passed	Untick it, run the Proof command yourself, and treat only your own terminal output as evidence
An open question gets answered in code	Nobody put the answer in spec.md	Stop, record the answer in spec.md with the product owner, and check the affected task against it
The agent loops on one failing test	Failed attempts in the chat pull the next attempt toward them	Reset to the last commit and start a new chat with your own diagnosis; see error recovery in Cursor

Where to go next with PRD-driven work in Cursor

MCP setup in Cursor Connect the agent to your issue tracker, database, and browser so it reads the PRD and checks its own work.

The artifact chain The full sequence from intent to production, with templates and a named owner for every file.

Build your first AI-assisted feature The one-chat version of this loop, for features small enough to finish in one sitting.

The evidence bundle Package the coverage table, scope, and gate results into one manifest a reviewer can sign off.

Using another agent as well? The same PRD-to-plan workflow in the terminal is on the Claude Code PRD workflow page, and Codex’s version of the plan-then-build loop is in your first Codex task. The team-level procedure for each file is on the Design and Build stage pages.