1 files changed, 104 insertions, 0 deletions
diff --git a/Omni/Agent/WORKER_AGENT_GUIDE.md b/Omni/Agent/WORKER_AGENT_GUIDE.md
new file mode 100644
index 0000000..f1f6f60
--- /dev/null
+++ b/Omni/Agent/WORKER_AGENT_GUIDE.md
@@ -0,0 +1,104 @@
+# Worker Agent Guide
+
+This guide describes how to run a headless Worker Agent using the Multi-Agent Workflow.
+
+## 1. Setup
+
+First, create a dedicated worktree for the worker:
+
+```bash
+./Omni/Agent/setup-worker.sh omni-worker-1
+```
+
+This creates `../omni-worker-1` sharing the same git history but with its own workspace and branch (`omni-worker-1`).
+
+## 2. Worker Loop
+
+The Worker Agent should run the following loop continuously:
+
+### Step 1: Sync and Find Work
+
+```bash
+# Go to worker directory
+cd ../omni-worker-1
+
+# Sync tasks from the live branch
+./Omni/Agent/sync-tasks.sh
+
+# Check for ready tasks
+task ready --json
+```
+
+### Step 2: Claim Task
+
+If a task is found (e.g., `t-123`):
+
+```bash
+# Mark in progress
+task update t-123 in-progress
+
+# Commit the claim locally
+./Omni/Agent/sync-tasks.sh --commit
+```
+
+### Step 3: Create Workspace
+
+**CRITICAL: Determine the correct base branch.**
+
+1.  **Check Dependencies**: Run `task deps t-123 --json`.
+2.  **Check for Unmerged Work**: Look for dependencies that have existing branches (e.g., `task/t-parent-id`) which are NOT yet merged into `live`.
+3.  **Select Base**:
+    *   If you find an unmerged dependency branch, check it out: `git checkout task/t-parent-id`.
+    *   Otherwise, start from fresh live code: `git checkout omni-worker-1` (which tracks `live`).
+
+4.  **Create Feature Branch**:
+    ```bash
+    git checkout -b task/t-123
+    ```
+
+### Step 4: Implement
+
+1.  Read task details: `task show t-123`
+2.  Implement changes.
+3.  **Run Tests**: `bild --test Omni/YourNamespace.hs`
+
+### Step 5: Submit for Review
+
+```bash
+# 1. Mark for review
+task update t-123 review
+
+# 2. Commit implementation
+git add .
+git commit -m "feat: implement t-123"
+
+# 3. Switch back to worker base branch to prepare for next loop
+# This detaches the worker from the task branch so the Planner can check it out
+git checkout omni-worker-1
+./Omni/Agent/sync-tasks.sh
+```
+
+## 3. Planner (Reviewer) Workflow
+
+The Planner Agent (running in the main repo) will:
+1.  See tasks in `Review` status (after checking out the worker's branch or waiting for them to be merged).
+    *   *Note: Since workers commit to local branches, you verify work by checking out their branch.*
+2.  Check out the worker's branch: `git checkout task/t-123`.
+3.  Review code and tests.
+4.  Merge to `live`:
+    ```bash
+    git checkout live
+    git merge task/t-123
+    # Conflicts in tasks.jsonl are handled automatically by .gitattributes driver
+    ```
+5.  Mark Done:
+    ```bash
+    task update t-123 done
+    git commit -am "task: t-123 done"
+    ```
+
+## Troubleshooting
+
+If `sync-tasks.sh` reports a conflict:
+1.  Manually run `task import -i .tasks/live-tasks.jsonl`
+2.  If git merge conflicts occur in `tasks.jsonl`, the custom merge driver should handle them. If not, resolve by keeping the union of tasks (or letting `task import` decide).