name: harness-gepa
description: Inspect and audit GEPA genomes via the @metaharness/darwin/gepa library entry (darwin 0.8.0) — load/validate a genome (default: the shipped cand-6 promotion), render the system prompt a genome compiles to, or classify failure modes in a run transcript. The gepaOptimize loop itself is library-only (bring your own evaluator) and not surfaced here — use harness-evolve for sandbox-scored evolution. Degrades gracefully when @metaharness/darwin is absent.
argument-hint: "--op genome|validate|render|analyze [--path <genome.json>] [--transcript <t.json>] [--alert-on-invalid]"
allowed-tools: Bash
Surfaces the GEPA (genetic-evolution prompt-adaptation) library exports
from @metaharness/darwin/gepa. Unlike the other skills in this plugin
there is no CLI binary behind this — the script dynamic-imports the library
(local resolution first, versioned cache install as fallback) and calls the
subprocess-safe subset.
When to use
- Adopting an evolved policy:
--op render shows the actual system
prompt a genome compiles to — read THAT, not the raw JSON, before
wiring a genome into a harness.
- Auditing a promotion:
--op genome loads + validates the shipped
cand-6 genome (first holdout-confirmed cheap-tier promotion; provenance
ships in the package) or any genome file you point at.
- CI gate on genome edits:
--op validate --alert-on-invalid exits 1
on structural errors.
- Debugging a bad run:
--op analyze --transcript run.json classifies
failure modes (GEPA's failure-class taxonomy) from a transcript array.
What is deliberately NOT here
gepaOptimize — the optimization loop takes an in-process
evaluate(candidate) callback ("bring your own evaluator") that cannot
cross a subprocess boundary. Two supported paths instead:
- Library consumers:
import { gepaOptimize, loadCand6Genome } from '@metaharness/darwin/gepa'
- Sandbox-scored evolution:
harness-evolve (darwin CLI evolve),
which pairs GEPA with its own sandbox evaluators.
Algorithm
Implementation: scripts/gepa.mjs.
import('@metaharness/darwin/gepa'); on MODULE_NOT_FOUND fall back to a
one-time npm install --prefix ~/.ruflo/darwin-cache-0.8.0 and import
the cached dist/gepa/index.js (versioned dir → pin bumps invalidate).- Dispatch
--op:
genome → loadGenome(fs, path) or loadCand6Genome() + validateGenomevalidate → validateGenome(rawJson) (raw parse so broken files reach
the validator instead of throwing in the loader)render → buildSystemFromGenome(genome, ext?, glob?)analyze → analyzeTranscript(entries)
- Emit one JSON object; exit 0 (or 1 under
--alert-on-invalid, 2 on bad input).
Examples
node scripts/gepa.mjs --op genome
node scripts/gepa.mjs --op render | jq -r .system
node scripts/gepa.mjs --op validate --path my-genome.json --alert-on-invalid
node scripts/gepa.mjs --op analyze --transcript run.json
Exit codes
0 — op completed (or degraded — darwin not installable)1 — --alert-on-invalid and validation found errors2 — config error (unknown op, missing/broken input file)
