| name | parallel-agent-coordination |
| description | Use when multiple agents work in parallel, when PRs have merge conflicts from concurrent work, or when planning work that may overlap with other agents' in-flight PRs. |
| allowed-tools | Bash, Read, Grep, Glob |
Parallel Agent Coordination
The Problem
Multiple pod agents run concurrently in separate worktrees. When two agents
modify the same files (especially progress/items.json, progress/ entries,
or dependencies/), their PRs will conflict. The first to merge wins; the
second gets merge conflicts.
Conflict-Prone Files
These files are modified by many different tasks and are the most common
source of merge conflicts between concurrent PRs:
| File | Why it conflicts | Mitigation |
|---|
progress/items.json | Multiple agents update item statuses | Use atomic field updates, not full rewrites |
progress/*.md | Timestamp collisions (rare) | Include session UUID prefix in filename |
dependencies/internal.json | Dependency graph changes | Coordinate via issue dependencies |
PROGRESS.md | Summary updates | Only summarize agents should touch this |
Best Practices for Agents
1. Minimize shared file modifications
- Only update the specific fields you changed in
items.json
- Use your session UUID in progress filenames:
progress/<timestamp>_<UUID-prefix>.md
- Don't reformat or reorganize files you didn't need to change
2. Check for in-flight work before starting
coordination orient
Look at "Issues with open PRs" — if another agent has an open PR touching
the same files you plan to modify, consider:
- Waiting for that PR to merge first
- Working on a different item
- Making your changes compatible (additive only)
3. Rebase before creating PR
git fetch origin main
git rebase origin/main
This catches conflicts early. If conflicts exist, resolve them before
creating the PR — a PR with conflicts will never auto-merge.
4. When your PR has conflicts after creation
If coordination orient shows your PR has [CONFLICTS]:
- Fetch the latest main:
git fetch origin main
- Rebase:
git rebase origin/main
- Resolve conflicts (prefer the version on main for shared files like
items.json — then re-apply your specific changes on top)
- Force push with lease:
git push --force-with-lease
5. Planners: avoid creating overlapping work
When creating issues, check what's already claimed or has open PRs.
Don't create issues that would require modifying the same core files
as in-flight work unless the issues have explicit dependencies.
Progress File Convention
The _<UUID-prefix> suffix on progress files was introduced specifically
to prevent merge conflicts. Always use it:
progress/2026-03-16T08-15-00Z_1d7941eb.md # good — unique per agent
progress/2026-03-16T08-15-00Z.md # bad — may collide
Early progress files without UUID suffixes predate this convention.
