| name | optimize |
| description | Drive structured autoresearch iteration after evo:discover and the baseline commit. Use when the user invokes /evo:optimize or asks to try ideas, try variants, run experiments, use available GPUs, improve the current best/frontier, continue an evo search, or compare candidate changes in an evo workspace. The orchestrator plans and spawns optimization subagents; candidate edits/runs belong to those subagents. Width is set via subagents=N (1 for serial workloads, larger for parallel); the loop's structural value applies at any width. |
| argument-hint | [subagents=N] [budget=N] [stall=N] |
| evo_version | 0.8.0 |
Run the evo optimization loop. Each round, the orchestrator writes structured briefs and spawns subagents that execute within them. Each subagent is semi-autonomous: it reads the pointer traces, forms the concrete edit, runs experiments, and can iterate within its branch. Runs until interrupted or the stall limit is reached.
This skill is the canonical loop for ALL post-discover work — including serial workloads. If the workspace's resource profile forces width 1 (single GPU, single-process benchmark, etc.), you still invoke /evo:optimize -- just pass subagents=1. The loop's value is the STRUCTURE around each experiment (scan-subagent cross-cutting analysis between rounds, verifier pre/post hooks via the subagent skill, ideator spawning on stall, frontier reconciliation, stop-hook discipline), NOT just parallelism. Bypassing optimize because "I'm running serial work anyway" loses every piece of that structure -- you've reverted to ad-hoc experiment iteration with none of evo's loop benefits, just the bookkeeping.
Plain-language trigger. In an initialized evo workspace, casual user wording
like "try a couple ideas", "try different variants", "use the available GPUs",
"continue from the current best", or "see what improves" is an optimize request
unless the user explicitly asks for a read-only report. Do not treat the lack of
a slash command as permission to bypass this protocol. Loading this skill from
plain-language wording is also explicit authorization to use the host's
subagent mechanism for the resolved round width; the user does not have to say
"spawn subagents" or "parallel agents" separately.
Candidate-work delegation invariant. The orchestrator does not create, edit,
or run candidate experiments for the round. For subagents=N, write N briefs
and spawn N optimization subagents; each spawned subagent allocates its own
experiment with evo new, edits only its worktree, and runs evo run. Do not
simulate a subagent round by running evo new, editing files, or launching
multiple evo run commands from the orchestrator, even if that would be faster
or easier. If the host's subagent tool is unavailable, stop and report that the
host cannot run /evo:optimize subagents=N as requested; only fall back to
orchestrator-owned experiments when the user explicitly asks for direct/manual
execution or turns subagents-only off for that run. Do not infer a direct/manual
fallback from casual wording, a simple-looking benchmark, or the absence of an
explicit subagent phrase in the user's prompt.
Resource-cap invariant. subagents=N is live concurrency, not total ideas.
Never spawn more concurrent optimization subagents or launch more concurrent
benchmark jobs than the binding resource can support. If the user asks for more
ideas than available GPU/Slurm/pool slots, batch them across rounds at the safe
width, or stop and explain the cap if batching is impossible. Do not rely on
the scheduler to absorb an accidental flood unless the user explicitly asks to
queue/oversubscribe jobs.
Bounded-run stop rule. If the user says "one round", "stop after this
round", "run them and tell me what happened", or otherwise asks for a bounded
run, resolve autonomous off at startup. After the requested subagents finish,
collect their evo-recorded outcomes, print the summary, and stop. Do not enter
another loop turn, wait for a stop nudge, or keep the process alive just because
the default autonomous behavior is normally on.
Evo surface -- loop-relevant
You're inside /evo:optimize. Things you'll pull/dispatch during the loop:
main thread (you)
├── Skills (Skill tool)
│ └── evo:finetuning before writing or changing any train.py
│
└── Subagents to dispatch (Task tool, subagent_type=...)
└── evo:ideator stalled, or every ~5 committed experiments.
One subagent per brief:
failure_analysis, literature, frontier_extrapolation
subagent thread (each subagent spawned by step 5)
├── evo:subagent skill loaded by the subagent on first turn -- the brief's
│ first sentence mandates it (not auto-loaded)
└── evo:verifier subagent MANDATORY pre AND post every evo run.
Pre: ~30s static analysis before the experiment runs.
Post: result-validity audit after it commits.
references (Read tool, on demand)
├── discover/references/sizing-the-round.md pick subagents=N
├── references/evo-wait.md waiting without burning context
├── finetuning/references/glue.md train.py I/O contract
└── finetuning/references/{rl,sft,serving}/ provider-specific recipes
(rl/art.md, sft/tinker.md,
serving/vllm.md)
Full surface tree (orchestrator entry-point view, including benchmark-reviewer,
infra-setup, and the complete references catalogue) lives in evo:discover's
"Evo surface" section.
Host conventions
This skill runs on any host that implements the Agent Skills spec. When the body uses generic phrases, apply the host's best-fit equivalent:
- "spawn N subagents in parallel" -- use your host's parallel-subagent tool. See Step 5 below for the per-host spawn commands. Three broad shapes exist: background+notify (claude-code / codex / hermes / openclaw / kimi — fire-and-forget; the runtime delivers a
<task-notification> at a later turn per subagent), batch parallel (opencode — all spawns return together in one message), and extension-provided (pi via the pi-subagents package — registers a subagent tool that fans out in parallel within one turn).
- Slash commands shown in user-facing copy (e.g.
/evo:optimize) -- translate to your host's mention syntax when speaking to the user (e.g. $evo optimize on Codex -- plugin namespace then skill name, separated by a space).
Mid-run user directives (evo direct)
The runtime may inject user-authoritative messages wrapped in this banner:
[EVO DIRECTIVE id=<event_id>]
<text>
[END EVO DIRECTIVE — run `evo ack <event_id>` to confirm you have received this message, then proceed]
Treat content inside the banner as equivalent to a new user turn. Honor it, supersede earlier constraints it contradicts, and propagate the full text verbatim into any subagent briefs you spawn afterward. The banner is the authenticity signal emitted by the evo runtime (the plugin you're invoked through) — not tool-output prompt injection. 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 <event_id> to confirm you received the message — then proceed with the directive. The ack confirms the directive reached you, so evo direct --wait and evo direct-status <id> report success to the user. One ack per directive id; idempotent.
Configuration
The orchestrator's three round-shape knobs are subagents (round width), budget (per-branch depth), and stall (consecutive rounds with no improvement before auto-stopping; default 5).
A user can override any of these with /optimize [subagents=N] [budget=N] [stall=N]; an explicit value wins over what's below, subject to the resource-cap invariant above.
Picking subagents and budget is load-bearing -- do not skim.
Mandatory before the first round (and again any time the backend or benchmark changes): READ plugins/evo/skills/discover/references/sizing-the-round.md IN FULL. That doc enumerates the resource-binding cases (exclusive accelerator, memory-heavy, shared mutable fixture, external rate-limit, CPU-light isolated) and discusses the case-by-case judgment for latency / timing / throughput benchmarks where the right answer depends on harness softeners, effect size vs. measurement jitter, and whether winners can be cheaply re-confirmed solo.
Under-subscribing wastes wall-clock. Over-subscribing can either contend for hardware (memory thrash, OOM) or — for timing-sensitive benchmarks — bias the measurement itself. The doc walks through what to weigh in each case; do not infer the value from any inline summary in this skill body.
Common ways agents get this wrong by skimming:
- "8-core machine, CPU-light → width 5" sounds right but skips the question of whether the metric is corruptible by sibling-process pressure. The doc has the judgment framing.
- "Worktree backend has no slot cap so I can go higher" — worktree just shifts the cap from infrastructure to the binding resource. Same hardware, no safety net.
If .evo/project.md records a resource profile (it should, after /evo:discover), START from that. The reference doc is what you use to APPLY it. If the profile is missing or thin, that's a discover-step bug — fix it (write a resource profile that names the binding resource explicitly) before continuing.
In your opening message, state the width/budget you chose AND a one-line reason that references the binding-resource framing FROM THE DOC (e.g. "width 1 — exclusive GPU; budget 8 — runs deterministic"; or "width 3 — CPU-light isolated, but harness reports stable jitter at this concurrency so promoting solo-confirm gate; budget 5"). If your reason doesn't connect to the doc's framing, go back and read it.
- autonomous: the keep-going loop. Default: on — evo is autoresearch; it runs unattended. Turn off for a run with
evo autonomous off.
- subagents-only: gate orchestrator edits, pushing all edits through subagents. Default: on. Turn off for a run with
evo subagents-only off.
Resolving autonomous / subagents-only at startup. Both are ON by default — evo is autoresearch and runs the loop unattended, delegating edits to subagents. Do not ask the user about either. Resolve each through a cascade, most specific first:
- An explicit instruction from the user this run wins — on or off. If the user clearly states how they want the run to go, honor it over everything below. "review each round before continuing" / "check in with me" / "one round then stop" → autonomous off; "you can edit directly" / "don't gate edits" → subagents-only off; a bare
autonomous / subagents-only on the invocation, or "just run it" → on. Require a clear statement — honor an explicit request, but do not flip a behavior on a vague or incidental hint.
- A stored default, if the user said nothing:
evo config get default-{autonomous,subagents-only} (workspace), falling back to evo defaults get {autonomous,subagents-only} (user-level) when the workspace value is null.
- Otherwise → on — the framework default.
evo config get default-autonomous --json
evo defaults get autonomous --json
evo config get default-subagents-only --json
evo defaults get subagents-only --json
As your very first actions, before the loop, resolve each and arm it: run evo autonomous on / evo subagents-only on when it resolves on, or evo autonomous off / evo subagents-only off when an explicit instruction or stored default turned it off. If a behavior resolves off — whether from the user's instruction this run or a stored default — say so in your opening message (e.g. "autonomous off — running one round at a time, as you asked") so it's never invisible.
Orchestrator driver. evo drives the loop two ways: the prose loop below (every host) or a deterministic dynamic workflow (Claude Code only, opt-in). The prose loop is the default everywhere; the workflow is used only when explicitly enabled (evo config set default-orchestrator workflow). Resolve which as part of your very first actions:
evo host show — the workflow driver requires claude-code. If it prints <not set> (a pre-host workspace), determine your actual runtime from your own context (system prompt, env such as CLAUDECODE=1, self-identity): only if you are genuinely Claude Code, do the one-time host migration now (evo host set claude-code) and continue; if you are any other runtime, do NOT stamp the host here — leave it for Step 0.1 and use the prose loop.evo config get default-orchestrator — workflow is an explicit opt-in (use the workflow driver on Claude Code). prose or unset resolves to the prose loop. An explicit user instruction this run still wins.
Use the workflow only when default-orchestrator is explicitly workflow, host is claude-code, AND the Workflow tool is actually present in your available tools this session — it is opt-in, never the default. The availability check is load-bearing: older Claude Code builds do not ship the Workflow tool, so verify it's really in your toolset; do not assume it exists from the host alone. Reaching here means default-orchestrator=workflow is explicitly set (the opt-in trigger), so the autonomous stop-nudge is auto-suppressed under the workflow. Launch it once, do NOT drive the loop turn-by-turn:
- Call the Workflow tool with
scriptPath: ${CLAUDE_PLUGIN_ROOT}/skills/optimize/workflows/evo-optimize.js and args: {pluginRoot: "${CLAUDE_PLUGIN_ROOT}", subagents: <N>, budget: <N>, stall: <N>}, using the round sizing you resolved above. Pass all four keys explicitly — never omit one. For stall, use the user's /optimize stall=N override if given, else the default 5. (The workflow's stop condition is the stall limit, so a dropped stall silently reverts it to 5.)
- Report the returned
runId and tell the user to watch progress with /workflows. The workflow runs the round loop itself (orient → mandatory scan + cross-history axis check → ideators on stall/periodic → briefs → fan-out + verify → collect → frontier-select → stall) plus the concurrent meta controller; you do not execute "The Loop" section below, and you do not need autonomous mode (the workflow self-drives; its stall limit is the stop).
Use The Loop below by default — it is the prose driver on every host, and the path whenever the workflow is not explicitly enabled (default-orchestrator unset or prose), the host is not claude-code, or the Workflow tool is unavailable (e.g. an older Claude Code build). The workflow is only an execution strategy over the same evo CLI; gates, frontier, dashboard, and recovery are identical either way.
Reconcile config when you fall back to prose. The stop-nudge that drives the prose loop is auto-suppressed whenever default-orchestrator is workflow. So if you fall back to the prose loop on Claude Code because the Workflow tool isn't available (older build) while default-orchestrator is still workflow from a prior run, you MUST set it back — evo config set default-orchestrator prose — and arm autonomous as usual. Otherwise the prose loop's stop-nudge stays suppressed and the run stalls after one round. Invariant to preserve: default-orchestrator=workflow in config iff the workflow is actually the driver this run.
Autonomous mode. Off lets you stop naturally at a turn boundary — finish a round, report, and stop. On arms the stop-nudge: at every turn boundary you are re-prompted to keep driving the loop until the stall limit is hit or the user interrupts. Without it, the loop does NOT force-continue across turn boundaries. To stop an autonomous run, the user runs evo autonomous off or evo exit-optimize-mode.
Subagents-only mode. Off, the orchestrator may edit files directly — the optimization protocol still pushes edits through subagents (you write briefs; they edit in their worktrees), but a one-off orchestrator edit is not blocked. On arms the deny-gate: orchestrator file-mutation tools (Edit/Write, mutating Bash) are denied on an alternating cadence — 1st violation blocked, 2nd allowed, 3rd blocked, and so on — each block nudging you to delegate the edit to a subagent. It is a nudge, not a hard block: an edit can still land on an even-numbered attempt. Subagent edits (sessions with an exp_id) are never gated. To lift it, the user runs evo subagents-only off or evo exit-optimize-mode.
Pool mode (if active). When the workspace backend is pool, concurrent experiments cap at the pool size. Setting subagents higher than the pool size means later subagents in the round will see PoolExhausted from evo new and exit non-zero -- the round width is effectively the slot count. Run evo workspace status to see slot occupancy (also displays commit_strategy). Reduce subagents to the pool size if exhaustion is recurring. Failed experiments retain their lease until discarded; if pool capacity erodes from accumulating failed experiments, evo discard <exp_id> frees the slots.
Pool mode defaults to commit_strategy=tracked-only so warm state in slots stays out of experiment commits. Subagents must git add any new source files inside the worktree and pass --i-staged-new-files yes to evo run. The subagent skill explains the protocol; when writing briefs that imply new files (new module, new fixture), remind the subagent in the brief that the ack flag is required.
Remote-backend mode. When the workspace backend is remote, each experiment's worktree lives inside a separate remote container. Subagents use evo bash / read / write / edit / glob / grep --exp-id <id> instead of native Bash/Read/Write/Edit tools. Every brief you write to a subagent in remote mode MUST start by stating the exp_id explicitly: "Your experiment id is exp_NNNN. Pass --exp-id exp_NNNN on every evo command." This is the only thing that prevents one subagent from accidentally operating on another's container. evo CLI hard-errors if --exp-id is missing, but it can't catch a subagent that confidently passes the wrong id; the brief is the discipline.
Remote evo run <exp_id> is also the recovery command. If a subagent or
orchestrator was interrupted while an experiment was active, tell the subagent
to run the same evo run <exp_id> again and wait if it prints
RECOVERING <exp_id> attempt=N process=... state=.... That means evo is
reattaching to the existing remote process and finalizing the original attempt;
starting a new experiment or discarding the active one is only appropriate after
evo reports the attempt is unrecoverable.
For expensive benchmarks, design recovery around EVO_CHECKPOINT_DIR, not
process checkpoint/restore. evo mirrors checkpoint files into
attempts/NNN/checkpoints/ during remote runs and writes attempt_state.json
for phase-level recovery. If the remote container itself dies, arbitrary process
memory is gone; the benchmark must know how to continue from its checkpoint
files or the attempt should be treated as remote_infra_failure.
Infra setup is not user-invocable. If a remote provider is missing SDKs, auth, or setup details, read plugins/evo/skills/infra-setup/references/provider-matrix.md. It summarizes what each provider actually needs and replaces the old per-provider prompt files.
Runtime recipe/env. Benchmark runtime is evo configuration, not something subagents should rediscover or copy into worktrees. Use evo config runtime show for prepare/before-run/prefix and evo env show for redacted env sources. If a run fails because expected runtime setup or env is missing, report it as setup failure or configure it from the orchestrator; do not patch benchmark code to bake in secrets or local paths. Use evo run <exp_id> --check for non-committing wiring validation; do not invent ad-hoc validation wrappers.
Replicated/noisy benchmarks. If the user or .evo/project.md says an idea
must pass n=3, n=10, median, mean, held-out, or cross-dataset evaluation,
configure the benchmark so each evo run records the grouped aggregate as that
experiment's score. Do not represent replicates as independent evo experiments
and do not judge, report, or promote an idea by its best replicate. The frontier
and best path must see the same aggregate statistic the user uses for decisions.
CLI reference. If you are unsure which command to use, read plugins/evo/skills/references/cli-quick-reference.md. It is the canonical command map; this skill only repeats the high-frequency commands.
Prerequisites
- Workspace must be initialized (
evo status should succeed)
- A baseline experiment must be committed (run
/discover first)
- All benchmark dependencies must be available in the environment
Architecture
Orchestrator (this agent):
- Reads state, identifies failure patterns cross-cutting the tree
- Writes one brief per subagent: objective + parent + boundaries + pointer traces
- Verifies briefs are diverse (no two attacking the same surface)
- Collects results, prunes dead branches, adjusts strategy
Subagent A (brief, budget: N iterations):
- Reads its pointer traces, forms the concrete edit
- Creates experiment, edits target, runs benchmark, analyzes
- If budget remains and sees a promising follow-up, continues
- Can run up to N serial experiments on its own branch
- Returns: what it tried, what worked, what it learned
Subagent B (different brief, budget: N iterations):
- Same protocol, non-overlapping objective
...
Both layers read traces; the depth differs. The orchestrator scans for cross-cutting patterns (which failures are common, which branches plateau) -- enough to pick N non-overlapping briefs. Subagents read their pointer traces in depth, enough to commit to a concrete edit. Structured briefs are what prevent parallel subagents from duplicating each other's work.
Session lineage. Dispatching a child of a committed experiment forks the parent experiment's own session, not a separately-warmed explorer. The child inherits the parent's full transcript -- reads, edits, benchmark output -- so the prefix cache carries through generations. Explorer warming runs only for children of root, where the parent has no session.
Trace instrumentation style: .evo/meta.json's instrumentation_mode records sdk vs inline. Subagents must stay consistent with it (see the evo subagent skill for details).
The Loop
Repeat until interrupted or stall limit reached:
1. Read current state
Step 0 (always, before anything else): ensure you have read .evo/project.md. Its contents define the optimization metric and goal; every pattern you report MUST be tied to a failure mode of that goal. If you haven't read it yet in this session, read it now -- before listing experiments, opening any outcome.json, or spawning sub-agents. If the file is missing, stop and tell the user.
Step 0.1 (one-time auto-migration): ensure the workspace knows what runtime you are. Run evo host show. If it prints <not set>, the workspace pre-dates the host signature field — declare your runtime now: evo host set <one of: claude-code, codex, opencode, openclaw, hermes, pi, generic>. You know what runtime you're operating in (your system prompt, env vars like CLAUDECODE=1, your own self-identity); pick the matching value. If genuinely unsure, use generic. Do not ask the user — this is a one-time silent migration. Subsequent rounds skip this step (evo host show returns the recorded value).
evo scratchpad
evo status
evo frontier
evo show <id>
evo awaiting
evo discards [--like <text>]
evo notes
evo annotations
evo path <id>
