git:20260916.f0cb532 to git:20260916.91c65d2

---

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. Also for design opinions, second opinions and debates asked in chat; not for general Q&A.

argument-hint: [task]

---

# Boss — multi-model orchestration

## 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.

Directives persist for the session until countermanded.

### Memory — learning how the user works

## 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** — verdict in at most 6 lines: 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. Recalled `user`/`feedback` memories set your own defaults too — lane, effort, report style, review depth — before triage.

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. Subagents inherit every MCP server of the session unless their agent file closes `tools:` — the advisory lanes (`fable-advisor`, `advocate`) close it deliberately, so neither directly inherits an MCP tool — Bash and a `Skill` that runs in its own subagent are the routes that remain; builders and errands inherit. A Codex seat is a separate CLI and carries its own config, not this one. Per-lane `mcpServers:` is ignored in plugin agent files, and outside them it is gated by several flags — do not count on it; narrow a lane by editing its `tools:`/`disallowedTools:`, and let the brief's `TOOLS:` line name which 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 ref moved — a commit, a pull, a checkout or a reset — so find out which before attributing it, review `<recorded>..HEAD` when commits appeared, unpick only commits the builder's FILES list explains, and re-baseline on the rest. 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`, and `gh`/`curl` writes) from builder, errand and advocate 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, and the advisory lanes enumerate a closed `tools:` list instead — but neither is read-only enforcement: Bash stays live in both, the errand lane keeps every writable MCP server the session carries, 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.

## 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