docs(agents): coordination protocol for parallel sub-agents

[bokelley]

Context

When kicking off parallel sub-agents, each agent needs to know which files the other agents are touching to avoid collisions. There's no template for this today, so agents stomp each other.

Acceptance Criteria

• Documentation section (in CLAUDE.md or new docs/agent-coordination.md)
• Example prompt template that includes "files other agents are touching"
• Checklist for spawning coordinated parallel work

Refs

• Observed during the comprehensive cycle (W2 ↔ W3 collisions)

[bokelley]

Triage

Classification: Feature request (docs)
Bucket(s): docs
Status: drafting-pr
Milestone: omitted

What the experts said:

• docs-expert: CLAUDE.md is the right location for this (not docs/); write-scope prompt template and imperative checklist fit the existing audience and style
• dx-expert: Execute — the pit of failure is agents silently overwriting each other with no error; write-scope partitioning in the prompt is the correct fix; git log --name-only is the right post-run verification command

My take: All three acceptance criteria are deliverable as a single non-breaking CLAUDE.md addition. The section installs the coordination contract at the only enforcement point available: the prompt passed to each agent at spawn time.

Drafting PR: adds ## Parallel Agent Coordination to CLAUDE.md with write-scope template, pre-spawn checklist (including dynamic-discovery handling and shared-file ownership), and post-run collision check.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01BojvrVjuAKWkJFda4dBMDU

---

Generated by Claude Code