---
name: workit-fanout
description: Run independent slices in parallel - one worker per isolated worktree with a fixed brief and file-scope manifest, a non-author verifier per slice, results in the ledger. Use for fan out, parallelize, parallel agents, split the work, delegate, swarm.
---

# Fan out parallel workers

Inline-first (workspace `delegation`): fan out only past a threshold, named as
each slice's `reason` (explore, parallel, backstop, high-risk-verify): an
explorer past ~3 tool calls or 10k tokens; parallel writers only for 2+ disjoint
units of ~100+ lines each. Coupled work stays with one owner. Workit never spawns.

1. **Plan the slices** (read the `workit-shape` skill's SKILL.md and follow it) in a plan file (`references/brief.md`):
   per slice an id, branch, REASON, TIER, SCOPE globs, `owns` for shared files,
   `dependsOn` only for a real dependency, and the brief fields. `workit fanout
   plan <plan.json>` refuses an empty or placeholder brief field (exit 2) and
   two slices that may write one file (exit 3) with a fix; apply it and re-run:
   refuse to spawn while a field is empty or the plan is refused. One PR per
   slice is the default; `"fanIn": "integration"` only when the user wants one
   PR (`references/orchestration.md`).
2. **Record standing orders** (`workit ledger standing add "<order>"`): every
   user directive all workers share. Directives decay across resumes.
3. **Brief each worker verbatim**: `workit fanout worktree create <slice>`
   (every host), then `workit fanout brief <slice>` (WORKTREE, SCRATCH, rules).
   Never hand-edit it; change the plan or the standing orders and render again.
4. **Spawn in a rolling window**, in the background, each in its own worktree:
   keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
   each one finishes. Model: the brief's `model:` and `effort:` lines (`workit models show`),
   else TIER (`references/orchestration.md`). Claude Code: the `implementer` agent; its spawn hook drops
   `isolation` and refuses a prompt without the brief.
5. **Judge liveness by side effects only:** `workit fanout status` (head age,
   PR, CI, verdict, landed; STUCK past the TIMEBOX). Stop a stuck worker and
   observe that it exited (a timeout is not proof). Removing a worktree drops
   its uncommitted changes: `workit fanout worktree release <slice>` records
   `git status` in the ledger first and refuses them without `--force`. Never
   two live workers on one branch.
6. **Retry once, then escalate.** A stuck or failed slice gets one retry with
   a fresh brief (`workit fanout brief <slice> --mode resume`, same branch);
   if that fails too, re-slice it, take it over, or report the gap. Never
   chain resumes. A fix round and recheck that both fail: a decider, not a
   third round; product choices go to the user (`references/orchestration.md`).
7. **Verify by the workspace `verification` setting** (`workit grant show`).
   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused and full a verifier (Claude Code: the `model` and `effort` of `workit models show --role verifier`) after the last push; one verdict at a stack's top covers its unchanged lower PRs, and a stale one with `reverify: focused` re-checks only the new diff, reusing green CI. `self`: a verifier that wrote none
   of the slices, or you if you wrote none. `independent` or high risk: a
   separate verifier session, never yours (doctrine: the ledger only refuses
   authors). One verifier may take a batch of slices, one verdict per branch
   (`workit ledger verdict <result> --branch <b> --how "<evidence>"`), in a
   session never chosen by the author. Spawn it with the brief's `verifier:` model (`workit models show --role verifier`). A review panel on separate models only at high risk.
8. **Fan in** with `workit fanout check`: out-of-scope files (any file outside
   it stops the fan-in) and `git merge-tree` conflicts with trunk and between
   siblings. Fix what it names until it exits 0; a merged slice reads as
   landed. Then `workit ledger check --branch <b>` per slice, land in `fanout
   status` order, release the worktrees you made, and `workit ledger standing
   clear`. Only you touch topology: workers never rebase, retarget or merge,
   except the integration-tip merge in integration mode. Then ship
   (read the `workit-ship` skill's SKILL.md and follow it) up to `defaultEndpoint` from `workit grant show`.

## Example

Bad brief: "Do the API part and add tests." (no scope, no acceptance, no
verify command, so nobody can tell when it is done)

Good brief: the output of `workit fanout brief usage-endpoint`
(`references/brief.md` shows one).

## Check

```sh
workit fanout check                # exit 0: in scope, no conflicts, landing order printed
workit ledger check --branch <b>   # per slice: accepted (current, passing, independent)
```