Orchestrator-Workers

Orchestrator-workers is the pattern for work too big for one context: one agent plans — decomposes the job, dispatches pieces, assembles results — while N workers each execute one piece in a fresh context (lesson 11), in parallel lanes (lessons 13, 19), usually on a cheaper model (lesson 10). Audit every endpoint. Migrate every call site. Review every file of a monster PR. The decomposition and dispatch are the easy 80% — you built all of that in the last four lessons. This pattern earns its own lesson at the merge, where three quiet failures live, and in one accounting question that decides whether the whole apparatus was worth building. Plus the honest closing question: whether your job needs it at all.

The accounting question: where did the peak go?

You fanned out because no single context could hold everything (lesson 2). Now watch the merge: every worker's result returns into the orchestrator's context. If workers return their full output — transcripts, diffs, complete analyses — the orchestrator ends the run holding approximately everything, your peak context is right back where it started, and you paid the fan-out premium (lesson 11) for the privilege. Fan-out doesn't remove the ceiling; it relocates the ceiling to the merge. The return format decides whether you hit it.

So the return contract — lesson 11's craft tip — becomes here the load-bearing design decision, a dial with three settings:

Return mode	Orchestrator holds	Capacity
Full output	everything	dozens of workers
Fixed summary	verdict + key findings	hundreds
Handle	a path/id to results on disk	thousands

In handle mode the orchestrator's context grows with the count of workers, not the size of their work — it drills into specific results only when the merge logic demands it. Choose per job, but choose knowingly: "just return everything" is the unexamined default, and it silently rebuilds the exact monolith the fan-out existed to escape.

The merge failures, named

Partial-as-complete. Twelve dispatched, nine return; the merge produces nine tidy records, and nothing anywhere says three sources were never examined. Lesson 19's completeness rule applies here with maximum force, because the orchestrator is the component that knows N: completeness computed from dispatched-versus-returned, reported explicitly ("9 of 12; workers 3, 7, 11 did not return"), and any merge that requires completeness refuses a partial set loudly rather than handing a plausible fraction downstream.

Failure laundering. The natural code — collect, filter to successes, aggregate — is precisely a machine for converting worker failures into silent absences. Failures are results: first-class entries ("worker 7: timeout after 3 retries; worker 11: output failed schema validation"), merged into the report, with the policy — retry? proceed flagged? abort? — decided deliberately in the orchestrator's design rather than implicitly by a filter() call.

Lost provenance. Every merged record carries which worker produced it (lesson 19's identity rule, surviving the merge). The day one lane misbehaves — wrong model, poisoned input, corrupted brief — provenance is the difference between discarding one lane's records and distrusting the entire report.

Running the planner well

The orchestrator's prompt is the highest-leverage prompt in the system: it spends every worker's budget and shapes every worker's output. Three practices:

Route asymmetrically (lesson 10). Planning, decomposition, and final synthesis are capability-steep — strong model. Per-item grinding is capability-flat by construction, because the plan removed the judgement — cheap models. This split is what makes large jobs affordable, and the eval (lesson 21) is how you verify the cheap tier holds: run a sample both ways, compare scores, then commit the fleet.

Decompose along independence lines (lesson 11's granularity rule, now with money on it). The unit of work is what must be understood together. Units that secretly depend on each other yield workers that each see half a problem — and no merge step can reassemble understanding that never existed in any single context. When you can't find independent units, that's not a decomposition puzzle to force; it's evidence the job wants one deep context instead (see the closing section).

Treat worker output as untrusted input. Workers read the world — files, tickets, web content — and their returns flow straight into the orchestrator's context, carrying whatever their inputs carried (lesson 26's injection surface, now internal). Structured return formats — parsed, schema-validated at the merge — narrow that channel exactly the way tool schemas narrow an API (lesson 7), and the validation doubles as your merge-time quality gate: a worker result that doesn't parse is a failed worker, handled by the failure policy, never a "probably fine" record.

The honest closing question: do you need this at all?

An orchestrator is management overhead — the premium (lesson 11), the merge risk (above), a second prompt surface to maintain. For a job of five similar items, a single session with a checklist beats the entire apparatus: no premium, no merge, no laundering risk. The pattern pays above the one-context ceiling — when the job genuinely exceeds what one window can hold at quality (a lesson 2 estimate, not a guess) — and below the ceiling it just costs. Deciding which side of that line your job sits on is the first orchestration decision, and "don't orchestrate" is a respectable professional answer.

When the job is real, though, this is the pattern that turns a thousand-file problem into an afternoon: plan smart, work cheap, merge honest — with the emphasis, always, on the third word, because the first two are where the glamour is and the third is where the truth is.