git:20260816.90c1377 to git:20260822.dabed7a

21 added, 44 removed. Audit A to A.

---

name: using-cap-evolve

- description: 'Entry-point router for cap-evolve. Use the moment a user asks to OPTIMIZE an agent capability against an eval — "optimize <X>", "make <X> score higher on <benchmark>", "improve this skill/tool/prompt". Decides whether a project already exists and routes accordingly: to intake (Phase 1) for a fresh request, or straight into the phase chain / `cap-evolve run` when `.capevolve/project/` is already scaffolded. Explains the two ways to run (standalone `/cap-evolve:<phase>` chain vs the fully-automatic `cap-evolve run`) and restates the non-negotiable honesty rules. Does no optimization itself.'

+ description: 'Front door for cap-evolve: routes an optimization request to the right pipeline phase. Use when someone wants an agent, skill, system prompt, tool surface, or MCP toolset to score higher on an eval, benchmark, or task suite — "optimize my skill", "raise the pass rate on these tasks", "my agent keeps failing these cases", "get this prompt''s accuracy up on my evals" — even when they never say "optimize", and whenever a .capevolve/ project or an unfinished run is in the tree. Routes to intake, the check gate, a resumed run, or the report; optimizes nothing itself. Not for making code or a query faster, and not for rewording one prompt with no eval to score it against. When the user names a phase or algorithm outright (baseline, gate, hill-climb, gepa), use that skill directly.'

component: orchestrate

argument-hint: "[what to optimize] [--base .capevolve]"

- arguments: "$ARGUMENTS"

allowed-tools: Read, Bash

- provides: [report]

- needs: [project]

+ provides: []

+ needs: []

sources: [evo, superpowers]

---

# using-cap-evolve — the router

- This is the front door. When someone says **"optimize \<X\>"**, you land here

- first. The router does not run any phase — it figures out *where the user is* and

- sends them to the right next step, then gets out of the way.

+ The front door: it works out *where the user is* and hands off, running no phase and

+ editing nothing. Boundary: this router picks the door, `orchestrate` drives the run.

## Routing decision

- Run the resolver to see the current state and the recommended next command:

+ Run from the user's project dir; `S` is the absolute path of the directory you loaded this

+ SKILL.md from — the one location always known here (no env var is set for a plugin install):

```bash

- python scripts/run.py "$ARGUMENTS" --base .capevolve

+ S=<this skill's own directory>; python "$S/scripts/run.py" --base .capevolve

```

- It prints `{state, next, sequence, ...}`:

- - **state `fresh`** (no `.capevolve/project/`): route to **`/cap-evolve:intake`** —

- it interviews the user, scaffolds the project, and gathers inputs. Never skip

- intake on a fresh request; never fabricate a NEEDED input.

- - **state `scaffolded`** (`capevolve.yaml` exists, check not yet green): route to

- **`/cap-evolve:implement-and-check`** and stop at the hard gate

- (`cap-evolve check` must print `{"ok": true}`).

- - **state `ready`** (check green): offer the two run modes below.

- - **state `running`/`finalized`**: route to **`/cap-evolve:report`** for status /

- the sealed-test result.

- ## Two ways to run (both honest, same engine)

- 1. **Standalone phase chain** — drive it turn by turn, inspecting each step:

- `/cap-evolve:intake` → `/cap-evolve:implement-and-check` →

- `/cap-evolve:baseline` → `/cap-evolve:<algorithm>` (e.g. `hill-climb`, `gepa`,

- `skillopt`, or `agent-optimize` in agent mode) → `/cap-evolve:finalize` → `/cap-evolve:report`.

- Use when you want to review each phase, or to run just one phase.

- 2. **Fully automatic** — `/cap-evolve:orchestrate --execute`, or directly:

- ```bash

- cap-evolve run --spec .capevolve/project/capevolve.yaml

- ```

- Sequences every phase, enforces the hard gate before spending budget, decides

- when to stop (budget/stall), and ends with the sealed-test number.

- Host-agnostic fallback (no plugin / non-Claude host): point the agent at

- `RUN.md` and follow it step by step. Same rules, no Claude-only features needed.

+ Follow `next`; pass `reason` on to the user. Two things the JSON cannot say for itself:

+ - On a fresh request go through `intake`, and if an input it needs is missing, ask the

+ user for it rather than inventing one (`intake` owns that rule).

+ - An existing run is never restarted from zero: interrupted → `cap-evolve run --resume`;

+ sealed and the user wants another attempt → `cap-evolve run --reuse-baseline <run dir>`.

- ## The non-negotiable rules (restated; enforced by core + hooks)

- - Split train/val/test once, seeded; **test is scored only at finalize**, once.

- - Accept on **val** by significance, never on the data the optimizer edited.

- - Do **not** edit `splits.json`, `rollouts/test/*`, or `*test*gold*` files —

- the plugin's PreToolUse hook blocks it; the seal lives in core.

- - An iteration may not "finish" while `cap-evolve check` is red (Stop hook).

+ ## Three ways to run — `orchestrate` has the detail

+ 1. **Phase chain** — `/cap-evolve:<phase>` turn by turn, so each step is inspected.

+ 2. **Deterministic** — `cap-evolve run --spec .capevolve/project/capevolve.yaml`

+ sequences the check gate → baseline → algorithm → finalize → report. It presumes

+ intake already happened; it does not run intake.

+ 3. **Agent handoff** — with `orchestration_mode: agent`, `cap-evolve run` stops after

+ baseline and hands the loop back to you; no sealed-test number until you finalize.

- ## References

- - `references/routing.md` — the state machine, the session-start injection JSON

- shape, and how this router relates to `orchestrate`.

+ No plugin, or a non-Claude host: follow `RUN.md` step by step. Same engine, same rules.