optimize

Run the GEPA-backed optimization loop. The plugin calls gepa.optimize_anything under the hood; each candidate it proposes is applied in a fresh git worktree, the benchmark is run, gates are checked, and the result is backported into .gepa-research/<run>/graph.json so the dashboard continues to render the lineage DAG.

Host conventions

• Slash commands shown in user-facing copy (e.g. /gepa-research:optimize) — translate to your host's mention syntax when speaking to the user (e.g. $gepa-research optimize on Codex — plugin namespace then skill name, separated by a space).

Configuration

All arguments are optional. Invoked as /optimize [max-metric-calls=N] [stall=N] [reflection-lm=MODEL].

• max-metric-calls — GEPA evaluator-call budget for this run (default: 50).
• stall — consecutive iterations without improvement before auto-stopping (default: 5).
• reflection-lm — model string passed to ReflectionConfig.reflection_lm (default: gepa's default, currently openai/gpt-5.1). Use e.g. anthropic/claude-opus-4-7 for Claude.

The legacy subagents, budget, and per-subagent knobs are no longer accepted — GEPA owns the search strategy.

Prerequisites

• Workspace must be initialized (gepa-research status should succeed).
• A baseline experiment must be committed (run /discover first). GEPA's seed candidate is read from the current best committed node's target file.
• The gepa library on the Python path (auto-installed as a transitive dependency when the CLI is installed from GitHub: uv tool install "git+https://github.com/CyrusNuevoDia/gepa-research#subdirectory=plugins/gepa-research").
• A reflection LM API key in the environment (OpenAI/Anthropic/etc., depending on the reflection-lm value). Without this the first GEPA iteration will fail.

Architecture

Orchestrator (this skill):
  1. Reads current best committed node from .gepa-research/<run>/graph.json
  2. Extracts seed_candidate: {target_relpath: file_contents}
  3. Calls gepa.optimize_anything(seed, evaluator=adapter.evaluate,
                                  objective=config["optimization_objective"],
                                  config=GEPAConfig(stop_callbacks=...))
  4. Reports the final best candidate and updates the graph

GepaResearchAdapter.evaluate (called by gepa per candidate):
  a. allocate_experiment(parent_id=best_committed)
     -> creates .gepa-research/<run>/worktrees/exp_NNNN and a fresh branch
  b. write candidate dict contents into the worktree
  c. run config["benchmark"] as subprocess; parse_score from stdout
  d. run inherited gates (collect_gates_from_path)
     -> on failure, return (0.0, {"gate_failures": [...], "traces": ...})
  e. on score improvement + all gates pass: maybe_commit_worktree + mark "committed"
  f. return (score, side_info) so gepa can reflect on stdout/stderr/traces