ruvnet/agent-harness-generator

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.