Cursor 3.2: subagents, worktrees, multi-root

The release was due Friday and the failing test sat in a worktree nobody owned. We had upgraded to Cursor 3.2 that same week, which is how three checkouts ended up holding three versions of one intent. Cursor 3.2 is a workflow migration disguised as a version bump: subagents, worktrees, and multi-root workspaces arrive together, and each one is a new place for intent to disappear. The upgrade takes a minute. Migrating your review habits is the part that hurts.

The migration nobody scopes

Counter-thesis: The decision is not whether Cursor can run more work at once; it is whether your repo can explain that work after it lands.

The wrong path: We believed more parallel lanes meant faster delivery, so we split every branch across worktrees and let the agents run. Waiting time fell. Explaining time exploded.

Diagnosis: Brooks's law was waiting for us. Adding workers to late work makes it later because coordination cost grows faster than capacity, and a subagent is a worker with perfect typing speed and zero shared context.

Thesis: Parallelize only what can be owned separately, and give every worktree an owner, a boundary, and a replay command.

What to split and what to keep serial

Split by ownership, not by impatience. Frontend copy, test expansion, docs, and isolated refactors parallelize well; payment flows, auth boundaries, and data migrations need one controlling hand until the plan is stable, because one decision there changes the contract for every other path.

Keep this table in the PR description for the first few runs. Once the pattern is stable, move it into a repo rule via Cursor Rules.

Three fixes that survive contact with Friday

Worktrees multiply faster than owners. Each checkout feels free until two of them edit the same module differently.

Named fix: the migration ledger. Plain markdown on purpose, so it works in a PR body, in AGENTS.md, or in a planning issue:

# Cursor 3.2 migration ledger

- Parent goal: split checkout smoke tests from checkout copy cleanup.
- Worktree A owner: frontend engineer
- Worktree A paths: `apps/site/src/app/checkout/**`
- Worktree A proof: `pnpm test checkout-copy`
- Worktree B owner: QA engineer
- Worktree B paths: `tests/checkout/**`
- Worktree B proof: `pnpm test checkout`
- Shared forbidden paths: `apps/site/src/lib/payments/**`, `infra/**`
- Merge rule: no worktree merges until both proof commands are pasted in the PR.

That ledger is the difference between parallel work and parallel confusion: a reviewer can audit the diff without replaying any chat.

Every root claims authority. Multi-root workspaces help when a change spans app code, tests, and docs; they hurt when rules differ between roots and each root believes it is in charge.

Named fix: the decision root. Pick one root where the rule file, the migration ledger, and the final review notes live. Other roots carry evidence, never competing instructions.

False green. Each worktree passes locally and the merged branch still fails, because nobody tested the union.

Named fix: the merged-branch proof. One command on the merged branch, pasted in the PR, closes the gap the local greens left open.

Where the docs end and the contract begins

The product surfaces are documented under Cursor Agent and Cursor Skills; connector behavior sits in Cursor MCP on top of the Model Context Protocol specification, and the changelog is where defaults quietly change. The docs explain the surfaces; the team still writes the operating contract. In our methodology terms, Plan defines the split, Build runs the agents, and Review checks whether the ledger still matches the diff. The single-branch version of this discipline is the scope ledger in Cursor subagents and skills for engineering teams, and the broader patterns live in the subagents and skills topic hub.

Synthesis: A worktree without an owner is a rental car without a named driver: easy to grab, and nobody's problem until it comes back dented.

Best ways to use this research

• Best for: Cursor teams deciding which rule, subagent, skill, or MCP boundary to standardize next after a Cursor 3.2 upgrade.
• Best first artifact: turn the migration ledger into a .mdc rule, AGENTS.md note, or review checklist before the next parallel run.
• Best comparison angle: compare the workflow against the current Cursor review path, connector scope, and team rule file; keep the path that leaves the shortest auditable trail.

Common questions

• What does Cursor 3.2 change for engineering teams?

  Cursor 3.2 makes parallel agent work normal: subagents, worktrees, and multi-root workspaces arrive together. Treat it as a workflow migration rather than a feature toggle, because each surface is a new place for intent to disappear unless every worktree carries an owner, a path boundary, and a replay command.

• When should a subagent get its own worktree?

  Give a subagent its own worktree when the work splits by ownership: test expansion, copy and docs, or a path-bounded refactor. Keep API contract changes mostly serial, and keep auth, billing, and data-loss paths out of parallel runs by default; those need one controlling hand until the plan is stable.

• How do you review a multi-root workspace?

  Name one decision root and review from there. That root holds the rule file, the migration ledger, and the final review notes; other roots contain evidence but never competing instructions. Without a decision root, rules differ between roots and reviewers cannot tell which guidance the agent actually followed.

• Why does parallel agent work fail in review?

  Because coordination cost grows faster than capacity: each worktree passes locally, the merged branch fails, and the PR body summarizes results instead of scope. The corrections are mechanical: mutex paths, a pasted migration ledger, and one merged-branch proof command before anything merges.

Next move

Run one Cursor 3.2 migration with the ledger above; if the reviewer cannot explain each worktree in two minutes, the split is still too vague. If you want a second pair of eyes on the rollout, talk to us.