Coding Agent Orchestration: Architecture for Parallel AI Development

Terminal count is not orchestration

Opening ten agents proves that your computer can open ten agents. It says nothing about whether their tasks are independent, whether two processes share state, whether a paused session needs input, or which build result should be believed.

An orchestrated system can answer five questions at any moment: who owns this task, what state is it in, which resources can it mutate, what evidence makes it complete, and how does its commit reach the trusted branch? If one answer lives only in someone's memory, that memory is part of the production architecture now. Unfortunate.

The four planes of a coding-agent system

These planes do not require six services. A small repository can implement them with a task file, Git worktrees, an ignored runtime manifest, a visible terminal grid, and a coordination helper. The architecture is a set of invariants before it is a product.

Choose the smallest orchestration mode that fits

Most product work should start with independent agents. Add a manager only when the coordination problem is real. A hierarchy drawn before the first task ships is usually a diagram of future latency.

The unit of orchestration is a verifiable outcome

“Improve auth” is not a parallel task. “Reject expired refresh tokens and add a regression test in the session service” is. A strong task defines the outcome, allowed surface, known constraints, evidence, and what must remain unchanged.

Outcome: Expired refresh tokens return 401 and cannot rotate.
Own: src/auth/session.ts, tests/auth/session.test.ts
Preserve: public token response shape
Evidence: focused regression test + typecheck
Handoff: branch, commit, dirty files, checks, risks, next action

Smaller is not always better. If two tasks must edit the same invariant and cannot be tested separately, splitting them creates coordination work without creating independent progress.

Use a state machine a human can inspect

A useful minimum is queued → running → waiting → ready → validating → integrated, with explicit failed, cancelled, and blocked exits. “Open in a terminal somewhere” is not a state.

1. Queued: scoped but not yet owned.
2. Running: one agent owns the task and its mutable resources.
3. Waiting: the agent needs input, a tool, or an external event.
4. Ready: an immutable reviewed commit and evidence exist.
5. Validating: the commit is inside the declared integration snapshot.
6. Integrated: ancestry proves the commit reached the trusted branch.

Timeouts should trigger inspection, not automatic destruction. A quiet compiler and a dead agent look identical until someone checks the process tree and the latest evidence.

Parallelize creation. Serialize expensive truth.

Agents should run focused checks as they work. Once commits are ready, one short-lived owner validates the combined snapshot. This prevents duplicate full builds, stale green results, and simultaneous merges against different versions of main.

The exact ready-queue protocol is documented in the parallel coding agents field guide. The filesystem setup is in the Git worktree guide. They are separate because orchestration and isolation solve different failures.

Measure trusted throughput, not agent activity

The numerator that matters is changes integrated with the evidence the repository requires. Useful supporting measures are median time to trusted merge, blocked-agent minutes, merge-conflict rate, failed validation runs, duplicate broad builds, and the amount of work abandoned after review.

CPU and terminal rendering also become orchestration constraints at larger grids. My GridBash benchmark note publishes the release-mode probes behind two terminal hot-path optimizations instead of pretending “20 agents” is a benchmark by itself.

A practical starting architecture

1. Write two to four tasks with independent file ownership and explicit evidence.
2. Create one worktree and runtime manifest for every editing agent.
3. Keep all sessions visible and label their task, branch, and state.
4. Require a structured handoff before a commit enters the ready queue.
5. Let one owner validate and integrate the batch, then release ownership.
6. Record collisions and blocked time before adding more agents.

Coding agent orchestration questions