From f9f53b1bdebd8259d8804e8d65137159e2bf48a7 Mon Sep 17 00:00:00 2001
From: Ahmed Darrazi <ahmeddarrazi@adsmac.local>
Date: Sun, 21 Dec 2025 01:20:29 +0100
Subject: [PATCH] docs: Add multi-agent coordination workflow to prevent
 conflicts

- Session-based branch isolation strategy
- Before/during/after workflow steps
- Git worktree alternative for advanced users
- Emergency conflict resolution procedures
---
 Agents.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/Agents.md b/Agents.md
index 503d98a..7e9b794 100644
--- a/Agents.md
+++ b/Agents.md
@@ -33,6 +33,94 @@ ## Workflow (Spec Kit)
 
 If requirements change during implementation, update spec/plan before continuing.
 
+## Multi-Agent Coordination
+
+**Problem:** Multiple AI agents working simultaneously on the same branch can create conflicts and confusion.
+
+**Solution:** Each agent session works on its own isolated branch.
+
+### Before Starting Work
+
+1. **Check branch status:**
+   ```bash
+   git status
+   ```
+   Must be clean. If dirty, stash or commit first.
+
+2. **Note current state:**
+   ```bash
+   git log -1 --oneline
+   ```
+   Record the latest commit hash for reference.
+
+3. **Create session branch:**
+   ```bash
+   # From feature branch (e.g., 001-filament-json)
+   git checkout -b $(git branch --show-current)-session-$(date +%s)
+   ```
+   Example: `001-filament-json-session-1734789123`
+
+4. **Confirm isolation:**
+   ```bash
+   git branch --show-current
+   ```
+
+### During Work
+
+- Make commits normally on your session branch
+- Session branch is throwaway - commit messages can be informal
+- Run tests frequently to validate changes
+
+### After Completing Work
+
+1. **Switch back to feature branch:**
+   ```bash
+   # Get the original branch name (remove -session-timestamp suffix)
+   ORIGINAL_BRANCH=$(git branch --show-current | sed 's/-session-[0-9]*$//')
+   git checkout $ORIGINAL_BRANCH
+   ```
+
+2. **Merge session work:**
+   ```bash
+   SESSION_BRANCH=$(git branch | grep session | tail -1 | xargs)
+   git merge $SESSION_BRANCH --no-ff -m "merge: agent session work"
+   ```
+
+3. **Clean up session branch:**
+   ```bash
+   git branch -d $SESSION_BRANCH
+   ```
+
+### Alternative: Git Worktree (Advanced)
+
+For completely isolated work environments:
+
+```bash
+# Create worktree for session
+git worktree add ../TenantAtlas-session-$(date +%s) $(git branch --show-current)
+
+# Work in separate directory
+cd ../TenantAtlas-session-*
+
+# After completion, merge back and remove worktree
+cd /path/to/main/TenantAtlas
+git merge worktree-branch
+git worktree remove ../TenantAtlas-session-*
+```
+
+### Emergency: Undo Conflicting Changes
+
+If two agents accidentally worked on the same branch:
+
+```bash
+# Reset to before the conflict
+git log --oneline -10  # Find the safe commit
+git reset --hard <commit-hash>
+
+# Or stash conflicting changes
+git stash push -m "conflicting-agent-work-$(date +%s)"
+```
+
 ## Architecture Assumptions
 - Backend: Laravel (latest stable)
 - Admin UI: Filament