August 27, 2026 · Harness Engineering · Coding Agents · Git · EN

How to Integrate Changes from Multiple Coding Agents Safely

A dependency-aware integration workflow for combining changes from Claude Code, Codex, Cursor, and other coding agents with contract gates, combined validation, rollback checkpoints, and evidence.

How to Integrate Changes from Multiple Coding Agents Safely

Integrating changes from multiple coding agents means combining stable worker checkpoints in dependency order, verifying contracts at every boundary, and proving the final user-visible outcome on one reproducible candidate. It is not the act of merging whichever branch reports “done” first.

The safest integration order is inherited from the plan created before execution. Task Decomposition for Multiple Coding Agents explains how to define that producer-consumer graph and keep blocked consumers from starting on guessed inputs.

Claude Code may change an API, Codex may regenerate clients, and Cursor may update the frontend. Every branch can be locally green while the combined result is broken: the client used an earlier schema, the UI assumed an old error shape, or a migration passed forward tests but failed rollback.

A safe integration workflow separates four questions:

1. What did each worker actually produce?
2. Which outputs are dependencies of other branches?
3. At which checkpoint did the combined candidate remain valid?
4. Which evidence proves the final behavior rather than isolated activity?

This guide focuses on that integration layer. Use Git Worktrees for Multiple Coding Agents for workspace isolation and the Coding-Agent Handoff Template for transferring worker state.

When two checkpoints disagree, use How to Resolve Merge Conflicts Between Coding Agents for the contract-first classification, source repair, and recovery workflow.

Why locally correct branches still fail together

Every worker validates against a particular base revision and a set of assumptions. Integration changes both.

Suppose three tasks start from commit a13f...:

Task A — API contract
  produces: OpenAPI schema and server behavior

Task B — generated clients
  assumes: final OpenAPI schema

Task C — web consumer
  assumes: final TypeScript client and public errors

If B and C begin from guessed contracts, their tests may pass against fixtures that no longer match A. Git can merge all files without a textual conflict and still create a semantic failure.

Treat each branch as a claim bundle:

A clean diff is useful. It is not proof of compatibility.

The dependency-aware integration pipeline

The pipeline has a rollback edge by design. A failed integration is not a reason to improvise directly on the candidate until tests turn green. Return to a known checkpoint, repair the branch that owns the broken contract, and preserve the evidence that exposed the gap.

1. Freeze every worker at a stable checkpoint

Do not begin integration from active, dirty worktrees. Each worker should provide a focused commit or an explicitly named patch based on a known revision.

For every branch, record:

## Worker checkpoint
- Task: avatar API contract
- Branch: `agent/avatar-api`
- Commit: `4d31...`
- Base: `origin/main@a13f...`
- Working tree: clean
- Produces: OpenAPI schema, server behavior, error codes
- Depends on: storage decision 0017
- Evidence: `scripts/validate-api avatar` — PASS, 18 tests
- Not run: generated clients, browser flow
- Residual risk: multipart mapping differs across generators

Verify the state rather than trusting the summary:

git -C ../worktrees/avatar-api status --short
git -C ../worktrees/avatar-api rev-parse HEAD
git -C ../worktrees/avatar-api merge-base HEAD origin/main
git log --oneline origin/main..agent/avatar-api
git diff --check origin/main...agent/avatar-api

If the tree is dirty, ask the worker to create a coherent checkpoint or explicitly list the uncommitted paths and why they cannot yet be committed. “Mostly done” is not an integration unit.

2. Verify handoffs before touching the integration branch

A handoff gate rejects branches whose claims cannot be reconstructed.

The integrator should be able to answer:

• What user-visible or contract-level outcome does this branch claim?
• Which exact commit contains it?
• Which files or interfaces are authoritative?
• Which upstream state did the work assume?
• Which checks passed, and what did each check prove?
• Which relevant checks were omitted?
• Which downstream branch depends on this output?
• What is the safe recovery checkpoint?

A branch that changes a public schema but omits the generated clients is not necessarily incomplete. It may be a valid producer checkpoint. The handoff must state that boundary so the next gate does not mistake omission for proof.

Use a clean reviewer or agent session for high-risk changes. If it cannot reconstruct the claim from repository state and the handoff, repair the handoff before integration.

3. Build the dependency graph from contracts

List what each task produces and consumes. Paths alone are not enough because two non-overlapping directories may share a schema, event, database, or generated artifact.

A — avatar API
  produces: OpenAPI schema, server behavior, error codes
  consumes: media-storage decision

B — generated clients
  produces: TypeScript and Python clients
  consumes: A's OpenAPI schema

C — web UI
  produces: browser upload flow
  consumes: B's TypeScript client, A's error semantics

D — documentation
  produces: public examples
  consumes: final CLI and API behavior

The resulting order is:

A -> B -> C -> D -> final outcome proof

Some work may be independent. A telemetry change can integrate beside A only if it does not alter the same runtime contract, configuration, migration, or test fixture. Mark independence explicitly instead of inferring it from different filenames.

A useful integration ledger is:

The graph is the merge plan. Completion notifications do not rewrite it.

4. Create a reproducible integration branch

Start from an exact clean base and keep worker branches intact until final verification passes.

git switch main
git fetch origin
git status --short
git switch -c integration/avatar-upload origin/main
git rev-parse HEAD

Record the base commit in the integration log. If origin/main moves while integration is active, decide explicitly whether to finish against the recorded base or rebuild the candidate on the newer revision. Do not silently mix bases midway.

Before the first merge, write the expected order and gates:

## Integration plan
- Base: `origin/main@a13f...`
- Candidate: `integration/avatar-upload`
- Order: API -> clients -> UI -> docs
- Conflict owner: integrator; contract owners consulted as needed
- Gate after API: focused contract suite
- Gate after clients: deterministic regeneration + compile
- Gate after UI: typecheck + component suite
- Final gate: upload smoke, migration/rollback if relevant, clean tree

This turns integration into a reproducible procedure rather than a live editing session.

5. Integrate one dependency boundary at a time

Merge or cherry-pick according to the repository’s declared history policy. The important rule is to preserve a reviewable unit and run the corresponding boundary gate before adding the next branch.

git merge --no-ff agent/avatar-api
scripts/validate-api avatar
git status --short
git rev-parse HEAD

# Record candidate checkpoint: API accepted.

git merge --no-ff agent/avatar-client
scripts/generate-clients
scripts/check-generated-clean
scripts/validate-clients avatar
git status --short

# Record candidate checkpoint: clients match accepted API.

git merge --no-ff agent/avatar-ui
scripts/validate-web avatar

If the API gate fails, do not merge the client branch “to see whether it fixes things.” The failure belongs to the current boundary. Repair or reject that checkpoint first.

Merge commits vs cherry-picks

Both can be safe when policy is explicit:

Do not choose the method based on which command avoids the current conflict. Choose it before workers start or at the integration-plan gate.

6. Classify conflicts before resolving them

Git reports textual conflicts. The dangerous conflicts are often semantic and produce no markers.

Use five classes:

Textual conflict

Two branches edit overlapping lines. Resolve with the owner of the affected behavior, then rerun all checks covering that file.

Contract conflict

One branch changes a schema, function signature, event, CLI, or persisted format while another assumes the old version. The contract owner decides the accepted shape; consumers adapt to it.

Generated-output conflict

Generated files differ because branches used different source revisions or tool versions. Resolve the source-of-truth inputs, then regenerate. Do not hand-merge generated output.

Behavior conflict

Files merge cleanly but the combined runtime behavior is wrong: middleware order changes, migrations interact, or one fallback masks another failure. Add a boundary or outcome test that reproduces the problem.

Authority conflict

Branches implemented contradictory instructions or decisions. Stop integration and repair the canonical source. Code should not arbitrate which repository rule was meant to win.

Record every non-trivial resolution:

## Conflict decision — generated avatar client
- Class: generated-output conflict
- Cause: client branch used schema `7bd2...`; accepted API is `4d31...`
- Resolution: regenerate from `4d31...`; discard hand-edited generated diff
- Owner/source: `openapi/avatar.yaml`
- Proof: generation clean; TypeScript and Python clients compile
- Durable repair: task template now requires producer commit in generation tasks

The durable repair prevents the same conflict from returning with different agents.

7. Separate boundary gates from final outcome proof

A boundary gate proves that one dependency transition is valid. Final validation proves the combined behavior.

A robust final gate for the avatar example might be:

scripts/validate-api avatar
scripts/check-generated-clean
scripts/validate-clients avatar
scripts/validate-web avatar
scripts/smoke-avatar-upload
scripts/smoke-avatar-errors
scripts/verify-migration-forward
scripts/verify-migration-rollback
git status --short

The last command matters. Generators, formatters, and tests can leave changed tracked files. A passing suite with an unexplained dirty tree is not reproducible completion.

Do not run every possible test reflexively. Choose checks that cover the changed contracts and the final outcome. Record relevant checks that were not run and why.

8. Preserve rollback checkpoints

After each accepted boundary, record the candidate commit:

Base                 a13f...
API accepted         b821...
Clients accepted     c904...
UI accepted          e117...
Final candidate      f563...

If the UI gate fails after the first two branches passed, the last known-good candidate is c904.... Preserve the failed state for diagnosis, then rebuild or reset the integration branch according to repository policy.

A safe repair loop is:

1. preserve logs and the failed candidate identifier;
2. classify the failure and identify the owning branch or contract;
3. restore or recreate the candidate from the last known-good checkpoint;
4. repair the source branch, not only the combined tree;
5. update its handoff and evidence;
6. rerun the failed boundary gate;
7. rerun every downstream gate whose assumptions changed.

Never delete worker branches or worktrees before the final candidate passes. Cleanup is the last lifecycle stage, not a way to simplify a failed integration.

9. Produce a final integration handoff

The final record should let a reviewer reproduce the completion claim without reading worker chats.

# Integration handoff — avatar upload

## Outcome
Avatar upload supports JPEG and PNG up to 2 MB in the API and web client.
Public errors render correctly. Forward and rollback migrations pass.

## Candidate
- Branch: `integration/avatar-upload`
- Commit: `f563...`
- Base: `origin/main@a13f...`
- Working tree: clean

## Integrated checkpoints
1. `agent/avatar-api@4d31...` — API schema and service behavior
2. `agent/avatar-client@91c2...` — regenerated TypeScript/Python clients
3. `agent/avatar-ui@73af...` — web upload flow
4. `agent/avatar-docs@1b20...` — public examples

## Conflict decisions
- Generated clients were regenerated from accepted schema; no generated file was hand-merged.

## Evidence
- `scripts/validate-api avatar` — PASS, 18 tests
- `scripts/check-generated-clean` — PASS
- `scripts/validate-clients avatar` — PASS
- `scripts/validate-web avatar` — PASS
- `scripts/smoke-avatar-upload` — PASS, JPEG and PNG
- `scripts/verify-migration-rollback` — PASS
- `git status --short` — clean

## Not run
- Safari browser flow — no runner in this environment

## Residual risk
- Safari multipart behavior requires release-candidate verification.

## Rollback
Last known-good base is `a13f...`; integration checkpoints are recorded above.

The final handoff is also the input to code review, release automation, or a clean verification agent.

A copyable multi-agent integration checklist

# Coding-agent integration checklist

## Freeze
- [ ] every worker has a stable commit or named patch
- [ ] exact base revision is known
- [ ] worktrees are clean or dirty paths are explicitly listed
- [ ] outcomes, changed contracts, evidence, omissions, and risks are recorded

## Order
- [ ] producer and consumer contracts are mapped
- [ ] integration order follows dependencies, not finish time
- [ ] independent branches are explicitly justified
- [ ] one integrator owns conflicts and combined proof

## Prepare
- [ ] integration branch starts from an exact clean base
- [ ] merge or cherry-pick policy is declared
- [ ] boundary gate for each branch is written before integration
- [ ] rollback checkpoints and evidence location are defined

## Combine
- [ ] one dependency boundary is integrated at a time
- [ ] its gate passes before the next branch is added
- [ ] conflicts are classified before resolution
- [ ] generated outputs are recreated from canonical sources
- [ ] non-trivial decisions are recorded

## Verify
- [ ] worker claims still hold on the combined candidate
- [ ] contract boundaries pass compatibility checks
- [ ] build, static, migration, and generated-output checks cover affected surfaces
- [ ] representative user-visible outcome passes
- [ ] omitted checks and residual risks are explicit
- [ ] final working tree is clean

## Close
- [ ] final candidate commit and base are recorded
- [ ] integration handoff is complete
- [ ] lasting corrections moved to canonical repository controllers
- [ ] worker branches and worktrees remain until acceptance
- [ ] cleanup follows the repository retention policy

Common integration failures

Merging in completion order

The first “done” branch may consume a contract that has not stabilized. Use the dependency graph.

Trusting worker-green as candidate-green

Worker proof is scoped to the branch. Run combined checks after every dependency boundary and final outcome proof after all relevant branches land.

Resolving generated files by hand

This hides a disagreement in source inputs or generator versions. Resolve the source, pin the tool if needed, and regenerate.

Fixing every failure only on the integration branch

The worker checkpoint and handoff remain wrong, so the next integration repeats the error. Repair the owning branch or canonical source and update its evidence.

Reusing a moving main

The candidate’s base changes silently midway through the process. Record one base and make any rebase or rebuild a deliberate new integration attempt.

Deleting worktrees after local tests

The combined candidate can still fail. Preserve recoverable worker state until final acceptance.

Treating a merge conflict as an agent problem

Conflicts reveal missing ownership, dependency, or authority information. Resolve the immediate change, then repair the repository controller that should have prevented ambiguity.

When serial execution is cheaper

Do not run several writers merely because the tools are available. Serial execution is usually better when:

• every task depends tightly on the previous task’s evolving output;
• one contract owner must make frequent design decisions;
• the repository lacks focused validation at subsystem boundaries;
• build or runtime resources cannot be isolated;
• the change is small enough that coordination costs more than implementation;
• rollback cannot preserve intermediate states safely.

Parallelism helps when tasks have bounded write surfaces, stable producer-consumer contracts, and cheap executable gates. Otherwise it multiplies assumptions faster than it produces valid work.

Make integration a repository capability

A team should not reinvent this process in every agent chat. Put the stable contract in repository-visible sources:

## Multi-agent integration

- Every concurrent writer returns a stable checkpoint and evidence handoff.
- One integrator owns dependency order, conflict decisions, and final proof.
- Contract producers integrate before generated or runtime consumers.
- Every branch has a boundary gate; worker-green is not candidate-green.
- Generated output is regenerated from canonical sources, never hand-merged.
- Candidate checkpoints are recorded after each accepted boundary.
- Final readiness requires combined outcome proof and a clean tree.
- Worker state is retired only after acceptance or explicit preservation.

Detailed commands belong in a linked runbook or scripts. Root instructions should make the invariant discoverable and route agents to the executable workflow.

The integration branch is where claims meet

Multiple coding agents can produce useful work quickly, but their branches are only partial claims. Reliability appears when one integration process reconstructs those claims, orders them by dependency, tests every boundary, and proves the combined outcome from a reproducible checkpoint.

The durable operating model is simple: stable worker commits, evidence-rich handoffs, one dependency graph, one integrator, progressive gates, named rollback points, and final outcome proof.

repository-harness provides a starting structure for making task boundaries, validation contracts, durable context, and evidence handoffs visible to Claude Code, Codex, Cursor, and other coding agents.

Related pages

• How to Manage Multiple Coding Agents in One Repository
• Git Worktrees for Multiple Coding Agents
• Coding-Agent Handoff Template
• How to Resolve Merge Conflicts Between Coding Agents
• Repository Harness Patterns
• Coding-Agent Failure Modes
• How to Migrate an Existing Repository to a Coding-Agent Harness
• How to Audit a Repository for Agent-Readiness
• repository-harness on GitHub

FAQ

How should I integrate changes from multiple coding agents?

Freeze every worker at a stable commit, verify each handoff, build a dependency graph, integrate contract-producing branches before their consumers, run focused checks after each step, and finish with combined validation against the user-visible outcome. One designated integrator should own conflict resolution, rollback, and the final evidence record.

Should coding-agent branches be merged in the order they finish?

No. Completion order is a notification sequence, not a dependency sequence. Merge the branches that establish schemas, interfaces, migrations, or shared behavior before branches that generate or consume those contracts. Independent branches can be integrated in either order only after their scopes and assumptions are verified.

Do green tests on every agent branch prove the integrated change?

No. Worker tests prove local claims against each branch’s base and assumptions. Integration proof must exercise the combined candidate, including shared contracts, generated artifacts, cross-package builds, migrations, end-to-end behavior, and repository cleanliness after formatters or generators run.

Who should resolve conflicts between coding-agent branches?

A designated integrator should resolve conflicts with help from the owner of the affected contract. The last agent to finish should not automatically choose the resolution. Conflicts should be classified as textual, contract, generated-output, behavior, or authority conflicts before editing.

Should I merge or cherry-pick coding-agent commits?

Use the repository’s declared integration policy. Merge commits preserve task boundaries and branch context; cherry-picking works well for focused, independently reviewable commits and linear-history workflows. Avoid copying uncommitted files because that discards provenance, base revision, and reproducible rollback.

How do I roll back a failed multi-agent integration?

Create a named integration branch from an exact clean base, record the candidate after each accepted branch, and preserve worker branches until final proof passes. When a gate fails, reset or rebuild the integration branch from the last known-good candidate, repair the responsible worker branch, and rerun from that checkpoint.

What evidence should a multi-agent integration handoff contain?

Record the exact base, branches and commits integrated, dependency order, conflict decisions, commands and observed results, generated-output state, omitted checks, residual risks, final candidate commit, and rollback checkpoint. The evidence should let a clean reviewer reproduce the completion claim without the agents’ chat transcripts.