Human or AI orchestrator
sequenceDiagram
actor You
participant C as Coordinator
participant A as Agents
participant O as Outside world
You->>C: Ask for something
C->>You: Human or AI orchestrator?
You->>C: Pick one, once
alt Human orchestrator
C->>You: Review plan
You->>C: Approve, you decide
C->>A: Lint and dispatch
else AI orchestrator
C->>A: Lint and dispatch, no stop
end
A-->>C: Built and tested
C->>You: Report and shipping choices
You->>O: Push or merge, only if you say so
How it works
Section titled “How it works”Think of a building site. Someone has to say “start” and sort out surprises. That person is the orchestrator. In superlite the coordinator (Opus, medium effort) does the planning and dispatching, and you choose how much of the deciding is yours. The coordinator never writes project code or runs raw tests. Agents and fixers do that.
You read a review plan and approve it. Until you do, nothing is linted, dispatched or sent to an agent. Hooks and scripts enforce this: dispatch, wave0 and build_prime exit with BLOCKED. After your yes, the run decides on its own and lists any scope change at the end, so you are asked once, not repeatedly.
superlite writes the machine plan, lints it, dispatches and rules on questions without stopping. It prints one line naming /superlite:agents at the first dispatch so you can watch, and asks nothing about views. Every choice it makes is recorded as a Ruling: and shown at the end.
For example, replying “go ahead” to a review plan is the yes the human gate waits for. Saying “I am away, decide yourself” in your request skips the menu and picks AI.
Example: the docs site run, from the question to the AI switch
Section titled “Example: the docs site run, from the question to the AI switch”-
You ask for a documentation site for superlite on GitHub Pages. Before it plans anything, you get one menu.
Claude Code · ~/superlite ❯ /superlite:start A documentation site for superlite on GitHub Pages❯ 1. Human orchestrator: I approve the plan before it runs2. AI orchestrator: hands off, it does everythingThe
inventingskill asks once, in the same menu call as its other opening questions, because every later gate depends on the answer. It skips the menu when your request already says “decide yourself” or “I am away”. -
You decide: you pick the human orchestrator. superlite sets the mode.
Claude Code · ~/superlite $ superlite-cli orchestrator statusorchestrator: human, awaiting approvalThe mode lives in
.superlite/orchestrator.jsonwithapproved: false. From here, hooks and scripts refuselint --stable,dispatch,wave0andbuild_prime, so a forgetful model cannot start the build. -
You read the review plan. The coordinator writes only this file, opens it, and stops.
docs/plans/2026-11-12-docs-site.review.md # superlite docs site: review plan## SummaryA short, clear documentation site on GitHub Pages, so people know exactly how to use superlite and what it does while it works. [...]## Rough time and costAbout 45 to 75 minutes and $15 to $30, mostly research and writing (rough, until the plan is linted).Plain words come first because this is the one point where you can still change the scope for free.
-
You decide: you reply with a clear yes, such as “go ahead”.
Claude Code · ~/superlite Reply approve to start, or tell me what to change❯ go aheadA hook writes your reply to
.superlite/human-replies.jsonl. The coordinator then runssuperlite-cli orchestrator approve --review docs/plans/2026-11-12-docs-site.review.md, which exits with BLOCKED unless a newer human reply is on file. The typed reply opens the gate, not the model’s belief. Detail: plan and approval. -
superlite rules. The coordinator writes the machine plan and records a decision you were not asked about.
docs/plans/2026-11-12-docs-site.md Ruling: content edges - writers must read finished fact sheets and the style guide; no stub can stand in for facts - cost: wave 2 waits on wave 1.This is the “switch to AI” in practice: after your one yes, the run decides alone. Each ruling states its cost if wrong, so you judge it at the end instead of being interrupted. It is why the page tasks started after the research tasks (parallel build).

Real output: the rulings from this docs-site run, as
grep Ruling .superlite/progress.mdlists them. -
You decide: say you must leave the desk while it builds. You type
/superlite:ai.Claude Code · ~/superlite ❯ /superlite:aiorchestrator: AIsuperlite no longer ends a turn to wait for you. It still defers anything destructive, security-sensitive or outward-facing, such as a push, and lists what it deferred.
/superlite:humanswitches back.
What you end up with: a review plan you approved, a machine plan with its rulings, and a finished build. Shipping stays yours: pushing, merging and publishing happen only on your answer. This run ended in PR #58.
Check the state at any time:
superlite-cli orchestrator statusIt prints human, awaiting approval, human, approved <time> by <name>, AI, or not set (ungated). A headless claude -p run defaults to AI.
Good to know
Section titled “Good to know”- Small inline work (trivial or bounded, no plan) is not orchestrated. It needs only your yes in chat and has no review plan.
- The gate is not a polite request. Hooks and scripts block the build commands until your reply is on record, as gates explains.
Plan and approval shows what you read and what your yes unlocks.