# https://github.com/ruvnet/metaharness Project Manual

Generated at: 2026-07-06 00:54:19 UTC

## Table of Contents

- [Introduction & Quick Start](#page-1)
- [System Architecture & Kernel](#page-2)
- [Templates, Hosts & Plugin Manifests](#page-3)
- [Self-Evolution, Routing & Cost-Pareto](#page-4)

<a id='page-1'></a>

## Introduction & Quick Start

### Related Pages

Related topics: [System Architecture & Kernel](#page-2), [Templates, Hosts & Plugin Manifests](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/ruvnet/metaharness/blob/main/README.md)
- [docs/USERGUIDE.md](https://github.com/ruvnet/metaharness/blob/main/docs/USERGUIDE.md)
- [docs/USAGE.md](https://github.com/ruvnet/metaharness/blob/main/docs/USAGE.md)
- [packages/create-agent-harness/src/bin.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/bin.ts)
- [packages/create-agent-harness/src/subcommands.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/subcommands.ts)
- [packages/create-agent-harness/package.json](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/package.json)
- [packages/create-agent-harness/src/index.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/index.ts)
</details>

# Introduction & Quick Start

**metaharness** is an opinionated scaffolding and orchestration toolkit for building AI coding agents. It packages reusable "harness" templates — pre-configured collections of prompts, skills, hooks, and tool integrations — so that teams can stand up a Claude Code–compatible agent workspace in seconds rather than assembling one from scratch. The project ships two coordinated packages: `metaharness` (the user-facing CLI) and `@ruvnet/agent-harness-generator` (the programmatic scaffold engine). Source: [README.md:1-20]()

## What is a Harness?

A harness is a self-contained agent workspace. It bundles system prompts, slash-command definitions, tool/hook configuration, and project conventions into a directory that Claude Code (or any compatible runtime) can load directly. Every scaffold produced by metaharness is a working plugin: from v0.1.3 onward, **20/20 templates ship a `.claude-plugin/plugin.json`** manifest, so the directory can be invoked with `claude -p --plugin-dir <harness>` immediately after generation. Source: [README.md:21-40]()

The repository exposes a catalog of templates (ranging from `minimal` to feature-rich, domain-specific stacks) so that users can start from a known-good baseline instead of writing every prompt and hook by hand.

## Installation

The CLI is distributed as the npm package `metaharness`. It can be invoked without a global install via `npx`, or installed once per machine:

```bash
# Run without installing
npx metaharness --help

# Or install globally
npm install -g metaharness
```

The published package wraps a thin entry point that delegates to the generator library. Source: [packages/create-agent-harness/package.json:1-30]() The `bin` field maps the `metaharness` command to the compiled `dist/bin.js` entry. Source: [packages/create-agent-harness/src/bin.ts:1-15]()

## Quick Start Workflow

The typical first-run experience is a single command that scaffolds a new harness into the current (or a target) directory:

```bash
# Create a new harness in ./my-agent
metaharness new my-agent

# Or scaffold into the current directory
metaharness new .
```

Behind the scenes, the CLI dispatches to `main()` in `bin.ts`, which parses subcommands and forwards them to the handler map defined in `subcommands.ts`. Each handler invokes the generator, copies the selected template into the destination, and emits a `.claude-plugin/plugin.json` automatically. Source: [packages/create-agent-harness/src/subcommands.ts:1-50]()

A minimal end-to-end session looks like this:

1. **Scaffold** — `metaharness new my-agent` copies template files and the plugin manifest.
2. **Inspect** — review `.claude-plugin/plugin.json`, `CLAUDE.md`, and any skill files.
3. **Customize** — edit prompts, add hooks, or layer in project-specific tooling.
4. **Run** — launch Claude Code against the harness directory.

## CLI Surface and Subcommands

The CLI exposes a small, predictable verb set so that users can navigate the system without memorizing flags. The handler map in `subcommands.ts` is the authoritative list of supported commands. Source: [packages/create-agent-harness/src/subcommands.ts:20-80]() Common entries include:

| Subcommand | Purpose |
|---|---|
| `new <dir>` | Scaffold a fresh harness from a template |
| `list` | Enumerate available templates |
| `learn` | Interactive walkthrough for first-time users |
| `update` | Refresh an existing harness with newer template revisions |

> ⚠️ Known issue: the compiled `dist/bin.js` discards `main()`'s return code, so every subcommand currently exits `0` even on failure — a failed command appears green in CI. Track progress in [issue #73](https://github.com/ruvnet/metaharness/issues/73). The `learn` subcommand was the first to receive a scope fix for this behavior in PR #72. Source: [packages/create-agent-harness/src/bin.ts:30-60]()

## Programmatic Use

For automation and embedding, the generator is published separately as `@ruvnet/agent-harness-generator`. Importing it lets scripts compose scaffolds alongside other tooling:

```ts
import { generateHarness } from "@ruvnet/agent-harness-generator";

await generateHarness({
  template: "minimal",
  destination: "./out",
  emitPluginManifest: true, // default true since v0.1.3
});
```

This entry point shares its core implementation with the CLI handlers, so behavior is consistent regardless of whether the user is at a terminal or inside a build pipeline. Source: [packages/create-agent-harness/src/index.ts:1-40]()

## Where to Go Next

- New users should read the **User Guide** for a guided tour of template selection and customization. Source: [docs/USERGUIDE.md:1-30]()
- Power users looking for flags, environment variables, and exit-code semantics should consult **Usage**. Source: [docs/USAGE.md:1-40]()
- Contributors extending the template catalog start in `packages/create-agent-harness/src/subcommands.ts` and the template assets shipped alongside the generator.

With a single `metaharness new` invocation, you get a working, plugin-ready Claude Code harness — and from there, every subsequent change is just editing files in a normal project tree.

---

<a id='page-2'></a>

## System Architecture & Kernel

### Related Pages

Related topics: [Introduction & Quick Start](#page-1), [Self-Evolution, Routing & Cost-Pareto](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/create-agent-harness/package.json](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/package.json)
- [packages/create-agent-harness/src/bin.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/bin.ts)
- [packages/create-agent-harness/src/main.ts](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/src/main.ts)
- [packages/create-agent-harness/dist/bin.js](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/dist/bin.js)
- [packages/agent-harness-generator/package.json](https://github.com/ruvnet/metaharness/blob/main/packages/agent-harness-generator/package.json)
- [templates/*/.claude-plugin/plugin.json](https://github.com/ruvnet/metaharness/tree/main/templates)
</details>

# System Architecture & Kernel

## Purpose & Scope

metaharness is a Node.js/TypeScript monorepo whose kernel is a **scaffolding CLI** that materializes *agent harnesses* — opinionated directory layouts consumable by Claude Code via `claude -p --plugin-dir <harness>`. The "kernel" in this project is therefore not a Rust/crate subsystem (as the example file list in some templates suggests) but the **`create-agent-harness` package**: the entry point that resolves a template, copies it onto disk, patches in the user-supplied name, and writes the plugin manifest `Source: [packages/create-agent-harness/package.json:1-40]()`. Two npm packages form the kernel surface: `metaharness` (the user-facing CLI shim) and `@ruvnet/agent-harness-generator` (the generator library) `Source: [packages/agent-harness-generator/package.json:1-30]()`.

## High-Level Architecture

The kernel follows a standard **monorepo → package → template** hierarchy:

```
metaharness (repo)
└── packages/
    ├── create-agent-harness/   ← CLI entry & dispatch
    │   ├── src/bin.ts          ← argv → subcommand
    │   ├── src/main.ts         ← core generator
    │   └── dist/bin.js         ← compiled shim
    ├── agent-harness-generator/← reusable generator lib
    └── ... (shared utilities)
└── templates/
    ├── minimal/.claude-plugin/plugin.json
    ├── research-assistant/.claude-plugin/plugin.json
    └── ... (20 templates total post-v0.1.3)
```

The CLI bin file is intentionally thin: it parses arguments and forwards the call to `main()`, then exits `Source: [packages/create-agent-harness/src/bin.ts:1-40]()`. The `main()` function holds the orchestration logic — template lookup, file rendering, and post-write verification `Source: [packages/create-agent-harness/src/main.ts:1-120]()`.

## Process Flow

A user invocation travels through three distinct layers:

1. **CLI shim** — `dist/bin.js` is what npm executes when the user runs `npx metaharness`. It `require`s the compiled TS source and invokes `main()` `Source: [packages/create-agent-harness/dist/bin.js:1-20]()`.
2. **Subcommand dispatcher** — `src/bin.ts` maps argv tokens to actions such as `init`, `learn`, `list`, or `update` `Source: [packages/create-agent-harness/src/bin.ts:30-80]()`.
3. **Generator core** — `src/main.ts` performs the actual scaffold; it loads a template from `templates/<name>/`, applies string interpolation, and writes the result `Source: [packages/create-agent-harness/src/main.ts:40-120]()`.

```mermaid
flowchart LR
    A[user: npx metaharness] --> B[dist/bin.js shim]
    B --> C[src/bin.ts dispatcher]
    C --> D[src/main.ts generator]
    D --> E[templates/* copy & render]
    E --> F[target directory + .claude-plugin/plugin.json]
    F --> G[claude -p --plugin-dir]
```

## Known Kernel Issue: Exit Code Propagation

The most prominent defect currently filed against the kernel is **silent exit-code loss** in the CLI shim. Issue #73 documents that `packages/create-agent-harness/dist/bin.js` discards the return value of `main()`, so every metaharness subcommand reports exit code `0` even when generation fails `Source: [packages/create-agent-harness/dist/bin.js:1-20]()`. The compiled shim looks roughly like:

```js
require("./main")(process.argv.slice(2));   // return value thrown away
```

The result: failed `init` or `learn` runs look green in CI and in shell pipelines that gate on `$?`. PR #72 fixed the symptom for the newly introduced `learn` subcommand but did not propagate the change to the broader kernel `Source: [https://github.com/ruvnet/metaharness/issues/73]()`. The canonical remediation pattern, present in correct kernel regions, is to forward the promise's resolved value: `process.exit(await main(...))` or `main(...).then(code => process.exit(code))` `Source: [packages/create-agent-harness/src/bin.ts:60-75]()`.

## Plugin Manifest Kernel (v0.1.3 Milestone)

As of **v0.1.3**, the kernel guarantees that **every scaffolded template ships a Claude Code plugin manifest** at `<harness>/.claude-plugin/plugin.json` `Source: [templates/*/.claude-plugin/plugin.json:1-20]()`. This is the contract that lets `claude -p --plugin-dir <harness>` recognize the directory as a first-class plugin rather than as loose files. Release v0.1.3 explicitly highlights that 20/20 templates include the manifest, removing the previous gap where only the `minimal` template was plugin-ready `Source: [https://github.com/ruvnet/metaharness/releases/tag/v0.1.3]()`. The manifest typically declares `name`, `version`, and an entry command; the kernel renders these from template variables during `main()` `Source: [packages/create-agent-harness/src/main.ts:80-110]()`.

## Kernel Boundaries

| Layer | Package | Role | Reusability |
|---|---|---|---|
| CLI shim | `metaharness` / `create-agent-harness` | argv parsing, process exit | single-user CLI |
| Generator | `@ruvnet/agent-harness-generator` | template render & copy | embeddable in other tools |
| Templates | `templates/<name>/` | static scaffolds with `.claude-plugin/` | per-template |

The boundary between `create-agent-harness` (the CLI wrapper) and `@ruvnet/agent-harness-generator` (the reusable library) is deliberate: the latter exposes a programmatic API so other tooling can invoke the same template engine without re-implementing rendering logic `Source: [packages/agent-harness-generator/package.json:15-30]()`.

## Operational Summary

- **Entry point**: `npx metaharness <subcommand>` → `packages/create-agent-harness/dist/bin.js`
- **Subcommands**: dispatched in `src/bin.ts` and executed in `src/main.ts`
- **Output contract**: a target directory containing `.claude-plugin/plugin.json` consumable by `claude -p --plugin-dir`
- **Open defect**: exit-code loss in the shim (Issue #73) — all commands currently exit 0
- **Kernel version marker**: v0.1.3 ships universal plugin-manifest support across all 20 templates

This architecture keeps the kernel small (CLI + one library), pushes complexity into per-template directories, and standardizes the plugin contract so downstream Claude Code invocations remain stable across template variants.

---

<a id='page-3'></a>

## Templates, Hosts & Plugin Manifests

### Related Pages

Related topics: [Introduction & Quick Start](#page-1), [System Architecture & Kernel](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/create-agent-harness/templates/catalog.json](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/templates/catalog.json)
- [packages/create-agent-harness/templates/vertical_coding/manifest.json](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/templates/vertical_coding/manifest.json)
- [packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl](https://github.com/ruvnet/metaharness/blob/main/packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl)
- [packages/host-claude-code/src/index.ts](https://github.com/ruvnet/metaharness/blob/main/packages/host-claude-code/src/index.ts)
- [packages/host-codex/src/index.ts](https://github.com/ruvnet/metaharness/blob/main/packages/host-codex/src/index.ts)
- [packages/host-github-actions/src/index.ts](https://github.com/ruvnet/metaharness/blob/main/packages/host-github-actions/src/index.ts)
</details>

# Templates, Hosts & Plugin Manifests

## Overview

The metaharness repository is structured around three cooperating concerns: **templates** that define the shape of a generated agent harness, **host packages** that adapt that harness to a specific runtime (Claude Code, Codex, GitHub Actions), and **plugin manifests** that allow the harness to be loaded as a Claude Code plugin. Together they let a single scaffolded directory be consumed by multiple execution environments without rewriting its contents. The community release `v0.1.3` formalised this by ensuring every one of the 20 templates in the catalog ships a `.claude-plugin/plugin.json` Source: [packages/create-agent-harness/templates/catalog.json:1-400]().

## Template Catalog and Manifests

The template catalog lives at `packages/create-agent-harness/templates/catalog.json` and is the single source of truth enumerating every scaffoldable harness. Each entry points to a template directory and references a `manifest.json` that describes the template's identity, intended host targets, and variable substitutions applied at generation time.

A concrete example is the `vertical_coding` template, whose manifest describes the harness's purpose and the hosts it is compatible with:

```json
Source: [packages/create-agent-harness/templates/vertical_coding/manifest.json:1-60]()
```

Manifests are consumed by `create-agent-harness` to:

- Select which files to copy into the target directory
- Resolve placeholder tokens (for example, `{{harnessName}}`) inside template bodies
- Decide whether the template supports a given host package before offering it to the user

Templates that previously lacked host support (only `minimal` worked with Claude Code's plugin loader) were unified in `v0.1.3`, so all 20 catalog entries now ship the plugin manifest described below.

## Host Packages

Host packages live under `packages/host-*/src/index.ts` and provide the runtime adapter that wires a generated harness to a concrete execution environment. Each host is responsible for translating the neutral scaffold into its own invocation conventions, environment variables, and tool-registration surface.

| Host Package | Runtime | Primary Role |
| --- | --- | --- |
| `host-claude-code` | Claude Code (local) | Loads the harness via `--plugin-dir`, exposes `.claude-plugin/plugin.json` |
| `host-codex` | Codex (local) | Mirrors the harness for Codex's command surface |
| `host-github-actions` | GitHub Actions | Bundles the harness as a CI workflow step |

Each `host-*/src/index.ts` re-exports a small, stable surface that the CLI consumes. The Claude Code host, for example, registers the scaffolded directory so that `claude -p --plugin-dir <harness>` picks it up directly, courtesy of the plugin manifest described in the next section Source: [packages/host-claude-code/src/index.ts:1-80]().

The Codex and GitHub Actions hosts perform analogous wiring without requiring the plugin manifest, because those runtimes do not honour `.claude-plugin/plugin.json`. This is why the manifest is described as Claude-Code-specific, even though the catalog entry for every template now includes it Source: [packages/host-codex/src/index.ts:1-80](), Source: [packages/host-github-actions/src/index.ts:1-80]().

## Plugin Manifests

A plugin manifest is a small JSON document placed at `.claude-plugin/plugin.json` inside the scaffolded harness. The template that emits it lives at `packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl` and is rendered with the same variable substitution engine used elsewhere in the generator:

```json
Source: [packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl:1-30]()
```

The manifest's primary fields are:

- `name` — the harness's display name when loaded as a plugin
- `version` — synchronised with the scaffolded `package.json`
- `description` — surfaced by Claude Code's plugin browser
- `entry` — the command or script Claude Code should invoke when the plugin is activated

Because the manifest is a template (`.tmpl`), every catalog entry can produce a customised plugin file at generation time without manual editing. The community release `v0.1.3` confirmed that **20/20 templates** now ship this file, which is what made `claude -p --plugin-dir <harness>` work uniformly across the catalog Source: [packages/create-agent-harness/templates/catalog.json:1-400]().

## End-to-End Flow

The interaction between catalog, templates, hosts, and plugin manifests can be summarised as:

```mermaid
flowchart LR
    A[catalog.json] --> B[template directory]
    B --> C[manifest.json]
    B --> D[.claude-plugin/plugin.json.tmpl]
    D --> E[rendered plugin.json]
    B --> F[scaffolded harness]
    E --> F
    C --> F
    F --> G[host-claude-code]
    F --> H[host-codex]
    F --> I[host-github-actions]
```

The catalog selects a template, the template supplies both a manifest and the plugin template, the generator renders the plugin file into the scaffold, and one of the host packages loads the resulting directory into its runtime Source: [packages/create-agent-harness/templates/catalog.json:1-400](), Source: [packages/create-agent-harness/templates/minimal/.claude-plugin/plugin.json.tmpl:1-30]().

## Community Notes

- **v0.1.3 milestone**: every scaffold now ships `.claude-plugin/plugin.json`, removing the previous asymmetry where only the `minimal` template was usable with `claude -p --plugin-dir`. Source: community release notes for `metaharness@0.1.3`.
- **Known issue (#73)**: `packages/create-agent-harness/dist/bin.js` discards `main()`'s return code, so every `metaharness` subcommand exits 0 regardless of failure. This affects CI scripts that rely on non-zero exit to detect template-generation errors, but it is a CLI bug rather than a defect in the template/host pipeline itself. Source: GitHub issue #73.

---

<a id='page-4'></a>

## Self-Evolution, Routing & Cost-Pareto

### Related Pages

Related topics: [System Architecture & Kernel](#page-2), [Templates, Hosts & Plugin Manifests](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/darwin-mode/src/evolve.ts](https://github.com/ruvnet/metaharness/blob/main/packages/darwin-mode/src/evolve.ts)
- [packages/darwin-mode/src/scorer.ts](https://github.com/ruvnet/metaharness/blob/main/packages/darwin-mode/src/scorer.ts)
- [packages/darwin-mode/src/pareto.ts](https://github.com/ruvnet/metaharness/blob/main/packages/darwin-mode/src/pareto.ts)
- [packages/darwin-mode/src/gepa/loop.ts](https://github.com/ruvnet/metaharness/blob/main/packages/darwin-mode/src/gepa/loop.ts)
- [packages/router/src/index.ts](https://github.com/ruvnet/metaharness/blob/main/packages/router/src/index.ts)
- [packages/router/src/train.ts](https://github.com/ruvnet/metaharness/blob/main/packages/router/src/train.ts)
</details>

# Self-Evolution, Routing & Cost-Pareto

The **metaharness** project ships three tightly coupled subsystems that together drive an agent harness toward better quality at lower cost over time: a self-evolution engine (in `packages/darwin-mode`) that mutates and re-evaluates prompt/config candidates, a learned **router** (in `packages/router`) that picks the cheapest viable strategy per query, and a **Cost-Pareto** scorer that keeps the candidate set Pareto-optimal across quality and cost axes.

## 1. Self-Evolution Engine (GEPA Loop)

The heart of self-evolution lives in the **GEPA** (Generate-Evaluate-Pareto-Adapt) loop implemented under `packages/darwin-mode/src/gepa/loop.ts`. Each iteration:

1. **Generates** a candidate variation of the current harness (prompt edits, tool-config tweaks, or agent-graph rewrites) using mutation operators defined in `evolve.ts`.
2. **Evaluates** the candidate by running a deterministic eval suite, producing per-task scores.
3. **Pareto-adapts** the survivor set by adding the candidate only if it is non-dominated.
4. **Emits** an updated Pareto archive plus telemetry for downstream training.

The `evolve.ts` module exposes `Evolver`, an interface that wraps a base harness, a `Scorer`, and a Pareto archive; it persists intermediate state so a process crash mid-loop does not corrupt the archive. The candidate emission contract is `Candidate = { id, patch, meta }` and every candidate is hash-keyed so duplicates are deduplicated cheaply. Source: [packages/darwin-mode/src/evolve.ts:1-120]().

The `scorer.ts` module is responsible for normalizing raw eval outputs into a `(quality, cost, latency)` vector per task. Scoring is pluggable — scorers can be deterministic (regex/assertion-based) or LLM-graded — and the module enforces that every candidate receives the *same* task set in the *same* order, which is a precondition for fair Pareto comparison. Source: [packages/darwin-mode/src/scorer.ts:1-90]().

## 2. Cost-Pareto Front

The Pareto front is computed in `packages/darwin-mode/src/pareto.ts`. Given a list of scored candidates, the algorithm produces a list of non-dominated points where no other candidate is strictly better on both axes (quality↑, cost↓). The module exposes `paretoFront(candidates)` and `dominates(a, b)` primitives; both are pure functions that can be unit-tested without an LLM.

Key implementation details:
- **Multi-objective dominance**: quality dominates cost at user-specified weights, but the default treats them as independent objectives, producing a true front rather than a single optimum.
- **Archive mutation**: when a new candidate is added, dominated archive entries are pruned; this bounds archive size and ensures each generation's survivors are strictly non-dominated.
- **Serialization**: the front is persisted as JSON with a schema version field, enabling forward-compatible loading across metaharness versions (relevant to the v0.1.3 release notes, where every scaffold now ships `.claude-plugin/plugin.json` and uses the same archive loader). Source: [packages/darwin-mode/src/pareto.ts:1-150]().

The Pareto front is the bridge between the GEPA loop and the router: the router trains on it, not on raw candidates.

## 3. Router: Picking the Cheapest Viable Strategy

`packages/router/src/index.ts` implements the runtime router used by every scaffolded harness. The router accepts a query and returns the best `(strategy, expectedCost, expectedQuality)` triple, where a "strategy" is a concrete harness configuration from the Pareto archive.

The router is a small, fast classifier (typically a logistic-regression or shallow gradient-boosted model) trained over the features extracted from the query. At inference time it:

1. Extracts lightweight features (token-length bucket, intent tag, presence of code blocks, detected language, etc.).
2. Scores each candidate strategy against those features.
3. Returns the strategy whose expected quality exceeds the query's `qualityFloor` at the lowest expected cost; ties are broken by latency.

Because the router is trained on the *Pareto-optimal* subset rather than the full candidate set, the search space at inference is bounded and the router can run on every query with negligible overhead. Source: [packages/router/src/index.ts:1-200]().

## 4. Training the Router

`packages/router/src/train.ts` consumes the JSON artifacts emitted by the GEPA loop and fits the router model. The training pipeline is offline and reproducible:

| Step | Input | Output |
|------|-------|--------|
| Load archive | `archive.json` from GEPA | Candidate table |
| Feature build | Eval traces + queries | Feature matrix `X` |
| Label build | `(strategy, cost, quality)` tuples | Target vector `y` |
| Fit | `X`, `y` | Serialized router artifact |

Training is invoked by the `metaharness train-router` CLI command; the resulting artifact is checked into the scaffold so the runtime needs no network access. Source: [packages/router/src/train.ts:1-180]().

## End-to-End Flow

The three subsystems compose into a single feedback loop: GEPA produces a Pareto archive → the trainer consumes the archive → the runtime router uses the trained artifact on live queries → logged traces feed back into the next GEPA generation.

```mermaid
flowchart LR
  A[GEPA Loop] -->|archive.json| B(Pareto Front)
  B --> C[Router Trainer]
  C -->|router.json| D[Runtime Router]
  D -->|query + trace| E[Agent Harness]
  E -->|eval results| A
```

This closed loop is what makes a metaharness *self-evolving*: every scaffold produced by `@ruvnet/agent-harness-generator` includes both the GEPA driver and the router, so a fresh `metaharness init` is already wired for continuous improvement once eval data accumulates. Source: [packages/darwin-mode/src/gepa/loop.ts:1-160](), [packages/darwin-mode/src/pareto.ts:1-150](), [packages/router/src/index.ts:1-200](), [packages/router/src/train.ts:1-180](), [packages/darwin-mode/src/scorer.ts:1-90](), [packages/darwin-mode/src/evolve.ts:1-120]().

Note: the GEPA/router pipeline is independent of the CLI exit-code bug tracked in [issue #73](https://github.com/ruvnet/metaharness/issues/73); the latter affects only `packages/create-agent-harness/dist/bin.js` and does not corrupt archive or router artifacts.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: ruvnet/metaharness

Summary: Found 14 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/4

## 2. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/47

## 3. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/22

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/48

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/15

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/20

## 7. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/ruvnet/metaharness

## 8. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/ruvnet/metaharness

## 9. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/ruvnet/metaharness/issues/73

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/ruvnet/metaharness

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/ruvnet/metaharness

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/ruvnet/metaharness

## 13. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/ruvnet/metaharness

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/ruvnet/metaharness

<!-- canonical_name: ruvnet/metaharness; human_manual_source: deepwiki_human_wiki -->