# Harness Evolve

> Ejecuta @metaharness/darwin evolve para mutar las siete superficies de política de un harness, puntuar cada variante en sandbox y promover solo las mejoras medidas.

Fuente: https://skillsagentes.com/skills/ruvnet/ruflo/harness-evolve
Markdown: https://skillsagentes.com/skills/ruvnet/ruflo/harness-evolve.md

Repositorio: https://github.com/ruvnet/ruflo
Autor: ruvnet
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 110 tok instalada, 1.6k tok al activarse, 1.6k tok con todos los archivos del bundle
Bundle: 1 archivo, 6 KB
Permisos que pide: bash

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ruvnet/ruflo --skill harness-evolve --agent claude-code
# Cursor
npx -y skills add ruvnet/ruflo --skill harness-evolve --agent cursor
# Codex
npx -y skills add ruvnet/ruflo --skill harness-evolve --agent codex
# Gemini CLI
npx -y skills add ruvnet/ruflo --skill harness-evolve --agent gemini
# Windsurf
npx -y skills add ruvnet/ruflo --skill harness-evolve --agent windsurf
# Cline
npx -y skills add ruvnet/ruflo --skill harness-evolve --agent cline
```

## Qué hace

- Muta una superficie de política por variante (planner, contextBuilder, reviewer, retryPolicy, toolPolicy, memoryPolicy o scorePolicy).
- Puntúa cada variante en sandbox y promueve solo las que ganan de forma medida.
- Sin --confirm solo imprime el plan; no escribe nada hasta confirmarlo.
- Con --diagnose, clasifica los fallos de las variantes perdedoras con las herramientas GEPA.

## Cuándo usarla

- Una puntuación de harness-score está por debajo del objetivo y no sabes qué superficie de política es responsable.
- Vas a preparar un harness para un vertical nuevo y quieres una configuración inicial hallada empíricamente.
- Quieres comparar tu harness ajustado a mano contra una línea base evolucionada.

## Cuándo no

- Para optimización continua en segundo plano; Darwin Mode se inicia manualmente, no de forma autónoma.
- Para evolucionar ruflo mismo en CI, algo que ADR-153 rechaza explícitamente.

## Qué la activa

- "Evoluciona este harness durante 3 generaciones"
- "Compara mi harness ajustado a mano contra un campeón evolucionado"

## Antes de instalar

- Se degrada con normalidad si @metaharness/darwin no está instalado.
- runs shell commands

## Archivos

- SKILL.md — 6 KB

## SKILL.md

Reproducido tal cual desde ruvnet/ruflo bajo MIT. Esta sección es el documento original y está en inglés.

Surfaces the upstream `metaharness-darwin evolve` CLI as a ruflo skill. The
**write** layer that pairs with ADR-150's read layer (score / genome /
mcp-scan / threat-model / oia-audit). Use when you have a harness whose
readiness scores are flat and you want to discover *which* surface mutation
moves them — without retraining the foundation model.

## When to use

- A `harness-score` result is below target and you don't know which policy
  surface is responsible.
- You're seeding a harness for a new vertical and want to find a good
  starting configuration empirically rather than hand-tuning.
- You're comparing your hand-tuned harness against an evolved baseline
  (treat darwin's champion as the strawman).

## When NOT to use

- For continuous background optimization. Darwin Mode is human-initiated.
  Wire it into CI for one-shot exploration, not for autonomous self-modification.
- For ruflo itself in CI. ADR-153 §5 explicitly rejects auto-evolving ruflo
  — the CI gate verifies graceful degradation, not convergence.

## Algorithm

Implementation: [`scripts/evolve.mjs`](../../scripts/evolve.mjs).

1. Validate args (`--repo` exists, caps on `--generations` ≤ 50, `--children`
   ≤ 20, `--concurrency` ≤ 8, sandbox/selection/mutator are known values).
2. Without `--confirm`: print plan + exit 0 (mirrors `harness-mint` safety
   convention; defense in depth over the upstream `safety.ts` checks).
3. With `--confirm`: shell to `npx -y @metaharness/darwin@~0.8.0 metaharness-darwin evolve <repo> ...`
   via the shared `_darwin.mjs` async helper. Per-generation progress is
   forwarded to stderr; final champion JSON is captured from stdout.
4. Compute timeout from `generations × children × per-variant` (per-variant
   ≈ 60s real, ≈ 2s mock). Caller may override with `--timeout-ms`.
5. Honor upstream exit code 99 — propagate as "safety-disqualified", do not
   remap. This is a designed-in tripwire (a variant tripped `inspectVariant`
   for secrets / shell-out / network / dynamic-eval). See ADR-153 §"Safety model".
6. Optional `--alert-on-no-improvement`: exit 1 when champion ≤ parent.

## The seven mutation surfaces

| Surface | What it owns |
|---|---|
| `planner` | task decomposition / step ordering |
| `contextBuilder` | what gets fed into the prompt |
| `reviewer` | self-critique / output verification |
| `retryPolicy` | when + how to retry on failure |
| `toolPolicy` | which tools the agent may use, under which conditions |
| `memoryPolicy` | what to persist, recall, forget |
| `scorePolicy` | how the agent grades its own output |

One mutation per variant. Multi-surface mutations are not allowed (causal
attribution stays clean).

## Output

Reports land under `<repo>/.metaharness/`:

```
.metaharness/
  archive.json         # full lineage tree (sampling next gen draws from this)
  lineage.json         # parent→child edges only
  variants/<id>/       # per-variant code (kept for audit)
  runs/<id>/           # per-variant sandbox test output
  reports/winner.json  # final champion + score delta vs parent
```

Skill stdout = JSON `{success, data: {champion, plan, durationMs, improved}}`
(plus `data.diagnosis` when `--diagnose` is passed — see below).

## Failure diagnosis (`--diagnose`)

GEPA's key trick is natural-language failure diagnosis from execution traces
feeding the next mutation — not just scalar fitness. `--diagnose` adds a
modest slice of that: after the evolution completes, the losing / failed
variants' transcripts are run through darwin's GEPA library ops
(`analyzeTranscript` + `classifyFailure`, via the shared `importGepa`
resolver in `scripts/_darwin.mjs`) and a `diagnosis` section is appended to
the emitted JSON:

```json
"diagnosis": {
  "available": true,
  "scope": "losing-variants",
  "variants": [
    { "id": "g1_v0", "transcripts": 2,
      "failureClasses": { "exploration-loop": 1, "edit-mechanics": 1 },
      "dominantClass": "exploration-loop" }
  ],
  "totals": { "exploration-loop": 1, "edit-mechanics": 1 }
}
```

Upstream shape caveats (verified against `@metaharness/darwin@0.8.0`):

- `metaharness-darwin evolve --json` prints a TEXT leaderboard — the stdout
  carries no JSON and no transcripts. Per-variant run records live at
  `<repo>/.metaharness/runs/<id>.json`.
- Those run records hold sandbox exec traces (`{taskId, exitCode, stdout,
  stderr}`), which are NOT GEPA `{actionRaw, obs}` transcripts. Diagnosis
  therefore uses GEPA-shaped transcripts when a run record embeds them
  (agent sandbox / future upstream), falls back to the champion's transcript,
  and otherwise emits `diagnosis: {available: false, reason, traceSummary}`
  where `traceSummary` is a mechanical per-variant tally (tasks / failed /
  timedOut / blockedActions).
- `--diagnose` NEVER fails the run — any internal error degrades to
  `{available: false, reason: "diagnosis-failed: ..."}`.

## Exit codes

| Code | Meaning |
|---|---|
| 0  | Evolved OK, or dry-run, or degraded (Darwin absent) |
| 1  | `--alert-on-no-improvement` and champion did not beat parent |
| 2  | Config error or evolution infrastructure failure |
| 99 | Upstream "safety-disqualified" (PROPAGATED, not remapped) |

## Graceful degradation (ADR-150 constraint 3 + ADR-153)

When `@metaharness/darwin` is not installed, the script emits
`{degraded: true, reason: 'metaharness-darwin-not-available', hint: ...}`
and exits 0. ruflo continues to function. CI's
`no-metaharness-smoke.yml`-style job asserts this path.

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [ruvnet](https://skillsagentes.com/creators/ruvnet.md) — 275 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Harness Gepa](https://skillsagentes.com/skills/ruvnet/ruflo/harness-gepa.md): Inspecciona y audita genomas GEPA: carga y valida un genoma, renderiza el system prompt que compila, o clasifica los modos de fallo de una transcripción de ejecución.
- [Deepseek Reason](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-reason.md): Completion en modo razonamiento contra deepseek-reasoner (R1) de DeepSeek. Devuelve el chain-of-thought por separado de la respuesta final. Lee DEEPSEEK_API_KEY y degrada si falta o la API no responde.
- [Deepseek Chat](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-chat.md): Completion de un solo turno contra el modelo deepseek-chat de DeepSeek vía /v1/chat/completions. Lee DEEPSEEK_API_KEY y degrada con status:degraded si falta o la API no responde. Para tareas sin razonamiento.
- [Adr Index](https://skillsagentes.com/skills/ruvnet/ruflo/adr-index.md): Construye o reconstruye el índice de ADRs y su grafo de dependencias ejecutando scripts/import.mjs, en vez de cientos de llamadas MCP.
- [Agntcy Status](https://skillsagentes.com/skills/ruvnet/ruflo/agntcy-status.md): Muestra el estado de la integración AGNTCY/SLIM/CASA: si los paquetes están instalados, qué transporte está activo y si el enforcement de CASA está habilitado.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)