| name | Preventing Subagent Collisions |
| description | Prevent task duplication, file conflicts, and coordination failures when multiple subagents work in parallel on the same Superagent project. Covers both Superagent→Subagent coordination and Master Agent→Superagent worktree coordination. Uses manage_plan and manage_tasks as the coordination hub. |
| when_to_use | when spawning multiple subagents in parallel in the same project, when subagents might claim the same task or edit overlapping files, when coordinating parallel work using invoke_subagent or invoke_superagent, when multiple Superagents run in isolated git worktrees, when task.md needs to be shared across agents |
| version | 4.0.0 |
| languages | ["typescript","shell"] |
Preventing Subagent Collisions
Overview
Two separate collision scenarios exist in the 3-tier architecture. Both must be handled:
| Scenario | Tier | Risk |
|---|
| A — Subagent collision | Superagent → Subagents | Two subagents claim same task or edit same file within one worktree |
| B — Worktree collision | Master Agent → Superagents | Two Superagents in different worktrees both edit shared files (package.json, CHANGELOG.md, AGENTS.md), causing merge conflicts |
Core principle (both scenarios): The parent pre-assigns tasks AND file scopes before spawning. Shared files are never touched in parallel — always serialized.
Scenario A — Subagent Collision (Superagent tier)
The Coordination Model
| File | Purpose | Owner |
|---|
_implementation_plan.md | All tasks, file scopes, agent assignments | Parent (via manage_plan) |
_task.md | Active task checklist — status per task | Parent updates; subagents read only |
_task_history.md | Archive of completed tasks | Automatic |
Subagents do NOT call manage_plan or modify _task.md. They receive a pre-assigned task in their prompt and report back when done. Parent updates status via manage_tasks.
Plan Template with Agent Assignments
# Feature X Implementation Plan
## Proposed Changes
- [ ] [agent: researcher] Research existing auth patterns — src/auth/**
- [ ] [agent: coder-a] Implement JWT middleware — src/auth/jwt.ts, src/auth/middleware.ts
- [ ] [agent: coder-b] Implement billing service — src/billing/**, tests/unit/billing/**
- [ ] [agent: reviewer] Review and test all changes — tests/**, docs/**
## Shared Files (Read-Only for Parallel Agents)
- src/types/index.ts
- src/config/constants.ts
- package.json
If an agent needs to modify a shared file: STOP and report to parent.
## Verification Plan
### Automated Tests
`bun test`
### Manual Verification
Verify no conflicts in git log.
Spawn with fileScope
Use fileScope parameter — auto-injects ## FILE SCOPE (Enforced) into subagent system prompt structurally:
invoke_subagent(typeName: "coder", role: "coder-a", prompt: "...",
fileScope: ["src/billing/**", "tests/unit/billing/**"])
invoke_subagent(typeName: "coder", role: "coder-b", prompt: "...",
fileScope: ["src/auth/**", "tests/unit/auth/**"])
fileScope is strongly preferred over prose — it cannot be forgotten by the parent.
Monitor and update status:
manage_subagents(action: "list")
manage_subagents(action: "report", conversationIds: [...])
manage_tasks(action: "update", index: 2, status: "/") // spawned
manage_tasks(action: "update", index: 2, status: "x") // done
Scenario B — Worktree Collision (Master Agent tier)
This is the most common source of silent merge conflicts. Multiple Superagents in isolated git worktrees each try to modify shared repo-level files — the worktree itself is clean, but merge fails.
Files That Must NEVER Be Modified Inside a Worktree
These files are shared across all worktrees and must only be written by the Master Agent AFTER all branches are merged:
| File | Why |
|---|
package.json | Version bump → merge conflict if two worktrees both bump |
CHANGELOG.md | Both agents prepend an entry → conflict at top of file |
AGENTS.md | Shared project rules → concurrent edits collide |
README.md | Same section updated by two agents → conflict |
.env.example | Config templates → format conflicts |
| Any root-level config | Single source of truth — serialize writes |
Superagent Worktree Constraint
A Superagent inside a worktree MUST:
- ✅ Implement its feature (code files, tests, docs for that feature)
- ✅ Include in final report: what changed + what version/changelog entry SHOULD say
- ❌ NOT bump
package.json version
- ❌ NOT write to
CHANGELOG.md
- ❌ NOT modify
AGENTS.md or README.md
- ❌ NOT run
git push or git tag
If a Superagent discovers it must modify one of these files: STOP. Report to Master Agent with the proposed change. Master Agent serializes it after merge.
Master Agent Post-Merge Sequence (Strictly Sequential)
After merge_superagents completes for all branches:
1. Collect changelog entries from all Superagent reports
2. bun run build → verify clean build on merged main
3. bun test → verify all tests pass
4. Bump version in package.json (ONE time, after all merges)
5. Prepend all changelog entries to CHANGELOG.md (ONE write)
6. Update AGENTS.md if needed (ONE write)
7. Commit: "chore: release vX.X.X"
8. git_worktree prune — clean up merged worktrees
Never interleave these steps with remaining merges. One branch at a time, then post-work once.
Master Agent Plan Annotation for Worktrees
## Proposed Changes
- [ ] [agent: auth-superagent, branch: feat/auth] Implement JWT auth — src/auth/**
- [ ] [agent: billing-superagent, branch: feat/billing] Implement billing — src/billing/**
## Worktree Shared Files (Post-Merge Only — Master Agent Handles)
These files must NOT be modified by any Superagent worktree:
- package.json (version bump)
- CHANGELOG.md (entry to be collected from agent reports)
- AGENTS.md
## Verification Plan
### Automated Tests
`bun test`
### Manual Verification
Run `bun run build` on merged main. Verify no conflicts.
Serialization Gates
| Operation | When | Who |
|---|
bun install / deps install | BEFORE spawning | Parent once |
| DB schema migrations | BEFORE spawning | Parent once |
git pull --rebase | BEFORE spawning | Parent once |
merge_superagents / git merge | AFTER all done | Master Agent |
package.json version bump | AFTER all merges | Master Agent only |
CHANGELOG.md update | AFTER all merges | Master Agent only |
AGENTS.md / README.md edits | AFTER all merges | Master Agent only |
| Deploy / publish | AFTER version commit | Master Agent |
Task Status in _task.md
| Status | Meaning | Who Sets It |
|---|
[ ] | Pending | Parent at plan creation |
[/] | In-progress | Parent when agent spawned |
[x] | Completed | Parent when agent reports done |
Quick Reference
Problem Solution
──────────────────────────────────────────────────────────────────
Two subagents pick same task → Pre-assign in plan + prompt before spawning
Subagent edits wrong file → Use fileScope param in invoke_subagent
Shared file conflict (subagent) → Declare read-only in plan; agent stops + reports
Worktree merge conflict → Never touch package.json/CHANGELOG in worktrees
Parent loses track of progress → manage_subagents(action: "list") + manage_tasks list
Superagent bumped version → Revert in worktree; Master Agent does it post-merge
npm install conflicts → Run BEFORE spawning
Common Mistakes
❌ Superagent bumps package.json version inside worktree
Two Superagents both bump version → merge conflict in package.json every time.
Fix: Superagents report what the version change SHOULD be. Master Agent does ONE bump post-merge.
❌ Superagent writes to CHANGELOG.md inside worktree
Two agents both prepend an entry → conflict at top of file.
Fix: Superagent includes changelog entry text in its final report. Master Agent collects and writes once.
❌ Letting subagents self-assign from _task.md
Two agents read the same [ ] task and both start working on it.
Fix: Assign tasks explicitly in prompt. Agents never self-assign.
❌ Subagents calling manage_tasks or manage_plan
Concurrent writes to _task.md corrupt the file.
Fix: Only parent calls manage_plan and manage_tasks.
❌ Spawning agents sequentially with wait: true
Loses all parallelism benefit.
Fix: Issue all invoke_subagent calls in one turn (wait: false), then monitor with manage_subagents.
❌ Merging branches mid-run
Mid-run merge introduces commits parallel agents didn't see → conflicts.
Fix: Merge only after ALL agents finish.
❌ Not using fileScope param
Parent forgets to include scope in prose → subagent touches wrong files.
Fix: Always pass fileScope: [...] to invoke_subagent. It is auto-injected structurally.
Integration
Pairs with:
master-agent-orchestration — orchestration workflow for Master Agent tiersuperagent-planning — use manage_plan to create assignment-annotated plansusing-git-worktrees — worktree lifecycle managementdispatching-parallel-agents — when to dispatch; use THIS skill for coordination
