Multi-Agent Coordination: How to Run Three AI Agents Without Merge Conflicts

Table of content

Running one AI agent at a time creates a bottleneck. The agent writes code, you wait. It runs tests, you wait. It updates docs, you wait.

The fix: run three agents in parallel. One implements, one tests, one documents. They work simultaneously on different parts of your codebase while you review their outputs.

This guide shows how to do it: plan the interfaces, set up isolated workspaces, launch the agents, and merge their work.

Why Three Agents

Sequential	Parallel (3 agents)
Implement, then test, then document	All three simultaneously
45 minutes of waiting	15 minutes of parallel work
Context gets stale between phases	Fresh context throughout
One blocked agent blocks everything	Other agents continue

The constraint is file boundaries. Each agent needs exclusive ownership of specific directories. Overlap means merge conflicts and wasted work.

The Three-Agent Pattern

Kaushik Gopal’s Agentic Flow methodology uses three specialized agents:

Agent	Focus	Typical Paths
Implementer	Core logic	`src/`, `lib/`
Tester	Test coverage	`tests/`, `__tests__/`
Documenter	Docs and comments	`docs/`, `README.md`

Each agent assumes the others will complete their work. The Tester writes tests against interfaces the Implementer will create. The Documenter describes behavior that will exist once implementation finishes.

This parallel assumption works because you plan the interfaces upfront.

The Four-Phase Workflow

Phase 1: Plan

Before spawning any agents, define what each one will do.

Create a plan file:

# Feature: User Authentication

## Interfaces (shared contract)
- `AuthService.login(email, password) -> Token`
- `AuthService.logout(token) -> void`
- `AuthService.refresh(token) -> Token`

## Implementer tasks
- [ ] Create AuthService class in src/services/
- [ ] Implement JWT token generation
- [ ] Add refresh token rotation

## Tester tasks
- [ ] Unit tests for token generation
- [ ] Integration tests for login flow
- [ ] Edge case tests for expiration

## Documenter tasks
- [ ] API documentation in docs/auth.md
- [ ] Update README with auth setup
- [ ] Add code comments to public methods

The interface contract matters. All three agents reference it. Without agreed interfaces, the tester writes tests for methods that don’t exist and the documenter describes behavior that never gets implemented.

Phase 2: Set Up Workspaces

Each agent needs an isolated workspace. Use git worktrees:

# Create three worktrees from your main repo
git worktree add ../project-impl -b feature/auth-impl
git worktree add ../project-test -b feature/auth-test
git worktree add ../project-docs -b feature/auth-docs

Create an AGENTS.md file in the root that all worktrees share:

# AGENTS.md

## Current Feature: User Authentication

### Interface Contract
- AuthService.login(email, password) -> Token
- AuthService.logout(token) -> void
- AuthService.refresh(token) -> Token

### File Ownership
| Agent | Owns | Must Not Touch |
|-------|------|----------------|
| Implementer | src/services/auth.ts | tests/, docs/ |
| Tester | tests/auth/ | src/, docs/ |
| Documenter | docs/auth.md, README | src/, tests/ |

### Success Criteria
- All tests pass
- Documentation matches implementation
- No lint errors

This file serves as the single source of truth. Every agent reads it first.

Phase 3: Launch Agents

Use tmux to manage three sessions:

# Create a new tmux session with three windows
tmux new-session -d -s agents -n impl
tmux new-window -t agents -n test
tmux new-window -t agents -n docs

# Start Claude in each window
tmux send-keys -t agents:impl "cd ../project-impl && claude" Enter
tmux send-keys -t agents:test "cd ../project-test && claude" Enter
tmux send-keys -t agents:docs "cd ../project-docs && claude" Enter

# Attach to the session
tmux attach -t agents

Switch between windows with Ctrl+B then window number (0, 1, 2).

Give each agent its specific instructions:

Implementer:

Read AGENTS.md first. You are the Implementer.
Implement the AuthService according to the interface contract.
Only modify files in src/. Do not touch tests/ or docs/.
Commit when each method is complete.

Tester:

Read AGENTS.md first. You are the Tester.
Write tests for the AuthService interface contract.
Assume the Implementer will create the service at src/services/auth.ts.
Only modify files in tests/. Do not touch src/ or docs/.

Documenter:

Read AGENTS.md first. You are the Documenter.
Document the AuthService based on the interface contract.
Assume implementation will match the contract exactly.
Only modify docs/ and README. Do not touch src/ or tests/.

Phase 4: Verify and Merge

Once all agents finish, merge their work:

# Switch to main branch
cd ../project
git checkout main

# Merge each agent's branch
git merge feature/auth-impl --no-ff -m "feat: implement AuthService"
git merge feature/auth-test --no-ff -m "test: add AuthService tests"
git merge feature/auth-docs --no-ff -m "docs: document AuthService"

# Run the full test suite
npm test

If tests fail, you have two options:

Fix manually - Small issues, fix in main
Spawn a fixer agent - Larger issues, create a new worktree and have an agent fix the integration problems

Clean up after merge:

git worktree remove ../project-impl
git worktree remove ../project-test
git worktree remove ../project-docs
git branch -d feature/auth-impl feature/auth-test feature/auth-docs

Avoiding Merge Conflicts

Conflicts happen when agents touch the same files. Prevent them:

Strategy	Implementation
File isolation	Define exclusive paths per agent in AGENTS.md
Interface contracts	Agree on method signatures before implementation
Atomic commits	Small, frequent commits make conflicts easier to resolve
Review checkpoints	Check progress midway, not just at the end

The most common conflict: shared config files. If package.json needs updates for tests and implementation, assign one agent to handle it.

AGENTS.md Structure

A complete AGENTS.md file:

# AGENTS.md

## Project Context
Brief description of the codebase and conventions.

## Current Task
What we're building right now.

## Interface Contracts
```typescript
// Shared interfaces that all agents reference
interface AuthService {
  login(email: string, password: string): Promise<Token>;
  logout(token: string): Promise<void>;
  refresh(token: string): Promise<Token>;
}

Agent Assignments

Agent	Owns	Forbidden
Implementer	src/	tests/, docs/
Tester	tests/	src/, docs/
Documenter	docs/	src/, tests/

Shared Dependencies

Files multiple agents might need (handle carefully):

package.json - Implementer owns, others request changes
tsconfig.json - Do not modify

Success Criteria

All methods implemented
80%+ test coverage
API docs complete


## Common Mistakes

**Starting agents before planning.** Without interface contracts, agents make incompatible assumptions. Plan takes 10 minutes. Fixing conflicts takes an hour.

**Overlapping file ownership.** Two agents editing `utils.ts` guarantees conflicts. Make boundaries explicit.

**No sync points.** Check agent progress every 15 minutes. Catching divergence early is easier than fixing it after 45 minutes of parallel work.

**Skipping the verification phase.** Tests written against assumed interfaces often need adjustments. Budget time for integration fixes.

## When to Use Single-Agent Instead

Parallel agents add coordination overhead. Use a single agent when:

- Task is small (< 30 minutes)
- Files are tightly coupled
- You need real-time collaboration (pair programming style)
- The scope is unclear and will evolve during implementation

Parallel agents work best on well-defined tasks with clear file boundaries.

## Quick Reference

```bash
# Setup
git worktree add ../proj-impl -b feat/impl
git worktree add ../proj-test -b feat/test
git worktree add ../proj-docs -b feat/docs

# Launch (tmux)
tmux new-session -d -s agents -n impl
tmux new-window -t agents -n test
tmux new-window -t agents -n docs
tmux send-keys -t agents:impl "cd ../proj-impl && claude" Enter
tmux send-keys -t agents:test "cd ../proj-test && claude" Enter
tmux send-keys -t agents:docs "cd ../proj-docs && claude" Enter
tmux attach -t agents

# Switch windows: Ctrl+B, then 0/1/2

# Merge
git checkout main
git merge feat/impl feat/test feat/docs

# Cleanup
git worktree remove ../proj-impl ../proj-test ../proj-docs
git branch -d feat/impl feat/test feat/docs

Next: Kaushik Gopal’s Agentic Flow

Topics: ai-agents ai-coding workflow