The Orchestrator / Worker Model

Think of the orchestrator as a really good project lead, and the workers as the teammates it hires for one job each. You hand the lead your idea. It splits the idea into small, separate pieces ("build the login form," "wire up the database," "style the page"), then it hires one helper for each piece. Every helper gets its own private copy of your project to work in, called a worktree, so nobody is editing the same file at the same time.

When a helper finishes, it leaves a little written report saying what it did. The lead reads each report, folds that helper's work into the main pile one piece at a time (this folding-in is called a merge), and then tells you the whole story. You do not have to track any of this by hand. You describe what you want, and the lead runs the team. Every dotted-underline word here has a definition, so hover the ones that are new to you.

The flow is: orchestrator reads your spec, carves it into independent units, and calls spawn_worker for each unit that produces real code. Every worker is a fresh, isolated agent with its own worktree and branch cut from the orchestrator's branch. The orchestrator fans out in batches up to a concurrency cap, then blocks on wait_for_workers until that batch reports back, merges each result in, and spins the workers down to free slots for the next batch.

The leverage: you stop hand-feeding tasks one at a time. Write a spec sharp enough to slice into independent pieces and the orchestrator parallelizes it for you. The better you scope the units (genuinely independent, minimal overlap), the cleaner the fan-out and the fewer merge conflicts on the way back in. Pure research or code-reading does not get a worker: the orchestrator uses built-in read-only subagents for that, and saves workers for changes that deserve a branch.

Mechanically: the orchestrator persona decomposes the request into independent units, then for each unit that produces a committable diff it calls spawn_worker (from the sparkle-orchestrator MCP server). Each worker gets a real git worktree on a branch cut from the orchestrator's own branch. The orchestrator spawns up to a live concurrency cap per batch, calls wait_for_workers([ids]) (which blocks on each worker writing .sparkle/result.json, not on process exit), merges, then spin_down_worker to reclaim slots. list_workers shows live status.

The worker's final act is a structured hand-back: a .sparkle/result.json with schemaVersion: 1, taskId, branch, status (success | failed | partial), filesChanged, summary, and optional notes. That is the contract the orchestrator parses, so integration is driven by structured data, not by scraping terminal prose. Read-only analysis goes to built-in Task-tool subagents; workers are reserved for branch-worthy changes.

You get the speed of a whole team without having to manage a whole team. You make one clear request; behind the scenes several helpers work at the same time, and the chief keeps it all organized and folds it together for you. Nothing lands by surprise: the chief brings the finished work back, explains what happened, and you stay in charge of the big decisions. It means you can build bigger things than one person typing one command at a time ever could, without needing to learn how any of the plumbing works.

This is the difference between "I prompt, it codes, I wait, I prompt again" and actually commanding throughput. One spec becomes a fleet of agents building in parallel, then a clean, single-threaded integration you can trust. You hold the intent and the review; the orchestrator holds the dispatching and the merge order. That is the discipline that turns a fast demo into shipping real features, because the slow serial part (one task at a time) is gone and the dangerous part (everyone merging at once) is structurally prevented.

The value is a clean separation between dispatch and execution, with a deterministic integration order. You author the decomposition (or let the orchestrator propose it from a spec), and you get N isolated branches converging through one sequential merge queue instead of a free-for-all. The structured result contract means the integration step is programmable and auditable rather than a guess. You keep real git, real commits, real branches; what you gain is a coordinator that never lets two producers race the same working tree.

In plain terms: the chief is the only one allowed to hire. A helper cannot turn around and hire its own helpers. That keeps things simple and safe, so the work can never spiral into a confusing tree of agents hiring agents. There is always exactly one person in charge: the chief you talk to.

One level of fan-out, full stop. Workers can still use built-in read-only subagents for research, but every edit is theirs and they cannot recurse into more workers. That ceiling is a feature: it keeps the merge graph shallow, the concurrency cap meaningful, and the cost bounded. You always know the shape of the fleet.

The leaf constraint bounds the spawn tree to depth one: a single orchestrator over a flat set of leaf workers. No transitive spawn_worker, so no unbounded recursion, no exponential branch explosion, and one obvious integration point. Workers may invoke built-in Task-tool subagents for read-only context, but all mutations stay on the leaf's own branch. The orchestrator is also pinned to never touch main; its branch is the only integration target.

Folding work together is where things can go wrong if you are careless, so the chief is deliberately patient: it brings in one helper's work, makes sure it fits cleanly, and only then reaches for the next. If two pieces ever disagree about the same line, the chief pauses and asks you instead of guessing. Slow and safe beats fast and broken.

Sequential merging is the whole reason this beats juggling agents yourself. Parallel build, serial integration: you get the speed of fan-out without the chaos of everyone merging into the same branch simultaneously. Scope your units to minimize overlap and the merge queue mostly just works; when it does not, the orchestrator halts on the conflict rather than papering over it.

Integration is a serialized merge queue into the orchestrator's branch, never main and never concurrent: git merge <worker-branch>, verify clean, commit, then spin_down_worker, then the next. This is the direct mitigation for the classic multi-agent merge mess (several agents racing the same tree, colliding on .git/index.lock and conflicts). Conflicts the orchestrator cannot resolve with confidence are surfaced with the offending paths, not auto-resolved. The final report is the consolidated outcome: what each worker did, what merged cleanly, and what is left for you to land to main yourself.

A plain terminal has no idea what a "team of helpers" is. It is one window where you type one command and wait for one answer, then type the next. There is no chief, no helpers, no automatic folding-together. You would have to be the chief, the helper, and the bookkeeper all at once, by hand. Sparkle gives you the chief so you do not have to be.

A terminal is one serial REPL: one session you babysit, one task at a time. There is no concept of delegation, sub-agents, or a structured result you can program against. To fake this in a shell you would hand-manage tmux panes all fighting over the same working tree. Sparkle makes the coordination a first-class feature instead of a juggling act.

A terminal has no notion of delegation, isolated worktrees per task, or a structured hand-back. Everything is one interactive session against one shared working directory. You can approximate fan-out with worktrees and shell scripts, but you own all the plumbing: spawning, waiting, parsing, and serializing every merge by hand. The orchestrator/worker model bakes the fan-out, the .sparkle/result.json contract, the concurrency cap, and the sequential merge discipline into the runtime.