---
name: spawn-codex-worker
description: "Use when dispatching a validated Sprint Contract to a Codex CLI worker in an isolated git worktree. Triggers after write-sprint-contract + braid validate pass."
---

# Spawn Worker

## Preconditions

- `$BRAID_ROOT/queue/<task-id>.yaml` exists
- `braid validate <task-id>` returned OK
- `$BRAID_TARGET_REPO` is set and points to a clean-enough target branch
- No active worker already owns an overlapping scope (check `braid status`)

## Process

### 1. Run spawn via CLI (do NOT tmux-send-keys directly)

```bash
braid spawn <task-id>
```

The CLI handles:
- `git worktree add $BRAID_WORKERS_DIR/<task-id> -b worker/<task-id>` (idempotent)
- Copy `queue/<task-id>.yaml` → `worktree/.sprint-contract.yaml`
- Copy `$BRAID_ROOT/templates/worker/AGENTS.md` → `worktree/AGENTS.md`
- Write worktree-local `.git/info/exclude` for infra files
- Launch `codex --profile <profile> exec --ephemeral ...` with reasoning-effort override
- Redirect stdin to `/dev/null` to prevent hang-on-completion
- Write `reports/<task-id>.exit` when worker finishes

### 2. Record and move on

Never babysit a single worker. After spawn:
- Note the task-id
- Check for overlapping-scope workers before dispatching the next
- Continue planning in parallel up to the parallelism cap (default 3)

## What you must NOT do

- Manually `tmux split-window` or `send-keys` — the CLI is deterministic
- Write the contract into the worktree yourself
- Launch `codex` directly — the CLI applies profile and exit-code capture
- Modify files inside the worktree after spawn — the worker owns it until report

## Readiness signal

A worker is considered finished when BOTH exist:
- `$BRAID_ROOT/reports/<task-id>.md`
- `$BRAID_ROOT/reports/<task-id>.exit`

Only then invoke `verify-worker-output`. If only `.md` exists, the worker is still writing (not atomic-committed yet) — wait.

## Failure modes

- **CLI exits non-zero on spawn**: contract validation or worktree conflict. Fix the contract, retry.
- **Worker appears stuck (no visible pane activity for long stretches)**: check the log (`braid logs <task>`); if truly hung, `tmux kill-pane` manually and write rework.
- **Report but no .exit**: crashed mid-write. Don't trust the partial report; treat as FAIL.