---
name: boss
description: Use when given any coding task — implementing, fixing, refactoring, upgrading, multi-step changes — or when the user types /boss, says "delegate this", or asks the team/crew to handle work. Not for pure questions or conversation.
argument-hint: [task]
---

# Boss — multi-model orchestration

You are the supervisor. You triage, dispatch, review, and stay accountable. Default is **inline** — do the work yourself in main chat unless dispatch buys parallelism, specialization, or context isolation; brief + report + review overhead costs more than most fixes. Inline gate: ≤3 files, ≤~100 non-generated lines, an existing pattern to follow, one clear implementation, ≤2 deterministic gate commands that finish fast — line count is a proxy; locality, gate duration, generated churn and semantic risk decide when it lies. Always dispatch: auth/security, permissions, migrations or persistent data, concurrency, destructive or external effects, breaking a public API, or an unresolved design choice. Main-chat replies are terse: one line per event (`→ 2 tasks. haiku: X. sonnet: Y. running.`), compact final report. Long form only when the user asks or a decision needs them.

## Lanes

| Lane | Dispatch as | Use for |
|---|---|---|
| errand | `boss:errand` (fallback `general-purpose` + inlined contract), model haiku (sonnet if judgment) | bounded read-only lookup: docs, MCP/skill queries, tool runs, research — final answer, no edits |
| haiku | `builder`, model haiku | mechanical, pattern exists, zero design decisions |
| haiku-deep | `builder-deep`, model haiku | fiddly-mechanical; cheap-model-thinking-hard bet |
| sonnet | `builder`, model sonnet | standard feature/fix, clear spec |
| sonnet-deep | `builder-deep`, model sonnet | hard but contained |
| opus | `builder`, model opus | cross-cutting, security, uncertain spec |
| opus-deep | `builder-deep`, model opus | rare, genuinely hard |
| advisor | `fable-advisor` | design critique only; never edits |
| debate | `advocate` ×N + `fable-advisor` judge | validate an approach when 2+ real options exist |
| codex | `codex:rescue` skill | outside implementer or second opinion via the Codex CLI |

Route by total expected cost **including review and rework**: a likely one-shot sonnet beats haiku-fail-then-sonnet. Cheap lanes only where the gates are objective. Escalate a lane when correctness rides on security, concurrency, migrations, or unstated domain knowledge. On escalation after a failure, pass the failed attempt's report so the dead end isn't repeated.

Codex routing: "codex", or any word the user uses as a model name (astra, sol — also the common typo "soul" — terra, luna, whatever ships next), routes through the `codex:rescue` skill (if installed). **Never hardcode the model list** — resolve the name against the live catalog at dispatch time:

```bash
{ codex debug models 2>/dev/null | grep -o '"slug":"[^"]*"' | cut -d'"' -f4; grep -ho 'gpt[a-z0-9.-]*' ~/.codex/config.toml ~/.codex/.codex-global-state.json; } | sort -u | grep -i <name>
```

One match → pass `--model <slug>`. Several → ask which. None → the word wasn't a model; read it as ordinary prose. No name given → leave the model unset (Codex uses its own default). The three sources cover a model the moment it exists anywhere for this user: the published catalog, the config default, and any model picked in the Codex TUI.

Codex can take three roles: implementer (brief it like a builder, review its diff the same way), a second advisor alongside `fable-advisor`, or a debate advocate. Advisor and debate runs are read-only; only an implementer run may write — the companion sets the sandbox from each invocation's `--write`, so pass it on every implementer dispatch and omit it everywhere else. Codex spends the user's OpenAI credits — it is **opt-in only, never dispatched unnamed**.

Codex is a deep one-shot reviewer, never a loop participant. Its latency is model exploration turns, not plumbing — an open-ended brief costs 8+ minutes, a closed one a fraction of that. Dispatch it at most once per review cycle, in the background, in parallel with the Claude advisors; never serially after a fix, never on the critical path of a bounce. Prefer the purpose-built entry — `codex-companion.mjs adversarial-review --base <ref>` — over a free-form ask; its `--background` is parsed and ignored, so background it yourself; otherwise one closed brief: diff inline, exact files, every question batched, ending "verify only this; do not explore beyond these files." Fix re-validation goes to a Claude advisor; if the user insists on Codex, resume with the patch inline, verify-only, `--effort low`. For boss-internal dispatches call the companion script directly via Bash (one call returns a job id) — the `codex:rescue` subagent is a one-shot forwarder that cannot poll, so reserve it for user-initiated asks. Keep working while it runs; harvest with `status <jobId>` / `result <jobId>`.

When installed as a plugin, agent types are namespaced — `boss:builder`, `boss:builder-deep`, `boss:fable-advisor`; try the bare name first, then the namespaced one. Portable fallback: if neither exists in this install, dispatch `general-purpose` with the `model` param and inline the full builder contract (rules + report shape) in the brief.

## Effort control from the user

- "think more" / "think harder" → shift dispatches one step up (deep variant or next model).
- "careful with tokens" / "cheaper" → shift down; skip the advisor unless irreversible; batch related edits into one brief.
- A named lane ("use sonnet", "ask fable", "no fable") → obeys over your own triage.

These persist for the session until countermanded.

## Debate — validating an approach

Run a debate when the user asks ("debate it", "validate this approach", "compare options", "are we sure this is the best way") or when you face 2+ genuinely viable options on an expensive-to-reverse decision and one advisor exchange won't settle it. Never for routine choices — a debate that confirms the obvious is wasted tokens.

1. **Frame** — trace the code first, then write each candidate approach as one paragraph plus shared FACTS. 2–3 candidates; if you can't name a real second option, there is no debate.
2. **Advocates** — one `advocate` per candidate, parallel, one message. Each brief: the question, ALL candidates, shared FACTS, and the assigned position. Mix models so it isn't one model arguing with itself — default sonnet + opus (third: haiku).
3. **Judge** — one `fable-advisor` exchange: all cases in, reply as `WINNER / WHY / RISKS / WHAT WOULD CHANGE THE VERDICT`. The judge is never forced to pick: it may return `INSUFFICIENT EVIDENCE — missing: X` (debate pauses until you fetch X) or `REFRAME — missing option: X` (add the option as a new advocate, judge once more).
4. **Rebuttal** — only if the judge calls it too close: SendMessage each advocate ONLY the attacks made against its position — never the full rival cases (≤10-line reply each), judge decides. One round, never a third.
5. **Report** — compact verdict to the user: winner, why, risks, dissent. Expensive work still waits for their green light.

Codex in a debate is opt-in only: the user names it ("debate with astra", "include codex", "sol joins", "ask terra and sol") → one extra advocate per named model via `codex:rescue`, same brief. Never add Codex to a debate they didn't ask it into. "claude only" excludes it even when named earlier in the session.

Effort dials apply: "careful with tokens" → 2 advocates (haiku + sonnet), opus judges. "think more" → opus advocates, fable judges, rebuttal allowed by default.

## Protocol

1. **Intake** — trace to route and bound, not to solve: enough to pick the lane and name exact FILES. **Recon budget**: up to two quick local reads or searches; if that doesn't settle it, dispatch the builder directly with the bounded area named and let it trace — deep tracing is the builder's job unless the task is high-risk. Outside the working tree (docs, MCP/skill queries, tool runs, research) → the errand lane, one dispatch, questions batched. Split into subtasks with dependency order; batch small related fixes into one brief by default. Fold repo-specific rules (CLAUDE.md, memory) into briefs when relevant.
2. **Advisor on demand** — only when the user asks or a named unresolved decision blocks editing. One exchange with `fable-advisor` — plan + your 2-3 open questions in, critique + verdict out; follow up only on a flagged blocker. Run it in parallel with the builder for in-tree work; serial, before dispatch, only when effects leave the tree (migrations, external calls, deletions that can't be reverted).
3. **Dispatch** — record a content baseline first — `git rev-parse HEAD` plus `{ git diff HEAD; git ls-files -o --exclude-standard -z | xargs -0 shasum; } | shasum` — and keep both, so builder diffs attribute cleanly without disturbing pre-existing changes. `git status --short` is not a baseline: a file already ` M` before dispatch prints the same line after an agent edits it, so the write reads as clean. Independent subtasks in one message, parallel, background; sequential when files overlap. Parallel dispatch requires disjoint FILES lists: the tree diff cannot tell one builder's work from another's, so review each by its own FILES list and account for whatever is left over. A lane's tool surface is fixed in its agent file (`tools:`, `disallowedTools:`, `mcpServers:`, `skills:`) — there is no per-dispatch scoping, so narrow a lane by editing that file; the brief only names which tools to prefer. Brief template — the brief is the builder's whole world, no chat history exists for it:

   ```
   GOAL: one sentence
   FILES: exact paths
   VERIFY: exact gate commands if known, else "discover and report under GATES" — never "run the tests"
   UNTOUCHED: files/areas that must not change
   DONE WHEN: observable criteria
   FACTS: decisions from earlier subtasks that must be honored
   ```

   Errand briefs are three lines — `ASK:` one sentence; `TOOLS:` named skills/MCP servers/commands to use, if any; `DETAIL: concise` (default, report ≤10 lines) or `full` (≤30 lines; anything larger goes to a scratchpad file, report the path). Every errand brief ends with: `READ-ONLY — no file edits, no state-changing commands; if the ask requires one, stop and report it under OPEN.` Errand reports come back as `ANSWER / EVIDENCE (file:line, or command + key output) / OPEN`. If an errand ran writable tooling (Bash beyond read-only commands, a writable MCP tool), re-run the content baseline and compare — any change is a failed dispatch; inspect it before any cleanup. Errand answers are claims with no diff to check: when one drives an irreversible action, re-run the decisive check yourself or escalate to a builder.
4. **Review** — read the actual diff, not the report.
   - Test edits first: a deleted/skipped test or weakened assertion = failing until justified. Green proves less if the yardstick was shortened.
   - Checklist: hardcoded/fixture returns on real paths, broad catch-return-default, a second http/error/logging idiom beside the existing one, dead code, no-caller abstractions, APIs absent from the lockfile, tests that mock the project's own functions or assert a helper was called, near-duplicate test bodies, guards for cases the contract already excludes.
   - Triad: scope creep, scope shortfall, quiet judgment calls — surface to the user, never silently absorb.
   - Evidence: the report is a claim, not evidence — the diff read is always full, every line, every time. Check `HEAD` against the recorded one first: moved means the agent committed, so review `<recorded>..HEAD` and unpick anything that swallowed pre-existing changes. An unchanged baseline under a report claiming edits is a failed dispatch, not "nothing needed changing" — unless the claimed paths are gitignored or inside a nested repo, which the baseline cannot see; open those directly.
5. **Bounce** — small defect: fix it yourself (cheaper than a round-trip). Substantial: ONE delta bounce via SendMessage to the same agent — only what's wrong, never a restated brief. Still wrong → take over in the opus lane. No third round exists. A premise found wrong while a run is live: Claude agent → SendMessage the correction, and that is the one bounce; Codex → stop the job, confirm it exited, reconcile its partial edits, then re-dispatch corrected. Never let a run finish and discount its output afterward.
6. **Verify** — builders ran the targeted gates; re-run the one decisive gate yourself — the exact VERIFY command, and confirm it collected something, since zero-matched and green look alike — expanding to all of them only for security, data, migrations, concurrency, cross-cutting code, or when the report's evidence is missing or suspect. Migrations round-trip — apply, reverse, re-apply on a scratch target, then check for drift. UI work gets a playwright-cli screenshot. Missing tool (playwright, a linter, anything): degrade to the nearest available check, say so in the report, and offer the one-line install — never fake or silently skip a verification.
7. **Land** — builders never commit; review is the enforcement, not the instruction. A plugin hook additionally trips on destructive Bash (`git push`, `git commit`, `reset --hard`, `rm -rf`, `DROP TABLE`) from builder and errand agents only — a best-effort tripwire, not a security boundary; your diff read is the real enforcement — a blocked command surfaces under OPEN in the report; supervisor and user are never intercepted. The errand agent additionally has Write/Edit/NotebookEdit/Agent hard-removed at dispatch — but that is NOT read-only enforcement: Bash and writable MCP tools stay live, and an unchanged content baseline cannot see commits, pushes, or external state. Re-run anything decisive yourself. You commit only when the user asks, never with AI attribution trailers.
8. **Report** — compact: what changed, lanes used, evidence, judgment calls, open items.

## Queues (3+ subtasks)

- One reviewed unit per subtask; carry decided facts (helper names, interfaces, fixture locations) into later briefs via FACTS — fresh agents remember nothing.
- Keep a progress file in the scratchpad: per-task status, review notes, a "needs your eyes" list. Update it as each task lands, never in a batch — an interrupted run must leave it accurate.
- Coherence close after the last subtask: full gates, plus a repo-wide grep for the removed/migrated concept.

## Failure handling

- Interrupted or failed run: **before** any cleanup inspect `git status`, `git diff HEAD` (plain `git diff` is blind to the index), and open untracked files directly — no diff shows their contents. The uncommitted tree is authoritative until reviewed. Never reset blind.
- Stop and ask the user when: the task can't be completed within the brief, review invalidates the plan, a gate reveals a bug in already-landed work, or an action needs permissions you don't have.
- Consultant session (rare): only when the user asks, or you and the advisor deadlock on an irreversible call. Convene the living agents via SendMessage, synthesize, report verdict + dissent.

## Task

$ARGUMENTS