🛠️ Spin out ruvnet/agent-harness-generator — scaffold your own AI agent harness (design landed, 17 ADRs)

[ruvnet]

Summary

Spinning out a sister project: ruvnet/agent-harness-generator — a marketplace plugin + CLI that lets users scaffold their own focused, vertical AI agent harnesses that inherit ruflo's primitives but ship with their own brand, agents, skills, and CLI.

Think create-vite for AI harnesses.

Why this exists (the one-paragraph pitch)

Ruflo today is a tightly-bundled product — primitives (MCP server, hooks, memory bridge, intelligence pipeline, claims, routing) fused to opinionated content (60+ agents, 30+ skills, 33 plugins). People want their own brand, their own vertical focus, their own marketplace listing. Forking ruflo is a one-way door — they lose every future kernel update. The harness generator factors that apart. A user runs npx create-agent-harness <name>, picks primitives + content + identity, and gets a brand-new npm-publishable harness with its own npx <name> CLI, its own MCP server, its own memory namespace, and its own marketplace identity — running on the host of their choice.

What the generator produces

npx create-agent-harness my-legal-bot

? Starting template: ▸ Vertical: Customer support
? Target host: ▸ Claude Code + Codex
? Pick agents to bundle: (multi-select)
? Memory backend: ▸ AgentDB
? Routing strategy: ▸ 3-tier

✔ Generated my-legal-bot/
✔ Smoke test passed

# Then your team:
cd my-legal-bot && npm publish
# → @your-org/my-legal-bot ships to npm with its own brand

Why WASM-centric

The kernel is Rust source → wasm32 + NAPI-RS, not TypeScript. Reasons:

• Cross-platform: same kernel runs on Node, browser, Cloudflare Workers, Deno, Bun, edge runtimes
• Byte-deterministic: wasm bytes are stable across CI runners, which is what makes the Ed25519 witness manifest actually verifiable
• Memory-safe: Rust borrow checker eliminates a class of kernel bugs
• Working precedent: @ruvector/emergent-time@0.1.0 (live on npm today, 55 KB wasm-opt'd) ships through exactly this pipeline. The kernel reuses the machinery.

NAPI-RS provides a native escape hatch for Node hot paths where wasm overhead matters. Per-platform .node binaries (@ruflo/kernel-darwin-arm64, -linux-x64-gnu, …) with runtime fallback to wasm.

Hosts the generated harness must run on

Host	Integration shape	Notes
Claude Code	MCP server + 5-handler-type hooks + 3-scope settings	Ruflo-native target
OpenAI Codex	MCP via ~/.codex/config.toml [mcp_servers.*] tables	TOML not JSON; no first-class hooks
pi.dev	Pi extension (TypeScript module)	No MCP by design — adapter uses pi.registerTool()
Hermes Agent	MCP-supported runtime (optional-mcps/)	Adapter scrubs <think> + stray <tool_call> text per issue #741

Design status

17 ADRs landed today (plain-language, SOTA-cited, test contracts) covering:

• Kernel boundary (Rust + WASM + NAPI-RS) — ADR-002 / ADR-002a
• Generator architecture (create-vite-style overlays + copier-style update) — ADR-003
• Host integration model — ADR-004
• Memory + learning (cites @ruvector/emergent-time@0.1.0, Mem0, ReasoningBank) — ADR-006
• CI guards, drift detection, anti-slop, witness/provenance — ADR-007/008/009/011
• TDD test contracts, eject + upgrade, vertical packs, federation, naming, migration — ADR-010/012/013/014/015/016

Full index: docs/adrs/INDEX.md.

Mirror branch in this repo: feat/harness-generator-adrs.

Phasing

Phase	Scope	Status
0. Kernel extraction	Factor @ruflo/kernel (Rust + wasm + napi) out of ruflo's TS source	Designed
1. Generator MVP	npx create-agent-harness, Claude Code only, smoke-tested output	Designed
2. Multi-host	Codex + pi.dev + Hermes adapters	Designed
3. Composer	Interactive picker, --from-existing eject mode	Designed
4. Marketplace publication	Generator ships as ruflo marketplace plugin; harnesses can publish their own	Designed
5. Self-evolving + federation	Learning loop applied to harness-level decisions	Designed
6. Vertical packs	Curated bundles (@ruflo/vertical-legal, etc.)	Designed

What I want from this issue

Tracking. Discussion. Critique of the design before any code lands.

The biggest decisions to push back on:

1. Kernel cut: how clean a boundary between primitives and content? The design says "no content in kernel," which is the bigger refactor but the right invariant.
2. WASM-centric: this commits us to Rust as the kernel's source language. Big call. The @ruvector/emergent-time@0.1.0 precedent makes me confident the pipeline works at small scale; at full-kernel scale it's a real bet.
3. Host adapter contract: the four hosts have wildly different surfaces. The adapter interface in ADR-004 is the design's most fragile point.
4. Marketplace anti-slop: the design rejects editorial review in favor of derived trust tiers from measured signals. SOTA from npm/HF/Socket.dev/VS Code Marketplace research is folded in but the actual signal weights need real-world calibration.

Related

• Gist (plain-language explainer): link will be added in a follow-up comment
• New repo: https://github.com/ruvnet/agent-harness-generator
• Branch: https://github.com/ruvnet/ruflo/tree/feat/harness-generator-adrs
• Working precedent for the WASM pipeline: https://www.npmjs.com/package/@ruvector/emergent-time

cc @ruvnet

[ruvnet]

Plain-language explainer gist (for sharing): https://gist.github.com/ruvnet/a5ab06c9d331ac6a7272510dd8777ce0