Orchestrator

/runbooks:orchestrator takes a goal, such as every runbook of one capability, and drives agents that move runbooks through the whole flow: map, create, run and to-test. Several agents work at the same time, 4 by default. The command writes no runbook itself. It plans the work, launches one agent per stage, answers the agents' questions when a file settles them, asks you the rest, and commits what the agents wrote. It stops when the goal is met or when you interrupt it.

❯ /runbooks:orchestrator --goal "Implement all clients runbooks"
❯ /runbooks:orchestrator --goal "Make every draft runbook active" --max-agents 2

How it works

The goal

You write the goal in your own words. The command turns it into a list of runbooks:

• A runbook id, such as users.create, is that runbook. An id that does not exist gets the closest ids, and the command asks which one.
• A capability, or "all clients runbooks", is every runbook of that capability. When coverage lists routes or endpoints of it that no runbook cites, a map stage comes first and writes their placeholders. "All" or "the project" is the same without a capability.
• A state, such as "every draft" or "active runbooks with no script", is the runbooks in that state.
• A change, such as "after the diff from develop", is the runbooks that /runbooks:list --affected returns, each one updated first.

Without --goal, the command offers up to three goals built from the state of the project, such as the capability with the most placeholders. A goal that is not runbook work, such as building a feature or registering a role, gets the command that does it, and the orchestrator stops. A goal with two readings gets one question before anything starts. Deprecated runbooks are always left out, and so are invalid ones, with their problems listed.

The plan

A unit is one runbook taken from its current status to a target. A stage is one command an agent follows for that unit.

The stages depend on the runbook's surface:

• A ui runbook gets create when it is a placeholder or does not exist, run until a full run passes, then to-test. The script comes last, because a ui runbook runs in the browser without one.
• An api runbook gets create, then to-test, then run, because it runs only through its script. active and scripted are the same target here.
• update takes the place of create when the goal says the behavior changed, with the diff since git.base as its source unless the goal names another.

The map stage runs first and alone, because the other units may be its placeholders. Then the units closest to their target go first, and inside a tier, runbooks tagged critical. The command prints the plan before it launches anything: each runbook with its surface, upstream mode, status now, target and stages, and the runbooks it left out with the reason. A plan with no unit means the goal is already met.

Before the first agent

An agent cannot fix its environment, so the command checks it once:

• Run mode. ui runbooks run in headless when the Playwright MCP server is loaded, else in script. It never uses the modes that need a person or a visible browser: guided, headed, chrome and prompt.
• The app and the upstream API. When app.baseUrl or, for a live runbook, upstream.baseUrl does not answer, it asks whether to start it, wait for you, or stop.
• Accounts. The env var names of each role's account exist in the secrets file. A missing name is one question now instead of a blocked run later.
• The test command. An api runbook or a to-test stage needs tests.<surface>.command.
• The upstream server. Nothing listens on upstream.port, and the project's copy of the server matches the plugin version. When it does not, the command offers /runbooks:setup before any stage starts (see the copy in the project).

One agent per stage

Every stage is a new agent with a clean context. An agent that carried create into run would hold the whole investigation of the code while it drives the browser. The next stage of the same runbook gets the earlier stages' reports in its brief instead.

Each agent runs on the model of its command's row in the models table, such as create on opus and run --mode test on haiku (see models). --model puts every stage on one model. The brief also carries the decisions the command would otherwise ask you: the run mode, every viewport of the config for a new ui runbook, a design link only when a frame matches the screen by name, every flow of a --from dir source, adopting an existing test that maps to a step, and no waived steps.

The lock

The app, the browser, the upstream server and the test database are shared, so one stage at a time holds them: run, to-test, and a create or update that records fixtures for a mocked runbook. Every other stage runs in parallel, up to --max-agents. A board with one line per runbook, its stage in flight and its status prints after every event.

Questions and failures

The command answers an agent itself when a file settles the question, such as the config, roles.json, the code or a plugin reference. It also answers when a fixed decision covers it, or when the choice has no product consequence, such as a file path or a test name. It asks you when the answer depends on what the product should do, on credentials or an environment it cannot reach, on an action that is hard to undo, or on the scope of the goal. The other agents keep working while you answer.

When a step expected one thing and the screen showed another, where the Expected came from decides. Read from the code, with a code line that plainly produces what was seen: the agent misread the code, and the command adds an update before the next run. From a spec, a ticket or your text, a rule the code itself breaks, or a run that passed before: you choose.

• The runbook is wrong. An update from the code goes before the next run.
• The application is wrong. The runbook waits, and the failed report stays as the record of the bug. When you say the fix is in, its run starts again.
• Skip it. The goal completes without that runbook, and the close says why.

No agent and not the orchestrator changes the application's code. A failure caused by the environment, such as the app that stopped answering, gets fixed and the stage runs once more. A stage that fails twice comes to you: launch it again, skip the runbook, or stop.

Commits

The agents never commit. The orchestrator commits the files each agent reported, by the commits.runbooks policy. With auto, each runbook gets one commit when it reaches its target, such as add clients.create runbook, script and first run. With ask, one question at the close proposes one commit per runbook. With never, the close lists the paths. A file that was already dirty when the command started is never staged without asking. Scripts in a UI tests repository get their own commit there, and reports in _runs/ stay local.

The close

• One line per runbook: its status at the start and at the end, the run result, the script and the commit.
• Every question the command answered itself, with its answer, so you can check them.
• What the goal did not reach, and the one command that continues it: /runbooks:orchestrator with the rest of the goal, or /runbooks:whats-next.