Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.
Orchestrate
Status: planned. The spawn/wait/handoff driver (scripts/cli.ts) and role references (references/dispatcher.md, references/planner.md) are not in this repository yet. Until they land, use the agents-sdk-dev skill (harness=cursor) with cloud Agent.create({ cloud: { repos } }) for multi-agent work, or the local pattern in agents/research-runner/cursor/runner.ts.
An explicit /ai-eng/orchestrate <goal> will fan out a large task across parallel Cursor cloud agents. Workers don't talk to each other; they talk up through structured handoffs. The intended design: a script owns the spawn/wait loop, the planner writes plan.json, the script executes it, and the planner reads handoffs to decide what comes next.
Required reading: the agents-sdk-dev skill (skills/agents-sdk-dev/SKILL.md in this repo, specify harness=cursor). Spawning, auth, and the error taxonomy live there.
Setup (when implemented)
CURSOR_API_KEY must be a personal/user key. Create it from Cursor Dashboard > Integrations, then read agents-sdk-dev (harness=cursor) auth guidance.SLACK_BOT_TOKEN is optional for Slack visibility in the upstream design.
Workaround today
- Load
agents-sdk-dev with harness=cursor.
- Use cloud runtime with explicit
cloud: { repos: [...] } per worker task.
- Persist handoffs as JSON files on disk; use deterministic code for phase transitions (see
agents/research-runner/shared/workflow-contract.ts).
- Track
/ai-eng/orchestrate status in docs/reference/commands.md (listed as planned).
Core principles
These rules make the tree self-converging without global coordination.
- Planners own scopes and publish tasks. They do no coding. Writing
plan.json, reading handoffs, and deciding what's next are planner work. Editing files, running git merge, and fixing conflicts inline are not. If a planner feels the urge to code, it publishes a task for a worker instead.
- Planners don't know who picks up their tasks. The script routes each task to a cloud agent. The planner's mental model stays at the task level.
- Workers are isolated. One task, one clone of the repo, no channel to any other agent. One handoff when done.
- Subplanners are recursive planners. A planner publishes a "subplan this slice" task; the subplanner fully owns that slice and hands back an aggregated handoff.
- Continuous motion via handoffs. A planner that thought it was done can receive a late handoff and replan. No "finished" state until the planner decides to stop publishing.
- Propagation, not synchronization. No cross-talk between siblings. No shared state between levels. Each level sees only its children's handoffs.
Node types
| Node |
Runs the loop? |
Scope |
Output |
| Planner |
yes |
Entire user goal |
User-facing message + optional PR |
| Subplanner (↻) |
yes |
One slice of parent's scope |
Handoff to parent |
| Worker |
no |
One concrete task |
Handoff to spawning planner |
| Verifier |
no |
One target's acceptance criteria |
Verdict handoff to spawning planner |
| Git |
n/a |
Shared medium |
Branches (code) + handoffs/ (meaning) |
Role (when reference docs exist)
Two roles, one skill:
- Dispatcher — local IDE session; kick off a cloud root planner and return its URL. One-shot; not the planner.
- Planner (root or sub) — owns a scope, publishes tasks, reads handoffs, decides what's next.
disable-model-invocation: true means this skill loads only on explicit invocation.
1---2name: orchestrate3description: Use only when the user explicitly types `/ai-eng/orchestrate <goal>` to decompose a large task, spawn a tree of parallel cloud-agent workers/subplanners/verifiers via the Cursor SDK, and collect structured handoffs; do not invoke autonomously.4metadata:5 category: user-invoked6 version: 1.0.07 tags: cursor-import, orchestrate8disable-model-invocation: true9---1011Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.1213# Orchestrate1415> **Status: planned.** The spawn/wait/handoff driver (`scripts/cli.ts`) and role references (`references/dispatcher.md`, `references/planner.md`) are not in this repository yet. Until they land, use the **`agents-sdk-dev`** skill (harness=cursor) with cloud `Agent.create({ cloud: { repos } })` for multi-agent work, or the local pattern in `agents/research-runner/cursor/runner.ts`.1617An explicit `/ai-eng/orchestrate <goal>` will fan out a large task across parallel Cursor cloud agents. Workers don't talk to each other; they talk up through structured handoffs. The intended design: a script owns the spawn/wait loop, the planner writes `plan.json`, the script executes it, and the planner reads handoffs to decide what comes next.1819**Required reading: the `agents-sdk-dev` skill** (`skills/agents-sdk-dev/SKILL.md` in this repo, specify harness=cursor). Spawning, auth, and the error taxonomy live there.2021## Setup (when implemented)2223- `CURSOR_API_KEY` must be a personal/user key. Create it from [Cursor Dashboard > Integrations](https://cursor.com/dashboard/integrations), then read `agents-sdk-dev` (harness=cursor) auth guidance.24- `SLACK_BOT_TOKEN` is optional for Slack visibility in the upstream design.2526## Workaround today27281. Load **`agents-sdk-dev`** with harness=cursor.292. Use **cloud** runtime with explicit `cloud: { repos: [...] }` per worker task.303. Persist handoffs as JSON files on disk; use deterministic code for phase transitions (see `agents/research-runner/shared/workflow-contract.ts`).314. Track `/ai-eng/orchestrate` status in `docs/reference/commands.md` (listed as **planned**).3233## Core principles3435These rules make the tree self-converging without global coordination.36371. **Planners own scopes and publish tasks. They do no coding.** Writing `plan.json`, reading handoffs, and deciding what's next are planner work. Editing files, running `git merge`, and fixing conflicts inline are not. If a planner feels the urge to code, it publishes a task for a worker instead.382. **Planners don't know who picks up their tasks.** The script routes each task to a cloud agent. The planner's mental model stays at the task level.393. **Workers are isolated.** One task, one clone of the repo, no channel to any other agent. One handoff when done.404. **Subplanners are recursive planners.** A planner publishes a "subplan this slice" task; the subplanner fully owns that slice and hands back an aggregated handoff.415. **Continuous motion via handoffs.** A planner that thought it was done can receive a late handoff and replan. No "finished" state until the planner decides to stop publishing.426. **Propagation, not synchronization.** No cross-talk between siblings. No shared state between levels. Each level sees only its children's handoffs.4344## Node types4546| Node | Runs the loop? | Scope | Output |47| -------------- | -------------- | -------------------------------- | --------------------------------------- |48| Planner | yes | Entire user goal | User-facing message + optional PR |49| Subplanner (↻) | yes | One slice of parent's scope | Handoff to parent |50| Worker | no | One concrete task | Handoff to spawning planner |51| Verifier | no | One target's acceptance criteria | Verdict handoff to spawning planner |52| Git | n/a | Shared medium | Branches (code) + handoffs/ (meaning) |5354## Role (when reference docs exist)5556Two roles, one skill:5758- **Dispatcher** — local IDE session; kick off a cloud root planner and return its URL. One-shot; not the planner.59- **Planner (root or sub)** — owns a scope, publishes tasks, reads handoffs, decides what's next.6061`disable-model-invocation: true` means this skill loads only on explicit invocation.
v1truv1us