ASK KNOX
beta
Learn/Parallel Agent Dispatch & Worktrees/Lesson 414
LESSON 414

The Orchestrator / Lead / Worker Hierarchy

Three roles with strict separation of concerns — the hierarchy that prevents parallel dispatch from collapsing into parallel chaos.

9 min read·Parallel Agent Dispatch & Worktrees

The Hierarchy That Prevents Parallel Chaos

Dispatching multiple agents without a clear role structure is not parallel dispatch — it is parallel chaos. Five agents all editing the same files, all reporting "done" without verifying their outputs, and an orchestrator trying to make sense of contradictory results.

The hierarchy exists to prevent this. Three roles. Strict separation of concerns. Each role has things it does and things it never does.

The Three Roles

The Orchestrator is the primary session. It does not write feature code. It identifies parallelism, writes dispatch prompts, waits for results, performs convergence, and edits shared registry files at the end. The orchestrator is the only agent that touches index.ts, tracks.ts, tiers.ts, and test count files.

The Lead is an optional sub-orchestrator for large domains. When Knox is dispatching a 10-agent track-building session, he might have a Content Lead (owns lesson MDX files) and a Diagram Lead (owns TSX components), each coordinating 3-4 workers in their domain. The Lead collects domain results and reports a domain summary to the orchestrator. Most sessions do not need a Lead layer — it pays off only when a single domain has enough internal coordination need (roughly 3+ workers in one distinct domain) that managing it directly would overwhelm the orchestrator, which in practice shows up at larger total scale.

The Worker owns one bounded scope. It works in isolation (its own worktree or its own repo). It runs its own verification. It reports PASS or FAIL with evidence. It never touches files outside its declared scope. The worker's output is not "I think it works" — it is the actual test output, pasted verbatim.

The Orchestrator Never Writes Files — Why This Matters

This rule seems obvious until the first time you're tempted to break it.

Knox is watching a worker struggle with a particular TypeScript error. The orchestrator session already has the context. It would take 30 seconds to fix the error directly. Why not just fix it?

Because that fix goes into the main working tree, not into the worker's worktree. When the worker eventually commits its branch and the orchestrator cherry-picks both, there is now a conflict between the orchestrator's direct edit and the worker's independent fix. The convergence step breaks.

The discipline: if code needs to change, dispatch a worker task for it. Even small changes. Even "obvious" fixes. The isolation boundary is what makes the convergence step predictable.

Role Confusion Anti-Patterns

The most common anti-pattern in practice is the Coding Orchestrator: a primary session that starts writing code because it's "faster" and the worker is "taking too long." This is the pattern that eliminates all parallel leverage. The orchestrator is now occupied with code, cannot coordinate other workers, and has turned L4 into L2.

The second most common is the Registry-Editing Worker: a worker that "helpfully" adds its export to components/mdx/index.ts while finishing its assigned task. This seems fine until a second worker does the same thing. The merge produces duplicate exports. TypeScript errors. Convergence breaks. The rule is absolute: workers never touch registry files.

When to Add a Lead Layer

The Lead layer becomes valuable when:

  • A single distinct domain has enough workers (roughly 3+) that it needs domain-internal coordination before the orchestrator can usefully review it
  • The domains are large, distinct, and internally complex (full-stack features with 5+ files per domain)
  • Domain-specific validation logic exists that the orchestrator should not need to know
  • As a secondary heuristic, total scope grows past what one orchestrator can track directly (often around 10+ workers)

For most parallel dispatch sessions — including every track-building session in this academy — the orchestrator manages workers directly. The Lead is an advanced pattern for fleet-scale orchestration.

The Primary Session Stays in Command

This is the one rule from CLAUDE.md that applies specifically to parallel dispatch: "Primary session stays in command." It means the orchestrator's Claude Code session is always the coordination point. Workers run in separate sessions (separate terminal tabs, separate tmux panes, separate machine sessions). The orchestrator waits while workers execute.

During wait time, the orchestrator is not idle — it is:

  • Reviewing previously completed worker outputs
  • Writing dispatch prompts for the next wave
  • Editing registries from the previous wave's convergence
  • Running /code-review-swarm on completed work

The orchestrator's attention is the scarce resource. Allocate it to coordination, not execution.

What's Next

The next lesson goes deep on the dispatch prompt itself — the document that makes a worker task bounded, verifiable, and collision-safe. The scoped dispatch prompt is the orchestrator's primary output. Everything downstream depends on its quality.