Cursor Planner/Worker Architecture: Multi-Agent Coordination Insights

Core Issue

Cursor’s March 2026 publication, “Scaling long-running autonomous coding,” revealed a key engineering conclusion: the Planner/Worker hierarchical architecture is the core paradigm for addressing multi-agent coordination bottlenecks. This article provides the most systematic empirical data on multi-agent coordination since the Anthropic C Compiler parallel experiments.

Lessons from Anthropic vs. Cursor’s Evolution

In the analysis of the MetaMorph distributed coordination mechanism, we observed Anthropic’s experimental approach: multiple agents coordinated through shared files and Git file locks. The advantages include decentralization and no single point of bottleneck, while the disadvantages include “risk aversion”—agents without a hierarchical structure tend to avoid difficult tasks.

Cursor’s Planner/Worker architecture offers a different solution: introducing a hierarchical structure while allowing each level to focus on different responsibilities.

“Our next approach was to separate roles. Instead of a flat structure where every agent does everything, we created a pipeline with distinct responsibilities. Planners continuously explore the codebase and create tasks. Workers pick up tasks and focus entirely on completing them.” — Cursor Engineering: Scaling long-running autonomous coding

Core Architecture: Three-Stage Cycle

┌─────────────────────────────────────────────────────────────────┐
│                        PLANNER AGENT                            │
│  Continuously explores the codebase, breaks down tasks, generates task queue                       │
│  Recursively generates sub-planners for parallel planning                            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
                    Task Queue (shared state)
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                       WORKER AGENTS (N)                       │
│  Parallelly consume task queue, each independently completes tasks                           │
│  Do not coordinate, do not communicate, do not care about the global perspective                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        JUDGE AGENT                               │
│  Evaluates whether the current iteration meets the goals, decides whether to continue to the next round                    │
└─────────────────────────────────────────────────────────────────┘

Responsibilities of the Planner

Planners do not execute; they only plan:

• Continuously explore the structure of the codebase and understand module boundaries
• Break down large tasks into parallelizable subtasks
• Generate and maintain the task queue
• Recursively generate sub-planners: create specialized planners for specific domains (e.g., network layer, UI layer)

“Planners continuously explore the codebase and create tasks. They can spawn sub-planners for specific areas, making planning itself parallel and recursive.” — Cursor Engineering Blog

Responsibilities of the Worker

Workers do not plan; they only execute:

• Consume tasks from the task queue
• Focus on end-to-end implementation of single tasks
• Do not coordinate with other workers
• Push results to the shared branch upon completion

“Workers pick up tasks and focus entirely on completing them. They don’t coordinate with other workers or worry about the big picture.” — Cursor Engineering Blog

Responsibilities of the Judge

At the end of each cycle, the Judge Agent decides whether to continue:

• Evaluate whether the current iteration has met the goals
• Determine if another iteration is needed
• Prevent infinite loops

Evolution of Coordination Mechanisms: Learning from Failures

Cursor’s blog reveals that the Planner/Worker architecture was not established overnight but underwent three iterations:

First Attempt: Flat Structure + Shared Files + Locks

Agent A ──┐
Agent B ──┼──→ Shared File (coordination state) + File Lock
Agent C ──┘

Failure Reasons:

• Agents held locks for too long or forgot to release them
• The actual throughput dropped from 20 agents to 2-3
• Single point locks became bottlenecks
• When agents failed, locks could not be released, causing system deadlock

Second Attempt: Optimistic Concurrency Control (Lock-Free)

Agent A: read → modify → write (succeeds if state unchanged)
Agent B: read → modify → write (retries if state changed)

Failure Reasons:

• Lack of hierarchical structure led to risk aversion among agents
• No one was responsible for difficult tasks
• Agents avoided hard problems, only making minor changes
• The team churned for a long time without substantial progress

Third Attempt: Planner/Worker Hierarchy ✓

After introducing role separation, coordination issues largely disappeared:

• Planners took on coordination pressure
• Workers only needed to focus on execution
• No complex locking mechanisms were required
• Scalable to hundreds of concurrent workers

“This solved most of our coordination problems and let us to scale to very large projects without any single agent getting tunnel vision.” — Cursor Engineering Blog

Key Engineering Data

Cursor provided astonishing empirical data:

Key Insights on Model Selection

Cursor discovered the importance of matching model roles:

“We found that GPT-5.2 models are much better at extended autonomous work: following instructions, keeping focus, avoiding drift, and implementing things precisely and completely. Opus 4.5 tends to stop earlier and take shortcuts when convenient.”

Key conclusions:

• Planners need continuous work capability: GPT-5.2 > Opus 4.5
• Different roles for the same model perform differently: GPT-5.2 as Planner is better than GPT-5.1-Codex
• Select models by role rather than using a universal model

“We now use the model best suited for each role rather than one universal model.”

Engineering Additions to Cursor Agent Best Practices

The concurrent Best practices for coding with agents provided specific practices for Harness engineering:

Agent Harness Three Components

Harness = Instructions + Tools + Model

• Instructions: System prompt + rules
• Tools: File editing, codebase search, terminal execution
• Model: Select the optimal model for each task

“Cursor’s agent harness orchestrates these components for each model we support. We tune instructions and tools specifically for every frontier model.”

Rules vs. Skills: Static Context vs. Dynamic Capability

Cursor proposed a distinction between Rules and Skills:

Rules (.cursor/rules/): Always loaded static context

# Commands
- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker

# Code style
- Use ES modules (import/export), not CommonJS

# Workflow
- Always typecheck after making changes

Skills (.cursor/skills/): Dynamically loaded capabilities as needed

• Skill is a SKILL.md file package
• Contains custom commands, hooks, domain knowledge
• Agents determine when to load relevant Skills

“Unlike Rules which are always included, Skills are loaded dynamically when the agent decides they’re relevant.”

Extending Agent’s Hook Mechanism

Cursor provides a hook system for long-running agents:

// .cursor/hooks/grind.ts
interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  process.exit(0); // Stop the loop
}

if (scratchpad.includes("DONE")) {
  process.exit(0);
} else {
  // Continue iterating
  console.log(JSON.stringify({
    followup_message: `[Iteration ${input.loop_count + 1}/${MAX_ITERATIONS}] Continue working.`
  }));
}

Combined with .cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

This implements an autonomous iterative mode of “run until tests pass.”

Comparison with Anthropic MetaMorph Architecture

The author believes: the two are not mutually exclusive but suitable for different scenarios. Cursor’s hierarchical structure is suitable for large projects with a clear goal but ambiguous paths; MetaMorph’s distributed locks are suitable for scenarios where tasks are naturally divisible and executor capabilities are equal.

Engineering Insights

What Went Right

1. Separation of Concerns: The separation of responsibilities between Planners and Workers resolved coordination issues.
2. Judge Prevents Infinite Loops: The introduction of a judging mechanism allows the system to autonomously terminate.
3. Model Selection by Role: Instead of using one strongest model, select the most suitable for each role.
4. Iterating from Failures: The correct architecture was found after three attempts.

Known Limitations

“Planners should wake up when their tasks complete to plan the next step. Agents occasionally run for far too long. We still need periodic fresh starts to combat drift and tunnel vision.”

• Planners cannot wake up proactively and must wait for fixed cycles.
• Agents sometimes run for too long.
• Periodic restarts are needed to combat drift and tunnel vision.

Core Conclusion

“Can we scale autonomous coding by throwing more agents at a problem? The answer is more optimistic than we expected. Hundreds of agents can work together on a single codebase for weeks, making real progress on ambitious projects.”

Multi-agent coordination is indeed a challenge, but hierarchical structures provide a feasible solution.