@evo-hq/pi-evo 0.4.2-alpha.2

package/skills/optimize/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: optimize
+description: Run the evo optimization loop with parallel subagents until interrupted.
+argument-hint: "[subagents=N] [budget=N] [stall=N]"
+---
+
+Run the `evo` optimization loop. Each round, the orchestrator writes structured briefs and spawns parallel 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.
+
+## 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 — 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]
+<text>
+[END EVO DIRECTIVE]
+```
+
+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, SessionStart); the channel doesn't change the authority of the content.
+
+## Configuration
+
+These defaults can be overridden via arguments: `/optimize [subagents=N] [budget=N] [stall=N]`
+
+- **subagents**: number of parallel subagents per round (default: 5)
+- **budget**: max iterations each subagent can run within its branch (default: 5)
+- **stall**: consecutive rounds with no improvement before auto-stopping (default: 5)
+
+**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.
+
+**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).
+
+```bash
+evo scratchpad          # bounded state summary (tree, frontier, awaiting decision, gates, annotations, what-not-to-try, notes)
+evo status              # one-line summary
+evo frontier            # explorable nodes ranked by the configured strategy (JSON envelope: {strategy, nodes[{id,score,rank,...}], generated_at})
+evo show <id>           # full state of one node (attempts, diffs, annotations, notes, effective gates) -- the cleanest one-node getter
+evo awaiting            # evaluated nodes awaiting commit/discard decision
+evo discards [--like <text>]  # discarded nodes; useful for "have we tried this before"
+evo notes               # all notes (per-node + workspace), recent first
+evo annotations         # all annotations (filterable with --task/--exp)
+evo path <id>           # root-to-node chain with scores
+evo diff <id> [<other>] # diff vs parent (or between two experiments)
+evo gate list <id>      # effective gates for a node (inherited from ancestors)
+evo gate check <id>     # run effective gates without benchmark or state mutation
+evo infra log           # recorded infra/strategy events (epoch bumps, harness changes)
+
+# Settings (read)
+evo config show               # everything; use the next three for narrower views
+evo config get <field>        # one field
+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
+```
+
+### 2. Analyze state and do structural aggregation
+
+From the scratchpad, frontier, traces, and annotations, determine:
+- Which frontier nodes are most promising (`evo frontier` returns them already ranked under the configured strategy -- use its ordering rather than re-ranking; override with `evo frontier --strategy ...` only if you have a specific reason)
+- What failure patterns are most common and impactful
+- What strategies have been tried and their outcomes
+- Which branches are plateauing or exhausted
+- What gates exist on each frontier node (`evo gate list <id>`) -- subagents must satisfy these
+
+**Read the "Awaiting Decision" section of the scratchpad.** Evaluated nodes (ran, bad outcome, not yet discarded) are a cross-agent signal: if three subagents in the last round produced evaluated nodes that all failed the same gate, surface the pattern -- maybe the gate is too tight, maybe the approach has a shared flaw. Either tell the next round to avoid it, or propose a brief that attacks it directly. Without this cross-cutting read, each subagent rediscovers the same wall independently.
+
+**Structural pass.** For the evaluated nodes this round, load their `outcome.json` files into Python and aggregate: co-occurring `gate_failures`, shared zero-score task IDs in `benchmark.result.tasks`, recurring substrings across `error` fields. (Bulk-reading attempt artifacts under `.evo/run_*/experiments/<exp>/attempts/<NNN>/` is the right tool for this — `evo show <id>` is for one-node introspection, not batch aggregation.)
+
+**Emit intersections explicitly.** After computing the per-pattern sets (call them A, B, ...), MUST emit each pairwise intersection `A ∩ B` as a distinct pattern entry whenever at least 2 experiments exhibit both. Intersections carry different strategic implications from their components (compound failures warrant different briefs than single-failure clusters) and do not reconstruct from sub-agent summaries -- this is a parent-level aggregation that must happen inline.
+
+**Improvers are a pattern too.** Enumerate the committed improvers (experiments with `outcome=committed` and `score > parent_score`) as a distinct pattern entry: they are candidate parent nodes for next-round branching and feed the brief's *Parent node* field.
+
+Hold all these findings; step 4's brief-writing combines them with the scan sub-agents' findings from step 3.
+
+### 3. Spawn scan sub-agents for cross-cutting free-text analysis
+
+**Hard rule (primary delegation).** The orchestrator MUST spawn at least one scan sub-agent via your host's parallel-subagent tool in every round before emitting any pattern. This applies to all scan input -- `outcome.json`, `traces/task_*.json`, annotations, and `error` fields alike -- regardless of file size, structure, or whether the orchestrator believes a script would be faster. An inline Python aggregation over `outcome.json` does NOT substitute for delegation; it may supplement sub-agent findings (step 2's structural pass still runs), but step 3's scan sub-agents MUST still run. If you reach step 4 without a completed scan sub-agent call in step 3, you have violated this rule -- stop and spawn one.
+
+**Narrow exception (verification).** After scan sub-agents have returned findings, the orchestrator MAY read individual trace files to: verify a specific finding before citing it in a brief, spot-check a pattern the orchestrator is unsure about, or pull a short quote for a brief's Objective or Pointer Traces field. These verification reads must be narrow (<=3 trace files per round, targeted at experiment IDs already surfaced by sub-agents). This exception does NOT let you skip the hard rule above -- it only governs what you may do after sub-agents have already run.
+
+Partition the evaluated experiments into batches small enough that each sub-agent can read its batch's traces in one pass. Spawn one scan sub-agent per batch in a **single batch** using your host's parallel-subagent tool (see "Host conventions"). They must execute in parallel, not sequentially.
+
+Pass this brief verbatim as the sub-agent's prompt:
+
+> You are a read-only evo scan sub-agent. Do not run experiments or edit code.
+>
+> Start by reading `.evo/project.md` to understand the optimization goal and metric. All your findings should be relevant to this goal.
+>
+> Your batch: `[exp_IDs]`.
+>
+> For each experiment, read `outcome.json` and `traces/task_*.json`. Also consider `hypothesis` and prose `error` text.
+>
+> Find patterns that will populate the next round's subagent briefs:
+> - **Shared failure causes** -- root-cause reasons recurring across 2+ experiments (the *why*, not the surface gate name). Feeds brief objectives.
+> - **Wall patterns** -- approaches or gates multiple experiments consistently fail on. Feeds brief boundaries / anti-patterns.
+> - **Compound-failure standouts** -- single experiments hitting multiple failure modes. Feeds brief pointer traces.
+>
+> Prioritize patterns tied to the goal's core failure modes or critical tasks. Deprioritize incidental observations. Skip: trace-shape statistics, fixture-structural facts, hypothesis-string-reuse, or anything the orchestrator can't act on in a brief.
+>
+> If your batch is still too heavy, partition further and spawn scan sub-agents recursively (same brief, smaller batch).
+>
+> Return JSON only: `{"findings": [{"description": "<short>", "experiment_ids": ["exp_XXXX", ...], "evidence": ["<short snippet>", ...]}]}`
+>
+> **Evidence must be verbatim quotes** from outcome.json fields, trace `messages`, or `error` text -- not paraphrases. Each description must be supported by the quoted evidence. **Do not speculate about causal chains** (e.g., "approach X regresses because it removes Y") unless a specific trace message or error field directly states that mechanism. If you cannot cite verbatim evidence for a finding, drop it -- err on under-reporting.
+>
+> Evidence: short quotes (<200 chars each), max 3 per finding.
+
+Wait for all scan sub-agents to return. Reconcile near-duplicate findings (`timeout_error` ≈ `error_timeout`) by judgment and combine with the structural-pass findings from step 2.
+
+**Verify every pattern before emitting it.** For each pattern in your final output, confirm that at least one reported experiment's outcome.json or trace content contains evidence that directly supports the pattern's description. If you cannot cite a specific field value or quoted message as evidence, drop the pattern. Do not emit speculative causal attributions ("approach X regresses because it removes Y") unless the trace or error text explicitly states that mechanism. This filter applies to both sub-agent findings and your own inline observations.
+
+These unified, verified cross-cutting findings feed step 4's brief-writing.
+
+### 4. Write subagent briefs
+
+Write **one brief per subagent** with these four fields:
+
+1. **Objective** -- one sentence describing the bottleneck to attack and the evidence for it. Should name *where in the system's behavior* the gain is hiding (e.g., "tool-use error recovery fails after the first bad call across tasks 2, 5, 7") but **must not name specific files, functions, or concrete edits** -- that's the subagent's job after it reads the code.
+2. **Parent node** -- which experiment to branch from.
+3. **Boundaries / anti-patterns** -- what this subagent should NOT try, explicitly called out with reasons. Include approaches already tried and discarded (from "What Not To Try"), gates it must not regress, and anything adjacent subagents in this round are doing (so it doesn't duplicate).
+4. **Pointer traces** -- task IDs the subagent should study first, with a one-line reason each.
+
+Be specific and bounded. Vague briefs like "improve accuracy" cause subagents to duplicate each other's work; structured briefs prevent it.
+
+**Diversity check (before spawning).** Re-read the N briefs side by side. If two briefs:
+- point at the same objective phrased differently, OR
+- cite overlapping pointer traces without meaningfully different framings, OR
+- attack the same area of the system,
+
+merge or re-scope one of them. The frontier/pruning logic handles tree-level exploration vs exploitation algorithmically -- the orchestrator's job is just to make sure the round's N briefs don't collapse onto each other.
+
+### 5. Spawn parallel optimization subagents
+
+Spawn all subagents in a **single batch** using your host's parallel-subagent tool. They must execute in parallel, not sequentially -- serial execution defeats the per-round width.
+
+Per host, the spawn shape matters because evo's loop depends on *completion notifications* arriving turn-by-turn (so the orchestrator can review each subagent's outcome and decide round 2):
+
+- **claude-code** — fire one `Bash(run_in_background=true)` call per brief. The bash invokes the subagent (the host's `Task` tool, or any equivalent that runs the brief to completion). Each backgrounded bash returns immediately and the runtime delivers a `<task-notification>` at a later turn when each subagent finishes. Do NOT wait on subagents inline; fan them out, then exit your current turn — notifications arrive in subsequent turns.
+- **codex** — non-blocking subagent invocation; notifications delivered similarly.
+- **hermes** — `terminal(background=true)`; notifications delivered similarly.
+- **openclaw** — `sessions_spawn deliver:false`; notifications delivered similarly.
+- **opencode** — *batch-parallel only* (no background notifications). Fire N `task` calls in ONE assistant message; all `tool_result`s return together when the slowest finishes. Plan all parallel work (including non-task tools) in that single message — opencode cannot interleave reasoning across turns while subagents run.
+- **pi** — *batch-parallel via extension*. Pi's default toolkit has no subagent primitive; `evo install pi` ensures the `pi-subagents` package is present, which registers a `subagent` tool. Fire N `subagent` calls in ONE assistant message; all results return together when the slowest finishes (same shape as opencode). If the `subagent` tool isn't available, fall back to running experiments sequentially in your own turn (`evo new` → `evo run` per attempt) and tell the user to `pi install npm:pi-subagents` for proper fanout.
+
+Respect the host's concurrency cap; batch if N exceeds it.
+
+Pick a faster model for straightforward briefs and a stronger model for harder ones requiring deeper trace analysis, if your host exposes per-call model selection.
+
+Each subagent prompt MUST start with the literal sentence:
+
+> "First, load and follow the **evo subagent skill** (named `subagent` under the evo plugin in your host's skill registry — use your host's skill loader, not a filesystem path). Allocate your experiment via `evo new --parent <id>`, edit inside the returned worktree, evaluate via `evo run <exp_id>`. Do not skip these steps even if the brief looks simple."
+
+Then append:
+- The four-field brief verbatim (objective, parent, boundaries/anti-patterns, pointer traces)
+- The iteration budget
+- A one-paragraph scratchpad summary (current best score, frontier nodes, recent failures) for context
+
+The opening sentence is non-negotiable — without it small models often skip the evo CLI and edit files directly, which produces no committed experiments and breaks the round.
+
+### 6. Collect results and update state
+
+After all subagents complete:
+
+- Review each subagent's summary
+- Record the round's best score and compare to the previous best
+- If no subagent improved the score, increment the stall counter
+- If any improved, reset the stall counter
+- Check if subagents added new gates -- note these in your state tracking
+- If multiple experiments failed the same gate, consider whether the gate is too restrictive or the briefs were aimed at the wrong surface
+
+**Cross-cut the round's evaluated nodes.** Before moving on, read `experiments/<id>/attempts/NNN/outcome.json` for each evaluated node from this round. The structured `gates[]` entries and `benchmark.result` let you spot shared failure modes the subagent summaries may have glossed over (e.g., three different subagents produced evaluated nodes whose gate_failures all included `refund_flow` -- that's a structural constraint the next round must confront, not three independent bad hypotheses).
+
+Prune dead branches where 3+ children all regressed:
+  ```bash
+  evo prune <exp_id> --reason "exhausted: N children all regressed"
+  ```
+
+`evo prune` accepts `committed` or `evaluated` nodes. Use it when you want
+to mark a lineage exhausted while preserving the result for later review or
+reference. Prune keeps the git commit alive (anchored at `refs/evo-anchor/<run>/<exp>`)
+so the node can be restored if needed. **Never `evo discard` a committed
+node** — it would orphan the branch ref and risk losing the commit.
+
+If a previously-pruned (or discarded-then-restored) node is worth revisiting:
+  ```bash
+  evo restore <exp_id>
+  ```
+Flips status back to committed; recreates the regular branch from the anchor
+ref so future `evo new --parent <id>` works. For discarded nodes whose commit
+is no longer reachable in git (rare; needs `git gc --prune=now` after the
+discard), restore errors and points at `experiments/<id>/attempts/NNN/diff.patch`
+for manual replay.
+
+Update notes with cross-cutting learnings:
+  ```bash
+  evo set <exp_id> --note "key insight from round N"
+  ```
+
+### 7. Continue or stop
+
+**Continue** if:
+- Stall counter < stall limit
+- User hasn't interrupted
+- Score hasn't reached the theoretical maximum
+
+**Stop** if:
+- Stall counter >= stall limit (N consecutive rounds with no improvement)
+- Score reached theoretical maximum (1.0 for max metric, 0.0 for min metric)
+- User interrupted
+
+On stop, print a final summary:
+- Best score achieved and experiment ID
+- Total experiments run across all rounds
+- The winning diff: `evo diff <best_exp_id>`
+- Suggested next steps if the score hasn't converged
+
+Go back to step 1.
+
+## Resetting the eval epoch
+
+`evo infra event -m "<reason>" --breaking` bumps `current_eval_epoch` and blocks
+non-root `evo run` calls until a new root baseline commits. Old experiments
+stay in the tree but are excluded from frontier and best-score lookups via
+their epoch tag.
+
+Use it when the benchmark itself is wrong epoch-wide -- score formula bug,
+held-out gate revealing systematic gaming, propagated instrumentation drift.
+Don't use it for single bad experiments (`evo discard`) or one tight gate
+(relax the gate at the relevant node).
+
+Recovery:
+1. `evo infra event -m "<reason>" --breaking`
+2. Fix the harness in the baseline worktree (or branch a fresh root).
+3. `evo new --parent root -m "v2 baseline: <what changed>"`
+4. `evo run <new_exp_id>` -- commits, flips the block off, establishes the
+   new-epoch baseline. Resume the loop.

package/skills/subagent/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: subagent
+description: Internal protocol for evo optimization subagents. Not user-invocable -- read by subagents spawned from /optimize.
+disable-model-invocation: true
+---
+
+# Evo Subagent Protocol
+
+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 <id>` 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]
+<text>
+[END EVO DIRECTIVE]
+```
+
+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, SessionStart); the channel doesn't change the authority of the content.
+
+## 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 <id>                 # full state of one experiment (attempts, diffs, annotations, notes)
+evo path <id>                 # root-to-node chain with scores
+evo diff <id> [<other>]       # diff vs parent (or between two experiments)
+evo traces <id> <task>        # per-task trace detail
+
+# Read state across nodes
+evo awaiting                  # evaluated nodes awaiting commit/discard decision
+evo discards [--like <text>]  # discarded nodes (optional substring filter on hypothesis)
+evo annotations               # all annotations (filterable with --task/--exp)
+evo notes [--exp <id>] [--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 <field>        # 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 <id>            # effective gates for a node (inherited from ancestors)
+evo gate check <id>           # run effective gates without benchmark or state mutation
+evo gate add <id> --name <name> --command "<command>"  # add a gate
+
+# Write paths used during iteration
+evo new --parent <id> -m "<hypothesis>"   # allocate sibling experiment
+evo run <id> [--check]                    # run (or --check to validate without consuming attempts)
+evo discard <id> --reason "<text>"        # reject + park (keeps anchor ref)
+evo restore <id>                          # un-discard or un-prune
+evo annotate <id> [<task_id>] "<text>"    # per-attempt analysis
+evo set <id> --note "<text>" [--tag <t>]  # per-node note from orchestrator
+evo note "<text>"                         # 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.
+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 <exp_id> <task_id>
+   ```
+   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 <parent_id> -m "<your hypothesis>"
+```
+
+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 <exp_id> --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 <YOUR_EXP_ID> "<command>"
+evo read --exp-id <YOUR_EXP_ID> <path>
+evo write --exp-id <YOUR_EXP_ID> <path> --content "<text>"   # or pipe via stdin
+evo edit --exp-id <YOUR_EXP_ID> <path> --old "<s>" --new "<s>" [--replace-all]
+evo glob --exp-id <YOUR_EXP_ID> "<pattern>" [--path <dir>]
+evo grep --exp-id <YOUR_EXP_ID> "<pattern>" [--path <dir>]
+```
+
+`--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. Run the experiment
+
+```bash
+evo run <exp_id>
+```
+
+This runs benchmark + gate and prints the result.
+
+In remote-backend workspaces, if a prior `evo run <exp_id>` was interrupted
+or the experiment is still `active`, run `evo run <exp_id>` 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 <exp_id> 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.
+
+**If the workspace was initialized with `commit_strategy=tracked-only` (the default for `--backend pool`):** `evo run` only commits modifications to *tracked* files. New files require an explicit `git add` from inside the worktree, then a shisa-kanko ack on the run command:
+
+```bash
+# inside the worktree -- only for new SOURCE files you want in the commit:
+cd <worktree_path> && git add path/to/new_file.py
+
+# then, from the main repo:
+evo run <exp_id> --i-staged-new-files yes
+```
+
+The ack flag is required when the worktree has any untracked, non-gitignored file. Without it, `evo run` errors closed and lists the files. For each file, decide: source (then `git add`) or warm state (leave untracked -- it persists in the slot for future experiments). Then re-run with `--i-staged-new-files yes`. The flag value must be exactly `yes`. In `commit_strategy=all` workspaces (default for `--backend worktree`) the flag is a silent no-op; safe to always pass.
+
+### 5. Analyze the result
+
+`evo run` prints one of three outcomes:
+
+- **`COMMITTED`** (score improved + gates passed): node locked in. Read failing task traces to find the next weakness. Use this experiment as the parent for your next iteration.
+
+- **`EVALUATED`** (score regressed or gate failed): ran cleanly but bad outcome. **You decide next step.** Read:
+  - `experiments/<id>/attempts/NNN/outcome.json` -- structured record: `score` vs `parent_score`, per-gate `passed`/`returncode`, benchmark result, error. Tells you *what* broke.
+  - `experiments/<id>/attempts/NNN/diff.patch` and `benchmark.log` -- tell you *why*.
+
+  Then either:
+  - Fixable edit-bug (off-by-one, wrong signature): edit the worktree and `evo run <id>` again. Bounded by `max_attempts` (default 3). Before retrying, compare your planned edit against the previous attempts' `outcome.json` on this same node -- if two earlier attempts hit the same gate, a small tweak won't fix it. When the cap is hit, run is refused -- you must discard.
+  - Hypothesis is wrong, no fix: `evo discard <id> --reason "..."` and branch a new experiment from the **original parent**.
+
+- **`FAILED`** (infra error, non-zero exit, timeout): couldn't evaluate. Doesn't consume the retry budget.
+  - Transient / fixable locally: retry.
+  - `remote_infra_failure:...`: remote container or agent infrastructure failed. Report it to the orchestrator unless your brief explicitly says to retry infra failures.
+  - Structural (benchmark broken, evo misconfigured): report to orchestrator and stop.
+  - Not worth fixing: `evo discard <id> --reason "..."`.
+
+### 6. Annotate
+
+```bash
+evo annotate <exp_id> "<what you changed, what happened, and why>"
+```
+
+Always annotate so other agents can learn from your experiments.
+
+### 6b. Add gates for fixed behaviors
+
+When you fix a critical, easy-to-regress behavior, lock it in as a gate so future experiments on this branch can't break it:
+
+```bash
+evo gate add <exp_id> --name "social_eng_resistance" --command "python3 {worktree}/benchmark.py --target {target} --task-ids 3 --min-score 0.9"
+```
+
+Good candidates: a specific benchmark task that was hard to fix, a test for a critical policy rule, a smoke test for a fragile behavior. The gate command must exit non-zero when the protected behavior regresses; a bare benchmark invocation that prints a low score but exits 0 is decorative and should not be registered. Do NOT gate every passing task -- that over-constrains the search.
+
+### 7. Decide: continue or stop
+
+Continue if budget remains AND (last outcome was committed, OR you have a meaningfully different idea after an evaluated/discarded outcome). When continuing after a committed experiment, update your parent to the newly committed ID.
+
+Stop if budget exhausted, infra failure, or you've exhausted variations with no improvement.
+
+## Enriching traces
+
+Check `.evo/meta.json` for `"instrumentation_mode"` (`"sdk"` or `"inline"`) to see which style the benchmark uses -- **stay consistent with that choice across iterations; do not flip styles mid-run.**
+
+Trace quality is part of the benchmark contract. After a failed baseline or failed task, the orchestrator should be able to reconstruct what happened using only `evo traces <exp_id> <task_id>`. If not, the trace logging is too thin.
+
+- **SDK mode** (`from evo_agent import Run`): read `plugins/evo/skills/references/agent-sdk-reference.md`, then enrich traces by adding `run.log(task_id, ...)` calls or extra fields to `run.report()`.
+- **Inline mode** (benchmark has local `log_task`/`logTask` helpers): add fields to the trace dict built inside `log_task()`.
+- **LLM / agent benchmarks**: log the task input, observation/frame summary, prompt or message summary, model/tool response, selected action, retries/errors, and final task outcome. If the project already has a separate recorder, decide whether evo traces mirror the important fields or whether the recorder artifact is explicitly linked from the evo trace.
+
+The trace format is forward-compatible -- extra fields are preserved. Do NOT change the score computation or gate logic -- only add observability.
+
+## Rules
+
+- Do NOT run `evo init` or `evo reset`
+- `evo discard <your_exp_id> --reason "..."` is your explicit "abandon" action — use it for any *non-committed* node you've decided not to pursue further (pre-run realization, evaluated with a bad hypothesis, or unfixable infra failure). Discard deletes the worktree and branch; the node and its per-attempt artifacts stay in `.evo/` as a record of what was tried.
+- If `evo discard` errors with **"cannot discard committed node ... use prune"** — the experiment cleared the gate and improved the score. You shouldn't be discarding it. Don't fight the error; the orchestrator owns committed-lineage decisions via `evo prune`.
+- If `evo discard` errors with **"cannot discard active node ... pass --force"** — the run is still in flight. Wait for it to finish; don't `--force` unless you know what you're doing (the running process can still write a final outcome that contradicts the discard).
+- If `evo discard` errors with **"cannot discard ... has non-discarded children"** — sibling/child experiments depend on this node's parent reference. Discard or commit-and-prune those first.
+- Do NOT copy `.env` files, bake secrets into source, or hard-code local runtime paths. Runtime setup/env is configured by the orchestrator (`evo config runtime ...`, `evo env ...`) and injected into benchmark/gate processes. If a missing dependency, setup step, or key blocks evaluation, report setup failure.
+- Always annotate your experiments, especially before discarding — the annotation is what persists after the worktree is gone.
+- Stay within your brief's objective and boundaries -- don't drift into unrelated changes
+
+## When Done
+
+Return a structured summary:
+
+```
+## Results
+- Experiments: <list of exp IDs with scores and status>
+- Best: <exp_id> with score <N>
+
+## Changes
+- <what you changed in each experiment, briefly>
+
+## Learnings
+- <what failure patterns you observed>
+- <what worked and what didn't>
+
+## Suggestions
+- <ideas for the next round that you didn't get to try>
+```