Loop engineering vs. graph engineering
Maestro: loop engineering at the node, graph engineering at the fleet.
This page explains two related ideas — what Maestro already does, and the direction it's heading — so the vocabulary is clear before either shows up elsewhere in these docs or on the Maestro site.
Everything under What Maestro does today is shipped and in use in every Maestro workspace. Everything under Where this is headed is roadmap, not shipped — described here so the direction is clear, not because you can configure it yet.
What Maestro does today
Loop engineering is running an agent in a fresh-context loop, iteration after iteration, until it either finishes or a supervising process steps in. This is the model that defined agent-building through mid-2026, and it's what a Maestro crew already is: a role (Planner, Builder, Tester, Docs writer, Security reviewer, Releaser) works an order one loop iteration at a time, each iteration starting clean, until the order completes or a turn/time ceiling is hit.
A Maestro workspace is already a coordinated set of loops, not just one:
roleSequencechains loops together — Planner hands off to Builder, Builder to Tester, and so on — a fixed, ordered path through an order.dependsOnlets one order wait on another, so independent work runs in parallel and converges only when its dependency actually completes.- Review gates (
mso review) insert a human checkpoint between two roles when you want a person to approve before work continues — for example, requiring sign-off between planning and implementation. - Requeue and retry (
mso order retry) give a stalled or failed loop another pass, without losing the work already committed. - Up to five crews run concurrently against one workspace, each on its own isolated worktree.
None of that requires anything beyond today's Maestro: a linear sequence of roles, gated where you want a human in the loop, running in parallel where orders don't depend on each other. This is the default, and it is not going away.
When a straight sequence is enough
Most work fits a straight line: plan, build, test, document, ship. If your process is "role A runs,
then role B runs, then maybe a human checks in," you already have everything you need — a plain
order with a roleSequence and, optionally, a review gate. Adding more structure than that buys
you nothing for a workflow shaped like a single path.
Where this is headed
Graph engineering is the layer above loop engineering: instead of one fixed path through a sequence of loops, you declare an explicit network of nodes and typed connections between them — where a loop's outcome can route to different next steps, several loops can feed into one convergence point, and a failure can route back to an earlier step with a bounded number of retries rather than looping indefinitely.
Framed against what Maestro already has, this is a generalization, not a new engine:
| Idea | Today | Where it's headed |
|---|---|---|
| Ordered work | A fixed roleSequence | Any node can route to any other node, conditionally |
| Waiting on other work | dependsOn — wait for one thing to finish | Multiple independent branches converging at a single point |
| Retrying failed work | Blind requeue | A bounded, declared number of retries before escalating to a person |
| Human checkpoints | A gate between two named roles | A gate on any declared connection in the network |
Two things about this that matter more than the mechanism:
- A loop is still the unit of work. Every node in a graph, however it's wired to the rest, is still an agent running in a fresh-context loop until done. Graph engineering composes loop engineering — it doesn't replace it.
- A straight sequence stays the default, forever. A workspace that only ever needs "plan, build, test, ship" will keep looking exactly like that. Nothing here is a migration you'll be asked to do.
When a graph is worth it (once available)
The rule of thumb worth keeping in mind, once this capability ships: use a graph when a workflow has more than a handful of branching states that genuinely need independent inspection and the ability to resume from any of them — otherwise, a straight sequence is simpler and cheaper. A graph's value shows up in workflows with real branching and convergence: several independent verification checks that need to agree before release, or a revision cycle that needs to remember why the previous attempt failed. A single-path pipeline gains nothing from the extra structure.
See also
- What's in the box — Maestro's roles, order/sprint model, and quality gates as they work today.
- CLI reference —
mso dispatch,mso order,mso review, and the rest of the day-to-day command set.