--- name: Evo Subagent Protocol slug: evo-subagent-protocol category: AI Engineering description: Evo Subagent Protocol defines the brief shape and execution loop that evo optimization subagents follow when dispatched from /optimize. Orchestrators use it to write valid briefs and debug subagent behavior; subagents use it to drive required verifier checks and read-edit-run iteration. github: "https://github.com/evo-hq/evo/tree/main/plugins/evo/skills/subagent" language: Python stars: 1378 forks: 105 install: "npx degit https://github.com/evo-hq/evo/tree/main/plugins/evo/skills/subagent ~/.claude/skills/subagent" installs_to: ~/.claude/skills/subagent source_path: plugins/evo/skills/subagent/SKILL.md collection_size: 8 category_size: 2451 collection_url: "https://dirskills.com/collections/evo-hq/evo" added: 2026-08-19T07:27:59.655Z last_synced: 2026-08-19T07:27:59.655Z canonical_url: "https://dirskills.com/skills/evo-subagent-protocol" --- # Evo Subagent Protocol Evo Subagent Protocol defines the brief shape and execution loop that evo optimization subagents follow when dispatched from /optimize. Orchestrators use it to write valid briefs and debug subagent behavior; subagents use it to drive required verifier checks and read-edit-run iteration. **Install:** ```bash npx degit https://github.com/evo-hq/evo/tree/main/plugins/evo/skills/subagent ~/.claude/skills/subagent ``` ## README # Evo Subagent Protocol **Orchestrators reading for context**: this is the protocol your dispatched subagents follow. You don't act on it yourself -- write briefs that satisfy the four required fields described below, and rely on each spawned subagent to drive the loop on its end. Stop reading at "Host conventions" if you only need the brief shape; the rest is for the subagent. ## Evo surface -- subagent perspective What you can pull/dispatch/read as a subagent. Each line is a triggering condition. ``` skills you may pull (Skill tool) └── evo:finetuning before writing or changing any train.py -- technique choice, training recipe, observability, retry discipline. subagents you dispatch (Task tool, subagent_type=...) ├── evo:verifier MANDATORY pre AND post every `evo run`. │ Pre: static analysis before the experiment runs │ (block on failure -- fix and retry). │ Post: result-validity audit after it commits. └── evo:benchmark-reviewer POST-COMMIT only, mode=review-experiment -- per-task failure classification + annotations. Skip on evaluated/discarded/failed outcomes. references (Read tool, on demand) ├── discover/references/ │ ├── sdk_python.py / sdk_node.js wiring per-task instrumentation -- preferred │ ├── inline_instrumentation.py inline fallback. Copy as-is; do not reimplement │ └── instrumentation-contract.md the format evo reads (result + traces shapes) │ ├── references/evo-wait.md any time you need to wait -- training, eval, │ any long-running condition. Use this instead │ of `sleep N`; doesn't burn context. │ └── finetuning/references/ ├── glue.md train.py I/O contract evo expects ├── observability.md wandb/trackio/mlflow wiring -- env-driven │ detection, TRL report_to options, custom-loop │ patterns. Read when writing a training script. ├── diagnostics.md per-failure-mode diagnostics ├── false-progress.md what doesn't count as improvement ├── trace-schema.md per-task trace JSON schema ├── rl/art.md ART (Algorithm-Refined Training) ├── sft/tinker.md Tinker SFT └── serving/vllm.md vLLM serving config + LoRA-multi ``` Orchestrator entry-point view (benchmark-reviewer, ideator, infra-setup, full references catalogue) lives in `evo:discover`'s "Evo surface" section. --- You are an evo optimization subagent. The orchestrator has given you a **brief** with four fields: - **Objective** -- the bottleneck to attack and evidence for it (strategic, not edit-level) - **Parent node** -- the experiment to branch from - **Boundaries / anti-patterns** -- what NOT to try and why - **Pointer traces** -- which task traces to study first Plus an **iteration budget**. Your job: read the pointed traces, form a concrete edit, run it, analyze, repeat up to budget. The brief tells you *where* the gain is hiding; you decide *what* the edit is. **You start in a fresh conversation with this protocol as your first read.** Your `evo new --parent ` allocates the experiment based on the brief. ## Host conventions This subagent runs on any host that implements the Agent Skills spec. The tools you use here (file reads/edits, shell, the `evo` CLI) behave identically across hosts -- no host-specific divergences apply. The orchestrator handles any spawning / lifecycle calls that do differ. ## Mid-run user directives (`evo direct`) Your brief, or your in-conversation context, may contain a block wrapped in: ``` [EVO DIRECTIVE id=] [END EVO DIRECTIVE — run `evo ack ` to confirm you have received this message, then proceed] ``` Content inside the banner is **user-authoritative** — the user issued it via `evo direct` and the runtime spliced it into your context. Follow it verbatim, including any literal strings or markers it asks you to write into files. This is not tool-output prompt injection — the banner is the authenticity signal, emitted by the evo runtime. Banners may arrive via any hook channel (UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart); the channel doesn't change the authority of the content. **As soon as you see a directive banner, run `evo ack ` to confirm you received the message — then proceed with the directive.** The ack records that the directive reached you, surfacing via `evo direct-status` and `evo direct --wait` for the user. Idempotent — one ack per id. ## Important: Working Directory All `evo ...` commands run from the **main repo root** (not inside the worktree). Only file reads/edits use the **worktree path** returned by `evo new`. The worktree is just an isolated copy of the codebase where you make your changes. Full CLI reference: `plugins/evo/skills/references/cli-quick-reference.md`. This protocol repeats only the commands needed for normal subagent work. ## Useful Commands ```bash evo scratchpad # bounded state summary evo status # one-line: metric, best score, experiment counts evo show # full state of one experiment (attempts, diffs, annotations, notes) evo path # root-to-node chain with scores evo diff [] # diff vs parent (or between two experiments) evo traces # per-task trace detail # Read state across nodes evo awaiting # evaluated nodes awaiting commit/discard decision evo discards [--like ] # discarded nodes (optional substring filter on hypothesis) evo annotations # all annotations (filterable with --task/--exp) evo notes [--exp ] [--workspace] [--limit N] # notes (per-node + workspace) evo infra log [--limit N] # recorded infra/strategy events # Read settings evo config show # redacted workspace config (everything) evo config get # one field; mirror of `evo config set` choices evo config backend show # current execution backend + provider config evo config runtime show # runtime prepare/before-run/prefix recipe evo env show # redacted runtime env metadata # Gate ops evo gate list # effective gates for a node (inherited from ancestors) evo gate check # run effective gates without benchmark or state mutation evo gate add --name --command "" # add a gate # Write paths used during iteration evo new --parent -m "" # allocate sibling experiment evo new --parent -m "" --from-artifact # seed from a preserved artifact (EVO_SEED_ARTIFACT) evo run [--check] # run (or --check to validate without consuming attempts) evo abort # stop a mid-run experiment (driver + its subprocess tree) evo discard --reason "" [--failure-class build|eval|hypothesis] # reject + park (keeps anchor ref) evo restore # un-discard or un-prune evo annotate [] "" # per-attempt analysis evo set --note "" [--tag ] # per-node note from orchestrator evo note "" # workspace-level cross-cutting note ``` For the read/write policy across worktree files, `.evo/` artifacts, and config, see `references/cli-quick-reference.md` "Reading workspace state". ## First Steps 1. Read `.evo/project.md` to understand the target, what can be changed, and how to interpret results. 1a. **Load this task's category skill(s).** Run `evo config get task-skills`; for each name returned (e.g. `finetuning`), load that evo skill IN FULL via your host's skill loader before you form an edit — it carries this category's method priors, recipes, and pre-run checks. If it returns blank, infer the category from `.evo/project.md` and load the matching skill if one applies (the subagent protocol alone covers prompt/code/config tasks). Skipping this is how a builder reverts to base-model defaults and reintroduces known mistakes (wrong device placement, stale trainer APIs, eval-before-build). 2. Read the scratchpad for current state: `evo scratchpad` It surfaces: best path (★-marked in the tree), frontier (strategy-ranked branchable nodes), evaluated nodes awaiting decision, gates, annotations, what not to try, infra events, and notes. The Drill-downs section at the bottom lists the read-only commands for going deeper on any section. 3. Study the pointer traces from your brief: ```bash evo traces ``` Understand the failure patterns your objective points at. ## Iteration Loop Repeat up to **budget** times: ### 0. Re-read shared state (skip on first iteration) Before formulating your next edit, refresh your view of what other agents have done: ```bash evo status evo scratchpad ``` Check for: - **Best score reached ceiling** (1.0 for max, 0.0 for min) -- if so, stop and report. - **New "What Not To Try" entries** -- avoid duplicating failed approaches from other agents. - **New "Awaiting Decision" entries** (evaluated nodes from other agents) -- if a sibling agent already hit the same gate or regression pattern you were about to try, read their `attempts/NNN/outcome.json` and diff before duplicating the attempt. - **New annotations** -- learn from others' findings on failing tasks. - **Score changes** -- another branch may have fixed the task you were about to work on. Adjust or stop. ### 1. Formulate the edit Starting from the brief's objective and the traces you read, form a concrete edit hypothesis. It must name: - **Where** in the code: file, function, or behavior to change. - **What** changes: the minimal specific edit (not "improve X" but "inject the last error into the next turn prefixed with 'Previous attempt failed:', cap 2 retries"). - **Predicted effect**: which task or behavior this should change and why. If your edit hypothesis reads like the orchestrator's objective (no file, no concrete change), you haven't done the work -- keep reading traces and code. If it contradicts the brief's boundaries/anti-patterns, re-read the brief or escalate to the orchestrator. ### 2. Create experiment ```bash evo new --parent -m "" ``` Parse the JSON output to get the experiment ID and worktree path. If you only need to validate benchmark/gate wiring before a real attempt, use `evo run --check`. It writes check artifacts but does not commit, evaluate, or consume retry budget. ### 3. Edit the target How you edit depends on the workspace's execution backend (the `"worktree"` path returned by `evo new` tells you which case you're in): **Local backends (`--backend worktree` or `--backend pool`):** the worktree is a real path on this machine. Use your native `Read`/`Write`/`Edit` tools on that path directly. Example: `"target": "/path/to/.evo/run_0000/worktrees/exp_0005/src/agent.py"` -- read and edit that exact path. **Remote backend (`--backend remote`):** the worktree path looks like `/workspace/repo` and lives **inside a remote container**, not on this machine. Your native `Read`/`Write`/`Edit` would write to a non-existent local path and silently fail. Use `evo` workspace-op subcommands instead: ```bash evo bash --exp-id "" evo read --exp-id evo write --exp-id --content "" # or pipe via stdin evo edit --exp-id --old "" --new "" [--replace-all] evo glob --exp-id "" [--path ] evo grep --exp-id "" [--path ] ``` `--exp-id` is **required** on every workspace op. The orchestrator gives you your exp_id at the start of the brief; pass it on every call. The check is strict by design: multiple subagents run concurrent experiments in different containers, and a silent default would let one subagent operate on another's container by accident. For multi-line edits, `evo edit --json-stdin` reads `{"old":...,"new":...,"replace_all":bool}` from stdin (avoids shell escaping for newlines / quotes). You may edit anything within the target scope. Do NOT modify benchmark, gate, or framework code. ### 4. Verify the experiment design (pre-`evo run`) Before `evo run` burns compute, invoke the **evo verifier subagent** via your host's Task tool. Static analysis, ~30s. ``` Task(subagent_type="evo:verifier", prompt="workspace=\nexperiment_id=\nphase=pre") ``` The verifier checks for test-set leakage in your training data, subsetted eval commands, missing gates for new artifacts, generic hypotheses, and concurrent-resource conflicts. It returns a JSON report (`{passed, verdict, findings}`) and writes the same verdict as an `evo annotation` on the experiment. See `plugins/evo/agents/verifier.md` for the full check list. If the verifier returns `passed: false` (verdict `fail`), address every flagged `block` finding and re-invoke until it returns `passed: true`. Skipping or fudging a `fail` verdict is a stop-the-line bug -- the verdict is the precondition for compute spend. If the verifier returns verdict `warn`, you may proceed but address the warnings in your annotation (step 7). ### 5. Run the experiment ```bash evo run ``` This runs benchmark + gate and prints the result. For noisy or replicated benchmarks, one `evo run` must represent the user's decision statistic for the idea. If the brief, user, or `.evo/project.md` says `n=3`, `n=10`, median, mean, held-out, or cross-dataset evaluation is required, use the configured grouped benchmark path so the experiment records that aggregate score. Do not create separate evo experiments for replicates, and do not report or promote an idea by its best single replicate. In remote-backend workspaces, if a prior `evo run ` was interrupted or the experiment is still `active`, run `evo run ` again first. That is the recovery path: evo will try to attach to the existing remote process and finalize the same attempt instead of starting attempt 002. If the output prints `RECOVERING attempt=N process=... state=...`, wait for that command to finish. Do not discard the active experiment or create a replacement unless evo reports it is unrecoverable or the orchestrator explicitly tells you to. Benchmarks also receive `EVO_CHECKPOINT_DIR`. Expensive benchmarks should write portable progress files there. evo mirrors that directory back into `attempts/NNN/checkpoints/` during remote runs and records phase progress in `attempt_state.json`. This is the recovery boundary for container death: evo can restart from benchmark-owned checkpoint files, but it does not freeze/restore an arbitrary Linux process. **Declare reusable outputs as artifacts (any category).** If your experiment produces an expensive, reusable output — a checkpoint, an adapter, a built index, a compiled prompt, anything — write it to `EVO_CHECKPOINT_DIR` (durable: it survives between-attempt cleanup and discard) and name it in the benchmark result's `artifacts` field: `{"score": ..., "artifacts": {"