# ruvnet/agent-harness-generator architecture

> Architecture diagram of the GitHub repository ruvnet/agent-harness-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruvnet/agent-harness-generator
- Repository: https://github.com/ruvnet/agent-harness-generator

## Overview

1. **Overall shape**
   This is a monorepo that acts as a **factory for agent harnesses**. The source repo contains the generator, the shared kernel, host adapters, benchmark tooling, a browser studio, templates, and publishing/validation scripts. The generated product is a separate npm-publishable harness zip/package that runs on a chosen agent host.

2. **Primary user entry points**
   There are two ways into the system: the **local CLI** (`metaharness` / `harness`) and the **browser Studio** in `apps/web-ui`. Both ultimately use the same TypeScript generator logic, but the Studio is entirely client-side and produces output locally rather than calling a backend service.

3. **Generation pipeline**
   The core factory lives in `packages/create-agent-harness`. It analyzes a repo, selects a template/vertical, renders files from `templates/`, and emits a complete harness with CLI entrypoints, README, tests, host config, skills, commands, and manifest files. The generated artifacts are meant to be owned and customized by the destination repo.

4. **Repo analysis and scaffold boundaries**
   The analysis side is intentionally static and deterministic: it inspects the input repo without executing it, infers language/build signals, computes fit/scoring, and then feeds those results into scaffold selection and manifest generation. This boundary is important because the “analysis” stage is separate from the “materialize a harness” stage.

5. **Host adapter layer**
   `packages/host-*` packages encapsulate output formats for different runtimes: Claude Code, Codex, pi.dev, Hermes, OpenClaw, RVM, Copilot, OpenCode, and GitHub Actions. Each adapter translates the same harness concepts into host-specific configuration files and conventions, so the generator can target multiple execution surfaces from one model.

6. **Shared kernel layer**
   The Rust workspace under `crates/kernel` is the shared runtime core. It contains subsystems for claims, dispatch, routing, MCP integration, memory, witness/provenance, federation, hooks, cost logic, and intel/observability. This kernel is built into both **WASM** and **NAPI** forms (`crates/kernel-wasm`, `crates/kernel-napi`) so the same primitives can be consumed across Node and browser/native paths.

7. **JavaScript kernel and routing**
   `packages/kernel-js` mirrors key kernel behaviors on the JS side, while `packages/router` provides model-routing logic, including a native optional path. The data flow here is: task/request metadata in, routing decision out, with the router using learned or trained signals to pick a cheaper model when possible.

8. **Benchmarks and evaluation**
   `packages/bench` contains the DRACO benchmark suite plus host benchmarks. This subsystem is not part of day-to-day harness generation; it is the evaluation layer used to compare models, measure grounding/quality/cost tradeoffs, and validate routing/scoring behavior. It feeds the router and benchmark assertions, not the scaffold output directly.

9. **Templates, examples, and published wrappers**
   `packages/vertical-*` and `examples-packages/*` are the packaged verticals and host wrappers that demonstrate the same generator output in different domains. The `examples/` directory provides runnable end-to-end demos, while `templates/` inside `packages/create-agent-harness` is the source of truth for what gets emitted. This split makes the repo both a product and a catalog of reference harnesses.

10. **Governance, provenance, and release flow**
    The repo is heavily gated by validation and release tooling in `scripts/` and `.github/workflows/`. Key stages include validation, SBOM generation, witness signing/verification, publish dry runs, npm publish with provenance, and GitHub Actions CI/security scans. The architecture assumes outputs should be reproducible, auditable, and safe to publish.

11. **Browser and deployment boundary**
    The Studio in `apps/web-ui` is built with Vite/React and deploys via GitHub Pages. That means the interactive UI is a static client, not a hosted service. Any generation state is local to the browser session or the downloaded artifact bundle.

12. **Documentation and contract layer**
    `docs/adrs/` and the top-level docs are not just guidance; they define the architectural contracts for kernel boundaries, host integration, MCP policy, witness/provenance, and release orchestration. In a diagram, these docs sit as governance over the rest of the system rather than as a runtime component.

13. **Tests as architecture enforcement**
    The `__tests__` tree spans CLI behavior, host adapters, kernel invariants, scaffold generation, security checks, and release/publish flows. The test suite is broad enough that it effectively defines the expected boundaries between analysis, generation, runtime adapters, and release tooling.

14. **High-level data flow to diagram**
    A useful diagram is: **user input or repo URL → static repo analysis → template/host selection → harness rendering → validation/signing/packaging → npm-publishable output**, with optional side flows into **benchmarks/router training** and **browser Studio generation**. The shared kernel sits underneath the output harness and is consumed by host adapters rather than by the original source repo directly.

Main entry points: [`crates/kernel/src/lib.rs`](https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel/src/lib.rs) (Kernel core), [`packages/create-agent-harness/src/renderer.ts`](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/renderer.ts) (Renderer), [`docs/ARCHITECTURE.md`](https://github.com/ruvnet/agent-harness-generator/blob/main/docs/ARCHITECTURE.md) (Docs & ADRs), [`packages/create-agent-harness/src/analyze-repo.ts`](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/analyze-repo.ts) (Repo analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_generator["Harness Factory"]
  node_node_cli["CLI<br/>entrypoint<br/>[bin.ts]"]
  node_node_analysis["Repo analysis<br/>static analysis<br/>[analyze-repo.ts]"]
  node_node_renderer["Renderer<br/>templating<br/>[renderer.ts]"]
  node_node_manifest["Manifest<br/>package spec<br/>[manifest.ts]"]
  node_node_templates["Templates<br/>[catalog.json]"]
  node_node_lib["Gen library<br/>shared library<br/>[index.ts]"]
end

subgraph group_group_studio["Browser Studio"]
  node_node_studio["Studio UI<br/>client app<br/>[App.tsx]"]
  node_node_studio_gen["UI generator<br/>browser pipeline<br/>[index.ts]"]
end

subgraph group_group_kernel["Shared Kernel"]
  node_node_kernel_rs["Kernel core<br/>rust runtime<br/>[lib.rs]"]
  node_node_kernel_wasm["WASM kernel<br/>wasm build<br/>[lib.rs]"]
  node_node_kernel_napi["NAPI kernel<br/>native build<br/>[lib.rs]"]
  node_node_kernel_js["Kernel JS<br/>js mirror<br/>[index.ts]"]
  node_node_router["Router<br/>model routing<br/>[index.ts]"]
end

subgraph group_group_host["Host Adapters"]
  node_node_hosts["Host adapters<br/>adapter layer<br/>[index.ts]"]
  node_node_examples["Example packs<br/>vertical packs<br/>[README.md]"]
end

subgraph group_group_eval["Evaluation"]
  node_node_bench["Bench suite<br/>evaluation<br/>[index.ts]"]
end

subgraph group_group_governance["Governance"]
  node_node_release["Release flow<br/>publishing<br/>[release.mjs]"]
  node_node_validate["Validation<br/>policy gates"]
  node_node_docs["Docs & ADRs<br/>architecture contracts<br/>[ARCHITECTURE.md]"]
end

node_node_cli -->|"analyze repo"| node_node_analysis
node_node_analysis -->|"select template"| node_node_templates
node_node_analysis -->|"derive manifest"| node_node_manifest
node_node_templates -->|"render inputs"| node_node_renderer
node_node_manifest -->|"emit config"| node_node_renderer
node_node_renderer -->|"shared logic"| node_node_lib
node_node_lib -->|"browser reuse"| node_node_studio_gen
node_node_studio -->|"drive UI"| node_node_studio_gen
node_node_studio_gen -->|"verify bundle"| node_node_validate
node_node_renderer -->|"target host"| node_node_hosts
node_node_hosts -->|"publish wrappers"| node_node_examples
node_node_kernel_rs -->|"compile to wasm"| node_node_kernel_wasm
node_node_kernel_rs -->|"compile to napi"| node_node_kernel_napi
node_node_kernel_rs -->|"mirror behavior"| node_node_kernel_js
node_node_kernel_js -->|"route requests"| node_node_router
node_node_router -->|"train and compare"| node_node_bench
node_node_bench -->|"assert quality"| node_node_validate
node_node_validate -->|"gate publish"| node_node_release
node_node_docs -.->|"define contracts"| node_node_cli
node_node_docs -.->|"define boundaries"| node_node_kernel_rs
node_node_docs -.->|"define governance"| node_node_release

click node_node_cli "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/bin.ts"
click node_node_analysis "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/analyze-repo.ts"
click node_node_renderer "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/renderer.ts"
click node_node_manifest "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/manifest.ts"
click node_node_templates "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/templates/catalog.json"
click node_node_lib "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/agent-harness-generator-lib/src/index.ts"
click node_node_studio "https://github.com/ruvnet/agent-harness-generator/blob/main/apps/web-ui/src/App.tsx"
click node_node_studio_gen "https://github.com/ruvnet/agent-harness-generator/blob/main/apps/web-ui/src/generator/index.ts"
click node_node_kernel_rs "https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel/src/lib.rs"
click node_node_kernel_wasm "https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel-wasm/src/lib.rs"
click node_node_kernel_napi "https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel-napi/src/lib.rs"
click node_node_kernel_js "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/kernel-js/src/index.ts"
click node_node_router "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/router/src/index.ts"
click node_node_hosts "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/host-claude-code/src/index.ts"
click node_node_examples "https://github.com/ruvnet/agent-harness-generator/blob/main/examples-packages/README.md"
click node_node_bench "https://github.com/ruvnet/agent-harness-generator/blob/main/packages/bench/src/index.ts"
click node_node_release "https://github.com/ruvnet/agent-harness-generator/blob/main/scripts/release.mjs"
click node_node_validate "https://github.com/ruvnet/agent-harness-generator/blob/main/scripts/validate-gcp-secrets.mjs"
click node_node_docs "https://github.com/ruvnet/agent-harness-generator/blob/main/docs/ARCHITECTURE.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_analysis,node_node_renderer,node_node_manifest,node_node_templates,node_node_lib toneBlue
class node_node_studio,node_node_studio_gen toneAmber
class node_node_kernel_rs,node_node_kernel_wasm,node_node_kernel_napi,node_node_kernel_js,node_node_router toneMint
class node_node_hosts,node_node_examples toneRose
class node_node_bench toneIndigo
class node_node_release,node_node_validate,node_node_docs toneTeal
```

## Components

### Harness Factory

CLI and library that analyze repositories and render agent harnesses.

- [CLI](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/bin.ts): entrypoint · Local command-line entry into the harness generator and related commands. · `packages/create-agent-harness/src/bin.ts`
- [Repo analysis](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/analyze-repo.ts): static analysis · Deterministic repo inspection, scoring, constraints, and scaffold selection. · `packages/create-agent-harness/src/analyze-repo.ts`
- [Renderer](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/renderer.ts): templating · Renders templates, writes files, builds manifests, and materializes harness output. · `packages/create-agent-harness/src/renderer.ts`
- [Manifest](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/src/manifest.ts): package spec · Harness metadata, host config, and emitted package structure. · `packages/create-agent-harness/src/manifest.ts`
- [Templates](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/create-agent-harness/templates/catalog.json): source templates · Canonical harness templates and vertical packs used as the source of truth for output. · `packages/create-agent-harness/templates/catalog.json`
- [Gen library](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/agent-harness-generator-lib/src/index.ts): shared library · Reusable generator library consumed by the CLI and the browser UI. · `packages/agent-harness-generator-lib/src/index.ts`

### Browser Studio

Client-side UI for importing repos and generating harness artifacts locally.

- [Studio UI](https://github.com/ruvnet/agent-harness-generator/blob/main/apps/web-ui/src/App.tsx): client app · Vite/React browser studio for local, client-side harness generation. · `apps/web-ui/src/App.tsx`
- [UI generator](https://github.com/ruvnet/agent-harness-generator/blob/main/apps/web-ui/src/generator/index.ts): browser pipeline · Repo import, scaffold, render, verify, and zip pipeline running in the browser. · `apps/web-ui/src/generator/index.ts`

### Shared Kernel

Rust and JS runtime core reused across hosts and generated harnesses.

- [Kernel core](https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel/src/lib.rs): rust runtime · Shared Rust kernel with claims, routing, dispatch, memory, hooks, witness, and federation. · `crates/kernel/src/lib.rs`
- [WASM kernel](https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel-wasm/src/lib.rs): wasm build · WebAssembly build of the shared kernel for browser-facing consumption. · `crates/kernel-wasm/src/lib.rs`
- [NAPI kernel](https://github.com/ruvnet/agent-harness-generator/blob/main/crates/kernel-napi/src/lib.rs): native build · Node-native binding build of the shared kernel. · `crates/kernel-napi/src/lib.rs`
- [Kernel JS](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/kernel-js/src/index.ts): js mirror · JavaScript-side mirror of kernel behaviors including dispatch and memory. · `packages/kernel-js/src/index.ts`
- [Router](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/router/src/index.ts): model routing · Request-to-model routing logic with native optional path and training hooks. · `packages/router/src/index.ts`

### Host Adapters

Target-specific wrappers that translate harness concepts into host conventions.

- [Host adapters](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/host-claude-code/src/index.ts): adapter layer · Host-specific output formats and conventions for multiple execution surfaces. · `packages/host-claude-code/src/index.ts`
- [Example packs](https://github.com/ruvnet/agent-harness-generator/blob/main/examples-packages/README.md): vertical packs · Published vertical packages and wrappers that demonstrate generated harnesses. · `examples-packages/README.md`

### Evaluation

Benchmarks and routing experiments used to measure quality and cost tradeoffs.

- [Bench suite](https://github.com/ruvnet/agent-harness-generator/blob/main/packages/bench/src/index.ts): evaluation · DRACO and host benchmarks used to compare quality, grounding, and cost. · `packages/bench/src/index.ts`

### Governance

Validation, release, docs, and CI controls that gate publishing.

- [Release flow](https://github.com/ruvnet/agent-harness-generator/blob/main/scripts/release.mjs): publishing · Packaging, publish dry runs, npm publish, provenance, and release orchestration. · `scripts/release.mjs`
- [Validation](https://github.com/ruvnet/agent-harness-generator/blob/main/scripts/validate-gcp-secrets.mjs): policy gates · Audit, SBOM, witness verification, security checks, and harness validation scripts. · `scripts/validate-gcp-secrets.mjs`
- [Docs & ADRs](https://github.com/ruvnet/agent-harness-generator/blob/main/docs/ARCHITECTURE.md): architecture contracts · Architecture docs and ADRs that define boundaries, integration, and release policy. · `docs/ARCHITECTURE.md`

## Connections

- CLI → Repo analysis: analyze repo · CLI starts with deterministic repository analysis and scoring.
- Repo analysis → Templates: select template · Analysis results drive template and vertical selection.
- Repo analysis → Manifest: derive manifest · Repo signals feed harness manifest generation.
- Templates → Renderer: render inputs · Template catalog provides the materialized file set.
- Manifest → Renderer: emit config · Manifest and host metadata shape emitted files.
- Renderer → Gen library: shared logic · Generator library is used by both CLI and browser paths.
- Gen library → UI generator: browser reuse · Studio reuses core generator logic client-side.
- Studio UI → UI generator: drive UI · The browser UI coordinates import, generation, and verification.
- UI generator → Validation: verify bundle · Browser pipeline validates artifacts before export.
- Renderer → Host adapters: target host · Rendered harnesses are adapted to host-specific conventions.
- Host adapters → Example packs: publish wrappers · Host adapters are reflected in packaged example wrappers.
- Kernel core → WASM kernel: compile to wasm · Rust kernel is built for browser/WASM consumption.
- Kernel core → NAPI kernel: compile to napi · Rust kernel is built for Node-native use.
- Kernel core → Kernel JS: mirror behavior · JS kernel mirrors key runtime behaviors.
- Kernel JS → Router: route requests · JS-side routing uses metadata to choose models.
- Router → Bench suite: train and compare · Benchmark outputs inform routing regression and training.
- Bench suite → Validation: assert quality · Benchmarks contribute validation signals and regressions.
- Validation → Release flow: gate publish · Validation, SBOM, and provenance checks gate release.
- Docs & ADRs → CLI: define contracts · Docs and ADRs constrain CLI and generator behavior.
- Docs & ADRs → Kernel core: define boundaries · Architecture docs specify kernel responsibilities and integrations.
- Docs & ADRs → Release flow: define governance · Release and provenance policies are documented as contracts.