From bd98a19662d0ff13de24aa3b1d41bf309bd8b308 Mon Sep 17 00:00:00 2001
From: Kpa-clawbot <259247574+Kpa-clawbot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 21:18:45 -0700
Subject: [PATCH] =?UTF-8?q?docs:=20add=20rule=2013=20=E2=80=94=20git=20wor?=
 =?UTF-8?q?ktree=20isolation=20for=20parallel=20agents?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 AGENTS.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1d316028..11a8f1e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,6 +97,27 @@ When opening a pull request, the description must be **valid, readable markdown*
 ### 12. Post a follow-up comment when review feedback is addressed
 When you push fixes for review comments, post a comment on the PR listing what was changed and the commit hash. Reviewers should not have to dig through commits to find what was fixed. Format: "Review feedback addressed (commit `abc1234`)" followed by a numbered list of what was done.
 
+### 13. Use git worktrees for parallel work — never pollute the main checkout
+Multiple agents work in parallel. The main clone (`C:\Projects\meshcore-analyzer\`) must stay on `master` and never be modified directly.
+
+**Implementation agents** must create a dedicated worktree before making any changes:
+```bash
+git worktree add _wt-<branch-name> -b <branch-name> origin/master
+cd _wt-<branch-name>
+# ... do all work here ...
+```
+After PR is merged, clean up: `git worktree remove _wt-<branch-name>`
+
+**Review agents** must NEVER read files from the working tree. Use git commands to read the remote branch directly:
+```bash
+git fetch origin <branch>
+git show origin/<branch>:<path/to/file>      # read a specific file
+git diff origin/master..origin/<branch>       # see the full diff
+```
+The working tree may have a different branch checked out. Reading it will give you wrong code.
+
+**Periodic cleanup**: run `git worktree prune` to remove stale worktree references.
+
 ## MeshCore Firmware — Source of Truth
 
 The MeshCore firmware source is cloned at `firmware/` (gitignored — not part of this repo). This is THE authoritative reference for anything related to the protocol, packet format, device behavior, advert structure, flags, hash sizes, route types, or how repeaters/companions/rooms/sensors behave.