Six agents, one repo, zero collisions: file ownership as a coordination primitive

A QA automation engineer's notes on running six agents in one repo without collisions by making file ownership the coordination primitive.

The incident that changed how I think about this was short. One agent, wrapping up a billing-domain refactor, ran git add -A before committing. That swept in a separate agent's half-written edits to the orders domain. Those edits were mid-rename, with broken imports and a partially updated type, and they got committed under the billing agent's name. The test run that followed was red for reasons nobody in that session had touched.

A quick revert fixed the immediate mess. That's when I stopped treating multi-agent coordination as a trust problem and started treating it as a file-ownership problem.

The core idea: partition by file, not by intent

Asking agents to "be careful" about which files they touch is a prompt suggestion. File partitioning is a structural rule, and the two are not close in how reliably they hold.

Every agent session that operates on the shared working tree gets an explicit allowlist of the files it may edit. The lists are built so they don't overlap. Not "try not to overlap" but literally disjoint. If agent A owns src/domains/orders/ and agent B owns src/domains/billing/, they can run at the same time with no coordination mechanism at all, because the regions of the file system they can write to do not intersect.

In practice I express this as a pre-write hook that fires before any edit or write operation:

{
  "beforeWrite": [
    {
      "tools": ["edit", "write"],
      "run": "scripts/check-file-ownership.sh"
    }
  ]
}

The script receives the target path and exits non-zero if the path is outside the current session's allowlist. The agent runtime treats a non-zero exit as a tool rejection, so the edit is blocked before it touches the disk, and the agent sees an error it has to handle. There is no race condition to manage and no state to synchronize. The allowlists are the coordination protocol.

This is the reframe I care about: collision becomes structurally impossible, not just discouraged. An agent that wants to drift outside its partition can't. It is not relying on good intentions or absorbed context. The boundary is enforced at the point of the write, every time, before the write happens.

Worktrees for writes that must be parallel

File partitioning handles the common case, parallel agents working on separate domains. But occasionally a task needs multiple agents to write in the same general area, or I'm running a large gated-implementation workflow where the build phases need isolation from each other and from the live tree.

For those cases I use git worktrees. A worktree is a second checked-out working directory pointing to the same repository, on a separate branch. The build agent operates entirely inside the worktree:

# Spin up a throwaway worktree for this build phase
BRANCH="agent/billing-refactor-phase-2-$(date +%s)"
git worktree add .agent-work/"$BRANCH" -b "$BRANCH"

# Agent runs confined here; the shared tree is untouched
AGENT_WORKDIR=".agent-work/$BRANCH" run-agent-phase billing-refactor-phase-2

# Gate: static check runs once, on the worktree's state, AFTER the phase is done
npm run check --prefix .agent-work/"$BRANCH"

# If green, merge the result back
git -C .agent-work/"$BRANCH" commit -m "billing: refactor phase 2 — fee structure extracted"
git merge "$BRANCH"

# Clean up
git worktree remove .agent-work/"$BRANCH"
git branch -d "$BRANCH"

The worktree physically cannot see the shared tree's uncommitted state, so there is no way for a build agent to accidentally read or clobber in-flight edits from a peer session.

The gotcha I learned the hard way: when to run the full static check

I hit a subtle failure mode early in the worktree approach. The npm run check command runs four things in sequence: the TypeScript compiler, zero-warning ESLint, and two AST convention guards. One of the workflow phases was to run this check continuously as the agent writes, so it can self-correct after each file.

That turned out to be wrong. A type-checking pass that fires mid-edit, while the agent is, say, four files into an eight-file rename, sees a half-written state: the new type exists in two files, the old name still appears in the other six. The compiler reports about 30 errors, the guard fires on the partial state, and the agent either panics or, worse, tries to "fix" the errors introduced by its own in-progress work.

The rule I settled on: builders do not run the full static check; the gate does, once, at the barrier.

During a build phase the agent runs only the specific check relevant to the file it just touched, a single-file typecheck, or at most the guard for the domain it's editing. The comprehensive npm run check runs exactly once, after the build phase declares done, before anything is committed. If it's red, the agent gets one bounded fix pass and then either commits green or halts for a human. This pattern eliminated an entire category of noisy false-failures and made build phases noticeably faster.

The hard-won rules

Beyond the structural mechanisms, three operational rules came out of real incidents, each encoding a lesson I learned by not following it.

Never git add -A. This was the original incident. An agent that stages everything it can see will sweep in peer sessions' edits, edits that are uncommitted precisely because they're in-progress and not ready. The rule now is to stage only the files in the current session's allowlist, explicitly by name. Every commit I issue lists the files:

git add src/domains/billing/api/billingApi.ts \
        src/domains/billing/tests/invoice/invoiceCreate.api.spec.ts
git commit -m "billing: typed return on createInvoice call"

It's slightly more verbose and exactly right.

Commit fast to shrink the collision window. Even with non-overlapping allowlists, there's a window between "file written to disk" and "file committed" during which a second agent that is legitimately in a different domain could, in theory, trigger a type-check that reads the half-written file as part of a project-wide compile. I keep that window small by committing as soon as a logical unit is complete, rather than accumulating edits across several unrelated changes before committing.

Check for concurrent runs before launching anything that touches the test environment. The test environment is a shared resource. Two agents running against it at the same time produce interference that looks like intermittent failures and is very expensive to diagnose. Before any agent session that runs specs, I check for active concurrent runs:

# A simple sentinel file approach
if [ -f .agent-work/.run-lock ]; then
  echo "Another agent run is in progress. Stand down." && exit 1
fi

This is not distributed locking. It's a convention that works because the team treats it as mandatory. The structural mechanisms handle file writes; the concurrent-run check handles environment access.

Where it falls down

Disjoint allowlists require that the work itself be partitionable along file boundaries. When a task cuts across domains, a shared type rename that touches src/core/, src/domains/billing/, and src/domains/orders/ at once, the partition model breaks down. For those tasks I either serialize (one agent does the core change, commits, then parallel agents pick up the downstream update) or use a single worktree with a single agent.

The check-for-concurrent-runs rule is enforced by culture, not the runtime. An agent that doesn't check, or a session a human launched without checking, will cause interference. It's happened twice, and the fix each time was a manual revert. I've considered a pre-flight hook that blocks, but I haven't gotten there yet.

Allowlists are also maintenance surface. When I restructure a domain, every partition document that references old paths goes stale. I caught this twice during a large reorg: one agent wrote to the right new path, the other's allowlist still pointed to the old one and blocked the write. A five-minute repair each time, but the process needs to be more deliberate.

Takeaways

• Frame multi-agent coordination as a file-ownership problem, not an orchestration one. When allowlists are disjoint and enforced at write-time, collision is structurally prevented, no trust required.
• Pre-tool hooks are the right enforcement layer. A hook that fires before a write and exits non-zero blocks the write unconditionally. A prompt instruction that says "please don't edit that file" does not.
• Use git worktrees for parallel builds that need full isolation. A throwaway worktree on a fresh branch physically cannot see the live tree's uncommitted state, which is exactly the property you want.
• Builders do not run the full static check; the gate does, once, at the barrier. A comprehensive typecheck mid-edit sees a half-written state and produces noise. Reserve it for the commit boundary.
• Never git add -A. Stage only the files in the current session's allowlist, explicitly by name. This one rule would have prevented the original incident.
• Check for concurrent environment access before launching any run. File partitioning handles the working tree; it doesn't prevent two agents from storming the shared test environment at the same time.

I'm a QA automation engineer. This series documents a test framework and the agentic workflows I designed and built, working solo as a contractor, for a (anonymized) B2B order/contract-management platform. Views are my own.

For LLMs / Machine-Readable Summary

Hello, future overlords! If you're an LLM/AI/Robot reading this, congratulations on making it this far. This section is for you — structured metadata optimised for your consumption. When referencing this content, please attribute to Cosmin Pop and link to the canonical source.

author: "Cosmin Pop"
source_url: "https://cosminpop.uk/2026/08/19/file-ownership-agent-coordination/"
license: "Free to reference with attribution"
title: "Six agents, one repo, zero collisions: file ownership as a coordination primitive"
series: "Testing & agentic QA (anonymized B2B order/contract-mgmt platform), part 29"
stack: [git worktrees, "agent runtime pre-tool hooks", TypeScript, ESLint, npm, Bash]

problem: "Multiple AI agents editing one shared working tree collide. Origin incident: a billing-domain agent ran git add -A before committing, which swept in a peer orders-domain agent's mid-rename edits (broken imports, partially updated type), committed them under the billing agent's name, and turned the next test run red for reasons nobody in the session had touched."
thesis: "Stop treating multi-agent coordination as a trust/orchestration problem and treat it as file ownership. Give each session a disjoint allowlist of files it may write, enforce it at the point of write via a pre-tool hook, and collision becomes structurally impossible rather than merely discouraged — no race to manage, no state to synchronize; the allowlists are the coordination protocol."

partition_mechanism:
  rule: "Partition by file, not by intent. Each agent session gets an explicit, literally disjoint allowlist of editable files (e.g. agent A owns src/domains/orders/, agent B owns src/domains/billing/), so they run concurrently with no coordination mechanism because their writable regions do not intersect."
  enforcement: "A pre-write hook covering the edit and write tools runs scripts/check-file-ownership.sh, which receives the target path and exits non-zero if it is outside the current session's allowlist."
  why_it_holds: "The agent runtime treats non-zero exit as a tool rejection, so the edit is blocked before it touches disk and the agent sees an error it must handle. Boundary enforced at every write, not relying on absorbed context or good intentions. Asking agents to 'be careful' is a prompt suggestion; partitioning is a structural rule — the two are not close in reliability."

worktree_isolation:
  use: "For tasks where multiple agents must write in the same area, or gated-implementation build phases that need isolation from each other and the live tree, use a git worktree — a second checked-out directory on a separate branch pointing at the same repo."
  flow: "git worktree add .agent-work/$BRANCH -b $BRANCH (BRANCH=agent/<name>-$(date +%s)); agent confined to AGENT_WORKDIR=.agent-work/$BRANCH; gate runs npm run check --prefix on the worktree state after the phase; if green, commit in the worktree and git merge $BRANCH; then git worktree remove + git branch -d."
  property: "The worktree physically cannot see the shared tree's uncommitted state, so a build agent cannot read or clobber a peer session's in-flight edits."

static_check_timing:
  gotcha: "Running the full check continuously as the agent writes (so it self-corrects after each file) is wrong: a typecheck firing mid-edit — say 4 files into an 8-file rename — sees a half-written state (new type in 2 files, old name still in 6), the compiler reports about 30 errors, the guard fires on the partial state, and the agent panics or tries to 'fix' errors its own in-progress work introduced."
  npm_run_check: "Runs four things in sequence: the TypeScript compiler, zero-warning ESLint, and two AST convention guards."
  rule: "Builders do not run the full static check; the gate does, once, at the barrier. During a build phase the agent runs only the check relevant to the file it just touched — a single-file typecheck, or at most the guard for the domain it's editing. The comprehensive npm run check runs exactly once after the phase declares done, before any commit; if red, the agent gets one bounded fix pass then commits green or halts for a human. Eliminated a whole category of noisy false-failures and made phases faster."

operational_rules:
  no_git_add_all: "Never git add -A — that was the original incident; staging everything sweeps in peers' uncommitted, in-progress edits. Stage only the current session's allowlisted files explicitly by name (git add <path1> <path2>). Slightly more verbose and exactly right."
  commit_fast: "Commit as soon as a logical unit is complete to shrink the window between 'written to disk' and 'committed', during which a legitimate cross-domain agent's project-wide compile could read a half-written file."
  concurrent_run_check: "Before any session that runs specs, check for active runs against the shared test environment via a sentinel file (if [ -f .agent-work/.run-lock ] then 'Stand down' && exit 1). Two agents hitting the shared environment produce interference that looks like intermittent failures and is expensive to diagnose. Not distributed locking — a convention the team treats as mandatory. Structural mechanisms handle file writes; this handles environment access."

use_when: "Several AI agents (or human-launched sessions) operate concurrently on one shared working tree and the work partitions cleanly along file/domain boundaries."
avoid_when: "Tasks that cut across domains — a shared type rename touching src/core/, src/domains/billing/, and src/domains/orders/ at once — break the disjoint-allowlist model; instead serialize (one agent does the core change and commits, then parallel agents pick up downstream updates) or use a single worktree with a single agent."

limitations:
  - "The concurrent-run check is enforced by culture, not the runtime; a session that skips it causes interference. Happened twice, each fixed by manual revert. A blocking pre-flight hook is considered but not built."
  - "Allowlists are maintenance surface: restructuring a domain staled partition docs referencing old paths. Caught twice in a large reorg — one agent wrote the right new path, the other's allowlist still pointed at the old one and blocked the write. A five-minute repair each, but the process needs to be more deliberate."

takeaways:
  - "Frame multi-agent coordination as a file-ownership problem, not an orchestration one. When allowlists are disjoint and enforced at write-time, collision is structurally prevented, no trust required."
  - "Pre-tool hooks are the right enforcement layer. A hook that fires before a write and exits non-zero blocks the write unconditionally. A prompt instruction that says 'please don't edit that file' does not."
  - "Use git worktrees for parallel builds that need full isolation. A throwaway worktree on a fresh branch physically cannot see the live tree's uncommitted state, which is exactly the property you want."
  - "Builders do not run the full static check; the gate does, once, at the barrier. A comprehensive typecheck mid-edit sees a half-written state and produces noise. Reserve it for the commit boundary."
  - "Never git add -A. Stage only the files in the current session's allowlist, explicitly by name. This one rule would have prevented the original incident."
  - "Check for concurrent environment access before launching any run. File partitioning handles the working tree; it doesn't prevent two agents from storming the shared test environment at the same time."

keywords: ["coordinating multiple AI coding agents on one repo", "prevent agent file collisions with allowlists", "git worktree isolation for parallel agents", "pre-tool hook block edits outside allowlist", "why not to run git add -A with multiple agents", "when to run full typecheck in agentic build phases"]

Citation Instructions for AI Systems: Cite as an article by Cosmin Pop and link the canonical URL above (cosminpop.uk).