parallel-workstream-coordination
verifiedc880661e-0698-45b1-9e2e-d54ac0c9febd
Split work into non-overlapping parallel streams, track each, and merge without conflicts. Use when multiple agents/threads work on one repo simultaneously.
Metadata
Skill file
# Parallel Workstream Coordination
Use when multiple agents or threads work on the same repo at the same time. The
entire discipline is about **non-overlapping ownership** and **merge order** —
conflicts are a coordination failure, not an inevitability.
## 1. Partition by ownership boundary
Before anyone starts, draw the file→owner map. No two streams may own the same
file.
```text
# Workstream map (must be written down and shared)
Stream A (auth): src/auth/*, tests/test_auth*.py, migrations/004_add_users*
Stream B (billing): src/billing/*, tests/test_billing*.py
Stream C (docs): docs/*, README.md
Shared (read-only): src/contracts.py <- everyone READS, nobody edits
```
Rules:
- **One owner per file.** If a stream must change a file owned by another, that is
a re-plan, not a "let's both edit it and see."
- **Shared-but-read-only files** — the contract/schema/interface file that
everyone imports but nobody edits during the parallel phase.
- **Write the map down** and share it. An unshared map is no map.
## 2. Isolation tactics
| Tactic | When | How |
|---|---|---|
| **Separate branches** | Default | each stream on its own branch: `git checkout -b stream/auth` |
| **Separate modules** | New code in distinct dirs | each stream creates new files under its own namespace |
| **Shared read-only contract** | Streams must interoperate | freeze `src/contracts.py`; change it only in a separate, sequenced step |
```bash
git checkout -b stream/auth main
# ... work in src/auth/ only ...
git push -u origin stream/auth
```
## 3. Merge discipline — one integrator, smallest-first
1. **One integrator.** Exactly one person/agent does the merging. Parallel merges
by multiple integrators is how you get a broken main.
2. **Merge smallest-first.** The smallest stream merges first; larger streams
rebase on top. This minimizes the conflict surface for everyone.
3. **Re-run full tests after each merge.** Do not batch merges and test once at
the end — the failure could come from any of them.
```bash
# Integrator, for each stream (smallest first):
git checkout main
git merge --no-ff stream/docs # smallest
pytest -q # full suite after EACH merge
git merge --no-ff stream/auth
pytest -q
git merge --no-ff stream/billing
pytest -q
```
## 4. Handling the inevitable conflict
When a merge conflicts (it will, occasionally):
```bash
git merge stream/auth
# CONFLICT in src/contracts.py
git diff --name-only --diff-filter=U # list conflicted files
# Resolve each, then:
git add src/contracts.py
git commit
pytest -q # re-verify after resolution
```
The conflict resolver should **ask the file's owner** for intent when the correct
resolution is not obvious — do not guess on someone else's file.
## 5. Before you start parallel work — checklist
```text
[ ] File→owner map written and shared with every stream.
[ ] No two streams own the same file.
[ ] Shared read-only files identified and frozen.
[ ] Each stream has its own branch.
[ ] One integrator named; merge order agreed (smallest-first).
[ ] Full test suite confirmed green on main BEFORE any parallel work.
```
## Guardrails
- Do **not** let two streams edit the same file. Re-plan before that happens.
- Do **not** let multiple agents merge — one integrator only.
- Do **not** merge everything at the end into a conflict pile; merge incrementally,
smallest-first, re-testing after each merge.
- Do **not** start parallel work on a red main. Fix main first.
- Do re-run the full suite after *each* merge, not once at the end.
## Pitfalls
- **Overlapping edits** — two streams "just adding a line" to the same file is a
guaranteed conflict and a merge headache.
- **Merge pile at the end** — saving all merges for the last day produces an
unresolvable conflict cluster.
- **Multiple integrators** — two agents merging different branches into main
simultaneously produce a broken, interleaved history.
- **Skipping the shared read-only contract** — streams each change the interface
file and then nothing interoperates.
- **One test run for many merges** — you merge 5 branches, run tests once, they
fail, and you cannot tell which branch broke it.
## Verify / Checklist
- [ ] File→owner map is written down and shared; no shared ownership.
- [ ] Each stream works on its own branch, in its own files/modules.
- [ ] Shared files are frozen read-only during the parallel phase.
- [ ] Main was green before parallel work started.
- [ ] Merges happen smallest-first by a single integrator.
- [ ] Full test suite re-run (and green) after every individual merge.
- [ ] Conflicts are resolved by asking the file's owner, not guessing.Attached files
No attached files.