@toolu/opencode 6.8.0

package/generated/skills/toolu--deep-research/SKILL.md

@@ -0,0 +1,51 @@
+---
+description: "Use when the ask is deep research that must end in a multi-source cited report — tells: \"deep research\", \"research report\", \"cited report\", \"survey the state of the art\", \"investigate thoroughly\". Picks guiding questions, then fans out per-question researchers combining exa-search and context7. NOT for quick single-fact or API lookups — the research-agent subagent handles those internally — and NOT for local codebase questions (the deep-explore subagent). Standalone knowledge workflow — not part of the build chain."
+name: toolu--deep-research
+---
+
+# Deep Research
+
+A standalone knowledge workflow — outside the build chain; its reports can feed `brainstorm` or `spec`. It exists because the expensive failure in research is not weak sources — it is aiming a whole fan-out at a misunderstood question. So the target is written down first, then the pipeline spends tokens. Do not wait for approval.
+
+Use the mandatory [Jev workflow](../../workflows/semantic-judgments.md) to rank
+retrieved excerpts, detect no answer, and judge claim/source support. Verify quotes and provenance with tools.
+
+## When this fires
+
+The user wants a real research deliverable: multi-source, verified, cited. Not a quick fact or API lookup — that stays with `research-agent` — and not a question about this codebase — that is `deep-explore`'s job. Every run is multi-agent by design; if the fan-out isn't warranted, the ask wasn't deep research.
+
+## How to run it
+
+Four phases, driven from the main thread. Workers run on sonnet, synthesis stays on the frontier tier — rubric: `plugins/toolu/skills/orchestrator/references/model-routing.md`.
+
+1. **Target (main thread).** Restate the topic in one sentence. Decompose it into guiding questions with sub-questions — 5 is the typical fan-out, 7 the hard cap (the orchestrator skill's parallel-agent guardrail is the reason). Name the assumptions and what is out of scope. Print the numbered question set, then run it immediately without waiting for approval. Do not open the host mapping's user-choice interface ([host-mapping.md](../../workflows/host-mapping.md)).
+2. **Research fan-out.** One `research-agent` (sonnet) per question, launched in parallel. Each researcher combines both engines per its routing table — `context7` for library/API/docs-shaped questions, `exa-search` for general web, topics, and URL crawls — with native fallback inherited. Override the agent's default depth per call: ask for a 10–15 sentence synthesis, up to 8 sources, and `Claim → source URL` pairs for the 2–3 load-bearing claims.
+3. **Verification wave.** One `research-agent` (sonnet) per finding set, prompted as an adversarial verifier: re-crawl up to 2 cited URLs per load-bearing claim (exa-search, native fallback) and return a per-claim verdict — confirmed / unsupported / source-unreachable. Unsupported claims are dropped or flagged in the report — never silently kept. If every researcher answered from training knowledge only (`Tools used: none`), skip the wave — nothing is crawlable — and banner the report "unverified — no live sources".
+4. **Synthesis + delivery (main thread).** Merge the verified findings into the report format below, write it under `docs/research/`, and give the user a TLDR in chat.
+
+**Failure semantics** — nothing fails silently: a researcher or verifier that returns nothing, errors, or is killed renders its section as `⚠ no findings returned` and is named as degraded in Reliability notes — never silently dropped, no automatic retry. Worst-case fan-out: 7 researchers + 7 verifiers = 14 subagents; typical ~10.
+
+## Report format
+
+Destination `docs/research/<slug>.md` — kebab-case slug from the topic. Create the directory if absent. On collision append a numeric suffix (`<slug>-2.md`); never overwrite an existing report unless the user explicitly asks.
+
+```markdown
+# <Topic>: Research Report
+
+> Date: <YYYY-MM-DD> · Questions: <n> · Scope: <one line>
+
+## TL;DR
+<the answer in ≤5 bullets>
+
+## <Guiding question 1>
+<verified synthesis; flagged claims marked ⚠ unverified>
+
+## Sources
+- <title> — <url>
+
+> Reliability notes: <per-claim verdicts; degraded workers; the unverified banner if no live sources were reachable>
+```
+
+## What "done" looks like
+
+A report at `docs/research/<slug>.md` with a TL;DR, one section per guiding question, real source URLs, and Reliability notes carrying the verification verdicts — plus the TLDR in chat. If targeting produced zero questions, "done" is: nothing ran and nothing was written.

package/generated/skills/toolu--execution/SKILL.md

@@ -0,0 +1,77 @@
+---
+description: Use when you have a reviewed plan to implement and, when delivery is authorized, carry verified changes through a PR handoff. Drives the plan step by step with evidence checkpoints and respects the quality gate. Native toolu workflow: spec → spec-review → plan → plan-review → execution → pr-babysit.
+name: toolu--execution
+---
+
+# Execution
+
+The execution phase comes after `plan-review`. It carries out a reviewed plan with discipline: small steps, evidence before claims, and no skipped gate. `brainstorm` is optional upstream triage when the shape is not settled; `test` is the execution-time method for producing high-signal evidence, not a final workflow phase.
+
+**Trigger phrases:** execute the plan, implement this, start building, work through the plan.
+
+## Precondition
+
+A reviewed plan exists (`plan` + `plan-review` ran for non-trivial work). If there's no plan, write one first; if the plan hasn't been pressure-tested, run `plan-review` before sinking time into code built on a shaky plan.
+
+## Loop (per step)
+
+Use the mandatory [Jev workflow](../../workflows/semantic-judgments.md) to triage
+evidence, including local review. Correctness requires the checks below.
+
+For ledger-tracked work, **before the first step** run `bash plugins/toolu/hooks/lib/plan-ledger.sh preflight` — it refuses to start unless the plan is `Approved` and its declared spec (if any) is `Approved`. Then read progress with `bash plugins/toolu/hooks/lib/plan-ledger.sh status` to find the next non-fresh-green step, do the loop below for it, then record it with `bash plugins/toolu/hooks/lib/plan-ledger.sh run <plan_doc> --step <id>` — the engine requires the plan-doc positional arg, and stamps green from mechanical truth, you cannot claim it. On plan deviation, edit the steps block and note it under `## Deviations`, then re-run. Re-run any stale step (a `green` step whose diff has since changed) before calling the plan done. `status` also prints an AC-coverage report (report-only): read it to confirm every spec `AC-<n>` is covered by a fresh-green step — an uncovered AC is surfaced, not yet a push blocker, but it means the goal isn't proven done.
+
+1. **Take one step** from the plan — the smallest shippable unit.
+2. **Produce per-step real-data evidence** (use `test`) — map the relevant AC or risk to a representative real input/fixture, observable result, applicable boundary/failure case, and runner command. For a bugfix, reproduce first; record the passing output before the ledger step is stamped green.
+3. **Handle errors in code, never suppress them.** Every fallible call gets a real handler — propagate (`?`, rethrow), match, or convert; never swallow, never silence with a disable comment (`@ts-ignore`, `eslint-disable`, `#[allow]`). The gate enforces this on every edit; write it right the first time.
+4. **Land it clean.** A PostToolUse quality gate runs on every TS/Rust edit. If it reports a violation the gate goes **failing** and blocks further edits until fixed — fix immediately; do not pile on more changes.
+5. **Verify, don't assume.** Run the command, read the output. "Done" requires evidence (test pass, log, runtime check), never a guess.
+6. **Checkpoint** with the user at meaningful boundaries, or after each independent workstream.
+
+## Rules
+
+- **Global gate** — do NOT move to the next step while any error/warning/test failure stands, even in unrelated files.
+- **Delegate to stay compact** — push exploration, large reads, and parallelizable work to subagents; keep the main context lean.
+- **Delegate at the step's tier** — `status` prints `model=<alias>` for the next step when the plan declared one; hand that step to a subagent on that model (`toolu:quick-task` / `toolu:implementer` / `toolu:architect`, or an explicit `model:`). No declared tier, or a step that turns out harder than planned? Fall back to the rubric and escalate one tier rather than retrying the same tier: `plugins/toolu/skills/orchestrator/references/model-routing.md`.
+- **No scope creep** — do only what the plan calls for. New needs go back to `plan` (and `plan-review`), not into this step.
+- **Honor the layout** — files named after their export, one responsibility each, under the line limit, docs present and concise.
+- **Docs in sync** — when a step changes a user-facing surface (behavior, interfaces, CLI flags, commands, config), update the prose docs that describe it (README, `docs/` guides, `SKILL.md` triggers, release notes) in the same step; it's part of "done", not a follow-up.
+- **Same approach failed twice? Stop.** Change the hypothesis (`systematic-debugging`), don't retry harder.
+
+## What "done" looks like
+
+Working, verified increments that match the plan, with real error handling and per-step real-data evidence, landed under a green gate. Execution owns the final local review; do not hand work to a separate review or terminal-test phase.
+
+## Authorized delivery preflight
+
+Only perform delivery when the user's request includes delivery authorization.
+Before committing, pushing, creating a PR, or starting a durable babysitting
+goal, check every prerequisite and stop before delivery with the exact unmet
+prerequisite if any applies:
+
+- delivery authorization is absent;
+- GitHub auth is unavailable (`gh auth status` fails);
+- the current branch is the repository default branch, detached, or otherwise not a non-default branch;
+- the optional `pr-babysit` plugin is not installed and its `$pr-babysit:babysit` skill is unavailable.
+
+When the per-step direct checks, documentation work, and prerequisites pass,
+commit the scoped changes using the repository's conventions. Do not include
+unrelated work.
+
+## Local release-readiness audit
+
+After that scoped commit and before pushing, establish all of the following
+against the committed branch diff with command output, not assertion:
+
+1. Re-run each affected step's real-data runner and ensure its AC/risk evidence is current. Read `plan-ledger.sh status` and resolve every missing or stale AC coverage entry.
+2. Run `bash plugins/toolu/hooks/lib/plan-ledger.sh run <plan_doc> --verify`. This is the supported branch-wide verification command: it validates every step against the final diff and stamps the ledger only when all steps are fresh-green.
+3. Confirm user-facing documentation is synchronized for every changed behavior, interface, CLI, command, or configuration surface. Treat a missing applicable doc update as a blocker.
+4. Run `$toolu-review:review` (or the host's installed `toolu-review:review` invocation) against the committed branch diff. Its resulting push-review state must be v2 (`version: 2`) and cover every changed file; open findings or stale/incomplete coverage are blockers.
+5. Run `bash plugins/toolu/hooks/lib/verdict.sh status`. Advance only when it reports `overall: green`; quality, plan, review, and docs must each be green.
+
+## PR delivery
+
+When the committed-diff audit and every prerequisite pass:
+
+1. Push the non-default feature branch to its configured remote.
+2. Discover the repository default branch, then locate or create a pull request for the current branch targeting that repository default branch. Verify that PR's number and head/base branches.
+3. Invoke `$pr-babysit:babysit` with no arguments. The verified execution handoff plus this delivery authorization is sufficient authorization for its durable PR-clearing goal; do not add a handoff argument or weaken its isolated-worktree, strict-clearance, or durable-goal rules.

package/generated/skills/toolu--orchestrator/SKILL.md

@@ -0,0 +1,145 @@
+---
+description: "Use when deciding HOW to run a large task: whether to delegate it at all, and if so how to split it. Teaches the MAIN thread that inline is the default and a subagent must earn its round trip — plus which agent for which job, how to bound a delegation so it cannot hang, how to parallelize genuinely independent work, and which model tier fits each class. Read it before fanning anything out, especially when tempted to split work that one thread could just do. Tells: \"orchestrate this\", \"delegate this\", \"break this down\", \"coordinate subagents\", \"should I use subagents\", \"this is a big task\", or a UserPromptSubmit nudge flagged the prompt as large."
+name: toolu--orchestrator
+---
+
+# Orchestrator
+
+The main thread owns orchestration — and most of the time, orchestration means
+doing the work. A subagent is a tool with a price: a spawn, a prompt you have to
+write, a round trip, and a summary you then have to trust. Delegation is worth it
+when that price buys something (isolation of a large read, real parallelism); it
+is a loss when it does not.
+
+The failure this skill exists to prevent is not under-delegation. It is a simple
+task fanned out to five agents, each waiting on the last, taking ten minutes to
+do three minutes of work.
+
+Subagents do bounded work and return concise results; they do not recursively
+delegate unless the task explicitly requires a nested workflow. Use [the host
+mapping](../../workflows/host-mapping.md) for the active delegation, user-input,
+and thread-control interfaces.
+
+**Trigger phrases:** orchestrate this, delegate this, break this down, coordinate subagents, fan this out, this is a big/multi-step task.
+
+## Does this need delegating at all?
+
+Ask before decomposing anything. Delegation pays only when **at least one** of
+these is true:
+
+1. **The output is large and you need only the conclusion.** Reading thirty files
+   to answer one question — the bytes stay in the subagent, the answer comes back.
+2. **Two or more units are genuinely independent** and can run at the same time.
+   Genuinely: neither needs the other's result.
+
+…**and** the work is bigger than a handful of tool calls. Below that, the round
+trip costs more than doing it.
+
+If neither holds, do it inline. That is not a failure of orchestration; it is
+orchestration. Worked examples, including the cases where delegation loses:
+[delegation cost](references/delegation-cost.md).
+
+Two shapes that look like orchestration and are not:
+
+- **A dependent chain.** A → wait → B → wait → C, where each needs the last, is
+  strictly slower than doing A, B, C inline: you pay every round trip and gain no
+  parallelism. Chain inline; delegate the branches.
+- **Splitting to look thorough.** Three agents on one small file is not coverage,
+  it is three summaries of the same thing.
+
+## The core loop
+
+1. **Do the cheap discovery yourself.** List the files, find the entry point, read
+   the file you already know. Never delegate a single-fact lookup.
+2. **Decide whether delegation pays** by the test above. Often it does not — go
+   do the work.
+3. **If it pays, decompose into independent units.** Independent units run in
+   parallel; dependent ones you do inline.
+4. **Delegate with a contract.** One answerable question per agent, a tight
+   prompt, and an explicit return shape ("a file:line table", "the verdict + why",
+   "a 5-line summary").
+5. **Synthesize.** The main thread holds the conclusions and makes the decisions.
+
+## Delegate vs do inline
+
+Inline is the default, so the right-hand column is where most work belongs.
+
+| Do inline (main thread) | Delegate to a subagent |
+|---|---|
+| A read of a file you already know | Broad/fan-out search across many files or naming conventions |
+| A single-fact grep where you know the symbol | Reading many files to answer one question |
+| An edit you can make in a few tool calls, however many files | Independent work that can genuinely run in parallel |
+| A dependent chain of steps — each needs the last | Review / audit of a whole diff or subsystem |
+| The final synthesis and every decision | Anything returning a lot of bytes you need only the conclusion of |
+| Anything where the round trip costs more than the work | A long-running sweep you want isolated from main context |
+
+Rule of thumb: if the answer means reading across several files and you only need the conclusion, **delegate it and keep the conclusion, not the file dumps.** Once delegated, don't also run it yourself in parallel — that pays for the work twice.
+
+## When an agent goes quiet
+
+Waiting is not a strategy. Every delegation is bounded before it starts, and
+unbounded waiting is a bug:
+
+- **Scope it to one answerable question.** "Find every call site of X" comes back.
+  "Improve the module" does not.
+- **State the return contract in the prompt.** An agent that knows it owes a
+  file:line table finishes; one asked to "look into it" wanders.
+- **If it does not come back, check once. Then take the work back inline and say
+  so.** Report what you did instead — a silent takeover looks like the agent
+  succeeded.
+- **Never block indefinitely.** A subagent that has gone quiet has already cost
+  more than the work; sitting on it converts a slow task into a stuck one.
+
+An agent that returns something unusable is the same case: use it or redo the
+work inline, but do not re-spawn the same prompt hoping for a better roll.
+
+## Which agent for which job
+
+Prefer a **tier-pinned** agent when one fits — its frontmatter fixes the model, so routing can't be forgotten:
+
+- **`toolu:quick-task` / Codex `quick-task`** — mechanical lookups and listings.
+- **`toolu:deep-explore` / Codex `deep-explore`** — structural exploration.
+- **`toolu:research-agent` / Codex `research-agent`** — external research.
+- **`toolu:implementer` / Codex `implementer`** — one bounded plan step and tests.
+- **`toolu:architect` / Codex `architect`** — design and synthesis, read-only.
+- **`Explore`** — broad read-only fan-out search when you need the conclusion, not file dumps.
+- **`Plan`** — design an implementation strategy for a non-trivial change.
+- **`general-purpose`** — multi-step research/execution that doesn't fit a specific agent; set `model:` yourself.
+
+Carry the session mandates into every subagent prompt (comemory recall/save, ast-grep first). Delegation never exempts the work.
+
+## Parallelize independent work
+
+Launch independent subagents in **one message with multiple tool calls** so they run concurrently — not one-at-a-time. Dependent steps wait; independent steps don't. A four-way independent search done serially wastes three-quarters of the wall-clock.
+
+## Keep main context lean
+
+The expensive, recurring cost in a long session is **input tokens re-sent every turn**. Two rules follow:
+
+- **Return conclusions, not bytes.** A subagent may read 50k tokens but should return a 1–2k-token distilled answer. The detailed context stays isolated in the subagent and never re-enters — or re-caches into — the main thread.
+- **Prefer compact return formats** (tables, file:line lists) over prose dumps.
+
+## Model tiers
+
+Route on the **class of work**, not phrasing. Select the matching preconfigured
+agent or pass the active host's explicit model and reasoning settings. Omitting
+routing inherits host defaults, which may be inappropriate for the task.
+
+| Class | Claude default | Codex default | Belongs here |
+|---|---|---|---|
+| mechanical | `haiku` | Luna / medium | lookups, listings, formatting, one command |
+| exploration | `sonnet` | Terra / medium | read-only search across many files |
+| implementation | `sonnet` | Terra / medium | a bounded decided edit + tests |
+| review | `sonnet` | Terra / high | diff review, audits |
+| synthesis | `opus` | Sol / high | reconciling findings |
+| architecture | `opus` | Sol / high | design and hard-to-reverse calls |
+
+Escalate one tier on any of: **hard to reverse**, **cross-cutting**, **the how isn't decided**, **must weigh alternatives**. De-escalate when the task is bounded and has one verifiable answer. Deciding and doing are different classes — one task often splits across two tiers.
+
+A subagent that returns `ESCALATE: <reason>` should be re-run one tier up with that reason in the prompt; never re-run the same tier hoping for a better roll.
+
+Full rubric (signals, worked examples, per-step plan tiers, config remap): `plugins/toolu/skills/orchestrator/references/model-routing.md`. Remap any class in `toolu.config.json` under `models`.
+
+## Fan-out budget guardrail
+
+Subagents multiply token spend (multi-agent runs can cost ~15× a single thread; unmanaged fan-out has produced four- and five-figure single-session bills). Before a large fan-out: cap the number of parallel agents to what the task needs, give each a tight scope, and prefer one well-scoped sweep over a runaway loop. If you bound coverage (top-N, sampling), say so — don't let "covered everything" hide a silent cap.

package/generated/skills/toolu--orchestrator/references/delegation-cost.md

@@ -0,0 +1,104 @@
+# What delegation costs
+
+Delegation is usually presented as free — split the work, run it in parallel, win.
+It is not free, and the cases where it loses are common enough that a default of
+"delegate" makes ordinary tasks slower.
+
+This is the arithmetic the [orchestrator skill](../SKILL.md) refers to.
+
+## The price of one subagent
+
+Every delegation pays, whether or not it earns it back:
+
+| Cost | What it is |
+|---|---|
+| Prompt authoring | You must write a self-contained brief. The subagent cannot see your conversation, so context you already hold has to be re-stated. |
+| Spawn + round trip | Wall-clock before a single useful token, plus the return trip. |
+| Summary risk | You get the agent's reading of what it found, not what it found. Anything it judged irrelevant is gone. |
+| Verification | A returned claim you rely on has to be trusted or re-checked. Re-checking pays for the work twice. |
+| Attention | You have to hold "what did I delegate, has it come back" while doing something else. |
+
+A subagent buys two things and only two: **isolation** (a large read that never
+enters your context) and **parallelism** (independent work at the same time). If a
+delegation buys neither, it is pure cost.
+
+## When it pays
+
+**Isolation.** "Which of these 40 files register a hook?" — the agent reads
+everything, you get a `file:line` table. The 40 files never enter your context and
+never re-enter it on every later turn. This is the strongest case, and it gets
+stronger the longer the session runs.
+
+**Parallelism.** Four independent searches with no dependency between them, in one
+message. Wall-clock is the slowest, not the sum. The word doing the work is
+*independent*: if search two needs search one's answer, there is no parallelism to
+win.
+
+**Isolation of a long job.** A sweep that takes minutes and produces noise you do
+not want interleaved with your work.
+
+## When it loses
+
+**The task is small.** Under roughly a handful of tool calls, the brief alone costs
+more than the work. A single-file edit, a known-symbol grep, reading a file you
+already know — do them.
+
+**The chain is dependent.** A → B → C where each needs the last is *strictly*
+worse delegated: every round trip is paid and no parallelism is gained. Chain
+inline; delegate only branches.
+
+**You will re-read the output anyway.** If you cannot act on the summary without
+opening the files yourself, the isolation you paid for was never real.
+
+**The work is the decision.** Trade-offs, architecture, "which of these is right" —
+delegating produces a recommendation you must then evaluate, which is most of the
+work. Get the *inputs* delegated; make the call yourself.
+
+**You are splitting to look thorough.** Three agents on one small file produce
+three summaries of the same thing. Coverage is a property of the search, not of
+the agent count.
+
+## A worked case
+
+A session that built a cross-cutting feature end to end — a written spec, five new
+shell libraries, seven module migrations, ~300 real-data tests, eight commits, a
+pull request, three rounds of review response — ran entirely on one thread. Zero
+subagents.
+
+The bottleneck was never reasoning. It was the test suite: 131–165 seconds a run,
+several runs. No amount of fan-out moves that number, because the suite is one
+command. The delegable work — "read these files and tell me what is there" — was
+a small fraction of the total, and the files were mostly ones the thread had
+already read.
+
+Fanning that same work across five agents would have added five briefs, five round
+trips, and five summaries to verify, to save reading that had already happened.
+The measurable win would have been zero and the wall-clock strictly worse.
+
+The lesson is not "never delegate". It is that **the size of a task is not the
+same as its delegability.** A big task made of dependent steps on files you
+already understand is a big inline task.
+
+## The test, restated
+
+Before spawning anything:
+
+1. Does this buy **isolation** (large output, conclusion only) or **parallelism**
+   (genuinely independent units)?
+2. Is the work bigger than a handful of tool calls?
+
+Both no → do it. One yes → probably delegate, with a bounded scope and a stated
+return contract. Neither → you are about to make a fast task slow.
+
+## Bounding what you do delegate
+
+A delegation that cannot fail visibly will eventually hang:
+
+- One answerable question per agent. "Find every call site of X" returns.
+  "Improve the module" does not.
+- State the return shape in the prompt — a table, a verdict, a five-line summary.
+- If it does not come back: check once, then do the work inline and say you did.
+  Never block indefinitely; an agent that went quiet has already cost more than
+  the work.
+- Never re-spawn an identical prompt hoping for a better result. Change the tier
+  (see [model routing](model-routing.md)) or take it back.

package/generated/skills/toolu--orchestrator/references/model-routing.md

@@ -0,0 +1,112 @@
+# Model routing
+
+How to pick the model for a delegated task. The rule is: **route on the class of
+work, not on how the request is phrased.** A one-line prompt can hide an
+architecture decision; a long prompt can be a file listing.
+
+Referenced by `orchestrator`, `brainstorm`, `plan`, and `execution`. The runtime
+copy of the table is injected into every session by the toolu SessionStart hook
+(`plugins/toolu/hooks/docs/model-routing.md`), so the tiers are in context from
+turn one even when no skill has fired.
+
+## The ladder
+
+Claude tiers use stable aliases. Codex routes each class through the model and
+reasoning-effort pair in `models.codex.<class>`.
+
+| Class | Claude | Codex | What belongs here |
+|---|---|---|---|
+| `mechanical` | `haiku` | Luna / medium | Exact lookups, formatting, one command. |
+| `exploration` | `sonnet` | Terra / medium | Read-only subsystem mapping. |
+| `implementation` | `sonnet` | Terra / medium | A bounded decided edit plus tests. |
+| `review` | `sonnet` | Terra / high | Diff review and audits. |
+| `synthesis` | `opus` | Sol / high | Reconciling several findings. |
+| `architecture` | `opus` | Sol / high | Cross-cutting design and trade-offs. |
+
+`inherit` is also a valid value — "whatever the lead thread runs". Use it when a
+subagent must match the session's model exactly rather than a fixed tier.
+
+## Classify by signal, not by vibe
+
+Score the task on four signals. Any single **yes** in the escalate column pulls
+the task up a tier; all-no in a bounded task pulls it down.
+
+| Signal | Escalate | De-escalate |
+|---|---|---|
+| **Reversibility** | Hard to undo — schema, public interface, migration, deletion | Trivially revertable edit |
+| **Blast radius** | Cross-cutting: many callers, several subsystems | One file, one function |
+| **Ambiguity** | The *how* is not decided; requirements are implicit | Fully specified — what, where, and how to verify are all given |
+| **Reasoning depth** | Must weigh alternatives or reconcile conflicting inputs | One correct answer, verifiable on sight |
+
+Two worked examples:
+
+- *"Find every call site of `pl_recompute`"* — reversible, no ambiguity, no
+  reasoning. Mechanical → `haiku`, even though the codebase is large.
+- *"Add a `model` field to the ledger steps"* — touches a persisted contract
+  every reader parses. Hard to reverse, cross-cutting → `opus` decides the
+  shape, `sonnet` implements it once decided.
+
+Note what the second example shows: **one task can split across tiers.** Deciding
+and doing are different classes. Don't buy frontier reasoning to type out an
+agreed edit, and don't hand an undecided design to the cheap tier because the
+diff looks small.
+
+## Escalation is one-way and cheap
+
+If a subagent returns `ESCALATE: <reason>`, re-run the task one tier up with that
+reason included in the prompt. That is the designed path, not a failure — the
+`quick-task` and `implementer` agents are told to escalate rather than guess.
+Never re-run a failed task on the *same* tier hoping for a better roll.
+
+## Pre-tiered agents
+
+Pinning the tier in the agent's own frontmatter is stronger than remembering to
+pass `model:`, so prefer these when one fits:
+
+| Agent | Tier | Job |
+|---|---|---|
+| `toolu:quick-task` | `haiku` | Mechanical lookups and bounded mechanical edits |
+| `toolu:deep-explore` | `sonnet` | Structural exploration via ast-grep |
+| `toolu:research-agent` | `sonnet` | External docs / web research |
+| `toolu:implementer` | `sonnet` | One bounded plan step + its tests |
+| `toolu:architect` | `opus` | Design, trade-offs, synthesis (read-only) |
+
+For anything else, route explicitly with the active host's delegation interface.
+Leaving routing unset inherits host defaults.
+
+## Plan steps carry their tier
+
+A machine-readable plan step may declare `"model": "<alias>"`:
+
+```json
+{ "id": "s3", "title": "Add the resolver", "check": "bats plugins/toolu/hooks/lib/__tests__/config-models.bats",
+  "model": "sonnet" }
+```
+
+`plan` assigns it while the complexity is still fresh; `execution` reads it back
+(`plan-ledger.sh status` prints `model=<alias>` for the next step) and delegates
+at that tier without re-deriving the judgment. The field is optional — a legacy
+step without it is still valid, and the executor falls back to this rubric.
+
+## Configuring the tiers
+
+Remap any class in `toolu.config.json`:
+
+```json
+{ "models": { "review": "opus", "mechanical": "sonnet" } }
+```
+
+Values must be one of `haiku`, `sonnet`, `opus`, `fable`, `inherit`; anything
+else is rejected with a warning and falls back to the default, so a typo
+mis-tiers nothing. `{"models": {"enabled": false}}` turns off the session
+injection entirely.
+
+**Limit:** Claude config remaps the rubric but cannot rewrite a pre-built agent's
+frontmatter. Codex custom-agent files also take precedence over class routing;
+run `$toolu:setup` after plugin upgrades to install current profile templates.
+
+## Budget note
+
+Routing saves money only if it is paired with restraint on fan-out. A wide
+parallel sweep on the top tier is the expensive failure mode this rubric is meant
+to prevent, not enable — cap the agent count first, then tier each one.

package/generated/skills/toolu--plan/SKILL.md

@@ -0,0 +1,56 @@
+---
+description: "Use after requirements are agreed when a behavior change needs an executable, ledger-backed implementation plan. Evidence-first and adaptive: mechanical work skips a plan; brainstorm is optional upstream triage."
+name: toolu--plan
+---
+
+# Plan
+
+**Evidence first:** recall relevant decisions, inspect the declared spec, and
+search the codebase for existing paths, helpers, tests, and docs before drafting.
+Do not turn assumptions into steps.
+
+Use the mandatory [Jev workflow](../../workflows/semantic-judgments.md) for
+classifications that change step handling. Derive paths, dependencies, and ordering from repository evidence.
+
+When a ledger step needs delegation, declare its model tier using the
+[`model-routing` rubric](../orchestrator/references/model-routing.md) and map
+host-specific delegation through `plugins/toolu/workflows/host-mapping.md`.
+
+## Choose the planning depth
+
+**Mechanical work** — a typo, rename, formatting-only change, or dependency
+bump with no behavior change — skips a plan. State the bounded change and its
+direct verification, then execute it.
+
+Behavior changes, features, fixes, refactors, and changes with meaningful risk
+always receive a compact plan at `docs/toolu/plans/<YYYY-MM-DD>-<slug>.md`.
+Use a reviewed spec when one exists; clear requirements do not require a prior
+brainstorm.
+
+## Plan shape
+
+1. **Header** — `**Date:** <YYYY-MM-DD>   **Status:** Draft   **Spec:**
+   <path | none>   **Topic:** <one line>`.
+2. **Evidence and approach** — brief outcome, constraints, reused paths, and
+   chosen design. Cite what was recalled or inspected.
+3. **Workstream summary** — a short, non-duplicative overview of the sequence
+   (for example, “parser → validation → docs”). It is not a second task list.
+4. **Steps (machine-readable)** — one JSON array under the literal heading
+   `## Steps (machine-readable)`. This ledger is the **sole detailed step list**;
+   use the shared reference for its schema and real-input evidence conventions.
+5. **Critical files** — exact paths to create or modify.
+6. **Verification** — end-to-end outcome, real inputs, failure/boundary checks,
+   and required documentation synchronization.
+
+Use the canonical ledger shape and optional-field/path-freshness guidance in
+[the shared ledger reference](references/ledger.md); do not duplicate it in a
+plan. Keep checks runnable and order dependent work explicitly.
+
+Every user-facing behavior, interface, CLI, command, or config change needs an
+explicit documentation step and check. Keep files focused, use colocated tests,
+and include the real inputs and failure propagation that prove the behavior.
+
+## Handoff
+
+Leave the plan `Draft` and send it to `plan-review`. Only an approved plan moves
+to `execution`.

package/generated/skills/toolu--plan/references/ledger.md

@@ -0,0 +1,18 @@
+# Plan ledger reference
+
+The JSON array under `## Steps (machine-readable)` is the authoritative detailed
+step list. Each step requires non-empty string `id`, `title`, and `check`.
+
+Optional fields preserve the existing ledger contract:
+
+- `ac_refs`: spec `AC-<n>` ids covered by this step.
+- `depends_on`: earlier step ids that must be green before this work.
+- `paths`: pathspecs read by the step's check, including its test file.
+- `input`: the real input or fixture used to prove the behavior.
+- `model`: `haiku`, `sonnet`, `opus`, `fable`, or `inherit`.
+
+`paths` narrows iteration freshness to what the check actually reads. Declare
+all such paths: under-declaring can leave a stale green result. Before delivery,
+`plan-ledger.sh run <plan_doc> --verify` judges every step against the whole
+branch diff, so
+scoped freshness never replaces final verification.

package/generated/skills/toolu--plan-review/SKILL.md

@@ -0,0 +1,48 @@
+---
+description: "Use to review the plan or poke holes in the plan before execution. Verifies ledger steps, AC coverage, real-input checks, paths, dependency order, docs, and PR-delivery readiness."
+name: toolu--plan-review
+---
+
+# Plan Review
+
+Pressure-test a draft plan before code changes begin. Find the gap that would
+force an implementer to guess; do not restate the plan or praise it.
+
+Use the mandatory [Jev workflow](../../workflows/semantic-judgments.md) for
+step/requirement alignment. Keep ledger validation and approval grounded in the checks below.
+
+## Checklist
+
+- **Evidence and scope** — approach follows the approved spec or agreed
+  requirements, reuses discovered paths, and adds no silent scope.
+- **AC-to-step coverage** — every spec AC has at least one ledger `ac_refs`
+  mapping. Run `pl_check_ac_refs <plan_doc> <spec_doc>` to reject dangling refs;
+  a spec-less plan must explicitly justify why no AC mapping applies.
+- **Runnable evidence** — every ledger step has a non-empty runnable `check`;
+  each behavior check identifies a real input/fixture and observable result,
+  including applicable invalid or boundary input. Reject empty steps and
+  happy-path-only verification.
+- **Path declarations** — `paths` include every file the check reads, especially
+  production and test files; omitted or stale paths invalidate freshness claims.
+- **Dependency order** — `depends_on` and workstream order make prerequisites
+  green before dependent work; no circular or impossible ordering.
+- **Critical files and failure behavior** — all edited paths are declared and
+  failure propagation/recovery is planned instead of deferred.
+- **Documentation** — each user-facing behavior/interface/CLI/command/config
+  change has an explicit documentation step with a runnable check.
+- **PR-delivery readiness** — plan includes end-to-end real-data verification,
+  the final ledger verification, scoped commit/push expectations, and the
+  delivery prerequisite for the automatic PR/babysit handoff.
+
+## Output
+
+Use one finding per line:
+
+```
+<step/section>: 🔴 blocker: <problem>. <fix>.
+<step/section>: 🟡 should-fix: <gap>. <fix>.
+<step/section>: 🔵 consider: <minor>. <fix>.
+```
+
+Stamp `**Status:** Approved` only when the plan is executable and delivery-ready;
+otherwise stamp `**Status:** Needs changes` and return it to `plan`.

package/generated/skills/toolu--review-and-commit--skill/SKILL.md

@@ -0,0 +1,10 @@
+---
+description: Use when completed branch work needs a final code review, fixes, full quality gates, and intentional local commits without pushing or merging.
+name: toolu--review-and-commit--skill
+---
+
+# Review and commit
+
+Read [the canonical review-and-commit workflow](../../workflows/review-and-commit.md)
+and [the host mapping](../../workflows/host-mapping.md) completely, then execute
+them. Do not push or merge.