Evo Exprmn Optmzr

---
name: evo-exprmn-optmzr
description: Convert evo's experiment-tree optimization model into a Hermes-native workflow for benchmark-driven code evolution using git worktrees, scored experiments, gates, traces, and iterative branching.
version: 1
---

Goal
- Let Hermes run evo-style optimization without requiring Claude Code plugin surfaces.
- Use repo-local git worktrees as experiment branches.
- Keep only changes that improve a measurable benchmark and pass gates.
- Preserve traces, diffs, and branch history for later inspection.

Use when
- User wants benchmark-driven autonomous improvement.
- A repo has a clear target file/module and a benchmark command that emits a parsable score.
- The task benefits from branching search instead of one linear edit loop.
- You want Hermes to explore multiple hypotheses with rollback discipline.

Do not use when
- There is no executable benchmark.
- Success is subjective and cannot be scored.
- The repo is too dirty to establish a clean baseline.

Core model absorbed from evo
- Workspace init with explicit target, benchmark, metric, optional gate.
- Each experiment gets its own git worktree from a parent node.
- Benchmark output is parsed into a numeric score.
- Candidate is kept only if score improves over parent and gates pass.
- Failed branches are discarded; good branches become new parents.
- Traces, diff, and notes are saved per experiment.
- Prefer shallow tree search over blind repeated edits on one branch.

Hermes-native workflow
1. Preconditions
   - Verify repo is git-controlled and clean enough to branch.
   - Verify benchmark command runs from repo root.
   - Verify score extraction rule before any code edits.
   - Verify any required gate commands.

2. Define experiment contract in chat or repo note
   - target path(s)
   - benchmark command
   - metric direction: max or min
   - gate command(s)
   - score parse rule
   - budget: number of branches / rounds

3. Create baseline
   - Run benchmark on current branch.
   - Save score and command output.
   - Treat this as root parent.

4. Branch experiments with worktrees
   - For each hypothesis, create a git worktree on a branch like `evo/<topic>/<n>`.
   - Make one focused change per branch.
   - Run benchmark.
   - Run gates.
   - Save benchmark output, gate output, diff, and short hypothesis note.

5. Keep or discard
   - If score improves and gates pass: keep branch as candidate parent.
   - Else: discard branch or leave as explicit failed trace if user wants auditability.

6. Iterate
   - Spawn more experiments from the best surviving parent.
   - Use traces from failed runs to propose new hypotheses.
   - Stop on budget exhaustion, stall, or user interrupt.

7. Finalize
   - Report best branch, best score delta, and gate status.
   - Present exact diff or commit for human decision.
   - Clean stale worktrees if user scope permits.

Suggested repo artifact layout
- `.hermes/evo/<run-id>/baseline.log`
- `.hermes/evo/<run-id>/experiments/<exp-id>/benchmark.log`
- `.hermes/evo/<run-id>/experiments/<exp-id>/gate.log`
- `.hermes/evo/<run-id>/experiments/<exp-id>/diff.patch`
- `.hermes/evo/<run-id>/experiments/<exp-id>/notes.md`
- `.hermes/evo/<run-id>/summary.md`

Recommended commands
- baseline: use `terminal()` from repo root
- branches/worktrees: `git worktree add ...`
- diff capture: `git diff <parent>...<branch>`
- traces/logs: write to repo-local files, not memory

Score parsing
- Prefer benchmark commands that print one numeric score plainly.
- If output is noisy, extract with a stable regex or small Python parser via `execute_code`.
- Never guess score direction; make max/min explicit.

Gates
- Gates are pass/fail safety rails separate from benchmark score.
- Typical gates: tests, lint, typecheck, smoke run, invariant checks.
- A higher score that fails a gate is rejected.

Heuristics
- Change one variable per branch when possible.
- Keep hypotheses short and falsifiable.
- Prefer 2-5 high-signal branches over many low-quality ones.
- If benchmark is slow, reduce branch fanout and increase hypothesis quality.
- Use delegate_task only when the user already approved a multi-branch coding run and subtasks are independent.

Pitfalls
- Do not start before baseline is reproducible.
- Do not compare scores across changed benchmark definitions.
- Do not keep ungated wins.
- Do not let multiple branches edit overlapping files without clear isolation.
- Do not store experiment state only in chat; keep repo-local artifacts.

Output pattern
- baseline score
- best branch
- score delta
- gate result
- kept vs discarded branches
- next best experiment directions