From 772a7fff5bface407803e6a22e43c6f7bdd95b9f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 3 May 2026 02:45:05 +0000 Subject: [PATCH 1/2] docs(agents): add parallel agent coordination protocol to CLAUDE.md Adds write-scope partitioning pattern, prompt template, and pre-spawn checklist to prevent silent file-collision overwrites when spawning parallel sub-agents (observed as W2/W3 cycle collisions, issue #425). https://claude.ai/code/session_01BojvrVjuAKWkJFda4dBMDU --- CLAUDE.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index d2c06963..e2c5f83b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,6 +184,42 @@ git worktree remove /tmp/claude-issue-- **Branch naming:** always follow `claude/issue--` — branch-protection rules enforce this pattern and PRs from non-conforming names may be rejected. +## Parallel Agent Coordination + +When spawning parallel sub-agents, each agent must receive an explicit write-scope +declaration in its prompt. Without this, agents silently clobber each other's changes — +the second write wins with no error or warning. + +**Prompt template for a parallel sub-agent:** + +``` +Task: + +Read scope (consult freely): +- +- + +Write scope (the ONLY files this agent may create or modify): +- +- + +Do not edit files outside your write scope even if you believe the change +would be an improvement. Leave a note in your final reply if you spotted +something worth fixing outside your scope. +``` + +**Pre-spawn checklist:** + +1. Enumerate every file any agent in the group might write. +2. Partition that set so each file appears in exactly one agent's write scope. +3. Pass each agent its partition explicitly (see template above). +4. After all agents complete: `git diff --name-only` — any file written by more than + one agent signals a scope-partition error, not a merge conflict. + +**Why this matters:** The triage-prompt's concurrent-expert pattern +(Step 4 / Step 6 pre-PR review) already spawns two experts in parallel. If both +experts generate edits, only the write-scope contract prevents silent overwrites. +This pattern was introduced after observed W2/W3 cycle collisions (#425). ## Additional Important Reminders From ee7f303b3ac87776554ff22a94684d0f42dc200a Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 3 May 2026 02:46:56 +0000 Subject: [PATCH 2/2] docs(agents): fix blocker feedback on parallel agent coordination section - Use git log for collision check (git diff --name-only is ambiguous after commits) - Add "no globs" note on write scope - Add guidance for dynamic file discovery during execution - Add shared-file ownership rule for checklist - Drop misleading "was introduced after" rationale paragraph; replace with present-tense enforcement rule https://claude.ai/code/session_01BojvrVjuAKWkJFda4dBMDU --- CLAUDE.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e2c5f83b..08099dfc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,11 +184,12 @@ git worktree remove /tmp/claude-issue-- **Branch naming:** always follow `claude/issue--` — branch-protection rules enforce this pattern and PRs from non-conforming names may be rejected. + ## Parallel Agent Coordination When spawning parallel sub-agents, each agent must receive an explicit write-scope -declaration in its prompt. Without this, agents silently clobber each other's changes — -the second write wins with no error or warning. +declaration in its prompt. Agents do not detect or refuse out-of-scope writes at +runtime; this contract is the only enforcement mechanism. **Prompt template for a parallel sub-agent:** @@ -199,27 +200,27 @@ Read scope (consult freely): - - -Write scope (the ONLY files this agent may create or modify): +Write scope (the ONLY files this agent may create or modify — exact paths, no globs): - - Do not edit files outside your write scope even if you believe the change -would be an improvement. Leave a note in your final reply if you spotted -something worth fixing outside your scope. +would be an improvement. If you discover during execution that you need to write +a file outside your scope, stop and record it in your reply instead. ``` **Pre-spawn checklist:** -1. Enumerate every file any agent in the group might write. +1. List every file any agent in the group is expected to write. If an agent may + discover additional files during execution, note that in your scope planning — + do not silently expand the write scope at runtime. 2. Partition that set so each file appears in exactly one agent's write scope. + For files both agents need to write, assign one owner; have the other emit the + required change as a note in its reply. 3. Pass each agent its partition explicitly (see template above). -4. After all agents complete: `git diff --name-only` — any file written by more than - one agent signals a scope-partition error, not a merge conflict. - -**Why this matters:** The triage-prompt's concurrent-expert pattern -(Step 4 / Step 6 pre-PR review) already spawns two experts in parallel. If both -experts generate edits, only the write-scope contract prevents silent overwrites. -This pattern was introduced after observed W2/W3 cycle collisions (#425). +4. After all agents complete, check for collisions: + `git log --name-only --oneline -` (N = number of agent commits), then look + for the same file appearing in more than one entry. ## Additional Important Reminders