evo-hq/evo

# Discover

Internal procedure for `evo:discover`. The user only sees the user-facing prompts, the dashboard URL, and the baseline score -- everything else is the agent's choreography.

## Evo surface

General guidance on the skills and tools available in evo. Each line is a triggering condition: if you're about to do X, pull/dispatch/read this. Don't preload -- act when the trigger fires.

**Always have a sense of the skill before jumping into its references.** A skill body carries the decision-making; references are concrete contracts that assume a decision has been made.

```
evo plugin
│
├── Main thread  (the orchestrator -- you, inside /evo:discover or /evo:optimize)

# Infra Setup

Use this when the user wants to change where experiments run: local worktrees, pool slots, or a remote provider such as Modal, E2B, Daytona, AWS, Azure, SSH, manual, or a custom dotted-path provider.

## Goals

- Be explicit about the target backend/provider.
- Check prerequisites before mutating evo config.
- Never install provider SDKs silently.
- Give one actionable auth command per provider.
- Keep provider credentials separate from benchmark runtime env.

## Flow

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,

# Report

Report the current evo workspace from recorded state only. A report request is
read-only, even if the user phrases it casually as "what happened?", "what got
better?", "what should I pay attention to?", or "I just woke up".

Do not spend compute while reporting:

- Do not run `evo run`, `evo gate check`, benchmark commands, or project eval
  scripts.
- Do not run `python bench.py`, `python slurm_eval.py`, `sbatch`, `srun`,
  `squeue`, `sacct`, or `scancel` to verify a result.
- Do not create launcher, monitor, parsing, or analysis scripts.
- Do not edit files.

# Ship

Turn a finished evo run into a change a maintainer would merge.

The optimize loop leaves a tree of committed experiments. The winning worktree
diff is not mergeable as-is: it carries debug prints, search-process churn,
over-broad edits, and sometimes a test that was relaxed to clear a gate. Shipping
is the step that re-derives the *minimal clean change* reproducing the winning
behaviour, lands it the way the repo expects (PR or merge), and reports how
mergeable it is.

Correctness is the floor, not the goal. The score says the behaviour works; this
skill decides whether the *diff* is fit to merge.

# 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=...)

# Discover

Internal procedure for `evo:discover`. The user only sees the user-facing prompts, the dashboard URL, and the baseline score -- everything else is the agent's choreography.

## Evo surface

General guidance on the skills and tools available in evo. Each line is a triggering condition: if you're about to do X, pull/dispatch/read this. Don't preload -- act when the trigger fires.

**Always have a sense of the skill before jumping into its references.** A skill body carries the decision-making; references are concrete contracts that assume a decision has been made.

```
evo plugin
│
├── Main thread  (the orchestrator -- you, inside /evo:discover or /evo:optimize)

# Finetuning

Priors, not rules. Only firm guardrails: held-out eval you never train on, no leakage, trust evo's recorded numbers over the run's self-report. Override anything else against the gate.

## Pick the technique by reward shape

Decide on the reward first, technique second. Choosing the comfortable technique over the matching one is the most common failure.

| Reward shape | Technique |
|---|---|
| Verifiable (exact match, unit tests, parser-decidable) | **RL** (GRPO / RLOO / PPO) — reward includes format, so the model learns to emit verifier-acceptable shape |
| Preference pairs (chosen vs rejected) | **DPO / KTO / ORPO** — cheaper than full RL, no rollouts |
| Demonstrations only (curated traces, chat data) | **SFT** — install format/tone/capability the base lacks |
| Have a scorer + want SFT stability | **RFT** — sample, filter by reward, SFT on survivors |

# Infra Setup

Use this when the user wants to change where experiments run: local worktrees, pool slots, or a remote provider such as Modal, E2B, Daytona, AWS, Azure, SSH, manual, or a custom dotted-path provider.

## Goals

- Be explicit about the target backend/provider.
- Check prerequisites before mutating evo config.
- Never install provider SDKs silently.
- Give one actionable auth command per provider.
- Keep provider credentials separate from benchmark runtime env.

## Flow

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,

# Report

Report the current evo workspace from recorded state only. A report request is
read-only, even if the user phrases it casually as "what happened?", "what got
better?", "what should I pay attention to?", or "I just woke up".

Do not spend compute while reporting:

- Do not run `evo run`, `evo gate check`, benchmark commands, or project eval
  scripts.
- Do not run `python bench.py`, `python slurm_eval.py`, `sbatch`, `srun`,
  `squeue`, `sacct`, or `scancel` to verify a result.
- Do not create launcher, monitor, parsing, or analysis scripts.
- Do not edit files.

# Ship

Turn a finished evo run into a change a maintainer would merge.

The optimize loop leaves a tree of committed experiments. The winning worktree
diff is not mergeable as-is: it carries debug prints, search-process churn,
over-broad edits, and sometimes a test that was relaxed to clear a gate. Shipping
is the step that re-derives the *minimal clean change* reproducing the winning
behaviour, lands it the way the repo expects (PR or merge), and reports how
mergeable it is.

Correctness is the floor, not the goal. The score says the behaviour works; this
skill decides whether the *diff* is fit to merge.

# 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=...)