Skip to main content

Multi-Agent Coding Workflow for Small Teams: Worktrees, Roles, Review Gates

Start with one implementer and a separate review pass. Add parallel writers only when their tasks have stable boundaries, and test their combined candidate before it reaches main.

LaoZhang AI TeamPublishedUpdated 14 min read
On this page
Conceptual small-team coding workflow with separate worker checkouts, pinned handoffs and one tested combined integration candidate

A small team can run multiple coding agents by giving each writer a bounded task, a separate checkout, and a named human owner. Collect committed results with reproducible handoffs, assemble them in a separate integration worktree, and test that exact combination before accepting it into main.

Start with one implementer and a separate review pass. Add a second writer when the tasks can proceed independently and someone has time to review both. Two green worker branches are useful inputs; the combined candidate still needs its own checks. Different branches in the same checkout do not separate working files, and a prompt saying “review only” does not establish a security boundary.

Choose a split your team can actually review

Use parallel implementation for complementary changes with a settled interface. For example, a CSV exporter and a download-filename helper can be separate tasks once the data format and naming rules are agreed. Keep the shared endpoint, dependency changes, and acceptance test under one owner. The human lead can also be the final reviewer; a small team does not need a different person for every role.

SetupChoose it whenWhat comes back
One implementer, then reviewThe change is tightly coupled or the team is trying this for the first timeOne bounded diff and a separate assessment
Two writers, then integration reviewEach can finish without guessing the other's unfinished behaviorTwo pinned commits, two handoffs, one tested candidate
Parallel investigationsYou need to compare explanations or approachesFindings or competing candidates; select one approach before implementation
A larger coordinated teamSeveral independent tasks exist and review capacity is availableA queue of reviewable results with explicit dependencies

Competing implementations are alternatives. If two agents each fix the same defect, compare their diffs and choose one; merging both is not the goal. Complementary work is different: both changes are intended to survive, so their interaction must be checked.

Keep work sequential when both agents need the same hot files, the API is still changing, a migration depends on unfinished code, or the reviewer cannot explain the combined behavior. Have one owner settle the contract first, then start the next task from the accepted commit. A task board does not remove a dependency.

Give roles concrete responsibilities

The lead owns the problem, shared interfaces, assignments, and merge order. Each implementer owns a small change and its focused tests. A verifier checks the supplied commit against the task and tries to reproduce the claimed result. The human reviewer decides whether the behavior is acceptable and whether the candidate may enter main.

An independent review pass should start from the requirements and pinned diff. Ask it to identify incorrect behavior, missing cases, and unsupported claims in the handoff. It should report findings before editing implementation files. When a repair is needed, assign the repair explicitly, produce a new commit, and repeat the affected checks. Silent edits during review make it unclear which version was approved.

Here is a reusable review instruction, separate from any vendor configuration:

Review the supplied base and head commits against the task requirements.
Read the changed files and relevant callers. Reproduce the named checks
in the assigned checkout. Report behavior defects and missing coverage
with file locations, reproduction steps, and the result you observed.
Do not repair the implementation or change shared services during this pass.
Return the checked head SHA, commands, exit status, and unresolved findings.

This describes cooperation. Enforce any required tool, filesystem, network, or account restrictions through the actual runtime controls and host environment. Do not assume that the role name, allowed-path list, or worktree location prevents an agent with broad permissions from accessing other resources.

Write a task brief before opening the second writer

A useful brief tells the worker what to produce, where to work, and how to recognize a finished result. For the fictional CSV-export feature below, the lead first agrees that CSV cells containing commas, quotes, or newlines must be quoted, embedded quotes must be doubled, and downloaded files must use the existing ASCII filename convention.

The exporter worker might receive this brief:

Task: Preserve CSV cell values in ticket exports.
Owner: export-csv worker; human owner: the issue lead.
Checkout: ../export-csv
Branch: codex/export-csv
Starting commit: paste the full approved base SHA here.

Change only src/csv.mjs and tests/csv.test.mjs.
Keep the existing export function signature and column order.
Handle commas, embedded quotes, newlines, and empty cells.
Do not change the HTTP endpoint, filename helper, dependencies,
credentials, database, or release configuration.

Run: node --test tests/csv.test.mjs
Acceptance: parsing the exported fixture reproduces the original cells;
existing ordinary-row tests still pass.

Stop and report if this requires a shared interface change.
Deliver: committed head SHA, changed paths, exact check command,
exit status, log location, remaining limitations, and review focus.

A second worker can own src/download-name.mjs and its test, preserving the agreed filename convention. The lead owns the combined download acceptance test and any HTTP wiring. This is an example of task design, not a claim that those paths or commands exist in your project. Replace them with your repository's real entry points and checks before assigning work.

Name shared resources too. A worker that needs a development server should receive its own port. A test requiring storage should use an approved disposable fixture or separate test database. Give dependency locks, migrations, shared types, CI configuration, and release scripts one owner. Keep each checkout's mutable build output separate. Sharing a download cache can be reasonable when the tooling supports it; sharing writable build directories or a live database needs a deliberate plan.

Conceptual task brief and durable coding handoff identifying owner, checkout, pinned commits, paths, acceptance commands, results and limitations

Use separate worktrees and record their starting commit

A Git worktree provides another working directory with its own index and HEAD. Linked worktrees share the repository's object database and most references; repository configuration is shared by default. They do not provide a separate operating-system sandbox, network, home directory, credentials, port range, or database. These distinctions follow the Git worktree manual.

For manual worktrees, start from a clean checkout and an approved local main. The following commands assume a POSIX shell, unused sibling directory and branch names, and that the lead has already obtained the intended base through the team's normal process. They do not fetch, publish, or deploy anything.

bash
# Run from the repository root; inspect this output before continuing.
git status --short
git worktree list

# Proceed only when the checkout is clean and main is the approved base.
base=$(git rev-parse 'main^{commit}')
git worktree add -b codex/export-csv ../export-csv "$base"
git worktree add -b codex/download-name ../download-name "$base"

git -C ../export-csv rev-parse HEAD
git -C ../download-name rev-parse HEAD

Both printed commits should equal base. Put that full SHA and the exact checkout path in each task brief, and confirm that each writer's tools actually use that path. Merely switching between branches in one directory gives two agents the same working files. Separate clones are another option, but you must still arrange how committed results reach the integrator.

Git normally refuses to check out a branch already used by another worktree. Give each writer a different branch. If a name or path is already occupied, inspect who owns it and choose a new name. Avoid using -B or --force to clear a routine assignment problem.

Do not blindly copy ignored environment files into every worktree. Decide which approved setup the task needs and which data it may access. If the execution host or local-file connection is unclear, first resolve where Codex, Claude Code, and ChatGPT Work can access your files.

Collect a handoff that identifies the tested version

Ask each worker to commit only its assigned files once its focused checks pass. For the fictional exporter, that means inspecting the diff, staging its two paths explicitly, and committing them on codex/export-csv. Do not treat an uncommitted folder or “all done” message as the merge input.

A durable handoff belongs wherever your team reviews changes: a pull request description, an issue attachment, or an approved task document. It should survive the agent conversation and name the version the reviewer can reproduce.

Task: CSV cell preservation
Base: <full starting commit SHA>
Head: <full committed result SHA>
Checkout/branch: ../export-csv / codex/export-csv
Changed paths: src/csv.mjs, tests/csv.test.mjs

Check: node --test tests/csv.test.mjs
Result: <actual exit status and test summary>
Log: <accessible log path or approved attachment>
Coverage: commas, quotes, newlines, empty cells, ordinary rows
Not checked: HTTP download integration
Review focus: round-trip preservation of a multiline cell
Open findings: <actual findings, or explicitly none found>
Next owner: integration reviewer

Angle-bracket entries are fields to fill with observed results. Never prefill them with a passing claim. The verifier should check the branch's changed paths, reproduce the focused command, and inspect relevant callers. Confirm the checkout is at the handed-off SHA and clean when testing. Record runtime and fixture details when they can change the result.

Any new commit, rebase, conflict resolution, dependency change, or test-relevant environment change requires updating the handoff and affected verification. A test log without the commit and conditions cannot tell the integrator what passed. A second agent's approval also does not grant permission for a new external action.

Test the exact combined candidate before merging

Build the proposed result away from main. Freeze worker handoffs at full commit SHAs, assemble those SHAs in a candidate branch, and run the project checks against that candidate. The important question is whether the exported download works after both changes are present.

For the fictional feature, the combined acceptance check should exercise the download path and verify the filename, column order, and round-trip preservation of cells containing quotes and newlines. Focused exporter and filename tests alone do not exercise that interaction.

The sequence below assumes both worker branches contain committed, reviewed changes. It also assumes your project already has ./scripts/check-export.sh, which runs its relevant behavioral checks and returns nonzero on failure. Supply your own real command; git diff --check only checks whitespace errors. Keep these commands and the following acceptance block in the same shell session so their variables remain available.

One integrator must own updates to local main throughout this sequence. Other writers can continue on their own branches, but nobody else should merge, reset, or advance the target. The SHA comparison below detects a changed target when checked; it is not an atomic lock against another writer.

bash
set -eu
# From the original repository root, with unused candidate names.
target=$(git rev-parse 'main^{commit}')
csv_head=$(git rev-parse 'codex/export-csv^{commit}')
name_head=$(git rev-parse 'codex/download-name^{commit}')

git worktree add -b codex/export-candidate ../export-candidate "$target"
git -C ../export-candidate merge --no-ff --no-edit "$csv_head"
git -C ../export-candidate merge --no-ff --no-edit "$name_head"

(cd ../export-candidate && ./scripts/check-export.sh)
# Required checks must leave no tracked or untracked edits.
test -z "$(git -C ../export-candidate status --porcelain)"
candidate=$(git -C ../export-candidate rev-parse HEAD)
git -C ../export-candidate rev-parse 'HEAD^{tree}'

A merge conflict or failing check stops the shell before the candidate is accepted. Keep the candidate checkout for diagnosis. If checks intentionally create untracked reports, archive those reports outside the checkout and restore cleanliness through the project's normal cleanup before recording the result. Inspect ignored output as well; ordinary Git status does not inventory it.

The reviewer now inspects the final diff from target to candidate, checks the complete feature against the brief, and records the candidate SHA, checks, findings, and acceptance decision. Review permissions, data handling, and other relevant security behavior explicitly when the change affects them. A generic AI review or green test suite is not a security certification.

With acceptance complete, use the original checkout on main:

bash
# Continue in the same shell, under the same single-integrator rule.
test "$(git branch --show-current)" = main
test -z "$(git status --porcelain)"
test "$(git rev-parse HEAD)" = "$target"
git merge --ff-only "$candidate"
test "$(git rev-parse HEAD)" = "$candidate"

The fast-forward makes the accepted commit the target's new tip without constructing a different merge commit. If main changed, stop and build a fresh candidate from the new target using unused candidate names. Recheck the final combination; do not reuse the old passing result as approval for a different tree. A hosted merge queue can serve this role if it tests the actual queued candidate against the current target.

After accepting one candidate, process the next item in order. Later workers may continue from their original base, but the next integration candidate must include the current accepted target. If a worker needs the updated interface, stop it at a checkpoint, preserve its edits, and have its owner update the branch. A rebase or repair changes its handoff SHA and verification obligations.

These examples were checked with an invented, disposable offline Git repository. That validates the illustrated Git sequence and its failure checks, not coding-agent performance or your application's behavior. Publishing the accepted branch and deploying it are separate team actions.

Review checks and sequential merge queue for accepting a coding change

Preserve failures before cleaning up

When a worker crashes, a merge conflicts, or the candidate fails, preserve the result before trying to make the worktree disposable. Keep the branch and commit SHA, the brief, failing command and output, and any useful partial changes. Assign a next owner and state whether they should repair the implementation, resolve a contract disagreement, or retry an environmental check.

For an existing failed candidate, this capture sequence writes records to a new temporary directory outside the checkout:

bash
archive=$(mktemp -d)
git -C ../export-candidate rev-parse HEAD > "$archive/head.txt"
git -C ../export-candidate status --short > "$archive/status.txt"
git -C ../export-candidate diff --binary > "$archive/unstaged.patch"
git -C ../export-candidate diff --cached --binary > "$archive/staged.patch"
git -C ../export-candidate ls-files --others --exclude-standard > "$archive/untracked.txt"
git -C ../export-candidate ls-files --others --ignored --exclude-standard > "$archive/ignored.txt"
printf 'Preservation directory: %s\n' "$archive"

The patches capture tracked changes, not the contents of untracked or ignored files. Review both inventories and copy necessary, approved files and logs into durable storage before deleting anything. Keep private data out of public issues and repositories. For conflicted merges, keep the checkout until the conflict state has been understood and saved; a patch alone may not reproduce every stage of the conflict.

FailureNext action
Both workers changed a shared contractPause dependent work. One owner settles the interface and issues revised briefs.
Focused checks pass, combined checks failKeep the candidate and logs. Reproduce the interaction, assign a repair, then rebuild and recheck the candidate.
The target moved after validationBuild a new candidate from that target and repeat affected review and checks.
A worker has only partial, uncommitted editsPreserve tracked patches and needed untracked/ignored files; have its owner resume or hand over explicitly.
The review queue keeps growingStop adding writers and finish reviewing the existing results.

Once accepted commits are reachable from main, all necessary artifacts are saved, and a worktree is clean, ordinary git worktree remove <path> can remove that manual worktree. Inspect ignored material first. Keep branch references needed for recovery. git worktree prune clears metadata for missing worktrees; it is not a way to preserve or finish their work. Product-managed worktrees have their own archive and retention flows, so use the product's supported lifecycle rather than assuming manual cleanup is interchangeable.

Fit Codex or Claude Code to the workflow

Choose the client after deciding who writes, where they work, and what passes the merge gate. The product details below follow official documentation checked on October 7, 2026; they are not a comparison of measured agent quality.

Codex app worktrees: In a Git project, start a Worktree chat and select its starting branch. The documented app flow normally creates a detached HEAD; use Create branch here when keeping the result on a branch, or Hand off to move the chat to Local. Confirm the actual starting commit. Copying selected local changes in the app flow differs from creating a clean manual worktree. .worktreeinclude applies to matching ignored files in local managed worktrees, skips source symlinks and existing destination files, and does not provide arbitrary untracked-file transfer. Review what you copy. See Codex worktrees.

Codex subagents: Current local releases document delegation when you request it or applicable project or skill instructions require it. Subagents inherit runtime permissions; live parent overrides can supersede custom role defaults. A delegated context does not automatically get its own worktree. Give writers explicit checkouts and verify the effective controls instead of treating a “read-only reviewer” label as confinement. See Codex subagents and permissions.

Claude Code subagents: Worktree isolation is an optional setting. Its documented default base is the repository's default branch, rather than the parent session's HEAD, so verify the starting SHA when a task depends on recent work. Context behavior also differs: a fork inherits conversation history, while a non-fork subagent starts from its definition. Interactive fork mode is enabled by default from v2.1.232; non-interactive defaults differ. See Claude Code subagent isolation and fork behavior.

Claude Code agent teams: Teams are experimental and disabled by default. They provide shared tasks and teammate messaging, but task-claim locking does not lock your source files or database. Teammates inherit the lead's permission mode except dontAsk; a lead bypassing permissions passes that behavior to teammates. Agent plan approval is distinct from human permission approval. Current limitations include no restoration of in-process teammates through session resumption, one team per session, and no nested teams. See agent teams, permissions, and limitations.

For a small-team first attempt, manually assigned worktrees and ordinary supervised sessions are enough to exercise the process. Add orchestration when tracking dependencies and collecting results becomes the problem to solve.

Decide whether the extra coordination is worthwhile

Try the smallest setup on a few comparable, low-risk tasks: one implementer followed by review, then two independent writers if the first handoffs are useful. This is an engineering suggestion, not a proven optimal agent count or a promise of speedup.

Count accepted tasks with a comparable scope and quality standard. Record human time spent briefing, reviewing, repairing, and resolving conflicts; elapsed time to acceptance; repeated work; check failures; and agent or runner cost. Measure the queue too: an implementation finished on Tuesday but unreviewed until Friday has not reduced delivery time.

For example, suppose three similar tasks take 150 minutes of total human handling with one writer. A parallel trial accepts three tasks with 110 minutes of review but 60 minutes of briefing and repair. Its human handling total is 170 minutes, so the apparent review improvement did not reduce the team's burden. Those numbers are illustrative, not observed results. Compare elapsed time and cost separately rather than using one metric to hide another.

Keep the split if it improves an outcome you care about without unacceptable rework, cost, or review delay. Shrink it when shared-contract disputes recur or the lead spends more time reconstructing work than reviewing it. Add another writer only when accepted output and review capacity support that decision. For API-billed usage, estimate Codex CLI token costs separately; a subscription allowance and an API dollar estimate are different measures.

FAQ

Are separate branches enough for multiple coding agents?

Only when each agent also has a separate checkout. Switching branches in one working directory leaves the agents sharing files and index state. Git worktrees provide separate working directories and indexes while sharing repository history and most refs; see the Git worktree manual.

What is the smallest useful multi-agent coding workflow?

One implementer, a separate verification pass, and a human who owns acceptance. Start there when the team is learning to write useful briefs and handoffs. A second simultaneous writer needs an independent task and its own checkout; adding one is a choice to test, not a safety guarantee.

What does a multi-agent security review actually establish?

It establishes only the findings supported by the inspected commit, review scope, and checks performed. Name the security questions that matter, such as authorization behavior or sensitive-data handling, and preserve reproduction details. Multiple reviewers, a role prompt, or a passing functional test does not establish sandbox isolation or certify the application as secure.

Can both worker branches pass while the merged result fails?

Yes. Each worker's checks ran against a particular snapshot. The combination may introduce an interaction neither check exercised, and the target may have changed. Assemble the pinned results on the current target, test that candidate, and accept the same commit under a single integration owner.

Should two alternative fixes be merged together?

Usually no. Treat them as competing candidates, compare them against the same acceptance criteria, and select one. Merge both only if a reviewer intentionally combines distinct, compatible parts and tests the resulting candidate.

Can Codex or Claude Code automatically isolate every worker?

Do not assume so. Codex delegation and worktree creation are separate concerns; Claude Code's isolation: worktree is optional, with a documented default-branch base. Inspect each worker's actual checkout and starting commit. Both products have permission and context behavior that must be checked separately from file separation. See Codex subagents and Claude Code subagents.

What should be saved when an agent fails halfway through?

Keep its committed head, tracked changes, necessary untracked and ignored files, task brief, failing output, and next-owner instructions. Store sensitive material privately. Preserve the worktree until you know those records are sufficient; Git patches and chat summaries alone do not capture everything.

Sources5

External pages this guide links to, in the order they appear. Last updated Oct 8, 2026.

  1. 1.Git worktree manualgit-scm.com/docs/git-worktree
  2. 2.Codex worktreeslearn.chatgpt.com/docs/environments/git-worktrees
  3. 3.Codex subagents and permissionslearn.chatgpt.com/docs/agent-configuration/subagents
  4. 4.Claude Code subagent isolationcode.claude.com/docs/en/sub-agents
  5. 5.agent teamscode.claude.com/docs/en/agent-teams