leos-agent 6.1.0

package/scripts/render_adapters.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""Render harness adapters from config/models.json and canonical role prompts."""
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[1]
+CONFIG_PATH = ROOT / "config" / "models.json"
+ROLE_ROOT = ROOT / "roles"
+CLAUDE_MANIFEST = ROOT / ".claude-plugin" / "plugin.json"
+GENERATED = "<!-- Generated by scripts/render_adapters.py; do not edit. -->\n"
+READ_ONLY = {"expert", "explore", "investigator", "planner", "reviewer"}
+
+
+def _split_role(text):
+    lines = text.splitlines()
+    if not lines or lines[0] != "---":
+        raise ValueError("role prompt is missing YAML frontmatter")
+    try:
+        end = lines.index("---", 1)
+    except ValueError as exc:
+        raise ValueError("role prompt has unterminated YAML frontmatter") from exc
+    return lines[1:end], "\n".join(lines[end + 1 :]).strip() + "\n"
+
+
+def _without(frontmatter, keys):
+    return [line for line in frontmatter if not any(line.startswith(key + ":") for key in keys)]
+
+
+def _agent_docs(role, tier, config):
+    source = (ROLE_ROOT / f"{role}.md").read_text(encoding="utf-8")
+    frontmatter, body = _split_role(source)
+
+    claude_frontmatter = _without(frontmatter, {"model", "effort"})
+    # Concrete model, never a plugin-config placeholder: Claude Code does not
+    # interpolate plugin options into agent frontmatter, so a placeholder here
+    # reaches the model selector verbatim and every spawn dies with "issue
+    # with the selected model". config/models.json stays the one source.
+    #
+    # And a *bare* alias, never an alias with a context suffix: the agent
+    # frontmatter `model` field documents exactly three accepted shapes — a
+    # bare alias, a full model id, or `inherit`. `opus[1m]` is valid for
+    # /model and for skill frontmatter, but it is not one of those three, so
+    # it is the same undocumented-assumption bet that the placeholder was.
+    # Skill frontmatter (skills-claude/*) keeps [1m]; agents do not.
+    claude_frontmatter.append(f"model: {config['harnesses']['claude'][tier]['model']}")
+    effort = config["harnesses"]["claude"][tier].get("effort")
+    if effort:
+        claude_frontmatter.append(f"effort: {effort}")
+    claude = (
+        "---\n"
+        + "\n".join(claude_frontmatter)
+        + "\n---\n\n"
+        + GENERATED
+        + "\n"
+        + body
+    )
+
+    cursor_frontmatter = _without(frontmatter, {"model", "effort", "tools"})
+    cursor_frontmatter.append("model: inherit")
+    if role in READ_ONLY:
+        cursor_frontmatter.append("readonly: true")
+    cursor = (
+        "---\n"
+        + "\n".join(cursor_frontmatter)
+        + "\n---\n\n"
+        + GENERATED
+        + "\n"
+        + body
+    )
+    return claude, cursor
+
+
+def _opencode_agents(config):
+    """Render adapters/opencode/agents.json: one entry per role, keyed by
+    role name, sourced from the same roles/*.md canonical prompts and the
+    same config/models.json tiers every other harness reads.
+
+    A role whose tier resolves to the same model as `opus` on this harness
+    is skipped — that is `expert`/fable here, since opencode's tier table
+    collapses Fable onto Opus (see the opencode harnesses block). Dropping
+    it, rather than registering a fake rung, matches the removed v3.1
+    bridge's posture.
+    """
+    opencode = config["harnesses"]["opencode"]
+    opus_model = opencode["opus"]["model"]
+    agents = {}
+    for role, tier in sorted(config["roles"].items()):
+        model = opencode[tier]["model"]
+        if model == opus_model and tier != "opus":
+            continue
+        source = (ROLE_ROOT / f"{role}.md").read_text(encoding="utf-8")
+        frontmatter, body = _split_role(source)
+        fm = {}
+        for line in frontmatter:
+            if ":" not in line:
+                continue
+            key, _, value = line.partition(":")
+            fm[key.strip()] = value.strip()
+        if role in READ_ONLY:
+            permission = {"edit": "deny"}
+        else:
+            # Stopgap for opencode#5894 (unconfirmed whether
+            # tool.execute.before intercepts subagent bash): coarse denies
+            # on the catastrophic rm class for write-capable agents. The
+            # precise tripwire stays hooks/bash-guard.py.
+            permission = {
+                "bash": {
+                    "rm -rf ~": "deny",
+                    "rm -rf ~/*": "deny",
+                    "rm -rf /": "deny",
+                    "rm -rf /*": "deny",
+                }
+            }
+        agents[role] = {
+            "description": fm.get("description", ""),
+            "mode": "subagent",
+            "model": f"openrouter/{model}",
+            "prompt": body,
+            "permission": permission,
+        }
+    return json.dumps(agents, indent=2, sort_keys=True) + "\n"
+
+
+def _table(rows):
+    lines = ["| Tier | Model | Effort |", "|---|---|---|"]
+    for tier in ("fable", "opus", "sonnet", "haiku"):
+        item = rows[tier]
+        lines.append(f"| {tier.title()} | `{item['model']}` | {item.get('effort', 'native default')} |")
+    return "\n".join(lines)
+
+
+def _collapse_note(rows):
+    """Name tiers that share one model on this harness.
+
+    The policy treats the four tiers as distinct rungs, and its "no Fable
+    tier here, cap escalation at Opus" branch only fires if the harness says
+    so. A mapping that silently points two rungs at one model leaves that
+    branch unreachable while the expert rung is materially fake.
+    """
+    by_model = {}
+    for tier in ("fable", "opus", "sonnet", "haiku"):
+        by_model.setdefault(rows[tier]["model"], []).append(tier)
+    collapsed = [tiers for tiers in by_model.values() if len(tiers) > 1]
+    if not collapsed:
+        return ""
+    groups = ", ".join(
+        "≡".join(t.title() for t in tiers) + f" (`{rows[tiers[0]]['model']}`)"
+        for tiers in collapsed
+    )
+    note = f"\nTier collapse here: {groups} — routing between collapsed rungs buys role, not power. "
+    if any("fable" in tiers and "opus" in tiers for tiers in collapsed):
+        note += (
+            "Fable is not a real rung: `expert` cannot break a deadlock a "
+            "collapsed Opus already lost, so cap escalation at Opus and report. "
+        )
+    return note.rstrip() + "\n"
+
+
+def _skill_notes(config, harness):
+    """Name the leo:* skills this harness does not get, and why.
+
+    Silence here is worse than the exclusion: a policy Skill index that lists
+    skills the harness never registered reads as "available" until someone
+    invokes one. Reason strings describe placeholders in prose on purpose —
+    tests/test_harness_mappings.py fails the build if the literal Claude
+    token appears in a non-Claude mapping.
+    """
+    skills = config.get("skills", {})
+    missing = set(skills.get("exclude", {}).get(harness, ()))
+    if harness != "claude":
+        missing |= set(skills.get("claudeOnly", ()))
+    if not missing:
+        return ""
+    reasons = skills.get("reasons", {})
+    lines = ["", "## Leo skills not available here", ""]
+    for name in sorted(missing):
+        lines.append(f"- `leo:{name}` — {reasons.get(name, 'not portable to this harness')}.")
+    lines.append("")
+    lines.append(
+        "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."
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _mapping_docs(config):
+    claude_rows = config["harnesses"]["claude"]
+    codex = config["harnesses"]["codex"]
+    cursor = config["harnesses"]["cursor"]
+    hermes = config["harnesses"]["hermes"]
+    hermes_rows = {tier: hermes[tier] for tier in ("fable", "opus", "sonnet", "haiku")}
+    opencode = config["harnesses"]["opencode"]
+    opencode_rows = {tier: opencode[tier] for tier in ("fable", "opus", "sonnet", "haiku")}
+    return {
+        "claude": GENERATED
+        + "# Claude Code mapping\n\n"
+        + _table(claude_rows)
+        + "\n\nSpawn the named native agent; its generated frontmatter selects the configured model.\n"
+        + _collapse_note(claude_rows)
+        + _skill_notes(config, "claude"),
+        "codex": GENERATED
+        + "# Codex mapping\n\n"
+        + _table(codex)
+        + "\n\nSpawn 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.\n"
+        "\nRead-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.\n"
+        + _collapse_note(codex)
+        + _skill_notes(config, "codex"),
+        "cursor": GENERATED
+        + "# Cursor mapping\n\n"
+        + _table(cursor)
+        + "\n\nCursor 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.\n"
+        + _collapse_note(cursor)
+        + _skill_notes(config, "cursor"),
+        "hermes": GENERATED
+        + "# Hermes mapping\n\n"
+        + f"Provider: `{hermes['provider']}`\n\n"
+        + _table(hermes_rows)
+        + "\n\nHermes 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.\n"
+        "\nThis 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.\n"
+        + _collapse_note(hermes_rows)
+        + _skill_notes(config, "hermes"),
+        "opencode": GENERATED
+        + "# OpenCode mapping\n\n"
+        + f"Provider: `{opencode['provider']}`\n\n"
+        + _table(opencode_rows)
+        + "\n\nRoles register as native OpenCode agents (from `adapters/opencode/agents.json`, "
+        "generated from `config/models.json` and `roles/*.md`) and are spawned via the task tool "
+        "as subagents. There is no per-spawn model override on this harness: each agent always "
+        "runs its registered model, so `reviewer` always runs the full Opus-tier model — the "
+        "trivial-diff Sonnet-tier downscale does not apply here; every diff gets the full review.\n"
+        "\nRead-only is harness-enforced here, unlike Codex and Cursor: read-only roles carry a "
+        "generated `permission.edit: deny`, so an off-policy write attempt is refused by OpenCode "
+        "itself, not merely discouraged by the prompt. Write-capable agents additionally carry "
+        "coarse `rm -rf` bash denies as a stopgap for opencode#5894 (unconfirmed whether "
+        "`tool.execute.before` also intercepts subagent bash); the precise tripwire stays "
+        "`hooks/bash-guard.py` on the primary agent.\n"
+        "\nNo `EnterWorktree` tool exists here — use leo:worktrees' raw `git worktree` fallback for "
+        "isolated branch work. State reads and writes go through `python3 <plugin-root>/scripts/state.py` "
+        "(`get` / `merge` / `path`), same contract as every other harness. There is no Workflow tool "
+        "and no `cost-tiered-fix.js` here — a batch of independent tasks is fanned out as manual "
+        "parallel task-tool subagent spawns instead.\n"
+        + _collapse_note(opencode_rows)
+        + _skill_notes(config, "opencode"),
+    }
+
+
+def render(config):
+    outputs = {}
+    for role, tier in sorted(config["roles"].items()):
+        claude, cursor = _agent_docs(role, tier, config)
+        # Claude Code agents MUST live at the conventional agents/ path: a
+        # manifest "agents" array of file paths validates but silently loads
+        # zero agents, and the conventional directory auto-loads.
+        outputs[ROOT / "agents" / f"{role}.md"] = claude
+        outputs[ROOT / "adapters" / "cursor" / "agents" / f"{role}.md"] = cursor
+    for harness, content in _mapping_docs(config).items():
+        outputs[ROOT / "skills" / "using-leo" / "references" / f"{harness}-mapping.md"] = content
+    outputs[ROOT / "adapters" / "opencode" / "agents.json"] = _opencode_agents(config)
+
+    # The manifest is no longer rewritten here: per-install model overrides
+    # were retired along with the placeholder they fed. Retiering means editing
+    # config/models.json and re-running this script, the flow README documents.
+    return outputs
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--check", action="store_true", help="fail if generated adapters drift")
+    args = parser.parse_args()
+    config = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    outputs = render(config)
+    drift = []
+    for path, expected in outputs.items():
+        if path.exists() and path.read_text(encoding="utf-8") == expected:
+            continue
+        if args.check:
+            drift.append(path.relative_to(ROOT).as_posix())
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(expected, encoding="utf-8")
+
+    # Stale generated files are drift too. Comparing only what render() would
+    # produce is blind to a file that exists and *shouldn't* — a role dropped
+    # from models.json, a harness renamed — so the orphan survives every
+    # --check and ships. Sweep the generated trees and flag anything unclaimed.
+    for pattern in (
+        "agents/*.md",
+        "adapters/cursor/agents/*.md",
+        "adapters/opencode/agents.json",
+        "skills/using-leo/references/*-mapping.md",
+    ):
+        for path in sorted(ROOT.glob(pattern)):
+            if path in outputs:
+                continue
+            rel = path.relative_to(ROOT).as_posix()
+            if args.check:
+                drift.append(f"{rel} (stale: nothing in config/models.json generates it)")
+            else:
+                path.unlink()
+                print(f"removed stale generated file: {rel}", file=sys.stderr)
+    if drift:
+        print("generated adapter drift: " + ", ".join(drift), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/state.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""state: machine-local JSON state for leos-agent skills and agents.
+
+CODE ships inside the plugin (possibly a versioned cache that a plugin update
+can wipe or relocate) — this file must never derive the data root from its own
+__file__ location. DATA always lives under
+${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}, independent of where this
+script itself happens to run from, so a plugin update can never lose state.
+
+State lives at $LEOS_AGENT_LOCAL_PATH/<name>.json (LEOS_AGENT_LOCAL_PATH is an
+optional override; unset, it defaults to ~/.leos-agent-local). The base is a
+dedicated data directory rather than a repo root, so there is no nested
+local/ segment inside it: state never syncs between machines. Top-level
+keys are "owner/repo" (or an
+absolute project path when there is no GitHub repo) so data stays separate per
+repo/project.
+
+  state.py get   <name> [<repo-key>]        print the repo's subtree, or the
+                                            whole file with no key ({} if absent)
+  state.py merge <name> <repo-key> <json>   deep-merge <json> into the subtree
+  state.py path  <name>                     print the backing file's path
+
+merge semantics: dicts merge recursively, lists union in order (deduped,
+so merging {"reviewed": [13]} twice never double-adds), scalars overwrite.
+merge calls are serialized (flock on a sibling <name>.json.lock) and each
+write is atomic (tempfile + os.replace), so concurrent merges from parallel
+agents never lose an update; get is lock-free. Exit codes: 0 ok, non-zero on
+error.
+"""
+import contextlib
+import fcntl
+import json
+import os
+import sys
+import tempfile
+
+
+def _data_root():
+    return os.environ.get("LEOS_AGENT_LOCAL_PATH") or os.path.join(os.path.expanduser("~"), ".leos-agent-local")
+
+
+def state_file(name):
+    if "/" in name or "\\" in name or ".." in name or os.path.isabs(name):
+        sys.exit(f"state: {name!r} is not a valid state name (no slashes, no .., not absolute)")
+    root = _data_root()
+    os.makedirs(root, exist_ok=True)
+    return os.path.join(root, f"{name}.json")
+
+
+@contextlib.contextmanager
+def _locked(path):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    fd = os.open(path + ".lock", os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+def load(path):
+    try:
+        with open(path) as fh:
+            data = json.load(fh)
+    except FileNotFoundError:
+        return {}
+    except json.JSONDecodeError as e:
+        sys.exit(f"state: {path} is corrupt ({e}) — fix or delete it")
+    if not isinstance(data, dict):
+        sys.exit(f"state: {path} is corrupt (top level is {type(data).__name__}, expected object) — fix or delete it")
+    return data
+
+
+def deep_merge(base, patch):
+    if isinstance(patch, dict):
+        merged = dict(base) if isinstance(base, dict) else {}
+        for key, value in patch.items():
+            merged[key] = deep_merge(merged.get(key), value)
+        return merged
+    if isinstance(patch, list):
+        merged = list(base) if isinstance(base, list) else []
+        for v in patch:
+            if v not in merged:
+                merged.append(v)
+        return merged
+    return patch
+
+
+def atomic_write(path, data):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as fh:
+            json.dump(data, fh, indent=1, sort_keys=True)
+            fh.write("\n")
+        os.replace(tmp, path)
+    except BaseException:
+        os.unlink(tmp)
+        raise
+
+
+def main(argv):
+    if len(argv) >= 2 and argv[0] == "path":
+        print(state_file(argv[1]))
+    elif len(argv) >= 2 and argv[0] == "get":
+        data = load(state_file(argv[1]))
+        if len(argv) >= 3:
+            data = data.get(argv[2], {})
+        print(json.dumps(data, indent=1, sort_keys=True))
+    elif len(argv) == 4 and argv[0] == "merge":
+        try:
+            patch = json.loads(argv[3])
+        except json.JSONDecodeError as e:
+            sys.exit(f"state: patch is not valid JSON ({e})")
+        path = state_file(argv[1])
+        with _locked(path):
+            data = load(path)
+            data[argv[2]] = deep_merge(data.get(argv[2], {}), patch)
+            atomic_write(path, data)
+        print(json.dumps(data[argv[2]], indent=1, sort_keys=True))
+    else:
+        sys.exit(__doc__.strip())
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

package/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": { "defaultMode": "auto" },
+  "tui": "fullscreen",
+  "theme": "auto",
+  "skipWorkflowUsageWarning": true,
+  "agentPushNotifEnabled": true
+}

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: brainstorming
+description: >
+  Design gate before non-trivial code — proportional to blast radius and
+  reversibility, the deliberate opposite of an unconditional gate. Contained,
+  easily reversible changes clear with one sentence of rationale; changes with
+  wide blast radius, hard to reverse, or that introduce new surface need
+  genuine, viable alternatives with trade-offs weighed before any code gets
+  written. Produces the chosen approach and its trade-offs, sized to the gate,
+  handed off to leo:writing-plans.
+when_to_use: >
+  Before starting non-trivial code: a new feature, a new integration surface,
+  a schema or data-model change, anything that's expensive or awkward to
+  undo. NOT for a contained, easily reversible tweak (that just needs one
+  sentence of rationale, not this skill's full procedure), NOT for pure
+  investigation (use investigator), and NOT for writing the plan itself
+  (leo:writing-plans) — brainstorming stops at a chosen approach, it never
+  slides into implementation.
+---
+
+# brainstorming
+
+Core rule: the depth of the design gate is proportional to blast radius and
+reversibility, not to how the task felt when it landed. A one-line change to
+a private helper does not need three alternatives; a new public API or a
+schema migration does.
+
+## Size the gate first
+
+Before generating anything, classify the change:
+
+- **Contained + easily reversible** (a local refactor, an internal helper, a
+  flag you can flip back) → one sentence of rationale is enough. Say what
+  you're doing and why, then move to leo:writing-plans or straight to
+  implementation per the routing table.
+- **Wide blast radius, hard to reverse, or new surface** (public API, schema
+  or data-model change, cross-service contract, anything users or other
+  systems will come to depend on) → full gate: genuine alternatives with
+  trade-offs, written down, before any code.
+
+When unsure which bucket, treat it as the wider one — the cost of one extra
+paragraph is nothing next to the cost of an unreversible wrong turn.
+
+## Alternatives must be viable
+
+Every alternative in a full gate has to be something a reasonable engineer
+could actually ship and defend, not a strawman stood up to make the first
+idea look good by comparison. If you can't articulate a real reason someone
+would pick alternative B, it isn't an alternative — go find one that's
+actually competing for the job, or drop down to the one-sentence gate because
+there's really only one sane approach.
+
+Test: could you argue for this option in front of Leo without a "but
+obviously we won't do this" tone? If not, it's a strawman — cut it.
+
+## Generation method
+
+To surface genuinely different options, vary along a different axis each
+time rather than producing three cosmetic variants of the same idea:
+
+1. **Data model vs. control flow vs. boundary/interface** — would this
+   problem look different if you moved the complexity into the data shape,
+   into how execution flows, or into where the interface/boundary sits?
+2. **Prior art in the repo** — grep for how this repo already solved a
+   similar problem (via explore, not inline digging) and steal that pattern
+   before inventing a new one. Consistency with existing structure is a real
+   trade-off, not a tie-breaker of last resort.
+3. **The 10x-simpler version** — what would this look like with one-tenth
+   the code/config/moving parts? Even when you don't ship it, it's usually
+   the sharpest lens on what the "proper" version is paying for.
+
+## Output
+
+- Contained/reversible: one sentence of rationale, folded into the plan or
+  the commit itself.
+- Full gate: the chosen approach plus the trade-offs record — a paragraph for
+  a medium decision, a short doc for a genuinely high-stakes one. Sized to
+  the gate, not padded to look thorough.
+
+Either way, the output is a decision, not code. Hand it to
+leo:writing-plans for the actual plan; brainstorming never slides into
+implementation itself.
+
+## Self-talk to catch
+
+- "I'll just list two options so it looks considered" — if you can't defend
+  both, that's a strawman, not a gate.
+- "This is a big change but I already know the answer" — blast radius and
+  reversibility decide the gate size, not your confidence.
+- "I'll sketch the plan while I'm at it" — that's leo:writing-plans' job;
+  stop at the chosen approach.
+- "One sentence feels thin for something this exciting" — excitement isn't
+  blast radius; if it's contained and reversible, one sentence is correct.
+
+## Escalation
+
+Planning-tier work runs at Opus per the routing table (plan mode in an Opus
+session, or the `planner` subagent otherwise). Escalate per the standard
+ladder: two failed passes at reaching a defensible set of alternatives step
+up a tier; a genuine deadlock between two Opus-tier framings goes to
+`expert`, announced in one line, never silently.
+
+## Works with
+
+- leo:writing-plans — takes the chosen approach and turns it into an
+  executable plan.
+- investigator — for questions that need evidence before a design question
+  can even be framed.
+- explore — cheap prior-art search feeding the generation method above.

package/skills/debugging/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: debugging
+description: >
+  Root-cause-before-fix loop for bugs, failing tests, crashes, and surprising
+  behavior. Five named phases — Reproduce, Localize, Hypothesize, Prove, Fix —
+  each with an exit criterion, so a fix never lands before the cause is
+  pinned to file:line. Diagnosis is read-only judge work (investigator); the
+  fix happens separately, at the routed tier.
+when_to_use: >
+  Any bug report, failing test, crash, stack trace, or "why does X happen"
+  before proposing a fix — used by the investigator agent and by the main
+  loop ahead of any edit that touches broken behavior. NOT for planned
+  feature work with no defect (that's planner), NOT for judging someone
+  else's diff (that's reviewer), and NOT a substitute for leo:verification
+  after the fix lands — this skill ends at Fix, verification is separate.
+---
+
+# debugging
+
+Core rule: no fix before the cause is REPRODUCED and LOCATED at file:line. A
+symptom going away is not proof — it's a coincidence until the loop below
+says otherwise.
+
+## When it fires
+
+Bug reports, failing tests, crashes, stack traces, flaky behavior, "this
+should work but doesn't." Route the diagnosis itself through `investigator`
+(Opus, read-only) per the model-routing table — this skill is its loop.
+Doesn't fire for greenfield feature work (no defect exists yet) or for
+diffing someone else's change (that's `reviewer`).
+
+## The five phases
+
+Named exactly, run in order, each with an exit criterion. Do not skip a
+phase because the bug "looks obvious" — obvious bugs are exactly the ones
+where a wrong guess ships fastest.
+
+| Phase | Exit criterion |
+|---|---|
+| **Reproduce** | The failure fires on command — a test, a script, a repro sequence — not "worked once." No stable repro yet is itself a finding: report it, don't guess past it. |
+| **Localize** | The failure is traced to a specific **file:line**, not a subsystem or a vibe ("something in auth"). Read the actual code path the repro exercises; don't infer from names or docs. |
+| **Hypothesize** | One sentence: "X happens because file:line does Y instead of Z." One hypothesis at a time — write it down before touching anything. |
+| **Prove** | The smallest evidence that the hypothesis IS the cause, not just correlated with it. Where the surface is testable, that's a failing test written per `leo:test-first` — red on the bug, and its assertion names the file:line from Localize. Where nothing is testable (infra, timing, external system), the next-smallest evidence: a log line, a debugger break, a minimal repro script. |
+| **Fix** | The change that makes Prove's evidence pass. Happens at the routed tier (`executor` for mechanical, `implementer` for real changes) — never by the same pass that diagnosed it. |
+
+Reproduce and Localize can compress into one step for a trivial case (a
+crash with a one-frame stack trace pointing straight at the bug) — but
+Hypothesize and Prove never collapse into Fix. If you catch yourself editing
+code before you've written the hypothesis sentence, stop and back up.
+
+## One hypothesis, one change
+
+Test one hypothesis at a time. If Fix doesn't clear Prove's evidence, the
+hypothesis was wrong — REVERT the change before forming the next one. Never
+stack a second speculative edit on top of a first that didn't pan out; you
+lose the ability to tell which change did what, and the diff stops being
+reviewable. Revert, re-enter Hypothesize with what the failed attempt taught
+you, and go again.
+
+## Stuck: the ladder
+
+After two failures on the same cause (two hypotheses tried and reverted, still
+no Prove), step up one tier rather than retrying at the same one — investigator
+haiku-assist steps to full investigator, investigator itself steps to a
+second, more evidence-fed pass, capped at Opus. A genuine deadlock, or two
+Opus verdicts on the same cause that disagree → `expert`, announced in one
+line ("escalating to expert: <question>") before it's invoked, never silent.
+Don't loop a third time at the same tier hoping the next guess lands — that's
+the same failure mode as skipping Prove, just slower.
+
+## Diagnosis and fix stay separate
+
+The phase that reaches the verdict (Reproduce through Prove) is read-only
+judge work — no edits, no reverts-of-other-people's-code, just evidence and a
+file:line. Whoever ran that pass hands the hypothesis and its proof to the
+executing tier for Fix. This mirrors why `reviewer` never patches what it
+finds: the same pass that wants to be right about the cause is a bad judge of
+whether it actually is. After Fix lands, `leo:verification` (or a plain
+`reviewer` pass on the diff) is the separate check that the fix is real and
+didn't just make Prove's specific probe go quiet.
+
+## Self-talk to catch
+
+- "It's obviously the timeout" — obvious is not file:line; go Localize it.
+- "Passing now, good enough" — passing isn't Prove; did you write the
+  failing-first check, or did the symptom just stop reproducing?
+- "I'll patch this and see if it helps" — that's skipping Hypothesize; name
+  the mechanism before touching code.
+- "One more tweak on top, I'm close" — that's the stacked-edit trap; revert
+  first.
+- "Third guess this tier, one more won't hurt" — it's the two-failures
+  trigger; escalate instead.
+
+## Works with
+
+`leo:test-first` for writing Prove's failing test. `leo:verification` for
+the post-Fix check. `investigator` runs this loop; `reviewer` judges the
+resulting diff once Fix is applied.