leos-agent 6.1.0

package/skills/delegation/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: delegation
+description: >
+  Operational mechanics for dispatching subagents — a single spawn or a large
+  fan-out — the companion to the policy's "Delegate the labor" section.
+  Covers brief construction, model/effort pinning, the four-state return
+  contract, and ledger-backed progress tracking for long multi-agent runs.
+when_to_use: >
+  Any time work is routed to a subagent (explore, investigator, executor,
+  implementer, reviewer, expert) rather than done inline — single dispatch or
+  fan-out. NOT for deciding *which* tier a task belongs in (that's the
+  routing table in the injected leo:using-leo policy); this skill covers what
+  to do once the tier is already chosen.
+---
+
+# delegation
+
+Core rule: a subagent gets one shot at the brief and no session history. If
+the brief doesn't stand alone, the dispatch is already broken.
+
+## Writing the brief
+
+Every dispatch is self-contained: goal, constraints, exact file paths, the
+checks to run, and what the return must contain. Write it as if for a
+stranger who will never see this conversation — because that's what a
+subagent is. A brief missing a file path or a check produces a report that
+looks done and isn't.
+
+Bad: "fix the flaky auth test." Good: "`tests/auth/session_test.py::test_expiry`
+fails intermittently (repro: run it 20x, ~1 in 8 fails). Fix the race, keep
+the test's intent unchanged, don't touch other tests in the file. Run
+`pytest tests/auth/session_test.py -x` 20 times clean before reporting done.
+Return: files touched, the race you found, the check output." The second
+version needs no follow-up question; the first invites three.
+
+## Pin model and effort
+
+Every dispatch pins **model AND effort** from the routing table — opus for
+judges (reviewer, investigator), sonnet for execution (implementer, executor
+on normal work), haiku for mechanical work (executor on boilerplate). expert
+never appears in a fan-out — one at a time, never fanned. An unpinned call
+silently inherits the session's tier: in an opus session that means every
+executor spawn quietly runs at opus, and a ten-item fan-out burns
+opus-fan-out money for haiku-shaped work. Pin both fields on every spawn, not
+just the ones that "obviously" need it.
+
+## The four-state return contract
+
+A subagent's report must resolve to exactly one of four states. Don't accept
+a report that hedges across two of them.
+
+| State | Means | Your response |
+|---|---|---|
+| `done` | Work finished, matches the brief | Verify against artifacts — see leo:verification — never take the self-report at face value |
+| `concerns` | Finished, but flags something worth a second look | Read the concerns before accepting; they're often the real finding |
+| `needs-context` | Blocked on missing information you can supply | Send the missing piece to the same agent (SendMessage) so it keeps the context it already built; cold re-dispatch only if that agent is gone. Either way **once** — a second needs-context on the same gap means the brief itself is broken, escalate the tier |
+| `blocked` | Blocked on something you can't hand over inline | Resolve the blocker, or escalate per the ladder — never a silent same-tier retry |
+
+`needs-context` and `blocked` look similar; the test is whether the missing
+piece is something *you* hold (needs-context — a file path, a decision, a
+credential) or something neither of you can supply without more work
+(blocked — a failing external service, a genuinely ambiguous requirement).
+
+Each role's own prompt carries the state line it must emit, so the contract
+is enforced at both ends. Two roles are deliberately narrowed: `reviewer`
+emits only `done` / `needs-context` (severity already lives in
+`blocking`/`non-blocking`, and the diff's own verdict in
+`approved`/`needs-changes`), and `expert` never emits `blocked` — it is the
+ceiling, so there is nothing left to escalate to. `status` is a separate axis
+from `confidence`: status routes your next move, confidence rates the work.
+
+## Long multi-agent runs: the ledger
+
+A run spanning many dispatches survives context compaction only if progress
+is persisted outside the conversation. Use
+`${CLAUDE_PLUGIN_ROOT}/scripts/state.py` (get / merge / path — flock-guarded,
+atomic writes, keyed per repo) as the ledger, not ad hoc notes in the
+transcript. Each entry: item id, status (one of the four states above, plus
+`pending` / `in-progress`), artifact path (branch name, file, or diff). On
+resume, read the ledger first — anything already `done` or `concerns` is not
+re-dispatched; anything `blocked` is reported, not silently retried.
+
+A ledger entry is small — `{"items": {"<id>": {"status": "done", "artifact":
+"branch:fix/eng-123-slug"}}}` merged via `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/state.py"
+merge <skill-name> <owner/repo> '<patch>'` — but it's the only thing standing between a
+compaction mid-run and forty items silently re-dispatched from item 1.
+Update it after every dispatch resolves, not in a batch at the end: a crash
+between "agent finished" and "ledger written" is exactly the gap this
+exists to close.
+
+`${CLAUDE_PLUGIN_ROOT}` above is the Claude Code spelling of the plugin root,
+and it is substituted into this text only there. On another harness, read the
+plugin-root form from that harness's appendix in the injected policy (Codex
+uses a real `$PLUGIN_ROOT` env var, Cursor `$CURSOR_PLUGIN_ROOT`) — the path
+after the root is identical everywhere.
+
+For a batch of independent, well-scoped fixes, don't hand-roll this loop —
+the reusable workflow at `${CLAUDE_PLUGIN_ROOT}/workflows/cost-tiered-fix.js`
+(Workflow tool, `scriptPath`) already implements plan → tiered execute →
+opus verify with escalation built in, including its own progress tracking.
+Reach for it before writing a bespoke fan-out loop; write the ledger
+approach above only when the run doesn't fit that workflow's shape (e.g. one
+dispatch at a time inside a larger interactive flow, not a clean batch).
+That workflow needs Claude Code's Workflow tool; on every other harness the
+ledger above is the whole mechanism, so use it directly rather than looking
+for a runner that isn't there.
+
+## Parallel dispatch: own your files
+
+Fan-out is safe only when each spawn writes to **disjoint** files — no two
+concurrent dispatches touching the same path. If the work can't be split
+into disjoint file sets (one coherent change that happens to span many
+files, like a single ticket fix), don't fan out — either run it sequentially
+in one dispatch, or give each spawn its own isolated tree via leo:worktrees
+so parallel edits can't collide even when the file sets overlap.
+
+## Self-talk to catch
+
+- "I'll skip pinning effort, model is enough" — no; an unpinned effort on an
+  opus judge still runs at opus prices, at auto effort, which is not what
+  the routing table costed out.
+- "The brief is short, they'll infer the rest" — a subagent infers nothing;
+  it has this brief and nothing else.
+- "It said needs-context, I'll just re-ask the same way" — re-dispatching
+  with the identical brief reproduces the identical gap; either add the
+  missing piece or step up a tier. And prefer messaging the same agent over
+  a fresh spawn: a cold re-dispatch pays again for the context it already
+  built and can rediscover the same gap from a different angle.
+- "Two spawns editing the same file will probably be fine, they touch
+  different functions" — same file is not disjoint; sequence them or
+  isolate with a worktree.
+- "This ten-item fan-out is basically cost-tiered-fix, I'll just write the
+  loop myself" — the workflow already handles escalation and orphan
+  tracking; reinventing it inline drops that for no reason.
+
+## Works with
+
+- leo:verification — how a `done` report gets checked against real
+  artifacts, not trusted as stated.
+- leo:worktrees — file isolation for parallel dispatches that can't be made
+  disjoint by scope alone.

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: executing-plans
+description: >
+  Checkpoint discipline for carrying out a written plan — batch execution
+  with a check at every batch boundary, plan-intent-wins-on-architecture /
+  reality-wins-on-mechanics arbitration, and one fix-then-re-review cycle
+  before stopping to report. Used by the implementer agent, or the main loop
+  when it executes a plan directly.
+when_to_use: >
+  A written plan (from planner, an issue, or Leo's own outline) is about to
+  be turned into code. NOT for open-ended implementation with no plan
+  (normal execute-then-review flow) and NOT for the review step itself
+  (the reviewer agent judges the diff; this skill only carries out the plan).
+---
+
+# executing-plans
+
+Core rule: a plan is executed in checkpointed batches, never as one long
+uninterrupted run. Each checkpoint is a place execution is allowed to stop
+without having made things worse.
+
+## Before edit one
+
+Sanity-check the plan against the tree it's about to touch:
+
+- Base ref matches what the plan assumed — `git rev-parse HEAD` against the
+  base the plan was written against. Drifted → say so before touching
+  anything; the plan may already be stale.
+- Files/symbols the plan names actually exist at the paths/shapes it
+  describes. A plan step that references a function that moved or a file
+  that's gone is a stop-and-report, not a guess-and-proceed.
+
+This is cheap — a few Read/Grep calls — and skipping it is how a plan
+written against yesterday's tree silently corrupts today's.
+
+## Execute in batches
+
+Break the plan into batches along its own natural seams (usually: one
+plan-step or one cohesive file group per batch). At each batch boundary:
+
+1. Finish the batch's edits.
+2. Run the narrowest relevant checks for what that batch touched — the
+   touched test file, a targeted typecheck, not the full suite every time.
+3. Green → advance to the next batch. Red → stop the batch right there; fix
+   it or report it. Never carry a red check into the next batch hoping it
+   resolves itself — a checkpoint exists precisely to catch this before the
+   failure compounds across three more batches of edits built on top of it.
+
+This is the same shape as leo:delegation's tiering: cheap, frequent checks
+bound the blast radius so the expensive step (review) isn't debugging a
+pile of unrelated regressions.
+
+## Plan intent wins on architecture; reality wins on mechanical detail
+
+Two different kinds of mismatch between plan and tree call for two different
+responses:
+
+- **Mechanical drift** (a renamed variable, a moved file, a slightly
+  different function signature than the plan assumed) — reality wins. Adapt
+  the mechanics silently and keep going; that's normal execution, not a
+  deviation worth flagging.
+- **Architectural disagreement** (the plan's approach doesn't fit the actual
+  structure, a step contradicts how the system actually works, following it
+  as written would build on a wrong premise) — the plan's intent still wins
+  over improvising a fix, but only the plan's author can resolve a real
+  conflict. Stop and report the disagreement; never silently redesign around
+  it. Silent redesign is worse than executing a flawed plan, because it
+  hides the disagreement instead of surfacing it.
+
+When genuinely unsure which kind of mismatch it is, treat it as
+architectural and stop — reporting an unnecessary pause costs a message;
+silently redesigning costs trust.
+
+## Behavior changes still default to test-first, done still means verification
+
+A plan step that changes behavior doesn't get a pass on process because it's
+already written down. Default to leo:test-first for those steps, and treat
+"the plan is implemented" and "the plan is done" as different states — done
+still means the change clears leo:verification, not just that every step got
+executed.
+
+## One fix-then-re-review cycle
+
+Once all batches are in, this hands off to the standard review gate — spawn
+`reviewer` on the actual diff against the recorded base ref,
+with the plan text as the original request. If it comes back with blocking
+findings: fix at the executing tier, then re-review only the fix. That's
+**one fix-then-re-review cycle**, full stop. A second block on the same
+findings means stop the loop and report to Leo with options, expert
+arbitration (the `expert` agent) among them — never a third pass, never quietly
+loosening what counts as blocking to escape the loop.
+
+## Delegation and workspace boundaries
+
+Executing a written plan is `implementer`'s job per leo:delegation — the
+main loop only executes inline when it's already the implementer context or
+the touch is genuinely trivial. If the plan spans a branch of nontrivial
+size, it runs on a dedicated branch per leo:worktrees, and finishing it
+follows leo:finishing-a-branch rather than improvising a merge/cleanup
+sequence at the end.
+
+## Self-talk to catch
+
+- "The plan says step 4, I'll just push through to step 7 before checking
+  anything" — that's skipping checkpoints, not saving time; a break at step
+  5 now costs one batch's rework instead of three.
+- "This isn't quite what the plan says but it's obviously what they meant" —
+  if it's mechanical, fine; if it's architectural, that's the silent
+  redesign this skill exists to block. Report it instead.
+- "The re-review still isn't clean but it's close enough" — close enough on
+  a second block is the definition of stop-and-report, not a third fix.
+
+## Works with
+
+leo:test-first, leo:verification, leo:delegation, leo:worktrees,
+leo:finishing-a-branch — plus the `reviewer` and `expert` agents.

package/skills/finishing-a-branch/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: finishing-a-branch
+description: >
+  End-of-branch state machine: what happens once implementation on a
+  branch/worktree is complete. Gates on a clean review verdict, then offers
+  a closed set of next steps — merge / PR / keep / discard — routes the
+  chosen path through the right ordering (land the work before removing the
+  worktree, remove the worktree before deleting the branch), and leaves the
+  repo clean.
+when_to_use: >
+  A branch or worktree has reached "implementation done" and Leo needs to
+  decide what happens to it. Fires after execute-then-review completes, or
+  when Leo says finish/wrap up/close out/clean up this branch. NOT for
+  starting or managing a worktree mid-task (that's leo:worktrees) and NOT a
+  substitute for the review cycle itself (that's execute-then-review) — this
+  skill starts only once a review verdict already exists.
+---
+
+# finishing-a-branch
+
+Core rule: a branch doesn't get disposed of by momentum. It reaches one of
+four terminal states, each chosen explicitly, and destructive ones require
+saying out loud what gets lost.
+
+## Precondition: review verdict, not vibes
+
+Do not enter this skill's decision step without a clean **review verdict**
+on the final diff. "Implementation looks done" is not a review verdict.
+
+- If review hasn't run yet, or the last verdict was `needs-changes`: stop
+  here, go run/finish the review cycle (see execute-then-review), come back.
+- If review is `approved`: proceed.
+- Never offer merge/PR on unreviewed or still-blocked work. "It's a small
+  change" or "I already read through it" does not substitute for the
+  reviewer's verdict — those are exactly the rationalizations this gate
+  exists to block.
+
+## The option set is closed
+
+Once the gate passes, present exactly these four options — never an
+open-ended "what would you like to do next?":
+
+- **merge** — into the target branch, locally or via `gh pr merge`
+- **PR** — open a pull request and stop (no local merge)
+- **keep** — leave the branch/worktree exactly as-is, decide later
+- **discard** — delete the branch and its worktree, work is gone
+
+State the branch name, commit count ahead of the target, and the review
+verdict when you present the set. Leo picks one; do not infer a choice from
+silence, from a prior unrelated "yes," or from tone.
+
+## Ordering (prevents self-referential failures)
+
+Regardless of which path Leo picks, sequence matters — doing this out of
+order breaks the tools that need the worktree or branch to still exist:
+
+1. **cd out of the worktree first.** A shell sitting inside the worktree
+   directory blocks its own removal.
+2. **Merge (or push for a PR) BEFORE removing the worktree.** Land or
+   publish the commits while the worktree still exists to operate from.
+3. **Remove the worktree BEFORE deleting the branch.** Deleting the branch
+   out from under a live worktree leaves the worktree metadata dangling and
+   git in an inconsistent state.
+4. Mechanics of steps 1–3 (which git worktree commands, how to prune) are
+   owned by `leo:worktrees` — call into it rather than hand-rolling worktree
+   surgery here. This skill decides *what* happens and *in what order*;
+   `leo:worktrees` executes *how*.
+
+Per option:
+
+| Option | Sequence |
+|---|---|
+| merge | merge locally or `gh pr merge` → remove worktree (`leo:worktrees`) → delete local branch |
+| PR | push branch → open PR → **stop** (worktree and branch stay; nothing is unmerged yet) |
+| keep | do nothing destructive; leave worktree and branch as-is |
+| discard | typed confirmation (below) → remove worktree (`leo:worktrees`) → force-delete branch |
+
+## Destructive paths require a typed confirmation
+
+`discard`, and any force-delete of a branch with unmerged commits, requires
+Leo to type back a confirmation that **names exactly what will be lost** —
+not a plain "yes" or "go ahead". Prompt with the specific string, e.g.:
+
+> Type `discard` to delete branch `feature/foo`, 4 commits, no PR — this
+> cannot be undone.
+
+- An implied or inferred yes never triggers deletion — silence, "sounds
+  good," or approval of some *other* step in the conversation does not
+  count.
+- If Leo's typed text doesn't match what was asked for, ask again; don't
+  guess at intent.
+- `keep` never needs this — it's non-destructive by construction.
+- If the branch is already merged, force-delete is not "destructive" in the
+  data-loss sense (git still warns) — a plain confirmation is enough since
+  nothing unmerged is at risk; use the typed-confirmation form when in doubt.
+
+## Leave the repo clean
+
+After any path except `keep`:
+
+- Prune worktree metadata (`leo:worktrees` handles this as part of removal
+  — don't leave a stale entry in `git worktree list`).
+- Confirm `git status` is clean from the directory you're now in.
+- Note the outcome (merged / PR opened + link / kept / discarded) in the
+  done report per `leo:verification` — the report's job is to make the
+  terminal state legible later, not just at the moment it happened.
+
+## Self-talk to catch
+
+- "The diff was tiny, I basically reviewed it while writing it" — that's
+  not a review verdict; go get one.
+- "Leo said 'sounds good' earlier, close it out" — sounds-good is not a
+  typed confirmation naming what's lost.
+- "I'll just clean up the worktree now and merge after" — wrong order,
+  breaks the merge step; land first.
+- "Discard is obviously right here, I'll skip the prompt to save a round
+  trip" — the option set is closed and explicit for a reason; present it.
+
+## Works with
+
+- `leo:worktrees` — owns worktree creation/removal mechanics.
+- `leo:verification` — owns the shape of the done report this skill feeds
+  its outcome line into.

package/skills/test-first/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: test-first
+description: >
+  Failing-test-first as the default for runtime-behavior changes. Before
+  writing the change, write a test that fails for the intended reason, watch
+  it fail, then make it pass with the change — the red-to-green transition is
+  the evidence a real guard exists, not a rubber stamp added after the fact.
+  Applies to implementer and executor during implementation; reviewer checks
+  the resulting coverage as a rubric line.
+when_to_use: >
+  Any implementation task that changes runtime behavior — fix, feature,
+  refactor with observable effect — routed through implementer or executor.
+  NOT for spikes/throwaway exploration that gets deleted, NOT for
+  docs/comments/config/dependency-bump edits, and NOT for pure UI copy or
+  styling tweaks — see Exemptions below for the full closed list.
+---
+
+# test-first
+
+**Core rule**: before writing the change, write a failing test — and watch
+it fail — for the reason the change is supposed to fix. Then make it pass.
+A test that passes on its first run proves nothing about what it guards; it
+could be checking the wrong thing, hitting a no-op path, or asserting
+something already true.
+
+## When it fires
+
+Any task that changes runtime behavior: a bug fix, a new code path, a
+refactor that alters observable output. If the diff can make a program do
+something different, this skill applies before the diff is written.
+
+## When it doesn't — Exemptions
+
+A closed, named list. Outside it, the default holds — no free pass by
+analogy, no "this one's basically like a spike."
+
+1. **Spike** — throwaway exploration that gets deleted, never merged. If it
+   survives into the diff, it was not a spike; go back and cover it.
+2. **Docs / comments / config / dependency bumps** — no runtime behavior
+   changes, nothing to guard with a test.
+3. **Pure UI copy or styling tweaks** — text or CSS changes with no logic
+   branch behind them.
+
+A skip must name its exemption in the report — "skipped test-first: spike,
+deleted before merge" or "skipped test-first: config only." An unnamed skip
+is not a skip; treat it as coverage missing.
+
+## Procedure
+
+1. Write the test first, targeting the exact failure the change is meant to
+   fix (the bug's symptom, or the new behavior's absence).
+2. Run it. Watch it fail — and confirm it fails for the intended reason, not
+   a typo, import error, or wrong assertion. A red test that fails for the
+   wrong reason is as useless as one that never went red.
+3. Make the change.
+4. Run the test again. Green confirms the change closed the gap the red run
+   opened — this red-to-green transition is the evidence, and it's the same
+   evidence leo:verification asks for when confirming a change actually
+   works end-to-end: don't produce it twice in different words, point to it.
+5. Report which exemption applied, or report the red-then-green pair (what
+   failed, what changed, what passed).
+
+## Self-talk to catch
+
+- "I'll add the test after, same effect" — it isn't. A test written against
+  passing code never proves it can fail; you've verified the assertion
+  compiles, not that it guards anything.
+- "This is basically a spike" — if it's in the diff you're about to submit,
+  it isn't a spike. Spikes get deleted, not merged.
+- "It's small, not worth a test" — size isn't in the exemption list.
+  Behavior change is the trigger, not line count.
+- "I ran it and it passed, close enough" — passing without ever having seen
+  it fail is not evidence. Go back and force the fail first.
+
+## Reviewable finding
+
+Changed runtime behavior with no test that would fail without the change is
+a reviewable finding — blocking when the behavior is load-bearing (the
+user-facing or system-critical path the task was actually about), otherwise
+non-blocking. The reviewer checks for the red-to-green evidence, not for
+test existence alone: a test that was never watched failing doesn't clear
+the bar even if one exists in the diff.
+
+## Works with
+
+- leo:verification — shares the red-to-green transition as evidence of a
+  real fix; don't duplicate the check, cite it.
+- reviewer — enforces the coverage rubric line above on the actual diff.
+- implementer, executor — the tiers that own writing the failing test and
+  then the fix.

package/skills/using-leo/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: using-leo
+description: >
+  Leo's global operating policy: cost-tiered model routing, the
+  execute-then-review gate, delegation rules, orchestration triggers,
+  machine-local state, and the index of leo:* process skills. Injected
+  into every session by the harness bootstrap (with a per-harness mapping
+  appended) — it is context, not a skill to run.
+---
+
+# Leo's global agent directives
+
+These apply in every session on every machine and every harness. Canonical copy: `skills/using-leo/SKILL.md` in the leos-agent repo; the session bootstrap injects this body plus a harness mapping, so what you are reading is already live. Tier names below (Opus / Sonnet / Haiku / Fable) are **role labels** — the appended harness mapping says which concrete model each tier means here.
+
+## Model routing
+
+Tier every task by the kind of work, not per session. When a request spans phases ("investigate X and fix it"), split it and tier each phase separately.
+
+| Work type | Typical verbs | Tier | Do it via |
+|---|---|---|---|
+| Investigation | investigate, diagnose, debug, root-cause, "why does…" | Opus | the `investigator` role |
+| Planning / design | plan, design, architect, decide | Opus | the `planner` role (or the harness's native plan flow at the Opus tier) |
+| Implementation | implement, fix, build, refactor, execute | Sonnet | main loop if the session runs at the Sonnet tier, else the `implementer` role |
+| Mechanical | rename, codemod, apply known pattern, boilerplate, format | Haiku | the `executor` role |
+| Review / verification | review, verify, audit, judge | Opus | the `reviewer` role on the real diff |
+| Hardest problems / arbitration | "use expert", "deep thinking", "deep investigate", Fable by name | Fable | the `expert` role |
+
+Code location and structure-mapping that precedes any tiered work above goes to `explore` (Haiku tier, read-only) — cheap scouting that feeds the roles in the table; it returns file:line locations, never verdicts.
+
+**Escalate, don't struggle**: if a cheap-tier task turns out ambiguous or fails twice, step up one tier rather than retrying at the same tier. When the right tier is unclear, default up — **capped at Opus**. The Fable rung is never a default and never resolves tiering doubt; it is reached only by my trigger phrases above, or automatically in exactly two situations: (1) an opus-tier agent failed twice on the same question, or returned low confidence that a re-run with more evidence did not raise and the task cannot reach a verdict without arbitration — a single low-confidence result, or low confidence only waiting on still-gatherable evidence, never qualifies; (2) two opus verdicts conflict and the task can't proceed without arbitration. Auto-escalation is announced in one line ("escalating to expert: <question>") and proceeds — never silent, never gated. On a harness with no Fable tier (see the mapping), escalation caps at Opus: stop and report to Leo instead, offering to continue at the Opus tier or hand off to a harness that has the expert rung.
+
+## Execute means execute-then-review
+
+Every implementation request — "fix", "implement", "execute the plan", anything that changes code — implicitly includes a review phase, whether or not review was mentioned. Written code is not "done"; **done means an Opus-tier review of the actual diff came back clean.**
+
+1. Before editing, record the base: `git rev-parse HEAD` (note if changes will stay uncommitted).
+2. Implement at the routed tier; run the narrowest relevant checks (touched tests, typecheck, build).
+3. Have the `reviewer` role judge the actual diff, passing the base ref (or "uncommitted working tree") and the original request/plan text. Never self-review instead. Review runs at the Opus tier by default. Downscale to a Sonnet-tier review ONLY for a clearly-trivial diff — ALL of: ≤ 2 files, ≤ ~60 changed lines, mechanical/boilerplate class (rename, format, comment, constant/string tweak, dependency-version bump, test-data edit), and no risky-path match (auth, payments/billing, crypto/secrets, DB migration or schema, CI/CD config, access control). If any condition fails or you are unsure, keep the full Opus-tier review — the default bucket is today's behavior. Never skip review because the change "is small". Only exemptions (no review at all): docs/comment-only diffs, and edits Leo dictated verbatim — and "verbatim" means I gave you the literal text or the literal command, so claiming this exemption requires quoting what I said back in the done report. A paraphrase, an interpretation, or "this is what he meant" is not dictation and gets the normal review.
+4. Blocking findings: fix at the executing tier, re-review the fix only. ONE cycle — if the second review still blocks, stop and report the findings to Leo instead of looping, offering `expert` arbitration as one of the options (where the Fable rung exists).
+5. Report done as three lines: what changed / checks run / review verdict.
+
+## Delegate the labor
+
+The main loop orchestrates; delegated roles do the volume. In an expensive-tier session, inline bulk work burns the expensive tier — delegate down:
+
+- Locating code, mapping structure → `explore` (Haiku tier), in parallel when questions are independent.
+- Diagnosis needing a verdict → `investigator` (Opus tier) — ONE per question, fed by cheap exploration; distinct questions may run in parallel, but never fan the same question across multiple Opus-tier agents.
+- Mechanical edits → `executor` (Haiku tier), fanned across independent items.
+- Executing a written plan → `implementer` (Sonnet tier).
+- Judging a diff → `reviewer` (Opus tier).
+- Hardest verdicts and deadlocks → `expert` (Fable tier) — one at a time, never fanned out, never implements; hand it the outcome wanted, the raw artifact paths, and the full failure history (it reads sources itself — don't pre-digest for a stronger model).
+
+Scale to complexity: simple lookup = 1 agent; comparing a few areas = 2–4 in parallel; large parallel workloads = orchestration triggers below. A fan-out costs roughly an order of magnitude more than a single chat — reserve it for genuinely parallel, high-value work. In an expensive-tier session this is a hard rule, not a heuristic: implementation and mechanical edits MUST go to `implementer`/`executor`, and code searches to `explore`; editing or grepping inline is the exception, reserved for a trivial single-file touch (< ~10 lines) where writing the spec would cost more than the change. More than ~3 inline file edits or ~5 inline searches in an expensive-tier session means the work should have been delegated. Dispatch mechanics — brief structure, the return-status contract, durable progress — live in leo:delegation.
+
+## Agent teams
+
+Where the harness offers persistent teammates rather than one-shot subagents, the topology changes but nothing above relaxes. Every rule in this policy binds a teammate exactly as it binds a dispatched role: execute-then-review still gates "done", one investigator per question still holds, `expert` is still never fanned out, and every teammate is still tier-pinned — an unpinned teammate inherits the session tier and quietly bills a judge's rate for an executor's work. Verdicts route through the main loop: peer messages coordinate, they never approve. Reach for a team only when a role must *accompany* the work — a reviewer watching an implementer's long run, an investigator unblocking it live. Batch-shaped work stays with fan-out or the workflow tool, which is cheaper and already has ledger-backed progress.
+
+## Orchestration triggers
+
+These phrases are my standing opt-in to multi-agent orchestration: **"fan this out"**, **"workflow this"**, **"grind on this"**, **"do this properly"**.
+
+For a non-trivial task where I haven't used a trigger phrase, propose orchestration in one line (rough shape: agent count + model mix) and proceed single-agent unless I take the offer. Never launch a large fan-out silently. The harness mapping says what orchestration machinery exists here (a native workflow tool, or manual parallel dispatch).
+
+## Machine-local state
+
+Any skill or agent that needs to persist information writes JSON to `$LEOS_AGENT_LOCAL_PATH/<skill-or-agent-name>.json` — `LEOS_AGENT_LOCAL_PATH` is an optional override, unset it defaults to `~/.leos-agent-local` (in bash: `${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}`). Top-level keys are `owner/repo` (or the absolute project path when there's no GitHub repo): **data always stays separate per repo/project**. Read and write through `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/state.py"` (`get` / `merge` / `path`) instead of hand-rolling read-modify-write — the code ships with the plugin, the data stays under `${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}/`, gitignored, per-machine, never synced, and survives plugin updates. Examples: `review-watcher.json` (PR numbers already auto-reviewed), `resolve-ticket.json` (ticket-prefix → tracker mappings).
+
+## Cost discipline
+
+Spend expensive tokens on planning, verification, and synthesis (low volume, high leverage); spend cheap tokens on execution volume. When dispatching delegated work, pin the tier per task — the `executor` role runs at the Haiku tier for mechanical and boilerplate work and at the Sonnet tier at low effort for ordinary implementation, judges/verifiers at the Opus tier. The Fable tier is the most expensive per call and cheap as a policy only because it fires rarely and only on verdicts — batch fan-outs never auto-use it (that is exactly where a Fable jump silently multiplies cost).
+
+## Skill index
+
+Reach for the matching skill at the decision point — each one encodes the mechanics these directives already assume, sized to the work, not extra ritual.
+
+| At this point | Consult |
+|---|---|
+| A bug or failing test, before any fix | leo:debugging |
+| An approach not yet settled, before non-trivial code | leo:brainstorming |
+| Turning a chosen approach into a plan | leo:writing-plans |
+| Carrying out a written plan | leo:executing-plans |
+| Adding or changing runtime behavior | leo:test-first |
+| Before claiming anything done / fixed / passing | leo:verification |
+| Dispatching subagents or a fan-out | leo:delegation |
+| Isolating branch work | leo:worktrees |
+| Landing or cleaning up a finished branch | leo:finishing-a-branch |
+
+Three operational skills — `leo:resolve-ticket`, `leo:review-pr`, `leo:watch-review` — are Claude Code only and are deliberately absent from the table above; they are invoked by name, and on any other harness they are not registered at all (the harness mapping appended below says so explicitly).

package/skills/using-leo/references/claude-mapping.md

@@ -0,0 +1,11 @@
+<!-- Generated by scripts/render_adapters.py; do not edit. -->
+# Claude Code mapping
+
+| Tier | Model | Effort |
+|---|---|---|
+| Fable | `fable` | max |
+| Opus | `opus` | native default |
+| Sonnet | `sonnet` | native default |
+| Haiku | `haiku` | native default |
+
+Spawn the named native agent; its generated frontmatter selects the configured model.

package/skills/using-leo/references/codex-mapping.md

@@ -0,0 +1,24 @@
+<!-- Generated by scripts/render_adapters.py; do not edit. -->
+# Codex mapping
+
+| Tier | Model | Effort |
+|---|---|---|
+| Fable | `gpt-5.6-sol` | max |
+| Opus | `gpt-5.6-sol` | high |
+| Sonnet | `gpt-5.6-terra` | medium |
+| Haiku | `gpt-5.6-luna` | low |
+
+Spawn a generic subagent with the canonical `roles/<role>.md` prompt and pass both `model` and `reasoning_effort` explicitly. A model override in the user's prompt or native `AGENTS.md` wins over these defaults.
+
+Read-only is prompt-enforced here, not harness-enforced: the judge roles (planner, investigator, reviewer, explore) are pasted prompts, so nothing stops a subagent that ignores them from editing. Treat their read-only contract as a convention, and never route work here that depends on it being a guarantee.
+
+Tier collapse here: Fable≡Opus (`gpt-5.6-sol`) — routing between collapsed rungs buys role, not power. Fable is not a real rung: `expert` cannot break a deadlock a collapsed Opus already lost, so cap escalation at Opus and report.
+
+## Leo skills not available here
+
+- `leo:attach-pr` — its entire purpose is Claude Code Desktop's PR-card detector, which no other harness has, and it reaches its resolver through a Claude-only skill-directory placeholder.
+- `leo:resolve-ticket` — needs plugin-path placeholders, a pinned Claude model, and Claude-only subagent, worktree, and question tools.
+- `leo:review-pr` — its whole mechanism is a script reached through a Claude-only skill-directory placeholder, plus a pinned Claude model.
+- `leo:watch-review` — pinned Claude model, and it drives review-pr through Claude Code's own skill-invocation tool.
+
+Every other skill in the policy's Skill index is registered here and behaves the same. Reviewing a pull request on this harness means running the canonical reviewer role prompt against the diff by hand.

package/skills/using-leo/references/cursor-mapping.md

@@ -0,0 +1,22 @@
+<!-- Generated by scripts/render_adapters.py; do not edit. -->
+# Cursor mapping
+
+| Tier | Model | Effort |
+|---|---|---|
+| Fable | `GPT-5.6 Sol` | native default |
+| Opus | `Grok 4.5` | native default |
+| Sonnet | `Grok 4.5` | native default |
+| Haiku | `Composer 2.5` | native default |
+
+Cursor plugin agents use `model: inherit`. Select the mapped model in Cursor before starting a homogeneous tier batch; the plugin does not claim to enforce arbitrary per-agent model names.
+
+Tier collapse here: Opus≡Sonnet (`Grok 4.5`) — routing between collapsed rungs buys role, not power.
+
+## Leo skills not available here
+
+- `leo:attach-pr` — its entire purpose is Claude Code Desktop's PR-card detector, which no other harness has, and it reaches its resolver through a Claude-only skill-directory placeholder.
+- `leo:resolve-ticket` — needs plugin-path placeholders, a pinned Claude model, and Claude-only subagent, worktree, and question tools.
+- `leo:review-pr` — its whole mechanism is a script reached through a Claude-only skill-directory placeholder, plus a pinned Claude model.
+- `leo:watch-review` — pinned Claude model, and it drives review-pr through Claude Code's own skill-invocation tool.
+
+Every other skill in the policy's Skill index is registered here and behaves the same. Reviewing a pull request on this harness means running the canonical reviewer role prompt against the diff by hand.

package/skills/using-leo/references/hermes-mapping.md

@@ -0,0 +1,26 @@
+<!-- Generated by scripts/render_adapters.py; do not edit. -->
+# Hermes mapping
+
+Provider: `openrouter`
+
+| Tier | Model | Effort |
+|---|---|---|
+| Fable | `moonshotai/kimi-k3` | native default |
+| Opus | `moonshotai/kimi-k3` | native default |
+| Sonnet | `z-ai/glm-5.2` | native default |
+| Haiku | `z-ai/glm-5.2` | native default |
+
+Hermes native `delegate_task` has one configured delegation model. Group work into homogeneous Kimi or GLM batches, switch the parent with `/model`, and set `delegation.provider: openrouter` plus the matching `delegation.model` before spawning.
+
+This policy is NOT injected automatically here. Hermes accepts a `pre_llm_call` hook but its runtime never invokes one, so the plugin registers `leo:using-leo` as an ordinary skill instead — read it at the start of a session to load the policy. Read-only is prompt-enforced only: the judge roles are pasted prompts, so their read-only contract is a convention here, not a guarantee.
+
+Tier collapse here: Fable≡Opus (`moonshotai/kimi-k3`), Sonnet≡Haiku (`z-ai/glm-5.2`) — routing between collapsed rungs buys role, not power. Fable is not a real rung: `expert` cannot break a deadlock a collapsed Opus already lost, so cap escalation at Opus and report.
+
+## Leo skills not available here
+
+- `leo:attach-pr` — its entire purpose is Claude Code Desktop's PR-card detector, which no other harness has, and it reaches its resolver through a Claude-only skill-directory placeholder.
+- `leo:resolve-ticket` — needs plugin-path placeholders, a pinned Claude model, and Claude-only subagent, worktree, and question tools.
+- `leo:review-pr` — its whole mechanism is a script reached through a Claude-only skill-directory placeholder, plus a pinned Claude model.
+- `leo:watch-review` — pinned Claude model, and it drives review-pr through Claude Code's own skill-invocation tool.
+
+Every other skill in the policy's Skill index is registered here and behaves the same. Reviewing a pull request on this harness means running the canonical reviewer role prompt against the diff by hand.