orchestrate

• prompts/andon-block.md
• prompts/empty-error-handoff.md
• prompts/failure-handoff.md
• prompts/finished-no-handoff.md
• prompts/loop-hygiene.md
• prompts/root.md
• prompts/slack-block.md
• prompts/subplanner.md
• prompts/verifier.md
• prompts/worker.md
• references/dispatcher.md
• references/handoffs.md
• references/planner.md
• references/spawning.md
• schemas/plan.schema.json
• schemas/state.schema.json
• scripts/__tests__/agent-manager-slack-mirror.test.ts
• scripts/__tests__/andon-root-cache.test.ts
• scripts/__tests__/checkpoint-restart.test.ts
• scripts/__tests__/comment-cli.test.ts
• scripts/__tests__/comment-retry-queue.test.ts
• scripts/__tests__/exit-on-error.test.ts
• scripts/__tests__/failure-handoff.test.ts
• scripts/__tests__/handoff-branch-parser.test.ts
• scripts/__tests__/handoff-verification-parser.test.ts
• scripts/__tests__/handoff-verification-record.test.ts
• scripts/__tests__/kickoff-dedupe.test.ts
• scripts/__tests__/measurements-compare.test.ts
• scripts/__tests__/measurements-mismatch.test.ts
• scripts/__tests__/measurements-parser.test.ts
• scripts/__tests__/models-catalog.test.ts
• scripts/__tests__/operator-boundary.test.ts
• scripts/__tests__/probe-models.test.ts
• scripts/__tests__/prompt-plan-validation.test.ts
• scripts/__tests__/redact-body.test.ts
• scripts/__tests__/schemas.test.ts
• scripts/__tests__/slack-adapter.test.ts
• scripts/__tests__/slack-channel-boundary.test.ts
• scripts/__tests__/slack-message-format.test.ts
• scripts/__tests__/slack-prompt-shape.test.ts
• scripts/__tests__/support/slack-web-api-mock.ts
• scripts/__tests__/verifier-startingref-reconcile.test.ts
• scripts/__tests__/wait-handoff-failure.test.ts
• scripts/__tests__/watchdog-inspect.test.ts
• scripts/__tests__/worker-branch-discipline.test.ts
• scripts/adapters/index.ts
• scripts/adapters/README.md
• scripts/adapters/slack/client.ts
• scripts/adapters/slack/index.ts
• scripts/adapters/types.ts
• scripts/biome.json
• scripts/bun.lock
• scripts/cli.ts
• scripts/cli/andon.ts
• scripts/cli/comments.ts
• scripts/cli/forensics.ts
• scripts/cli/index.ts
• scripts/cli/inspect.ts
• scripts/cli/task.ts
• scripts/cli/util.ts
• scripts/core/agent-manager.ts
• scripts/core/andon.ts
• scripts/core/branches.ts
• scripts/core/comment-retry-queue.ts
• scripts/core/failure-handoff.ts
• scripts/core/handoff.ts
• scripts/core/loop.ts
• scripts/core/prompts.ts
• scripts/core/redact-body.ts
• scripts/errors.ts
• scripts/measurements.ts
• scripts/models.ts
• scripts/package.json
• scripts/schemas.ts
• scripts/tools/generate-json-schemas.ts
• scripts/tools/nudge-root.ts
• scripts/tools/probe-models.ts
• scripts/tsconfig.json

SKILL.md

---
name: orchestrate
description: Use only when the user explicitly types `/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.
disable-model-invocation: true
---

# Orchestrate

An explicit `/orchestrate <goal>` fans out a large task across parallel Cursor cloud agents. Workers don't talk to each other; they talk up through structured handoffs. The spawn, wait, and handoff loop lives in `scripts/cli.ts`. The planner writes `plan.json`, the script executes it, and the planner reads handoffs to decide what comes next. Long-running agent loops drift; a script with a JSON state file keeps its footing.

**Required reading: the `cursor-sdk` skill ([cursor/plugins/cursor-sdk](https://github.com/cursor/plugins/tree/main/cursor-sdk)).** Spawning, auth, and the error taxonomy live there. Don't reimplement what that skill already documents.

## Setup

- `CURSOR_API_KEY` must be a personal/user key. Create it from [Cursor Dashboard > Integrations](https://cursor.com/dashboard/integrations), then read `cursor-sdk` Auth before using it.
- `SLACK_BOT_TOKEN` is optional. When set, pass `--slack-channel <id>` to `kickoff` or the first `run --root`, or set `SLACK_CHANNEL_ID`. The script stores the channel in `plan.slackChannel`, posts the kickoff thread there, mirrors task status, and reads Andon reactions. When the token is unset, the script logs once and runs without Slack visibility; correctness does not change.

## Core principles

These rules make the tree self-converging without global coordination.

1. **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.
2. **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.
3. **Workers are isolated.** One task, one clone of the repo, no channel to any other agent. One handoff when done.
4. **Subplanners are recursive planners.** A planner publishes a "subplan this slice" task; the subplanner fully owns that slice and hands back an aggregated handoff.
5. **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.
6. **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

Two roles, one skill. Read your role's reference file and skip the other.

**Dispatcher.** You're in a local IDE session and the user typed `/orchestrate <goal>`. Your job is to kick off a cloud root planner and return its URL. See `references/dispatcher.md`. One-shot; you are not the planner.

**Planner (root or sub).** You were spawned with a structured prompt that opens with "You are the root planner for:" or "You are a subplanner for:". Or the user chose to run the planning loop locally. You own a scope, publish tasks, read handoffs, decide what's next. See `references/planner.md`.

`disable-model-invocation: true` means this skill loads only on explicit invocation.