# Spawn Workers

We're going to tackle tasks described as follows: $ARGUMENTS

## Workflow

### 1. Task Analysis
First, analyze the tasks to understand:
- What issue tracker issues are involved (use `pb show <id>` or `bd --no-db show <id>` for details)
- Dependencies between tasks (use `pb dep tree <id>` or `bd --no-db dep tree <id>`)
- Which tasks can run in parallel vs must be sequential

**Pay attention to parallelism** — if tasks are blocked by others, hold off on starting blocked ones. Only start as many tasks as make sense given coordination and potential file conflicts.

### 2. Spawn Workers

Use `spawn_workers` to create worker sessions. The tool handles worktree creation automatically (default behavior).

**Standard spawn (recommended):**
```python
spawn_workers(workers=[
    {"project_path": "/path/to/repo", "issue_id": "cic-123", "annotation": "Fix auth bug", "skip_permissions": True},
    {"project_path": "/path/to/repo", "issue_id": "cic-456", "annotation": "Add unit tests", "skip_permissions": True},
])
# Creates .worktrees/<name>-<uuid>-<annotation>/ automatically
# Branches isolated per worker, badges show issue ID + annotation
```

**Spawn Codex workers (for OpenAI Codex CLI):**
```python
spawn_workers(workers=[
    {"project_path": "/path/to/repo", "agent_type": "codex", "issue_id": "cic-123", "annotation": "Fix auth bug", "skip_permissions": True},
])
# Codex workers end responses with "COMPLETED" or "BLOCKED: <reason>"
```

**Spawn without worktree (work directly in repo):**
```python
spawn_workers(workers=[
    {"project_path": "/path/to/repo", "issue_id": "cic-123", "use_worktree": False, "skip_permissions": True},
])
```

**Key fields:**
- `project_path`: Path to the repository (required)
- `agent_type`: `"claude"` (default) or `"codex"` for OpenAI Codex CLI. **This field should not be specified unless explicitly requested by the user.** The default agent type is used unless override is required.
- `issue_id`: The issue ID (Beads or Pebbles; shown on badge, used in branch naming)
- `annotation`: Short task description (use the issue title for clarity)
- `skip_permissions`: Set `True` — without this, workers can only read files
- `use_worktree`: Set `False` to skip worktree creation (default `True`)
- `worktree`: Dict with optional `branch` and `base` fields for worktree control
  - `branch`: Explicit branch name (auto-generated if omitted)
  - `base`: The ref/branch to branch FROM. Without this, workers branch from HEAD
    (often main). Set this when subtask workers need commits from a feature branch.

**Branching from a feature branch (epic/subtask workflow):**

When working on an epic with subtasks, the epic has a feature branch. Subtask workers
should branch FROM that feature branch so they have prerequisite commits:
```python
# Epic feature branch: "cic-100/auth-epic"
# Subtask workers branch from it, not from main:
spawn_workers(workers=[
    {
        "project_path": "/path/to/repo",
        "bead": "cic-101",
        "annotation": "Add login endpoint",
        "worktree": {"base": "cic-100/auth-epic"},
        "skip_permissions": True,
    },
    {
        "project_path": "/path/to/repo",
        "bead": "cic-102",
        "annotation": "Add signup endpoint",
        "worktree": {"base": "cic-100/auth-epic"},
        "skip_permissions": True,
    },
])
# Both workers start with all commits from the epic branch.
# Without base, they'd branch from HEAD/main and miss prior work.
```

**What workers are instructed to do:** When given an issue ID, workers receive the
issue tracker workflow using the detected CLI (`pb` or `bd --no-db`):
1. Mark in progress: `pb update <issue-id> --status in_progress` or `bd --no-db update <issue-id> --status in_progress`
2. Implement the changes
3. Close issue: `pb close <issue-id>` or `bd --no-db close <issue-id>`
4. Commit with issue reference: `git add -A && git commit -m "<issue-id>: <summary>"`

### 3. Monitor Progress

**Waiting strategies:**

- `wait_idle_workers(session_ids, mode="all")` — Block until all workers finish. Good for batch completion.
- `wait_idle_workers(session_ids, mode="any")` — Return when the first worker finishes. Good for pipelines where you process results incrementally.

**Quick checks (non-blocking):**

- `check_idle_workers(session_ids)` — Poll current idle state without blocking. Returns which workers are done.
- `examine_worker(session_id)` — Detailed status of a single worker.

**Reading completed work:**

- `read_worker_logs(session_id)` — Get the worker's conversation history. See what they did, any errors, their final summary.

**If a worker gets stuck:**
- Review their logs with `read_worker_logs` to understand the issue
- Unblock them with specific directions via `message_workers(session_ids, message="...")`
- If unclear how to help, ask me what to do before proceeding

**Note on Codex workers:** Codex idle detection uses JSONL polling instead of Stop hooks. Check their output for "COMPLETED" or "BLOCKED: <reason>" status markers.

### 4. Completion & Cleanup

After each worker completes:
1. Review their work with `read_worker_logs(session_id)`
2. Verify they committed (check git log in their worktree)
3. If the work looks good but they forgot to close the issue:
   `pb close <id>` or `bd --no-db close <id>`
   If the work needs fixes, message them with corrections via `message_workers`

**When all tasks are complete:**
1. Review commits in worktrees
2. Terminate worker sessions: `close_workers(session_ids)` — removes worktree directories but keeps branches
3. Merge or cherry-pick commits from worker branches to main
4. Delete worker branches when done: `git branch -d <branch-name>`
5. Provide a summary:
   - Which issues were completed
   - Any issues encountered
   - Final git log showing commits

**Note:** `close_workers` removes worktree directories but preserves branches. Commits remain accessible until you explicitly delete the branch.

To see existing worktrees: `list_worktrees(repo_path)`
