Add multi-agent isolation strategy using git worktrees

[don-petry]

Summary

• Adds a new Multi-Agent Isolation — Git Worktrees section to the org-level AGENTS.md
• Defines 6 core rules for running multiple AI agents concurrently without conflicts
• Covers tool-specific setup for Claude Code, GitHub Copilot, OpenAI Codex, Cursor, and manual worktrees
• Includes worktree naming conventions, environment/dependency guidance, cleanup rules, and a pre-launch coordination checklist

Why

Multiple agents working on the same repo were creating conflicting branches and stepping on each other's changes. Git worktrees are the industry-standard isolation primitive used by Claude Code, Cursor, Windsurf, Augment Intent, and dmux. This codifies the strategy so all agents and contributors follow the same rules.

Key rules

1. One workspace per agent
2. One agent per story/task
3. No overlapping file ownership (the most important rule)
4. Branch from the default branch only
5. One PR per workspace
6. 3–5 parallel agents max

Test plan

• Review the new section for clarity and completeness
• Verify worktree naming table matches actual tool behavior
• Confirm no conflicts with existing AGENTS.md sections

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive multi-agent isolation guidelines using Git worktrees: isolated workspaces per agent, one-agent-per-story/task mapping, serialization rules for shared files, and a recommended 3–5 parallel-agent cap.
  • Included branching/PR rules, worktree naming conventions, dependency/environment setup and cleanup guidance, tool-specific setup snippets, .gitignore recommendations, and a human coordination checklist.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b33201da-2880-49db-b510-5b18b48c1345

📥 Commits

Reviewing files that changed from the base of the PR and between 66a3bac and 2127bbb.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

Adds a "Multi-Agent Isolation — Git Worktrees" section to AGENTS.md specifying mandatory per-agent isolated workspaces, strict one-agent-per-story/task mapping, rules for branching and PRs, worktree naming conventions, tool-specific setup snippets, dependency handling, cleanup, and a human coordination checklist.

Changes

Cohort / File(s)

Summary

Documentation AGENTS.md

Added "Multi-Agent Isolation — Git Worktrees" section defining: isolated per-agent worktrees, one-agent-per-story/task mapping, prohibition of concurrent overlapping file edits (serialization for shared files), requirement to branch from the default branch (optionally origin/HEAD), exactly one PR per workspace, 3–5 parallel agent cap, detection guidance for file overlap, worktree/branch naming conventions tied to story/task IDs, tool-specific setup snippets (Claude Code subagents/CLI, manual git worktree usage), handling of environment/dependencies for fresh worktrees (including .worktreeinclude usage), .gitignore entries for worktree directories, cleanup rules for dirty worktrees and post-merge removal, and a human coordination checklist.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Addressing PR comments #1: Adds multi-agent worktree guidance to AGENTS.md that complements and overlaps with the isolation rules introduced here.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: adding a multi-agent isolation strategy using git worktrees to AGENTS.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/org-wide-agents-md

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds organization-level guidance to standardize how multiple AI agents (and humans) work concurrently in the same repo by using isolated workspaces—primarily Git worktrees—to prevent conflicting changes and overlapping file edits.

Changes:

• Adds a new “Multi-Agent Isolation — Git Worktrees” policy section with 6 core rules for concurrent agent work.
• Documents tool-specific setup patterns (Claude Code, Copilot coding agent, Codex, Cursor, manual worktrees).
• Provides naming, environment/dependency, cleanup, and coordination checklist guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Line 148: Add a short subsection to AGENTS.md after the existing rule 3 that
provides concrete guidance and lightweight tooling steps for detecting
file-overlap violations before running agents in parallel: create a "Detecting
File Overlap" heading and list quick checks such as reviewing each story's
acceptance criteria and implementation scope, using git commands like git log
--stat (or equivalent) to surface files touched by recent similar changes, and
fallback options (run stories sequentially or consult the team) to handle
uncertainty; ensure the new text is concise, actionable, and explicitly
recommends serializing stories if any overlap is detected.
- Around line 201-206: The fenced code block that lists files for the
.worktreeinclude entry is missing surrounding blank lines and a language
specifier; update the block showing ".env" and ".env.local" (the
.worktreeinclude example) to be a properly fenced block with a language token
(e.g., ```text) and ensure there is a blank line before and after the fenced
block so the list item and the following sentence ("After entering a
worktree...") render correctly.
- Around line 212-216: The markdown code block in AGENTS.md is missing
surrounding blank lines and the closing fence is malformed; update the section
that lists the cleanup commands so the fenced code block uses an opening fence
with language "```bash" on its own line, the two commands on separate lines, and
a closing "```" on its own line with a blank line before and after the block
(locate the snippet containing "git worktree remove <worktree-path>" / "git
branch -d <branch-name>" to apply the fix).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2f8566a6-4e01-4036-9de8-3a153247cc53

📥 Commits

Reviewing files that changed from the base of the PR and between a53c2fa and 66a3bac.

📒 Files selected for processing (1)

• AGENTS.md