# How to Spawn Parallel Cloud Agents with the Orchestrate Plugin: Planners, Workers, and Verifiers Explained

> Learn to spawn parallel cloud agents with Cursor's Orchestrate plugin. Discover how planners workers and verifiers run concurrently for efficient task execution. Optimize your workflows today.

- Repository: [Cursor/plugins](https://github.com/cursor/plugins)
- Tags: how-to-guide
- Published: 2026-05-25

---

**The Orchestrate plugin achieves parallelism by spawning ready tasks as separate cloud agents concurrently through the `spawnReadyPending` function in the run loop, enabling workers, subplanners, and verifiers to execute simultaneously when their dependencies are satisfied.**

The Orchestrate plugin in the `cursor/plugins` repository implements a plan-driven execution model that enables you to spawn parallel cloud agents using specialized task types and dependency management. By defining tasks in a JSON plan and leveraging the reconciliation loop in [`core/loop.ts`](https://github.com/cursor/plugins/blob/main/core/loop.ts), you can orchestrate complex workflows where multiple agents run concurrently, significantly reducing pipeline execution time for large-scale operations.

## Understanding the Orchestrate Plugin Architecture

### The Three Task Types

The Orchestrate plugin defines three distinct task types in [`orchestrate/skills/orchestrate/scripts/schemas.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/schemas.ts) (lines 29-31) that determine how cloud agents are spawned:

- **worker**: Runs a cloud agent that performs actual work such as compiling code, running tests, or deploying applications.
- **subplanner**: Spawns a child planner that can create additional workers or sub-planners, enabling hierarchical decomposition of complex workflows.
- **verifier**: Executes validation steps that check the output of another task, identified by the `verifies` field, ensuring quality gates are met before proceeding.

### Plan-Driven Execution Model

At the root of every orchestration is a **planner** that reads a JSON plan describing tasks and their dependencies. The `PlanSchema` in [`orchestrate/skills/orchestrate/scripts/schemas.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/schemas.ts) (lines 80-100) enforces validation rules requiring unique task names, valid types, and correct `dependsOn` references. This schema ensures that parallel task definitions are structurally sound before execution begins.

## How Parallel Spawning Works in the Run Loop

Parallelism emerges from the reconciliation loop implemented in [`orchestrate/skills/orchestrate/scripts/core/loop.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/core/loop.ts). When you execute `bun cli.ts run`, the loop enters an idempotent cycle that identifies and launches independent tasks simultaneously.

The key mechanism is `spawnReadyPending`, which gathers every pending task that either has no `dependsOn` entries or whose dependencies have reached the **handed-off** state. According to the source code at line 584 of [`orchestrate/skills/orchestrate/scripts/core/agent-manager.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/core/agent-manager.ts), the `AgentManager.spawnTask()` method creates a cloud agent via the Cursor SDK and records its `agentId` and `runId`.

The run loop (lines 118-149 in [`core/loop.ts`](https://github.com/cursor/plugins/blob/main/core/loop.ts)) implements concurrent execution through this pattern:

```typescript
await spawnReadyPending(mgr, running);
await Promise.all(running.map(mgr.waitAndHandoff));

```

This design means tasks with no mutual dependencies are all spawned in the same reconciliation pass, creating true parallelism across your cloud infrastructure.

## Creating Parallel Task Definitions

### Defining a Parallel Plan (plan.json)

To spawn parallel cloud agents, define tasks in your [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json) that lack mutual dependencies. The Orchestrate plugin will spawn these as concurrent agents:

```json
{
  "$schema": "https://json.schemastore.org/plan.json",
  "goal": "Release v2.0",
  "rootSlug": "release-2-0",
  "baseBranch": "main",
  "repoUrl": "https://github.com/example/project",
  "tasks": [
    {
      "name": "build-ui",
      "type": "worker",
      "scopedGoal": "Compile the UI assets",
      "startingRef": "main"
    },
    {
      "name": "run-unit-tests",
      "type": "worker",
      "scopedGoal": "Execute unit tests",
      "startingRef": "main"
    },
    {
      "name": "verify-unit-tests",
      "type": "verifier",
      "scopedGoal": "Ensure unit tests passed",
      "verifies": "run-unit-tests"
    },
    {
      "name": "decompose-features",
      "type": "subplanner",
      "scopedGoal": "Break feature set into independent pipelines",
      "startingRef": "main"
    }
  ]
}

```

In this configuration, `build-ui` and `run-unit-tests` have no `dependsOn` constraints, causing the orchestrate run loop to spawn **both** workers concurrently. The `verify-unit-tests` verifier waits for the `run-unit-tests` handoff before executing, while `decompose-features` launches a child planner capable of spawning its own parallel workers.

### Ad-Hoc Parallel Spawning from CLI

For immediate parallel execution without modifying [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json), use the CLI spawn command. According to [`orchestrate/skills/orchestrate/scripts/cli/task.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/cli/task.ts) (lines 275-284), ad-hoc tasks create entries in [`state.json`](https://github.com/cursor/plugins/blob/main/state.json) with `adHoc: true` and immediately invoke `AgentManager.spawnTask`:

```bash

# Spawn two workers concurrently

bun cli.ts spawn \
  --name build-ui \
  --type worker \
  --starting-ref main \
  --scoped-goal "Compile UI"

bun cli.ts spawn \
  --name run-unit-tests \
  --type worker \
  --starting-ref main \
  --scoped-goal "Run unit tests"

```

Run `bun cli.ts run` to attach the orchestration loop to both agents simultaneously.

### Nested Parallelism with Subplanners

Subplanners enable hierarchical parallelism. When a `subplanner` type task spawns, it runs a fresh instance of the orchestrate script that reads its own [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json):

```bash
bun cli.ts spawn \
  --name decompose-features \
  --type subplanner \
  --starting-ref main \
  --scoped-goal "Create feature pipelines"

```

The child planner inherits the parent's context and can spawn several workers in parallel within its own reconciliation cycle, creating nested levels of concurrent execution.

## Verification and Dependency Management

Verifier tasks operate as standard cloud agents with specialized semantics. They must declare a `verifies` field pointing to the task they validate. While verifiers wait for their target task's handoff, they can run **in parallel** with unrelated workers or sub-planners.

The dependency system respects `dependsOn` arrays, ensuring tasks execute only after their prerequisites complete. Because the loop is idempotent, re-running `bun cli.ts run` safely picks up new pending tasks without disturbing already-running agents, making it safe to incrementally expand your parallel workforce.

## Summary

- The Orchestrate plugin uses `spawnReadyPending` in [`core/loop.ts`](https://github.com/cursor/plugins/blob/main/core/loop.ts) to identify tasks ready for parallel execution.
- Three task types—**worker**, **subplanner**, and **verifier**—define different parallel execution patterns.
- Tasks without mutual `dependsOn` constraints spawn concurrently via `AgentManager.spawnTask` in [`agent-manager.ts`](https://github.com/cursor/plugins/blob/main/agent-manager.ts).
- Subplanners enable hierarchical parallelism by spawning child orchestration instances.
- The idempotent run loop allows safe re-execution to pick up additional parallel tasks without disrupting running agents.

## Frequently Asked Questions

### What is the maximum number of parallel cloud agents I can spawn with the Orchestrate plugin?

The Orchestrate plugin itself does not impose a hard limit on parallel agent spawning. The concurrency level is determined by your cloud infrastructure capacity and the Cursor SDK limits. Since `spawnReadyPending` in [`core/loop.ts`](https://github.com/cursor/plugins/blob/main/core/loop.ts) launches all ready tasks simultaneously using `Promise.all`, the practical limit depends on your cloud provider's available resources and rate limits.

### How does the Orchestrate plugin handle failures in parallel worker tasks?

When a cloud agent fails, the orchestration loop detects the failed state during the `waitAndHandoff` phase. Tasks with `dependsOn` references to the failed task will not spawn, effectively halting dependent branches of your pipeline. The idempotent nature of the run loop allows you to fix underlying issues and re-run `bun cli.ts run` to resume orchestration without restarting successful parallel branches.

### Can verifiers run in parallel with the tasks they are verifying?

No, verifiers explicitly depend on the completion of the task specified in their `verifies` field. The orchestrate loop ensures that a verifier only spawns after the target task reaches the **handed-off** state. However, verifiers can run concurrently with other unrelated workers or subplanners that they do not depend on, maximizing overall pipeline throughput.

### What is the difference between a subplanner and a regular worker in the Orchestrate plugin?

A **worker** executes specific work units like compiling code or running tests within the current orchestration context. A **subplanner** spawns a new orchestration instance that loads its own [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json) and can create additional parallel workers or subplanners. This architectural distinction enables decomposition of large features into independent pipelines while maintaining the same parallel execution semantics at each level.