Skip to content

Orchestrating multi-step work

I coordinate parallel work with contracts the runner checks after each phase.

Status: in daily use · checked Oct 26, 2026

In plain terms

A change that is too big for one worker is written down as a plan: lanes of work, phases inside each lane, and gates between them. Separate workers run the phases, a runner checks after each one that the worker stayed inside the files it owns, and a human decides at anything irreversible.

One worker with one brief covers most tasks (see lanes and the run ledger). Some changes touch several places in an order that matters: render a template, then apply it, then verify the service, then update the monitoring. Those get a plan. The runner that executes a plan is the orchestrate lane in the agent system, and this page is how it works and what it is built for.

What a plan is

A plan is a directory: a short readme with the goal, a machine-readable graph of the work, and one self-contained prompt per lane.

flowchart TB subgraph LA[Lane one] direction LR AC[Change phase] --> AV[Verify phase] end subgraph LB[Second lane, waits for the first lane's marker file] direction LR BC[Change phase] --> BV[Verify phase] end subgraph CL[Before the plan closes] direction LR AU[Read-only auditors]:::guard --> RU[Rollup] --> GT{{Operator gate}}:::guard --> DN[Done] end LA --> CL LB --> CL
  • A lane is a unit of work with an owner and a declared set of files it may change. Lanes with disjoint files can run side by side.
  • A phase is one step inside a lane. A worker is spawned for exactly one phase, reads a prompt scoped to it, does it and exits. It never advances to the next phase on its own, and workers talk to each other only through files.
  • A phase carries gates: the phases it waits for, marker files that another lane writes when it finishes something, and human approvals. A phase starts only when every gate is satisfied.
  • The runner derives the state of every phase from disk, so a crash or a restart resumes from what actually exists instead of from memory.

Ownership is checked after the fact

The runner records the repository state before it starts a worker and compares afterwards. Every changed file must match the owned paths of the phase's lane. If a worker touched something outside them, the phase is demoted from done to failed, a marker file doesn't override that, and the worker is retried with the violation spelled out, within a small bounded budget, before a person is asked. I don't rely on the prompt saying "stay in your lane". The prompt says it, and the runner checks.

The check has a known blind spot, which I state instead of hiding: it can only see files that git tracks, so a lane that changes untracked scratch space has to declare that in its prompt as unenforced.

History is protected the same way. When lanes touch the same repository the runner only ever reverts forward, never with a hard reset, and it records a checkpoint reference at each spawn. Before it undoes anything it checks that every checkpoint is still an ancestor of the current head, and if one isn't, it refuses to rewrite history and says which checkpoints were lost.

Humans decide at the irreversible steps

An operator gate pauses a phase mid-way. The worker writes a question file, the runner waits, and the answer comes back as approved, rejected or modified, one at a time or in a batch file the human writes. Gates are never answered programmatically, because they exist exactly where the runtime can't judge the situation.

Audit after each lane

When a lane's last phase finishes, the runner can spawn read-only auditors. A conformance auditor asks whether the lane delivered what its prompt said. A standards auditor asks whether the diff meets the project's own standards. Their findings are rolled up, and a plan can be set to block closing until a human has read the rollup (below).

Closing a plan is a gate

When every lane is done and every auditor has reported, the runner writes an overnight digest, so called because a plan often finishes while I am asleep: one file that says whether the plan as a whole is safe to close. It collects each lane's audit, the commits each lane made (read from the repository itself, because someone may have committed by hand in the same window), the assumption behind each human gate with the worker's evidence for it, and a set of programmatic checks. A gate can carry a command that re-checks its own assumption at close, such as "the tunnel is still up" or "the service is still listening", so the assumption is tested again at the end instead of being trusted from the start. The digest rates the plan green, findings or failed.

  • A green digest can close on its own if the plan allows it.
  • A findings or failed digest can never auto-close, even when the plan is set to advisory. That override isn't configurable.
  • A person then chooses an outcome: approve, approve with a backlog (the non-blocking items are written to the deferred-work list), fix the findings, or reject. Fixing the findings and rejecting keep the plan open.

Why "fix the findings" doesn't start a fixer. The digest reports and gates; it doesn't apply anything. If findings automatically spawned a worker to repair them, the system would be changing the code its own auditors had just judged, with nobody deciding the scope and no second look at the result. That is the self-approval loop the rest of the design exists to prevent. So the plan stays open, and a person writes the remediation as a new brief with its own owned paths and its own review.

Supervision stays out of the chat

Running a plan synchronously in a conversation fills it with worker logs nobody needs. A plan is run in the background by a supervisor, which reports a compact digest, and the chat is for planning, triage and escalation. The supervisor's own judgment calls, such as passing a gate recommendation, are made by a frontier model; the lanes themselves default to the cheap tier (cost routing).

Rules that came from live changes that went wrong

An early plan applied real changes to running services. It caused outages and several false passes, where a gate was green and the service was not. The rules that came out of it bind how a plan is run, and they are the part of this page I would defend hardest.

  • Verify by direct signal, never by the marker. A phase that changes runtime behavior must be proven in the running service: inspect the container, query the metric, check the unit. The thing the audit claimed has to be shown to be true in the live system.
  • A render is an apply. Rendering configuration recreates changed services and can re-apply firewall rules and enable units. Only a dry run with a diff is read-only.
  • Look before touching. A read-only pass over the live target, the templates and the dry-run diff finds false passes cheaply, before anything goes live. The lanes that got one found their problems at rest, with no outage.
  • A lockout protocol for changes that can cut off access. Don't approve until a rollback timer is armed with a tested rollback, a second independent session to the host is held open and idle, and a cold new login has been shown to work. If the human is away, these gates are parked and not auto-applied, because the rollback channel is the same channel that would be locked out.
  • Surgical applies. Recreate only the services that changed, one at a time, and verify each. Never a project-wide mass restart, never recreate a shared network, never reintroduce a change that was deliberately descoped.
  • Stop, don't grind. If an apply hits a cluster of false passes, or a verification will not go green after one rollback, leave the system at baseline, write down what happened and escalate.

How the runner itself is tested

The runner isn't tested by running a model. It is tested against a scripted fake worker that behaves deterministically: a clean run, an ownership violation, a gate round trip, a transient failure, a killed process, a missing marker, recovery of state after a crash, cleanup after a failure, an abort and a termination signal reaching the child. The whole suite makes no model calls and runs in seconds, and it is the regression contract for any change to the runner.

What it is built for

  • The scripted worker can't show a difference between what it emits and what the real worker emits; the parser is tolerant on purpose, so such a difference would show up as missing progress events and not as a crash.
  • It is designed for one operator on one set of machines. It isn't a distributed workflow engine and isn't meant to be one.
  • The ownership check sees tracked files only (above).

The rest of the system is in lanes and the run ledger, the guards it runs under in guard rails, and its failure rates in measuring agent reliability.