v3.0.0 to v4.0.0
132 added, 150 removed. Audit A to A.
---
name: Preventing Subagent Collisions
- description: Prevent task duplication, file conflicts, and coordination failures when multiple subagents work in parallel on the same Superagent project. Uses the existing manage_plan and manage_tasks system as a shared 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 task.md needs to be shared across agents
- version: 3.0.0
+ 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
- Superagent's `manage_plan` and `manage_tasks` tools already provide a shared task system via `_task.md`. The problem: when multiple subagents run in parallel and both read `[ ]` tasks, they claim the same task simultaneously.
+ Two separate collision scenarios exist in the 3-tier architecture. Both must be handled:
- **Core principle:** The parent agent pre-assigns tasks to specific subagents BEFORE spawning. Each subagent owns a named slice — never picks tasks on its own. No claiming race. No collision.
+ | 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.
+
---
- ## The Coordination Model
+ ## Scenario A — Subagent Collision (Superagent tier)
- Superagent's existing files serve as the coordination layer:
+ ### The Coordination Model
| File | Purpose | Owner |
|------|---------|-------|
- | `_implementation_plan.md` | Single source of truth: all tasks, file scopes, agent assignments | Parent (via `manage_plan`) |
- | `_task.md` | Active task checklist — status per task | Parent updates; subagents read |
+ | `_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 use `manage_plan` or modify `_task.md` directly. They receive a pre-assigned task in their prompt and report back when done. The parent updates `_task.md` status via `manage_tasks`.
-
- ---
-
- ## Pre-Spawn: Parent Assigns Tasks in the Plan
+ 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`.
- Before calling `invoke_subagent` or `invoke_superagent`, the parent must build the plan with **explicit agent assignments** in each task:
+ ### Plan Template with Agent Assignments
```markdown
# Feature X Implementation Plan
## Proposed Changes
- - [ ] [agent: researcher] Research existing auth patterns in codebase — src/auth/**
+ - [ ] [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 Agents)
- The following files can only be READ — not written — by parallel agents:
+ ## 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, it must STOP and report to the parent.
+ If an agent needs to modify a shared file: STOP and report to parent.
## Verification Plan
-
### Automated Tests
- `npm test`
-
+ `bun test`
### Manual Verification
- Verify all tasks complete with no conflicts in git log.
- ```
-
- Create this via `manage_plan`:
- ```json
- { "action": "create", "planContent": "..." }
+ Verify no conflicts in git log.
```
- ---
-
- ## Agent Prompt Template
+ ### Spawn with fileScope
- Every subagent prompt MUST include:
+ Use `fileScope` parameter — auto-injects `## FILE SCOPE (Enforced)` into subagent system prompt structurally:
```
- You are the [role] agent for this session.
-
- ## Your Assigned Task
- [Exact task description from the plan]
-
- ## Your File Scope
- You may ONLY read and write these files:
- - [file list from plan]
-
- ## Shared Files (Read-Only)
- These files exist but you must NOT modify them:
- - src/types/index.ts
- - package.json
- If you need to change one, STOP and report to the parent.
+ 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/**"])
+ ```
- ## When You Are Done
- Report back with:
- 1. Summary of changes made
- 2. Files touched
- 3. Test results
- 4. Any blocked items
+ > `fileScope` is strongly preferred over prose — it cannot be forgotten by the parent.
- Do NOT call manage_plan or manage_tasks — the parent handles task status updates.
+ 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
+ ```
---
- ## Parent Workflow: Before → Spawn → After
+ ## Scenario B — Worktree Collision (Master Agent tier)
- ### Phase 1 — Sequential Pre-Work (Before Spawning)
- Run these ONCE before spawning any agents:
+ 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.
- ```bash
- # Install dependencies once
- npm install
+ ### Files That Must NEVER Be Modified Inside a Worktree
- # Run pending DB migrations
- npm run migrate
+ These files are shared across all worktrees and must only be written by the Master Agent AFTER all branches are merged:
- # Pull latest changes
- git pull --rebase origin main
- ```
+ | 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 |
- Then create the plan with pre-assigned tasks via `manage_plan`.
+ ### Superagent Worktree Constraint
- ### Phase 2 — Parallel Spawn
- Issue all `invoke_subagent` calls in one turn (parallel, not sequential).
+ A Superagent inside a worktree MUST:
- Use `fileScope` parameter to enforce file boundaries structurally — the tool
- auto-injects a `## FILE SCOPE (Enforced)` block into the subagent's system prompt:
+ - ✅ 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`
- ```
- invoke_subagent(typeName: "researcher", role: "researcher", prompt: "...researcher task...",
- fileScope: ["src/**", "tests/**"])
- invoke_subagent(typeName: "coder", role: "coder-a", prompt: "...billing task...",
- fileScope: ["src/billing/**", "tests/unit/billing/**"])
- invoke_subagent(typeName: "coder", role: "coder-b", prompt: "...auth task...",
- fileScope: ["src/auth/**", "tests/unit/auth/**"])
- ```
+ 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.
- > If `fileScope` is omitted, the parent MUST include file scope explicitly in the `prompt` prose.
- > Using `fileScope` is strongly preferred — it cannot be forgotten.
+ ### Master Agent Post-Merge Sequence (Strictly Sequential)
- Monitor with:
- ```
- manage_subagents(action: "list")
- manage_subagents(action: "report", conversationIds: [...])
- ```
+ After `merge_superagents` completes for all branches:
- Update task status as each agent reports in:
- ```json
- { "action": "update", "index": 2, "status": "/" } // in-progress
- { "action": "update", "index": 2, "status": "x" } // done
```
-
- ### Phase 3 — Sequential Post-Work (After All Agents Done)
- Run these ONCE after all agents have finished:
+ 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
+ ```
- - Merge branches (if using worktrees)
- - Bump version in `package.json`
- - Update `CHANGELOG.md`
- - Run full test suite: `npm test`
- - Deploy or publish
+ Never interleave these steps with remaining merges. One branch at a time, then post-work once.
- ---
+ ### Master Agent Plan Annotation for Worktrees
- ## Task Status in `_task.md`
+ ```markdown
+ ## Proposed Changes
- Superagent's `manage_tasks` uses three statuses — use them consistently:
+ - [ ] [agent: auth-superagent, branch: feat/auth] Implement JWT auth — src/auth/**
+ - [ ] [agent: billing-superagent, branch: feat/billing] Implement billing — src/billing/**
- | Status | Meaning | Who Sets It |
- |--------|---------|------------|
- | `[ ]` space | Pending / not started | Parent at plan creation |
- | `[/]` slash | In-progress | Parent when agent is spawned for this task |
- | `[x]` x | Completed | Parent when agent reports done |
+ ## 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
- The parent (not the subagent) always controls `_task.md`. This prevents race conditions from concurrent writes.
+ ## Verification Plan
+ ### Automated Tests
+ `bun test`
+ ### Manual Verification
+ Run `bun run build` on merged main. Verify no conflicts.
+ ```
---
- ## Shared Files Protocol
-
- Files declared read-only in the plan must NEVER be modified by a parallel agent. If an agent encounters a situation where it must modify a shared file:
-
- 1. Agent stops and reports: `"Blocked: need to modify src/types/index.ts (shared file). Awaiting parent instruction."`
- 2. Parent decides:
- - Serialize the change (do it before or after parallel phase), or
- - Assign it to one specific agent and update the plan
+ ## Serialization Gates
- Never silently edit a shared file. That is how the collision happens.
+ | 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 |
---
- ## Serialization Gates
+ ## Task Status in `_task.md`
- | Operation | Phase | Why |
- |-----------|-------|-----|
- | `npm install` / `pnpm install` | BEFORE spawning | Concurrent writes break node_modules |
- | DB schema migrations | BEFORE spawning | Sequential ordering required |
- | `git pull` / `git fetch` | BEFORE spawning | Avoid index conflicts |
- | `merge_superagents` / git merge | AFTER all done | No mid-run merges |
- | `package.json` version bump | AFTER merge | One writer at a time |
- | `CHANGELOG.md` update | AFTER merge | Concurrent writes cause conflicts |
- | Deploy / publish | AFTER merge | Non-idempotent operation |
+ | 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 agents pick same task → Parent pre-assigns tasks in plan before spawning
- Agent edits wrong file → File scope declared per task in plan
- Shared file conflict → Declared read-only in plan; agent reports if blocked
- Parent loses track of progress → manage_subagents(action: "list") + manage_tasks(action: "list")
- Agent finishes — what now? → Agent reports back; parent calls manage_tasks update + x
- npm install conflicts → Run BEFORE spawning, not inside each agent
+ 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
- **❌ Letting subagents pick their own tasks from task.md**
+ **❌ 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 the agent prompt. Agents never self-assign.
+ 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 the parent agent calls `manage_plan` and `manage_tasks`. Subagents only read and report.
+ Fix: Only parent calls `manage_plan` and `manage_tasks`.
**❌ Spawning agents sequentially with wait: true**
- Loses all parallelism benefit. Each agent waits for the previous one.
- Fix: Issue all `invoke_subagent` calls with `wait: false` in one turn. Then call `manage_subagents` to monitor.
-
- **❌ Running npm install inside each subagent**
- Concurrent writes corrupt `node_modules` and `package-lock.json`.
- Fix: Run install once in Phase 1 before any spawning.
+ Loses all parallelism benefit.
+ Fix: Issue all `invoke_subagent` calls in one turn (`wait: false`), then monitor with `manage_subagents`.
**❌ Merging branches mid-run**
- A mid-run merge introduces commits agents didn't see, causing conflicts.
- Fix: Merge only after all agents finish (Phase 3).
+ Mid-run merge introduces commits parallel agents didn't see → conflicts.
+ Fix: Merge only after ALL agents finish.
- **❌ Not marking tasks in-progress when spawning**
- Parent cannot tell which tasks are assigned vs still available.
- Fix: Set status to `[/]` via `manage_tasks` immediately when spawning an agent for that task.
+ **❌ 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` — this skill covers the coordination detail for Phase 2 parallel work
- - `superagent-planning` — use manage_plan to create the assignment-annotated plan
- - `using-git-worktrees` — each agent's branch; combine with this skill for file-level safety
- - `dispatching-parallel-agents` — use when to dispatch; use THIS skill to coordinate once dispatched
+ - `master-agent-orchestration` — orchestration workflow for Master Agent tier
+ - `superagent-planning` — use `manage_plan` to create assignment-annotated plans
+ - `using-git-worktrees` — worktree lifecycle management
+ - `dispatching-parallel-agents` — when to dispatch; use THIS skill for coordination
- `finishing-a-development-branch` — Phase 3 cleanup and merge