File Manifest Discipline
Two agents, one file, and a merge conflict that required manually reconciling 200 lines of Python. The fix is a single rule: check for file overlap before dispatching parallel agents.
Two parallel agents on the Foresight trading bot. Both were legitimate, independent-looking tasks. T1 was refactoring the asyncio event loop wiring in the main trading loop. T3 was fixing candle boundary detection logic — an isolated signal processing issue.
Neither agent knew what the other was doing.
Both PRs passed CI.
Merging them required manually reconciling 200 lines in adjacent sections of trader.py. T1 had restructured the async flow. T3 had added boundary logic inside the same function body. The changes were architecturally compatible, but syntactically interleaved — neither merge strategy could reconstruct what the combined code was supposed to look like without reading both PRs simultaneously and rebuilding the intent by hand.
The rebase took longer than either original task.
The Independence Test
Before dispatching any pair of parallel agents, run the independence test:
Do their task scopes overlap in any file?
If yes — they are not independent. Two agents editing the same file are competing for the same lines. Even if they are working on different logical concerns, the physical proximity in the file creates merge conflict surface area that grows with how active the codebase is.
The test is binary. Not "do they overlap significantly" — just "do they overlap." Partial overlap is still overlap.
The File Manifest Solution
Before dispatching any parallel agents, create an explicit ownership manifest. Every agent that touches the filesystem gets one.
Agent T1 — asyncio refactor
Owns: trader.py, scheduler.py
May read (not edit): strategy.py, config.py
Must NOT touch: candle_feed.py, momentum_strategy.py, tests/
Agent T2 — scoring improvements
Owns: strategy.py, scoring_utils.py
May read (not edit): trader.py (for interface contracts only)
Must NOT touch: trader.py (T1 owns this), scheduler.py, tests/
Agent T3 — candle boundary logic
Owns: candle_feed.py, momentum_strategy.py
May read (not edit): trader.py (for hook points only)
Must NOT touch: trader.py (T1 owns this), strategy.py (T2 owns this), tests/
Three agents, zero file overlap. Each agent knows exactly what it owns, what it can read for context, and what is off-limits.
The manifest is not overhead. It is the plan.
How to Add Manifests to Agent Prompts
Every agent prompt for parallel work gets a file ownership section:
## File Ownership
You own the following files. Make all changes only within these files:
- candle_feed.py
- momentum_strategy.py
You may READ but NOT EDIT these files for context:
- trader.py (interface contracts and hook points only)
You must NOT touch any other file. If your task requires editing
a file not listed above, STOP and report back. Do not proceed.
The final sentence is load-bearing. Without it, agents interpret scope ambiguity as permission. With it, they surface the conflict before creating it.
The Overlap Check Before Dispatch
Before dispatching, list every file each agent will likely touch and check for overlaps. This can be a mental check for simple tasks or a literal list for complex ones:
# Before dispatching T1 and T3, list their scopes:
# T1: trader.py, scheduler.py
# T3: trader.py ← OVERLAP on trader.py
# Decision: sequence T1 and T3, not parallelize
# OR: re-decompose to eliminate the overlap
The check is cheap. The conflict it prevents is not.
Why Worktrees Do Not Solve This
The instinct when you hear "parallel agents" is to reach for git worktrees. Worktrees are excellent tools — they let multiple agents work on the same repo simultaneously without stepping on each other's unstaged changes.
They do not prevent file manifest conflicts.
A worktree isolates the working directory. Both T1 and T3 can edit trader.py in separate worktrees without a runtime collision — the OS has no conflict because the files are in different directories. The branches diverge cleanly.
The conflict is a logical conflict, not a filesystem conflict. It arrives at merge time, not sooner. By then, both agents have completed their work, both PRs have been reviewed, and the merge is the moment you discover that two independent reviewers approved two incompatible changes to the same function body.
Worktrees prevent runtime collisions. File manifests prevent logical conflicts. Use both. They are not substitutes for each other.
Re-Decomposing to Eliminate Overlap
When file overlap blocks parallelism, the right question is not "should I sequence or accept the conflict?" The right question is: "Why do these tasks overlap at all?"
T1 (asyncio wiring) and T3 (candle boundaries) both touched trader.py because both tasks had a dependency on the main trading loop. That was the wrong decomposition boundary.
A better decomposition would have separated by system boundary instead of by feature:
Agent A — main loop and scheduling (trader.py, scheduler.py)
Agent B — signal processing and boundaries (candle_feed.py, momentum_strategy.py, strategy.py)
The asyncio refactor and candle boundary fix both fit within their respective system boundaries without overlap. The parallelism is preserved. The conflict never exists.
File overlap is often a signal that the decomposition was drawn across the wrong dimension. Before sequencing, ask whether re-decomposing by file ownership would produce a cleaner split that preserves parallelism.
Lesson 176 Drill
Take the last multi-agent task you dispatched (or plan to dispatch). For each agent:
- List every file it needs to edit — not read, edit.
- Check every pair of agents for file overlap.
- For any overlap: are the tasks truly independent, or does the overlap signal that the decomposition boundary is wrong?
If there is overlap: sequence the conflicting agents, or re-decompose by file ownership. Write the manifest before the next dispatch.
The five minutes you spend on the manifest is not process overhead. It is how you buy back the hours you would otherwise spend in a merge conflict.