A reliable multi-agent workflow gives each task one owner, one acceptance gate, one branch, and one git worktree. It limits active work to the number of diffs the team can review, isolates ports, databases, caches, and credentials as deliberately as files, and merges through a single integration queue. Agents may coordinate through a lead, shared task list, or workbench, but no agent should silently own merge authority. The throughput ceiling is accepted review, not the number of model sessions you can start.
- One agent gets one bounded task, branch, worktree, and proof bundle.
- The WIP limit is set by review capacity, not available subscriptions or CPU cores.
- Worktrees isolate files and branches, but not ports, databases, secrets, caches, or external services.
- Tasks must be partitioned by ownership boundaries, not divided into overlapping file lists.
- Every lane returns the same artifact: plan, diff, checks, risks, and handoff.
- Merge remains a human-controlled integration queue with tests rerun after each dependency lands.
The throughput equation nobody puts on the agent dashboard
Multi-agent development is usually sold with a screenshot of many sessions running. Running is not the output. Accepted, integrated changes are the output. If four agents each produce a thirty-minute diff and one reviewer needs forty-five minutes per diff, the system creates work faster than it can finish it. The queue grows while the dashboard looks productive.
| Rate | Meaning | Failure signal |
|---|---|---|
| Agent start rate | How many tasks enter active work | Easy to maximize and mostly irrelevant |
| Agent completion rate | How many lanes claim they are done | Can rise while quality falls |
| Review rate | How many diffs a human can understand and accept | The usual bottleneck |
| Integration rate | How many accepted diffs land cleanly with the full suite green | Falls when tasks share contracts or infrastructure |
| Rework rate | How many landed changes reopen within days | The delayed signal that parallelism outran understanding |
Set the active-agent limit from review, not compute. A useful starting rule is one active implementation lane per available reviewer, plus one read-only research or verification lane. Raise the limit after a week only if completed diffs are reviewed the same day, merge conflicts remain low, and rework does not climb.
Partition work by ownership, not by enthusiasm
Parallel tasks must be independent enough to merge in either order or have an explicit dependency. “Agent A does the backend and Agent B does the frontend” is not independent if both invent the wire contract. “Agent A defines and tests the additive API contract; Agent B starts after that commit and implements the client” is a dependency the system can schedule.
| Good parallel split | Bad parallel split | Why |
|---|---|---|
| Two unrelated bug fixes in separate modules | Two agents refactoring the same shared utility | File and semantic overlap create conflict |
| Read-only investigation beside implementation | Two implementations of one requirement on the same branch | Research returns evidence without mutating the work surface |
| Platform clients after a shared contract is fixed | Each client invents its own field and semantics | One contract prevents drift |
| Tests for stable public behavior beside internal refactor | Tests written against an interface still being redesigned | Stable boundary makes independent acceptance possible |
| Documentation after behavior and examples are settled | Documentation guessing while implementation changes | Avoids parallelizing uncertainty |
Every task brief needs six fields: outcome, owned surface, explicit exclusions, dependency base, acceptance command, and reviewer. The owned surface may name modules or packages, but the stronger boundary is behavioral: this lane owns the parser and its tests; that lane owns the UI consumer after the parser contract lands. File lists alone miss generated files, shared types, and call sites.
OUTCOME: Reject expired session tokens before route handlers run
OWNS: auth middleware + middleware tests
DO NOT TOUCH: login UI, database schema, deployment config
BASE: main@abc123; depends on no other active task
VERIFY: npm test -- auth-middleware && npm run typecheck
REVIEWER: security owner; same-day review slot reservedIf the brief cannot state what the lane must not touch, it is not ready for parallel execution. Put it in planning, not in another worktree.
One branch and one worktree per implementation lane
Git worktrees let one repository expose several checked-out branches at the same time. Each path has its own index and working tree while sharing the object database. That is the right file-level primitive for parallel agents: no stashing, no checkout fights, and a diff attributable to one task.
git switch main
git pull --ff-only
git worktree add ../repo-auth -b agent/auth-expiry main
git worktree add ../repo-docs -b agent/auth-docs main
git worktree list
git -C ../repo-auth status --short
git -C ../repo-docs status --shortThe branch name should encode the task, not the model. Models change mid-session and do not explain the diff. Put model, agent version, prompt, and session identifier in the task record or handoff. Keep git history about repository intent.
A worktree is a collision boundary, not a process sandbox. Both agents may still see the same home directory, SSH agent, Keychain, cloud configuration, package caches, Docker daemon, and localhost. Both may start a server on port 3000 or point migrations at the same development database. The next section exists because most multi-agent failures happen outside git.
Isolate the state git does not know about
Two clean worktrees can still corrupt each other's run through shared mutable state. Make the isolation map part of repository setup so every lane receives a unique namespace automatically.
| Shared resource | Collision | Isolation pattern |
|---|---|---|
| Development port | Second server fails or tests hit the wrong build | Allocate a port from the task or derive one from a stable lane id |
| Database | Migrations and fixtures overwrite each other | Database or schema per lane; never point agents at shared staging |
| Redis / queues | Jobs and cache keys cross lanes | Prefix keys and queue names; separate container when cleanup is uncertain |
| Docker Compose project | Container names and volumes collide | Unique project name per worktree |
| Build cache | Stale or incompatible artifacts appear in another lane | Cache key includes base commit, platform, and dependency lock hash |
| Package lockfile | Independent installs produce merge churn | Only the dependency-owning lane edits it; others use the pinned state |
| Generated code | Two lanes rewrite the same output | One generator owner or regenerate once after integration |
| Simulator / browser profile | Tests observe another lane's state | Dedicated device, profile, or serial test queue |
Repository setup commands should accept a lane identifier and print the allocated resources. An agent should not guess a free port or database name. Deterministic allocation makes failures reproducible and cleanup possible.
External services need the same treatment. Use a test tenant, task-scoped namespace, idempotency key, and credentials that cannot reach production. If a service cannot isolate concurrent test data, serialize that test at the integration queue. Parallelizing a resource that has no isolation primitive is not acceleration. It is nondeterminism.
Permissions and secrets in the multi-agent case
The site's AI coding agent security guide covers permission modes, sandboxes, prompt injection, secrets, and review for one agent. Multi-agent work multiplies identity and data-flow problems. A token copied into four lanes is four opportunities for misuse, four log streams that may capture it, and four processes that must be stopped when it is revoked.
- Separate capability by role. A research agent needs read-only repository access. An implementation agent needs workspace writes. A verifier should not need the implementation lane’s write token. None needs merge or deploy by default.
- Issue short-lived credentials per lane. Put the task id in audit metadata where the provider supports it. Revoke on completion rather than waiting for a shared developer token to expire.
- Keep secrets out of prompts and transcripts. Inject them at tool execution, redact output, and log the secret name rather than value.
- Restrict network destinations. A lane reading untrusted code should not have arbitrary egress and a broad cloud token at the same time.
- Protect shared instruction files. Project agent instructions, workflow scripts, and CI policy affect every lane. Changes to them need dedicated ownership and review.
- Do not let agents approve each other’s authority. One agent can review a diff, but it cannot grant another lane broader credentials or waive the human merge gate.
Worktree paths are untrusted input when they cross process boundaries. Validate paths before cleanup, server startup, or artifact upload. Never identify a process to kill from a broad name or path match on a machine hosting several agents. Capture the process identifier at launch, verify its working directory and owner, and terminate only that process.
Use an orchestrator for routing, not for hiding decisions
A lead agent, shared task list, or workbench can route tasks, monitor status, and collect results. That coordination is useful when it keeps ownership visible. It becomes harmful when the lead silently rewrites scope, launches overlapping work, or compresses every result into a confident paragraph that discards evidence.
| Orchestrator should | Orchestrator should not |
|---|---|
| Enforce the WIP limit | Start every available task because a slot is idle |
| Check dependencies before dispatch | Assume file separation means semantic independence |
| Create or assign the worktree and branch | Let workers choose arbitrary shared paths |
| Preserve links to plans, logs, diffs, and checks | Replace evidence with a summary only |
| Escalate ambiguity before implementation | Invent product or architecture decisions to keep agents busy |
| Move work into a human review queue | Merge because two agents agree with each other |
Claude Code agent teams provide a lead, independent teammates, shared task lists, and direct inter-agent messages. Subagents are different: they run isolated context for a delegated subtask and return a summary to one parent session. Separate worktree sessions are different again: each is a full implementation lane with its own branch. Choose the least coordination machinery that fits the dependency graph.
A workbench such as Conductor or Continuum can make native agent sessions visible without turning one model into a sovereign project manager. Continuum runs supported agent CLIs as separate sessions and worktrees; Conductor presents a dense Mac board. The useful feature is state you can inspect, not autonomy for its own sake.
Standardize the proof bundle from every lane
Review slows sharply when each agent reports completion differently. Require the same proof bundle regardless of vendor or model. The bundle is a contract between implementation and review.
| Artifact | Required content | Reviewer question |
|---|---|---|
| Plan | Intended files, contract changes, verification, exclusions | Did the lane solve the assigned problem? |
| Diff | Only task-scoped changes, with generated output identified | Can I explain every changed line? |
| Checks | Exact commands, exit status, and focused result | Was the relevant behavior exercised? |
| Risk note | Security, data, compatibility, migration, and unverified surfaces | What could still fail after green tests? |
| Handoff | Base commit, branch, commits, dependencies, conflicts, cleanup | Can another person integrate this without the session? |
TASK: auth-expiry
BASE: abc123
BRANCH: agent/auth-expiry
CHANGED: middleware.ts, middleware.test.ts
VERIFY: npm test -- auth-middleware (pass); npm run typecheck (pass)
RISKS: clock-skew behavior unchanged; integration suite not run
DEPENDS ON: none
DO NOT MERGE WITH: active session-cookie refactor
CLEANUP: server pid 4821 stopped; test database auth_expiry_42 droppedA screenshot is required when the acceptance claim is visual. A command transcript is required when the claim is behavioral. A statement that tests pass without the command and exit status is not evidence. The proof should be cheap enough that every lane produces it, which means focused checks first and the full suite at integration.
Review in two passes
Review agent output in two passes because intent and implementation fail differently. The first pass asks whether the change belongs. The second asks whether the code is correct.
- Scope pass. Compare the brief, plan, and file list. Reject unrelated cleanup, new abstractions without a requirement, dependency changes without ownership, and deleted behavior the task did not authorize.
- Correctness pass. Trace inputs, state changes, errors, concurrency, authorization, and cleanup. Read deletions as carefully as additions. Run the focused checks yourself when risk warrants it.
- Adversarial pass for sensitive code. Use a fresh read-only reviewer for auth, billing, data deletion, secrets, networking, and deployment. Give it the diff and threat or invariant, not the implementation conversation.
- Product pass for UI. Run the built artifact, exercise the path, and capture proof. Static code review cannot confirm layout, focus, loading state, or device behavior.
Do not ask the implementing agent “is this correct?” and count its answer as review. It shares the assumptions that produced the diff. A fresh agent can help find issues, but a human still owns acceptance and merge authority.
Keep reviews small by rejecting oversized tasks before implementation. Once a lane returns 2,000 changed lines, the team faces a bad choice between slow review and shallow review. Task size is a safety control set upstream.
Merge through one integration queue
Parallel branches become a product only after integration. Use one queue with explicit ordering. A branch is rebased or updated against the current integration base, its focused checks rerun, then the shared suite runs after merge. If another active lane depends on a contract, publish the contract commit first and rebase the dependent lane before it continues.
Freeze the lane
Stop new edits once review starts. Any fix becomes a visible follow-up commit and reruns the affected checks.
Update from the integration base
Rebase or merge according to repository policy. Resolve conflicts with the task owner present; a clean textual merge can still be a semantic conflict.
Rerun focused proof
The original green result applied to the old base. Run the task gate again after updating.
Land one change
Keep merge ordering observable. Do not land a batch of dependent agent branches and diagnose the combined failure afterward.
Run shared gates
Typecheck, integration tests, schema checks, generated-file checks, and platform builds run on the integrated state.
Release dependent lanes
Rebase queued work on the new base and rerun its focused gate before review resumes.
Human merge is a durable control because it marks where accountability transfers from a disposable lane to the shared product. Branch protection, required checks, and code ownership should enforce that boundary even if the workbench offers a one-click PR button.
Failure modes that look like agent problems
| Symptom | Likely system cause | Fix |
|---|---|---|
| Agents repeatedly edit the same files | Tasks were split by ticket label, not ownership boundary | Serialize the shared contract or assign one owner |
| Tests pass alone and fail together | Shared database, port, cache, clock, or fixture state | Namespace the resource and add an integration test |
| Ready-for-review queue grows | WIP exceeds reviewer capacity | Stop dispatch, swarm review, lower the lane limit |
| Merge conflicts rise late in the day | Branches stayed active too long against a moving base | Use smaller tasks and publish dependency commits earlier |
| Quota disappears without accepted work | Agents explore vague tasks or duplicate research | Add a read-only planning lane and tighter briefs |
| One lane kills another server | Process management used broad name or path matching | Capture PID at launch and verify ownership before termination |
| Secrets appear in transcripts | Credentials were passed through prompts or verbose output | Inject at execution, redact, rotate, and narrow scope |
| Two agents agree on a flawed change | Shared context or copied assumptions | Use a fresh reviewer with the invariant and diff only |
These failures are coordination defects. Changing models may move their frequency but does not remove the mechanism. Fix task shape, isolation, proof, review, or queue policy first. A stronger model in the same broken system can generate the bad queue faster.
Metrics that tell you whether parallelism works
Measure one-agent baseline before claiming a multi-agent gain. The useful unit is a completed, accepted task of similar size.
| Metric | Healthy direction | What it diagnoses |
|---|---|---|
| Lead time: task ready to merged | Down | The actual throughput result |
| Queue time: done to review start | Near zero | Whether WIP exceeds review capacity |
| Review minutes per accepted task | Stable or down | Diff quality and task size |
| Rework within seven days | Stable or down | Whether shallow review is hiding defects |
| Merge conflicts per task | Down | Task independence and branch lifetime |
| Agent cost per accepted task | Down | Prompt precision, duplicate work, model routing |
| Human interventions per task | Down without rework rising | How much steering the lane needs |
| Abandoned lane rate | Low and explained | Planning quality and speculative work |
Do not optimize token cost alone. A cheap lane that produces a rejected diff consumed model budget and review attention. Do not optimize completion rate alone. An agent can mark a task complete before acceptance. Tie every metric to merged work and delayed rework.
A simple weekly review is enough: which lanes waited, conflicted, exceeded scope, failed verification, or reopened after merge? Change one operating rule at a time. Multi-agent development is a production system, and production systems improve through observed constraints rather than a bigger spawn button.
A practical operating model from two agents to eight
| Stage | Allowed concurrency | Required controls before advancing |
|---|---|---|
| Stage 1 | One implementation + one read-only verifier | Task card, clean branch, focused check, human merge |
| Stage 2 | Two independent implementation lanes | Separate worktrees, resource namespaces, same-day review slots |
| Stage 3 | Three to four lanes across modules | Dependency graph, integration queue, proof bundles, cost view |
| Stage 4 | Five to eight lanes across a team | Named dispatcher, reviewer rotation, credential automation, fleet and queue observability |
Stay at the lowest stage that meets lead-time goals. Stage four is not maturity if stage two finishes the backlog with less coordination. More lanes are justified by independent ready work and reviewers, not by agent availability.
- Morning: triage ready tasks, confirm dependencies, reserve reviewers, and start only the WIP limit.
- During work: agents update machine-readable state such as planning, running, blocked, verifying, and ready. Blockers preserve exact commands and error text.
- Review: freeze the lane, inspect scope then correctness, run the proof, and return findings as a bounded revision.
- Integration: land one reviewed branch, run shared gates, then refresh dependent branches.
- End of day: stop processes, revoke lane credentials, preserve required artifacts, remove disposable worktrees only after clean-state checks, and account for every active branch.
Continuum and Conductor can reduce the manual bookkeeping around this model. Claude Code agent teams can coordinate related research and implementation. Plain terminal windows plus scripts can implement the same discipline. The tool is secondary. The invariant is visible ownership from task creation through teardown.
Questions people ask
A workflow where several coding-agent lanes work concurrently on one product under explicit task ownership, branch and worktree isolation, shared-resource namespaces, standardized verification, human review, and one integration queue.
Start with one implementation agent and one read-only verifier. Add a second implementation lane only when both diffs can be reviewed the same day. The limit is review capacity and task independence, not CPU cores or subscriptions.
Use a separate worktree and branch for every concurrent implementation lane. Worktrees prevent checkout collisions and make diffs attributable. Read-only research subagents may not need one if they cannot edit.
No. They isolate checkout and index state. Agents can still share ports, databases, caches, Docker, simulators, home-directory credentials, SSH agents, and network access. Namespace or sandbox those separately.
A fresh read-only agent is useful for adversarial review, especially when it receives only the invariant and diff. It does not replace human acceptance, and agents should not grant each other credentials or merge authority.
Through one visible queue. Freeze the lane, update it from the current integration base, rerun focused checks, land one reviewed change, run shared gates, then refresh dependent branches. Keep merge authority human-controlled.
Shared authority. Copying one broad token, home-directory environment, or production-capable identity into many lanes multiplies exposure. Give each lane task-scoped credentials, tools, writable paths, network access, and teardown.
Measure lead time to merged change, queue time before review, review minutes, rework, merge conflicts, and cost per accepted task against a one-agent baseline. The number of sessions running is not a throughput metric.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.