docs/multi-agent-worktree.md

@@ -0,0 +1,57 @@
+# Multi-Agent Worktree Policy
+
+## Rule: Each Agent Session Gets Its Own Worktree
+
+To prevent conflicts when multiple agents work on the same repository:
+
+### Before Starting Work
+
+```bash
+# Create isolated worktree in /tmp
+WORKTREE_ID=$(date +%s)-$$
+WORKTREE_PATH="/tmp/infra-worktree-$WORKTREE_ID"
+
+git worktree add -b "agent/$WORKTREE_ID" "$WORKTREE_PATH"
+cd "$WORKTREE_PATH"
+
+# Do your work...
+git add .
+git commit -m "..."
+
+# Push when done
+git push origin "agent/$WORKTREE_ID"
+
+# Cleanup
+cd /opt/data/infra
+git worktree remove "$WORKTREE_PATH"
+```
+
+### Benefits
+
+- No branch conflicts between agents
+- Each agent has isolated working directory
+- Automatic cleanup after session
+- Easy to track which agent did what
+
+### For Hermes Agent
+
+Add to agent system prompt or skill:
+```
+Before modifying any git repository:
+1. Check if worktree already exists for this session
+2. If not, create one: git worktree add -b "agent/$SESSION_ID" /tmp/repo-worktree-$SESSION_ID
+3. Do all work in the worktree
+4. Push branch when complete
+5. Remove worktree on cleanup
+```
+
+### Manual Cleanup (if needed)
+
+```bash
+# List all worktrees
+git worktree list
+
+# Remove stale ones
+git worktree prune
+git worktree remove /tmp/infra-worktree-XXX
+```