# 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

# Update base branch with latest live code
# We use rebase to keep history linear (patch-based workflow)
# The custom merge driver handles tasks.jsonl conflicts during rebase
git fetch origin live
git rebase origin/live

# 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 fetch origin live && git checkout -b task/t-123 origin/live`.

4.  **Implement**:
    (Proceed to implementation)

### 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
 
 1.  **Update Status and Commit**:
     Bundle the task status update with your implementation to keep history clean.
 
     ```bash
     # 1. Mark task for review (updates .tasks/tasks.jsonl)
     task update t-123 review
 
     # 2. Commit changes + task update
     git add .
     git commit -m "feat: implement t-123"
     ```
 
 2.  **Signal Review Readiness**:
     Update the worker branch to signal the planner.
 
     ```bash
     # Switch to base branch
     git checkout omni-worker-1
     
     # Sync to get latest state
     ./Omni/Agent/sync-tasks.sh
     
     # Ensure the task is marked review here too (for harvest visibility)
     task update t-123 review
     
     # Commit this status change to the worker branch
     ./Omni/Agent/sync-tasks.sh --commit
     ```

    *Note: The Planner will now see 't-123' in 'Review' when it runs `harvest-tasks.sh`.*

## 3. Planner (Reviewer) Workflow

The Planner Agent (running in the main repo) will:
1.  **Harvest Updates**: Run `./Omni/Agent/harvest-tasks.sh` to pull "In Progress" and "Review" statuses from workers.
2.  **Find Reviews**: Run `task list --status=review`.
3.  **Review Code**:
    *   Check out the feature branch: `git checkout task/t-123`.
    *   **Rebase onto Live**: Ensure the branch is up-to-date and linear.
        ```bash
        git rebase live
        ```
    *   Run tests and review code.
4.  **Merge**:
    *   `git checkout live`
    *   `git merge task/t-123` (This will now be a fast-forward or clean merge)
5.  **Complete**:
    *   `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).