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

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, 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 (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 (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. 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, 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) implements concurrent execution through this pattern:

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 that lack mutual dependencies. The Orchestrate plugin will spawn these as concurrent agents:

{
  "$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, use the CLI spawn command. According to orchestrate/skills/orchestrate/scripts/cli/task.ts (lines 275-284), ad-hoc tasks create entries in state.json with adHoc: true and immediately invoke AgentManager.spawnTask:

# 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:

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 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.
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}