---
description: Use the ai-orchestrator Plan → Code → Judge loop for non-trivial implementation tasks.
alwaysApply: false
---

# AI Orchestrator Cursor Workflow

For non-trivial implementation work, keep planning, implementation, and checking separate. Cursor rules and MCP tools cannot switch Cursor's selected host model.

## With orchestrator MCP tools

Use this path when the `orchestrator_run_*` tools are available.

1. Optionally call `orchestrator_models` with `stage: "plan"` to preview trusted **server-side** candidates. Select the Cursor host coder separately and record its exact `provider/model` identity as `coderIdentity`.
2. Call `orchestrator_run_start` with a fresh bounded `requestId`, the task, optional repository context/features, and `coderIdentity`. Record the returned opaque `runId` and `revision`.
3. Show the returned plan and wait for explicit approval. Advance with a new `requestId`, the exact returned `expectedRevision`, and `event: { type: "plan_approved" }`. For revision feedback use `plan_revision_requested` instead and approve the replacement plan separately.
4. Implement only while `currentNode` is `coding`, run relevant tests, and gather `git diff` plus `git diff --staged`.
5. Call `orchestrator_run_advance` with a fresh `requestId`, the exact current revision, and `code_result_submitted` containing the diff and test output. The server selects an independent checker and owns every counter, retry, re-plan, and stop decision.
6. Follow `currentNode`, `permittedEvents`, `requiredAction`, and `remaining` exactly. On a rejection, address every returned fix and submit refreshed evidence. When a re-plan returns to `awaiting_approval`, obtain approval again. Stop on `done`, `failed`, `cancelled`, or `blocked`.
7. After the server durably closes a provider failure or checker rejection, call `orchestrator_run_recover` with a new request ID and exact revision. Never submit a category or diagnosis; those require durable server evidence and independent read-only DEBUG. Follow only returned `permittedEvents`: repair code when requested, approve a returned immutable successor plan, or leave blocked/terminal authority untouched.
8. Reuse a `requestId` only to retry the identical mutation after a lost response. If a revision conflicts, call `orchestrator_run_get`, reconcile the current state, and use a new request ID for any changed body. Use `orchestrator_run_cancel` for explicit cancellation.

The user-owned durable store, not Cursor notes or client-supplied counters, is run authority. Cursor remains the coder; MCP routes only its planner/checker calls. The stateless `orchestrator_plan` and `orchestrator_judge` tools remain available only for compatibility. Routing metadata never permits skipping approval or publication gates.

Graph execution is independently release-gated. Fresh installs remain on `execution.engine: "graph-shadow"`; repository input cannot promote graph authority or grant parallel writes. Treat synthetic graph tests as verifier coverage, not field evidence, and keep the compatibility path until a trusted release report proves a real compatibility window and clean rollback.

## Without orchestrator MCP tools

Follow `.cursor/skills/orchestrate/SKILL.md` section **Without orchestrator tools**. Produce and approve a plan, record each manually selected Cursor model identity, implement with a coding-capable maker, manually switch to an independent checker for diff review, and use the configured loop caps. If an independent checker is unavailable under strict policy, fail closed. A named model may be a configured preference or example, never a universal requirement.