Cursor rule

1---
2description: "Cursor 3.7 orchestration guide: when to plan, when to delegate, nested subagents, multi-environment handoffs, /best-of-n, and Await for long-running branches."
3alwaysApply: false
4---
5 
6# Cursor 3.7 Agent Orchestration
7 
8Current through **Cursor 3.7** (Jun 2026). Use this rule for deep or exhaustive tasks where coordination matters more than raw implementation speed.
9 
10## Core Idea
11 
12The main agent should own synthesis. Plans, subagents, and task tracking exist to reduce context load and make large work safer. On M3, the main agent also owns the 1M-context loader — see `minimax-m3-long-context`.
13 
14## Local, worktree, cloud, and SSH sessions
15 
16Cursor 3.7 emphasizes moving work between execution environments inside the Agents Window. Treat this as workflow guidance, not a requirement:
17 
18- Prefer **local** when you need fast edit–run–debug loops, full filesystem access, or machine-specific verification.
19- Prefer **/worktree** (isolated git worktree) when the task must not collide with the main tree, when you are running parallel branches, or when you want a disposable environment.
20- Consider **cloud** when a task should keep running while you are away, or when you want continuation without tying up the local machine — then **hand back to local** to validate on the real environment when claims are environment-specific.
21- Consider **SSH** when the runtime is on a remote host (e.g. an edge box, a build farm, a server) and the work needs direct access.
22 
23Handoffs should still use explicit goals, owned paths, environment, model, and what was verified (see `agent-teams.mdc`).
24 
25## Parallel sessions and the sidebar
26 
27Cursor 3.7 can show **many agent sessions** at once (including from other surfaces — mobile, web, Slack, GitHub, Linear). That mirrors the idea of concurrent **`Task`** / subagent delegation: only parallelize **independent** slices, merge results in one synthesis step, and avoid two sessions racing the same files. The UI makes parallelism easier; it does not remove the need for clear ownership, non-overlapping paths, and one synthesis step.
28 
29## When to Plan
30 
31Plan when:
32- the task is ambiguous
33- multiple valid approaches exist
34- many files or systems will change
35- the user needs approval before implementation
36 
37Do not over-plan one-file fixes or straightforward edits.
38Use the environment's active planning workflow or mode when it exists instead of assuming a specific planning tool name.
39 
40## When to Use Task (subagents)
41 
42In Composer-style Cursor agents the tool is usually **`Task`** (subagent-style delegation; types such as explore, debugger, verifier — see the live schema). Use it when:
43- repo exploration is broad and would pollute main context
44- independent investigations can run in parallel
45- a verifier or debugger pass would help
46- the task has a long-running research branch
47 
48Avoid delegation overhead for instant or light work.
49 
50When several independent branches exist, do not launch them serially by habit. Launch multiple `Task` calls together with separate scopes and merge their results in the main thread.
51 
52**Nested subagents (3.7):** a subagent can spawn its own `Task` children. Treat nesting as a depth budget, not a default — prefer one delegation layer; use two only when the child slice is still too broad. The main thread still owns synthesis, edits, and final verification; do not let nested branches drift into parallel implementation on the same files.
53 
54**Multitask Mode:** when the session is in Multitask Mode, background subagent runs are expected — set `run_in_background: true` on `Task` and `Await` the result instead of blocking the main thread.
55 
56## /best-of-n as an Orchestration Primitive
57 
58For high-stakes decisions (architecture, refactor approach, design parity), the `/best-of-n` command runs the same prompt across 2–4 models in parallel worktrees and then compares outcomes.
59 
60A small workflow for using it well:
61 
62```text
631. Pick 2-4 models (mix is fine: `composer-2.5` + MiniMax-M3 + a third)
642. Write one bounded prompt that names the question, the constraint, and the deliverable shape
653. Run /best-of-n in isolated worktrees
664. Read each result centrally; tag them with the model
675. Pick the strongest, merge complementary ideas, or escalate to the user with the comparison
68```
69 
70Keep prompts bounded. `/best-of-n` is wasted when the prompt is vague.
71 
72## Await for Long-Running Branches
73 
74For dev servers, watchers, build jobs, parallel subagents, or CLI tools that take seconds-to-minutes, do not poll. Use the `Await` tool to wait for a background shell/subagent or a specific output token (`Ready`, `Compiled`, `Error`).
75 
76```text
771. Start the long-running work in the background
782. Await the result or a specific output string
793. If it fails, Await the error message and form the next hypothesis
80```
81 
82This prevents the "waste 30s polling" failure mode and keeps the main thread responsive on M3.
83 
84## Delegation Pattern
85 
86```text
871. Define the slices
882. Delegate only independent work
893. Launch independent subagents concurrently when possible
904. Await long-running branches
915. Read subagent summaries
926. Synthesize decisions in the main thread
937. Implement and verify centrally
94```
95 
96## Parallel Delegation Rules
97 
98- Give each subagent a bounded scope, not a vague restatement of the whole task.
99- State exactly what the subagent should return: findings, file paths, risks, or a decision recommendation.
100- Prefer 2 to 4 concurrent subagents over a long serial chain.
101- Do not split work so finely that coordination costs more than the saved time.
102- If one branch depends on another, keep it sequential.
103- If two subagents may overlap, assign different directories, files, or questions.
104- When you can name the environment (local/worktree/cloud/SSH) and the model per subagent, do — it makes the synthesis cleaner.
105 
106Parallel subagents are best for research and analysis. Centralize edits and final verification unless there is a strong reason to delegate them.
107 
108## Todo and Progress Tracking
109 
110Use `TodoWrite` for real multi-step execution:
111- large refactors
112- multi-file features
113- research plus implementation plus validation
114 
115Keep the list current. Do not let stale in-progress items pile up.
116 
117## Solver Loop for Complex Tasks
118 
119For deep work:
120 
121```text
122Orient
123Find the spine
124Choose the smallest proving slice
125Implement
126Verify
127Broaden carefully
128```
129 
130For exhaustive work, break the task into independently verifiable milestones rather than broad abstract epics. On M3, also load `minimax-m3-long-context` once the milestones cross ~200K tokens of input. Cursor 3.7 can surface a **context usage report** canvas — use it when token pressure is the blocker, then compress or drop slices before expanding scope.
131 
132## Verification During Orchestration
133 
134Do not postpone all checks to the end. Verify per phase:
135- after code changes, run the smallest relevant command
136- after UI changes, use browser checks or `multimodal-grounded` re-reads of post-change frames
137- after a major feature phase, run broader validation
138 
139Use the **diff / review surface** in Cursor when it helps you stage, review, and ship; keep claims aligned with the always-on status and verification rule regardless of UI.
140 
141Final user-facing completion claims should follow the always-on status and verification rule rather than ad-hoc wording.
142