diff --git a/docs/multi-agent-worktree.md b/docs/multi-agent-worktree.md new file mode 100644 index 0000000..54ce934 --- /dev/null +++ b/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 +```