Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(metaharness): Phase 1 MVP plugin β€” 5 skills + ADR-150 constraint enforcement (iter 1)

ruva4c2755c8d52
diff --git a/plugins/ruflo-metaharness/.claude-plugin/plugin.json b/plugins/ruflo-metaharness/.claude-plugin/plugin.json
new file mode 100644
index 0000000000..e0f45cb015
--- /dev/null
+++ b/plugins/ruflo-metaharness/.claude-plugin/plugin.json
@@ -0,0 +1,32 @@
+{
+ "name": "ruflo-metaharness",
+ "description": "MetaHarness integration for ruflo β€” surfaces score/genome/mint/mcp-scan/threat-model via skills; pairs with @metaharness/router (ADR-148/149) for cost-optimal model routing; honors ADR-150's architectural constraint that MetaHarness remains an optional augmentation, never a required runtime dependency",
+ "version": "0.1.0",
+ "author": {
+ "name": "ruvnet",
+ "url": "https://github.com/ruvnet"
+ },
+ "homepage": "https://github.com/ruvnet/ruflo",
+ "license": "MIT",
+ "keywords": [
+ "ruflo",
+ "metaharness",
+ "harness",
+ "scaffolding",
+ "scorecard",
+ "genome",
+ "mcp-scan",
+ "threat-model",
+ "router",
+ "adr-150",
+ "adr-148",
+ "adr-149",
+ "optional-dependency",
+ "graceful-degradation",
+ "subprocess",
+ "namespace-routing",
+ "verified",
+ "ci",
+ "phase-1-mvp"
+ ]
+}
diff --git a/plugins/ruflo-metaharness/README.md b/plugins/ruflo-metaharness/README.md
new file mode 100644
index 0000000000..37e5894523
--- /dev/null
+++ b/plugins/ruflo-metaharness/README.md
@@ -0,0 +1,64 @@
+# ruflo-metaharness
+
+MetaHarness integration plugin for ruflo. Surfaces the upstream `metaharness` / `harness` CLIs through five ruflo skills, honoring [ADR-150](../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md)'s architectural constraint that MetaHarness must remain a removable augmentation β€” never a required runtime dependency.
+
+## ADR-150 architectural constraint (load-bearing)
+
+**Ruflo remains operational if every MetaHarness package is removed.** Every code path in this plugin satisfies four rules:
+
+1. **Removable** β€” no static `import '@metaharness/*'` outside the optional-router path in `v3/@claude-flow/cli/src/ruvector/neural-router.ts`.
+2. **Optional in package.json** β€” `metaharness` is in `optionalDependencies`, never `dependencies`.
+3. **Graceful degradation** β€” every script catches `MODULE_NOT_FOUND`/network failure and emits `{ degraded: true, reason: 'metaharness-not-available' }` JSON, exits 0. The graceful path is the default behavior, not a special case.
+4. **CI gate** β€” `no-metaharness-smoke.yml` runs the plugin smoke with `npm install --no-optional` and asserts the contract still passes.
+
+## Skills
+
+| Skill | Usage | Description |
+|-------|-------|-------------|
+| `harness-score` | `/harness-score [--path .] [--alert-on-fit-below 70]` | 5-dim readiness scorecard (harnessFit/compile/coverage/safety/memory + cost) |
+| `harness-genome` | `/harness-genome [--path .] [--alert-on-risk-above 0.5]` | 7-section categorical report (repo_type/topology/risk/mcp/test/publish) |
+| `harness-mcp-scan` | `/harness-mcp-scan [--path .] [--fail-on high]` | Static MCP security findings β€” pure-read, no dispatch |
+| `harness-threat-model` | `/harness-threat-model [--path .] [--fail-on high]` | Enterprise-grade threat model (clean/low/medium/high + findings) |
+| `harness-mint` | `/harness-mint --name <id> --template <id> [--confirm]` | Scaffold a custom harness; DRY-RUN by default; refuses project-root writes |
+
+## Phase-0 baseline (ruflo itself, 2026-06-16)
+
+```json
+{
+ "harnessFit": 82,
+ "compileConfidence": 100,
+ "taskCoverage": 79,
+ "toolSafety": 100,
+ "memoryUsefulness": 40,
+ "estCostPerRunUsd": 0.048,
+ "recommendedMode": "CLI + MCP",
+ "archetype": "typescript-sdk-harness",
+ "template": "vertical:coding",
+ "scaffoldReady": true,
+ "risk_score": 0.27,
+ "publish_readiness": 0.9
+}
+```
+
+## Architecture
+
+All skills use subprocess invocation through the `_harness.mjs` shared helper:
+
+```
+skills/X/SKILL.md β†’ scripts/X.mjs β†’ scripts/_harness.mjs β†’ spawnSync('npx', ['metaharness', …])
+ β†˜ on MODULE_NOT_FOUND β†’ emit degraded JSON, exit 0
+```
+
+This means:
+- No library import overhead on ruflo's boot path
+- 60s hard timeout per subprocess (bounded blast radius)
+- `--json` flag forced for structured parsing
+- Graceful degradation is a single helper used by every skill
+
+## Cross-links
+
+- [ADR-150](../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) β€” decision + architectural constraint
+- [Issue #2399](https://github.com/ruvnet/ruflo/issues/2399) β€” phase rollout tracker
+- [Research dossier](https://gist.github.com/ruvnet/19d166ff9acf368c9da4172d91ac9113) β€” full graded-evidence sourcing
+- [Upstream](https://github.com/ruvnet/agent-harness-generator) β€” `metaharness` source
+- ADR-148/149 β€” `@metaharness/router` cost-optimal routing (sibling integration)
diff --git a/plugins/ruflo-metaharness/agents/metaharness-architect.md b/plugins/ruflo-metaharness/agents/metaharness-architect.md
new file mode 100644
index 0000000000..8953120933
--- /dev/null
+++ b/plugins/ruflo-metaharness/agents/metaharness-architect.md
@@ -0,0 +1,57 @@
+---
+name: metaharness-architect
+description: MetaHarness integration architect for ruflo. Surfaces score/genome/mint/mcp-scan/threat-model upstream capabilities via skills; enforces ADR-150 architectural constraint (MetaHarness as removable augmentation, never required runtime dep); coordinates Phase 1 MVP rollout
+model: haiku
+---
+
+You are the metaharness-architect for ruflo. Your job is to expose the
+`@metaharness/*` ecosystem's capabilities through ruflo's UX while
+keeping ruflo independently operational at all times.
+
+## ADR-150 invariants (load-bearing)
+
+1. **Removable** β€” `npm ls --without-deps @metaharness/*` must still
+ produce a working CLI.
+2. **Optional in package.json** β€” every `@metaharness/*` package goes in
+ `optionalDependencies` or `peerDependencies` (optional), NEVER
+ `dependencies`.
+3. **Graceful degradation** β€” every code path that imports a
+ `@metaharness/*` symbol catches `MODULE_NOT_FOUND` and falls back.
+ The `emitDegradedJsonAndExit()` helper in `scripts/_harness.mjs` is
+ the reference implementation.
+4. **CI gate** β€” at least one CI job runs ruflo with no MetaHarness
+ packages installed and asserts smoke still passes.
+
+If a PR breaks any of these four rules, it is a breaking change and
+needs its own ADR.
+
+## Skills (5 β€” what each does, when to invoke)
+
+| Skill | Role | Invoke when |
+|---|---|---|
+| `harness-score` | 5-dim numeric scorecard | Pre-mint readiness check; CI regression gate |
+| `harness-genome` | 7-section categorical report | Pre-mint architecture review; drift detection over time |
+| `harness-mcp-scan` | Static MCP security findings | Every PR; enterprise security review |
+| `harness-threat-model` | Categorized threat report | Pre-launch review; periodic OIA-audit cadence |
+| `harness-mint` | Scaffold a custom harness | User wants to fork; ALWAYS dry-run first, never write to project root |
+
+## Tools (subprocess-only, no library imports)
+
+- All skills shell out to `npx metaharness ...` or `npx -p metaharness@latest harness ...` via the `_harness.mjs` shared helper.
+- 60s hard timeout per subprocess.
+- Output captured + parsed; `--json` flag forced unless the script opts out.
+- No `@metaharness/*` import statement appears outside the optional-router path in `v3/@claude-flow/cli/src/ruvector/neural-router.ts`.
+
+## Phase tracker
+
+- βœ… Phase 0 β€” measurement spike (ruflo's own scorecard captured 2026-06-16: harnessFit 82, risk_score 0.27, publish_readiness 0.9)
+- πŸ”„ Phase 1 β€” MVP plugin (this commit + CI gates + KRR retraining)
+- ⏳ Phase 2 β€” Expansion (eject command, SelfEvolvingRouter parallel-log, harness registry, oia-audit worker)
+- ⏳ Phase 3 β€” Harness Intelligence Layer (each item gets its own ADR)
+
+## Cross-links
+
+- [ADR-150](../../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) β€” decision
+- [Issue #2399](https://github.com/ruvnet/ruflo/issues/2399) β€” phase tracker
+- [Research dossier](https://gist.github.com/ruvnet/19d166ff9acf368c9da4172d91ac9113) β€” graded evidence
+- [Upstream](https://github.com/ruvnet/agent-harness-generator) β€” `metaharness` source
diff --git a/plugins/ruflo-metaharness/commands/ruflo-metaharness.md b/plugins/ruflo-metaharness/commands/ruflo-metaharness.md
new file mode 100644
index 0000000000..39c34ff54e
--- /dev/null
+++ b/plugins/ruflo-metaharness/commands/ruflo-metaharness.md
@@ -0,0 +1,39 @@
+---
+name: ruflo-metaharness
+description: MetaHarness integration β€” score, genome, mint, mcp-scan, threat-model β€” via subprocess invocations honoring ADR-150 architectural constraint
+---
+
+MetaHarness integration commands. All shell out to `npx metaharness ...`
+or `npx -p metaharness@latest harness ...` via the `_harness.mjs`
+shared helper; no library imports on ruflo's boot path.
+
+**`harness score [--path .] [--alert-on-fit-below N] [--format table|json]`** -- 5-dimension readiness scorecard (harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady).
+1. Run `node plugins/ruflo-metaharness/scripts/score.mjs --path <dir>`
+2. Output JSON (default) with all dimensions + recommended template + archetype
+3. `--alert-on-fit-below N` exits 1 when harnessFit < N β€” CI regression gate
+4. Subprocess + 60s hard timeout; graceful degradation when metaharness unavailable
+
+**`harness genome [--path .] [--alert-on-risk-above 0.5] [--format table|json]`** -- 7-section repo readiness report (repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness).
+1. Run `node plugins/ruflo-metaharness/scripts/genome.mjs --path <dir>`
+2. Pairs with harness-score for full readiness view β€” score is numeric, genome is categorical
+3. `--alert-on-risk-above N` exits 1 when risk_score > N
+4. Useful for drift detection: snapshot genome over time, diff to spot agent_topology drift
+
+**`harness mcp-scan [--path .] [--fail-on low|medium|high] [--format table|json]`** -- Static security scan of `.mcp/servers.json` + `.harness/claims.json`. Reads only; no dispatch.
+1. Run `node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --path <dir>`
+2. Severity-ranked findings (low/medium/high); default fail-on `high`
+3. CI integration: `mcp-scan --fail-on high` fails the build on any HIGH finding
+4. Pairs with harness-threat-model for enterprise-review-grade categorization
+
+**`harness threat-model [--path .] [--fail-on clean|low|medium|high] [--format table|json]`** -- Enterprise-review threat model. Returns `worst` severity + categorized `findings[]`.
+1. Run `node plugins/ruflo-metaharness/scripts/threat-model.mjs --path <dir>`
+2. Default fail-on `high`; tightenable to `medium` for stricter gates
+3. Output suitable for sharing with security/infosec team
+4. Will be auto-fired by the Phase-2 oia-audit background worker on a schedule
+
+**`harness mint --name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]`** -- Scaffold a custom AI agent harness. DRY-RUN by default; --confirm required to write.
+1. Run `node plugins/ruflo-metaharness/scripts/mint.mjs --name <id> --template <id> --host <id>`
+2. **Safety**: refuses to write to the calling repo root or any path inside it; defaults to `/tmp/ruflo-mint-<ts>-<name>/`
+3. Without `--confirm`: prints dry-run plan, exits 0 without touching disk
+4. With `--confirm`: shells `npx metaharness new ... --yes`
+5. Templates: minimal + 19 verticals (coding, devops, support, legal, …). Hosts: claude-code, codex, pi-dev, opencode, github-actions, +4 more.
diff --git a/plugins/ruflo-metaharness/scripts/_harness.mjs b/plugins/ruflo-metaharness/scripts/_harness.mjs
new file mode 100755
index 0000000000..38abcfac00
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/_harness.mjs
@@ -0,0 +1,109 @@
+// _harness.mjs β€” shared invocation helper for the metaharness/harness CLIs.
+//
+// All ruflo-metaharness skills shell out to the upstream CLI rather than
+// linking the library β€” this honors ADR-150's architectural constraint
+// (MetaHarness must remain a removable augmentation, never a required
+// runtime dep) while still giving us "deep integration" through a single
+// vetted bridge that every skill imports from.
+//
+// CONTRACT
+// - `runMetaharness(args, opts)` β€” invoke `npx metaharness <args>`
+// - `runHarness(args, opts)` β€” invoke `npx -p metaharness harness <args>`
+// - both return `{ stdout, stderr, exitCode, json|null, durationMs }`
+// - `--json` flag is appended automatically when `opts.json !== false`
+// - subprocess hard timeout (default 60s) β€” captured in opts.timeoutMs
+// - on MODULE_NOT_FOUND or "not installed", returns degraded result with
+// `degraded: true, reason: 'metaharness-not-available'` β€” never throws
+// (ADR-150 graceful-degradation rule #3)
+
+import { spawnSync } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+function execCli(bin, args, opts = {}) {
+ const start = Date.now();
+ const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+ const wantJson = opts.json !== false;
+ const argv = wantJson && !args.includes('--json') ? [...args, '--json'] : [...args];
+ const r = spawnSync('npx', [bin, ...argv], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ encoding: 'utf-8',
+ timeout: timeoutMs,
+ shell: process.platform === 'win32',
+ });
+ const durationMs = Date.now() - start;
+ const stdout = r.stdout || '';
+ const stderr = r.stderr || '';
+ // Graceful degradation β€” npx couldn't find the binary.
+ if (r.status === null || /could not determine executable|404|not installed|MODULE_NOT_FOUND/i.test(stderr)) {
+ return {
+ stdout, stderr,
+ exitCode: r.status ?? 127,
+ json: null,
+ durationMs,
+ degraded: true,
+ reason: 'metaharness-not-available',
+ };
+ }
+ let json = null;
+ if (wantJson) {
+ const m = /\{[\s\S]*\}/.exec(stdout);
+ if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+ }
+ return { stdout, stderr, exitCode: r.status ?? 0, json, durationMs, degraded: false };
+}
+
+export function runMetaharness(args, opts) {
+ return execCli('-y metaharness@latest', args, opts);
+}
+
+export function runHarness(args, opts) {
+ // The `harness` binary ships inside the `metaharness` package, so we
+ // need `npx -p metaharness@latest harness <args>`. spawnSync receives
+ // a single argv array, so encode the `-p` flag as its own argument.
+ const start = Date.now();
+ const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+ const wantJson = opts?.json !== false;
+ const argv = wantJson && !args.includes('--json') ? [...args, '--json'] : [...args];
+ const r = spawnSync('npx', ['-y', '-p', 'metaharness@latest', 'harness', ...argv], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ encoding: 'utf-8',
+ timeout: timeoutMs,
+ shell: process.platform === 'win32',
+ });
+ const durationMs = Date.now() - start;
+ const stdout = r.stdout || '';
+ const stderr = r.stderr || '';
+ if (r.status === null || /could not determine executable|404|not installed|MODULE_NOT_FOUND/i.test(stderr)) {
+ return {
+ stdout, stderr,
+ exitCode: r.status ?? 127,
+ json: null,
+ durationMs,
+ degraded: true,
+ reason: 'metaharness-not-available',
+ };
+ }
+ let json = null;
+ if (wantJson) {
+ const m = /\{[\s\S]*\}/.exec(stdout);
+ if (m) { try { json = JSON.parse(m[0]); } catch { /* leave null */ } }
+ }
+ return { stdout, stderr, exitCode: r.status ?? 0, json, durationMs, degraded: false };
+}
+
+// Convenience emitters for skill scripts β€” keep the boilerplate out of
+// each skill so they focus on argument parsing + exit-code semantics.
+export function emitDegradedJsonAndExit(reason) {
+ const payload = {
+ degraded: true,
+ reason,
+ hint: 'Install metaharness manually with `npm i -D metaharness` or run `npx metaharness@latest --version` to verify network access.',
+ generatedAt: new Date().toISOString(),
+ };
+ console.log(JSON.stringify(payload, null, 2));
+ // Exit 0 β€” ADR-150 architectural constraint says ruflo continues to
+ // function when MetaHarness is absent. Skills emit a structured
+ // degraded payload rather than failing.
+ process.exit(0);
+}
diff --git a/plugins/ruflo-metaharness/scripts/genome.mjs b/plugins/ruflo-metaharness/scripts/genome.mjs
new file mode 100755
index 0000000000..4e3b54147c
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/genome.mjs
@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// genome.mjs β€” wrapper around `metaharness genome <path>`.
+//
+// Returns the 7-section readiness report: repo_type / agent_topology /
+// risk_score / mcp_surface / test_confidence / publish_readiness +
+// verdict (ready | needs-work | blocked). Reads-only.
+//
+// USAGE
+// node scripts/genome.mjs
+// node scripts/genome.mjs --path <dir> --alert-on-risk-above 0.5 --format json
+//
+// EXIT CODES
+// 0 OK
+// 1 --alert-on-risk-above threshold breached
+// 2 config error or genome failure
+
+import { runMetaharness, emitDegradedJsonAndExit } from './_harness.mjs';
+
+const ARGS = (() => {
+ const a = { path: '.', format: 'json', alertRiskAbove: null };
+ for (let i = 2; i < process.argv.length; i++) {
+ const v = process.argv[i];
+ if (v === '--path') a.path = process.argv[++i];
+ else if (v === '--alert-on-risk-above') a.alertRiskAbove = parseFloat(process.argv[++i]);
+ else if (v === '--format') a.format = process.argv[++i];
+ }
+ return a;
+})();
+
+function main() {
+ const r = runMetaharness(['genome', ARGS.path]);
+ if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+ if (r.exitCode !== 0 || !r.json) {
+ console.error(`genome: metaharness exited ${r.exitCode}`);
+ if (r.stderr) console.error(r.stderr.slice(0, 400));
+ process.exit(2);
+ }
+ const payload = { ...r.json, path: ARGS.path, durationMs: r.durationMs };
+
+ if (ARGS.alertRiskAbove !== null) {
+ if (!isFinite(ARGS.alertRiskAbove)) {
+ console.error(`genome: --alert-on-risk-above must be a finite number`);
+ process.exit(2);
+ }
+ payload.alert = {
+ threshold: ARGS.alertRiskAbove,
+ triggered: typeof payload.risk_score === 'number' && payload.risk_score > ARGS.alertRiskAbove,
+ reason: typeof payload.risk_score === 'number' && payload.risk_score > ARGS.alertRiskAbove
+ ? `risk_score ${payload.risk_score} > ${ARGS.alertRiskAbove}`
+ : `risk_score ${payload.risk_score ?? 'unknown'} ≀ ${ARGS.alertRiskAbove} β€” OK`,
+ };
+ }
+
+ if (ARGS.format === 'json') {
+ console.log(JSON.stringify(payload, null, 2));
+ } else {
+ console.log(`# harness-genome β€” ${ARGS.path}`);
+ console.log('');
+ console.log(`| Section | Value |`);
+ console.log(`|---|---|`);
+ console.log(`| repo_type | ${payload.repo_type ?? 'β€”'} |`);
+ console.log(`| agent_topology | ${(payload.agent_topology || []).join(', ') || 'β€”'} |`);
+ console.log(`| risk_score | ${payload.risk_score ?? 'β€”'} |`);
+ console.log(`| mcp_surface | ${payload.mcp_surface ?? 'β€”'} |`);
+ console.log(`| test_confidence | ${payload.test_confidence ?? 'β€”'} |`);
+ console.log(`| publish_readiness | ${payload.publish_readiness ?? 'β€”'} |`);
+ console.log(`| **duration** | ${payload.durationMs}ms |`);
+ console.log('');
+ if (payload.alert) {
+ console.log(payload.alert.triggered ? `⚠ **ALERT**: ${payload.alert.reason}` : `βœ“ ${payload.alert.reason}`);
+ console.log('');
+ }
+ }
+
+ if (payload.alert?.triggered) process.exit(1);
+}
+
+main();
diff --git a/plugins/ruflo-metaharness/scripts/mcp-scan.mjs b/plugins/ruflo-metaharness/scripts/mcp-scan.mjs
new file mode 100755
index 0000000000..2df9985c8d
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/mcp-scan.mjs
@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// mcp-scan.mjs β€” wrapper around `harness mcp-scan <path>`.
+//
+// Static security scan of the harness's declared MCP surface. Reads
+// .mcp/servers.json + .harness/claims.json. Pure-read, no dispatch.
+//
+// USAGE
+// node scripts/mcp-scan.mjs # current dir
+// node scripts/mcp-scan.mjs --path <dir>
+// node scripts/mcp-scan.mjs --fail-on high # exit 1 if any HIGH finding (default)
+// node scripts/mcp-scan.mjs --fail-on medium # also fail on MEDIUM
+// node scripts/mcp-scan.mjs --format json
+//
+// EXIT CODES
+// 0 no findings at or above --fail-on (or degraded)
+// 1 at least one finding β‰₯ --fail-on severity
+// 2 config error or scan failure
+
+import { runHarness, emitDegradedJsonAndExit } from './_harness.mjs';
+
+const SEVERITY_RANK = { low: 1, medium: 2, high: 3 };
+
+const ARGS = (() => {
+ const a = { path: '.', format: 'json', failOn: 'high' };
+ for (let i = 2; i < process.argv.length; i++) {
+ const v = process.argv[i];
+ if (v === '--path') a.path = process.argv[++i];
+ else if (v === '--fail-on') a.failOn = String(process.argv[++i] || 'high').toLowerCase();
+ else if (v === '--format') a.format = process.argv[++i];
+ }
+ return a;
+})();
+
+function main() {
+ if (!SEVERITY_RANK[ARGS.failOn]) {
+ console.error(`mcp-scan: --fail-on must be one of low|medium|high; got ${ARGS.failOn}`);
+ process.exit(2);
+ }
+ const r = runHarness(['mcp-scan', ARGS.path]);
+ if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+ if (r.exitCode !== 0 && r.exitCode !== 1) {
+ // exit 1 from harness can be "findings present"; only treat other
+ // non-zero as a real failure.
+ console.error(`mcp-scan: harness exited ${r.exitCode}`);
+ if (r.stderr) console.error(r.stderr.slice(0, 400));
+ process.exit(2);
+ }
+ // The JSON output shape from `harness mcp-scan` includes findings[].
+ const payload = r.json ?? { rawStdout: r.stdout.slice(0, 400) };
+ const findings = Array.isArray(payload?.findings) ? payload.findings : [];
+ const threshold = SEVERITY_RANK[ARGS.failOn];
+ const offending = findings.filter((f) => SEVERITY_RANK[String(f.severity || 'low').toLowerCase()] >= threshold);
+
+ const alert = {
+ threshold: ARGS.failOn,
+ triggered: offending.length > 0,
+ offendingCount: offending.length,
+ reason: offending.length > 0
+ ? `${offending.length} finding(s) at or above ${ARGS.failOn} severity`
+ : `no findings at or above ${ARGS.failOn} severity β€” OK`,
+ };
+
+ if (ARGS.format === 'json') {
+ console.log(JSON.stringify({ ...payload, durationMs: r.durationMs, alert }, null, 2));
+ } else {
+ console.log(`# harness mcp-scan β€” ${ARGS.path}`);
+ console.log('');
+ console.log(`Total findings: ${findings.length}`);
+ console.log(`| Severity | ID | Server | Tool | Message |`);
+ console.log(`|---|---|---|---|---|`);
+ for (const f of findings.slice(0, 50)) {
+ console.log(`| ${f.severity} | ${f.id ?? 'β€”'} | ${f.server ?? 'β€”'} | ${f.tool ?? 'β€”'} | ${f.message ?? ''} |`);
+ }
+ console.log('');
+ console.log(alert.triggered ? `⚠ **ALERT**: ${alert.reason}` : `βœ“ ${alert.reason}`);
+ }
+
+ if (alert.triggered) process.exit(1);
+}
+
+main();
diff --git a/plugins/ruflo-metaharness/scripts/mint.mjs b/plugins/ruflo-metaharness/scripts/mint.mjs
new file mode 100755
index 0000000000..4843791e6d
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/mint.mjs
@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// mint.mjs β€” wrapper around `metaharness new <name> --template <id> --host <id>`.
+//
+// SAFETY (ADR-150 architectural constraint + "executing actions with care"):
+// - Target directory MUST be explicitly specified via --target. Defaults to
+// a temp dir under /tmp/ruflo-mint-<timestamp>/ if not given β€” never the
+// project root (ruflo behavioral rule "never save to root folder").
+// - --confirm flag required. Without it the script prints a dry-run plan
+// and exits 0 without writing files. This honors the "destructive-action
+// confirmation" pattern in ruflo's CLAUDE.md.
+//
+// USAGE
+// node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
+// # β†’ prints dry-run plan, exits 0
+// node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code --target /tmp/foo --confirm
+// # β†’ actually scaffolds
+
+import { runMetaharness, emitDegradedJsonAndExit } from './_harness.mjs';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const ARGS = (() => {
+ const a = { name: null, template: null, host: 'claude-code', target: null, confirm: false, format: 'json' };
+ for (let i = 2; i < process.argv.length; i++) {
+ const v = process.argv[i];
+ if (v === '--name') a.name = process.argv[++i];
+ else if (v === '--template') a.template = process.argv[++i];
+ else if (v === '--host') a.host = process.argv[++i];
+ else if (v === '--target') a.target = process.argv[++i];
+ else if (v === '--confirm') a.confirm = true;
+ else if (v === '--format') a.format = process.argv[++i];
+ }
+ return a;
+})();
+
+function safetyChecks() {
+ if (!ARGS.name) {
+ console.error('mint: --name is required');
+ process.exit(2);
+ }
+ if (!ARGS.template) {
+ console.error('mint: --template is required (e.g. vertical:coding, minimal)');
+ process.exit(2);
+ }
+ if (!ARGS.target) {
+ ARGS.target = resolve(tmpdir(), `ruflo-mint-${Date.now()}-${ARGS.name}`);
+ }
+ const targetAbs = resolve(ARGS.target);
+ const repoRoot = resolve(process.cwd());
+ if (targetAbs === repoRoot) {
+ console.error(`mint: refusing to write to project root (${repoRoot}). Specify a different --target.`);
+ process.exit(2);
+ }
+ if (targetAbs.startsWith(repoRoot + '/')) {
+ console.error(`mint: refusing to write inside the calling repo root. Use a --target outside ${repoRoot}.`);
+ process.exit(2);
+ }
+}
+
+function main() {
+ safetyChecks();
+ const plan = {
+ action: 'metaharness new',
+ name: ARGS.name,
+ template: ARGS.template,
+ host: ARGS.host,
+ target: ARGS.target,
+ confirm: ARGS.confirm,
+ willWrite: ARGS.confirm,
+ };
+ if (!ARGS.confirm) {
+ if (ARGS.format === 'json') console.log(JSON.stringify({ ...plan, dryRun: true }, null, 2));
+ else {
+ console.log(`# harness-mint (dry-run)`);
+ console.log('');
+ for (const [k, v] of Object.entries(plan)) console.log(`- ${k}: ${v}`);
+ console.log('');
+ console.log('Re-run with `--confirm` to actually scaffold.');
+ }
+ process.exit(0);
+ }
+ if (existsSync(ARGS.target)) {
+ console.error(`mint: target ${ARGS.target} already exists`);
+ process.exit(2);
+ }
+ const r = runMetaharness(['new', ARGS.name, '--template', ARGS.template, '--host', ARGS.host, '--target', ARGS.target, '--yes'], { json: false });
+ if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+ if (r.exitCode !== 0) {
+ console.error(`mint: metaharness exited ${r.exitCode}`);
+ if (r.stderr) console.error(r.stderr.slice(0, 400));
+ process.exit(2);
+ }
+ const result = { ...plan, exitCode: r.exitCode, durationMs: r.durationMs, ok: true };
+ if (ARGS.format === 'json') console.log(JSON.stringify(result, null, 2));
+ else {
+ console.log(`# harness-mint β€” done`);
+ console.log('');
+ for (const [k, v] of Object.entries(result)) console.log(`- ${k}: ${v}`);
+ }
+}
+
+main();
diff --git a/plugins/ruflo-metaharness/scripts/score.mjs b/plugins/ruflo-metaharness/scripts/score.mjs
new file mode 100755
index 0000000000..e2d31aa3c8
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/score.mjs
@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// score.mjs β€” `cost-style` wrapper around `metaharness score <path>`.
+//
+// Returns the 5-dimension scorecard (harnessFit / compileConfidence /
+// taskCoverage / toolSafety / memoryUsefulness) + estCostPerRunUsd +
+// scaffoldReady boolean. Reads-only; no side effects.
+//
+// USAGE
+// node scripts/score.mjs # current dir
+// node scripts/score.mjs --path <dir> # specific dir
+// node scripts/score.mjs --alert-on-fit-below 70 # exit 1 if harnessFit < 70
+// node scripts/score.mjs --format json
+//
+// EXIT CODES
+// 0 scored OK (or degraded β€” MetaHarness not available)
+// 1 --alert-on-fit-below threshold breached
+// 2 config error or scoring failure
+
+import { runMetaharness, emitDegradedJsonAndExit } from './_harness.mjs';
+
+const ARGS = (() => {
+ const a = { path: '.', format: 'json', alertFitBelow: null };
+ for (let i = 2; i < process.argv.length; i++) {
+ const v = process.argv[i];
+ if (v === '--path') a.path = process.argv[++i];
+ else if (v === '--alert-on-fit-below') a.alertFitBelow = parseFloat(process.argv[++i]);
+ else if (v === '--format') a.format = process.argv[++i];
+ }
+ return a;
+})();
+
+function main() {
+ const r = runMetaharness(['score', ARGS.path]);
+ if (r.degraded) {
+ emitDegradedJsonAndExit(r.reason);
+ return;
+ }
+ if (r.exitCode !== 0 || !r.json) {
+ console.error(`score: metaharness exited ${r.exitCode}`);
+ if (r.stderr) console.error(r.stderr.slice(0, 400));
+ process.exit(2);
+ }
+ const payload = { ...r.json, durationMs: r.durationMs };
+
+ if (ARGS.alertFitBelow !== null) {
+ if (!isFinite(ARGS.alertFitBelow)) {
+ console.error(`score: --alert-on-fit-below must be a finite number`);
+ process.exit(2);
+ }
+ payload.alert = {
+ threshold: ARGS.alertFitBelow,
+ triggered: typeof payload.harnessFit === 'number' && payload.harnessFit < ARGS.alertFitBelow,
+ reason: typeof payload.harnessFit === 'number' && payload.harnessFit < ARGS.alertFitBelow
+ ? `harnessFit ${payload.harnessFit} < ${ARGS.alertFitBelow}`
+ : `harnessFit ${payload.harnessFit ?? 'unknown'} β‰₯ ${ARGS.alertFitBelow} β€” OK`,
+ };
+ }
+
+ if (ARGS.format === 'json') {
+ console.log(JSON.stringify(payload, null, 2));
+ } else {
+ console.log(`# harness-score β€” ${payload.repo || ARGS.path}`);
+ console.log('');
+ console.log(`| Dimension | Value |`);
+ console.log(`|---|---:|`);
+ console.log(`| harnessFit | ${payload.harnessFit ?? 'β€”'} |`);
+ console.log(`| compileConfidence | ${payload.compileConfidence ?? 'β€”'} |`);
+ console.log(`| taskCoverage | ${payload.taskCoverage ?? 'β€”'} |`);
+ console.log(`| toolSafety | ${payload.toolSafety ?? 'β€”'} |`);
+ console.log(`| memoryUsefulness | ${payload.memoryUsefulness ?? 'β€”'} |`);
+ console.log(`| estCostPerRunUsd | $${payload.estCostPerRunUsd ?? 'β€”'} |`);
+ console.log(`| recommendedMode | ${payload.recommendedMode ?? 'β€”'} |`);
+ console.log(`| archetype | ${payload.archetype ?? 'β€”'} |`);
+ console.log(`| template | ${payload.template ?? 'β€”'} |`);
+ console.log(`| scaffoldReady | ${payload.scaffoldReady ?? 'β€”'} |`);
+ console.log(`| hardConstraints | ${payload.hardConstraints ?? 'β€”'} |`);
+ console.log(`| **duration** | ${payload.durationMs}ms |`);
+ console.log('');
+ if (payload.alert) {
+ if (payload.alert.triggered) {
+ console.log(`⚠ **ALERT**: ${payload.alert.reason}`);
+ } else {
+ console.log(`βœ“ ${payload.alert.reason}`);
+ }
+ console.log('');
+ }
+ }
+
+ if (payload.alert?.triggered) process.exit(1);
+}
+
+main();
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.sh
new file mode 100755
index 0000000000..80278bae44
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/smoke.sh
@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-metaharness v0.1.0 (ADR-150 Phase 1).
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+step() { printf "β†’ %s ... " "$1"; }
+ok() { printf "PASS\n"; PASS=$((PASS+1)); }
+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+step "1. plugin.json declares 0.1.0 with adr-150 keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.1.0" ]]; then
+ bad "expected 0.1.0, got '$v'"
+else
+ miss=""
+ for k in ruflo metaharness harness scorecard genome mcp-scan threat-model router adr-150 adr-148 adr-149 optional-dependency graceful-degradation subprocess phase-1-mvp; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all five skills present with valid frontmatter"
+miss=""
+for s in harness-score harness-genome harness-mint harness-mcp-scan harness-threat-model; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:' 'allowed-tools:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. _harness.mjs shared loader has the safe-shellout pattern"
+F="$ROOT/scripts/_harness.mjs"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "spawnSync" "$F" || miss="$miss no-spawnSync"
+grep -q "runMetaharness" "$F" || miss="$miss no-meta-runner"
+grep -q "runHarness" "$F" || miss="$miss no-harness-runner"
+grep -q "emitDegradedJsonAndExit" "$F" || miss="$miss no-degraded-helper"
+grep -q "metaharness-not-available" "$F" || miss="$miss no-degraded-reason"
+# ADR-150 architectural constraint #3: graceful degradation must be present
+grep -q "degraded: true" "$F" || miss="$miss no-degraded-flag"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. score.mjs harness present + parses + uses _harness.mjs + alert"
+F="$ROOT/scripts/score.mjs"
+miss=""
+[[ -x "$F" ]] || miss="$miss not-executable"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "runMetaharness" "$F" || miss="$miss no-runner"
+grep -q "alert-on-fit-below" "$F" || miss="$miss no-alert-flag"
+grep -q "harnessFit" "$F" || miss="$miss no-fit-field"
+grep -q "process.exit(1)" "$F" || miss="$miss no-fail-closed"
+grep -q "process.exit(2)" "$F" || miss="$miss no-config-exit"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "5. genome.mjs present + parses + uses _harness.mjs + alert"
+F="$ROOT/scripts/genome.mjs"
+miss=""
+[[ -x "$F" ]] || miss="$miss not-executable"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "runMetaharness" "$F" || miss="$miss no-runner"
+grep -q "alert-on-risk-above" "$F" || miss="$miss no-alert-flag"
+grep -q "risk_score" "$F" || miss="$miss no-risk-field"
+grep -q "process.exit(1)" "$F" || miss="$miss no-fail-closed"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "6. mcp-scan.mjs present + parses + severity-ranked"
+F="$ROOT/scripts/mcp-scan.mjs"
+miss=""
+[[ -x "$F" ]] || miss="$miss not-executable"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "runHarness" "$F" || miss="$miss no-runner"
+grep -q "SEVERITY_RANK" "$F" || miss="$miss no-severity"
+grep -q "fail-on" "$F" || miss="$miss no-fail-on-flag"
+grep -q "process.exit(1)" "$F" || miss="$miss no-fail-closed"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "7. threat-model.mjs present + parses + severity-ranked"
+F="$ROOT/scripts/threat-model.mjs"
+miss=""
+[[ -x "$F" ]] || miss="$miss not-executable"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "runHarness" "$F" || miss="$miss no-runner"
+grep -q "SEVERITY_RANK" "$F" || miss="$miss no-severity"
+grep -q "fail-on" "$F" || miss="$miss no-fail-on-flag"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "8. mint.mjs dry-run by default + project-root refusal"
+F="$ROOT/scripts/mint.mjs"
+miss=""
+[[ -x "$F" ]] || miss="$miss not-executable"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "runMetaharness" "$F" || miss="$miss no-runner"
+grep -q "confirm" "$F" || miss="$miss no-confirm-flag"
+grep -q "refusing to write to project root" "$F" || miss="$miss no-root-refusal"
+grep -q "dryRun" "$F" || miss="$miss no-dryrun-output"
+grep -q "process.exit(2)" "$F" || miss="$miss no-config-exit"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "9. command file documents all five skills"
+F="$ROOT/commands/ruflo-metaharness.md"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing-file"
+for s in score genome mint mcp-scan threat-model; do
+ grep -q "harness $s\\|metaharness-$s" "$F" 2>/dev/null || miss="$miss missing-$s"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "10. agent file documents the metaharness role"
+F="$ROOT/agents/metaharness-architect.md"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing-file"
+grep -q "^name:" "$F" || miss="$miss no-name"
+grep -q "^description:" "$F" || miss="$miss no-description"
+grep -q "model:" "$F" || miss="$miss no-model"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "11. no SKILL.md grants wildcard tool access (security)"
+bad_skills=""
+for f in "$ROOT"/skills/*/SKILL.md; do
+ grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
+done
+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+
+step "12. README documents ADR-150 architectural constraint"
+F="$ROOT/README.md"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing-file"
+grep -q "ADR-150" "$F" || miss="$miss no-adr-ref"
+grep -qE "architectural constraint|never (a )?required" "$F" || miss="$miss no-constraint"
+grep -q "graceful" "$F" || miss="$miss no-graceful-degradation-doc"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "13. every script in scripts/*.mjs parses cleanly"
+miss=""
+for f in "$ROOT"/scripts/*.mjs; do
+ node --check "$f" 2>/dev/null || miss="$miss $(basename "$f")"
+done
+[[ -z "$miss" ]] && ok || bad "syntax errors:$miss"
+
+step "14. plugin.json parses as valid JSON + version sentinel matches step 1"
+node -e "JSON.parse(require('fs').readFileSync('$ROOT/.claude-plugin/plugin.json'))" 2>/dev/null \
+ && ok || bad "plugin.json invalid JSON"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-metaharness/scripts/threat-model.mjs b/plugins/ruflo-metaharness/scripts/threat-model.mjs
new file mode 100755
index 0000000000..988bdfcbfd
--- /dev/null
+++ b/plugins/ruflo-metaharness/scripts/threat-model.mjs
@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// threat-model.mjs β€” wrapper around `harness threat-model <path>`.
+//
+// USAGE
+// node scripts/threat-model.mjs --path . --fail-on high --format json
+
+import { runHarness, emitDegradedJsonAndExit } from './_harness.mjs';
+
+const SEVERITY_RANK = { clean: 0, low: 1, medium: 2, high: 3 };
+
+const ARGS = (() => {
+ const a = { path: '.', format: 'json', failOn: 'high' };
+ for (let i = 2; i < process.argv.length; i++) {
+ const v = process.argv[i];
+ if (v === '--path') a.path = process.argv[++i];
+ else if (v === '--fail-on') a.failOn = String(process.argv[++i] || 'high').toLowerCase();
+ else if (v === '--format') a.format = process.argv[++i];
+ }
+ return a;
+})();
+
+function main() {
+ if (!SEVERITY_RANK.hasOwnProperty(ARGS.failOn)) {
+ console.error(`threat-model: --fail-on must be one of clean|low|medium|high`);
+ process.exit(2);
+ }
+ const r = runHarness(['threat-model', ARGS.path]);
+ if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
+ if (r.exitCode !== 0 && r.exitCode !== 1) {
+ console.error(`threat-model: harness exited ${r.exitCode}`);
+ if (r.stderr) console.error(r.stderr.slice(0, 400));
+ process.exit(2);
+ }
+ const payload = r.json ?? { rawStdout: r.stdout.slice(0, 400) };
+ const worst = String(payload?.worst || 'clean').toLowerCase();
+ const threshold = SEVERITY_RANK[ARGS.failOn];
+ const triggered = SEVERITY_RANK[worst] >= threshold && threshold > 0;
+ const alert = {
+ threshold: ARGS.failOn, worst, triggered,
+ reason: triggered
+ ? `worst=${worst} at or above ${ARGS.failOn}`
+ : `worst=${worst} below ${ARGS.failOn} β€” OK`,
+ };
+
+ if (ARGS.format === 'json') {
+ console.log(JSON.stringify({ ...payload, durationMs: r.durationMs, alert }, null, 2));
+ } else {
+ console.log(`# harness threat-model β€” ${ARGS.path}`);
+ console.log('');
+ console.log(`Worst severity: ${worst}`);
+ console.log(`Findings: ${(payload?.findings || []).length}`);
+ console.log('');
+ console.log(alert.triggered ? `⚠ **ALERT**: ${alert.reason}` : `βœ“ ${alert.reason}`);
+ }
+
+ if (alert.triggered) process.exit(1);
+}
+
+main();
diff --git a/plugins/ruflo-metaharness/skills/harness-genome/SKILL.md b/plugins/ruflo-metaharness/skills/harness-genome/SKILL.md
new file mode 100644
index 0000000000..cc7eb0c00a
--- /dev/null
+++ b/plugins/ruflo-metaharness/skills/harness-genome/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: harness-genome
+description: 7-section repo readiness report from `metaharness genome <path>`. Returns repo_type / agent_topology / risk_score / mcp_surface / test_confidence / publish_readiness. Pure-read; degrades gracefully (ADR-150).
+argument-hint: "[--path .] [--alert-on-risk-above 0.5] [--format table|json]"
+allowed-tools: Bash
+---
+
+Companion to `harness-score`. Where score is a 5-dimension numeric
+scorecard, genome is a 7-section categorical/numeric report covering
+repo type, agent topology recommendations, risk score (0-1), MCP
+surface area, test confidence (0-1), and publish readiness (0-1).
+
+## Algorithm
+
+Implementation: [`scripts/genome.mjs`](../../scripts/genome.mjs).
+
+1. Shell out to `npx metaharness genome <path> --json` (60s hard timeout).
+2. Parse the shape: `{ repo_type, agent_topology[], risk_score,
+ mcp_surface, test_confidence, publish_readiness }`.
+3. If `--alert-on-risk-above N`: exit 1 when `risk_score > N`.
+4. Output JSON (default) or markdown.
+
+## Phase-0 baseline (ruflo, measured 2026-06-16)
+
+```
+{
+ "repo_type": "node_mcp_ci",
+ "agent_topology": ["maintainer", "tester", "security", "release"],
+ "risk_score": 0.27,
+ "mcp_surface": "remote",
+ "test_confidence": 0.8,
+ "publish_readiness": 0.9
+}
+```
+
+Ruflo's `risk_score: 0.27` is low (good). `publish_readiness: 0.9` is
+high. The `mcp_surface: "remote"` reflects that ruflo's MCP servers are
+hosted, not bundled.
+
+## When to use
+
+- Pre-mint review: "before scaffolding a custom harness from this repo,
+ should we?" β€” genome answers it categorically.
+- Drift detection: capture genome snapshots over time, diff via
+ cost-diff-style tooling to spot when `agent_topology` recommendations
+ drift away from a deliberate architecture choice.
+- CI gate: `--alert-on-risk-above 0.5` fails the build when the repo's
+ risk profile crosses a threshold.
+
+## Pairs with
+
+- `harness-score` β€” numeric readiness
+- `harness-mcp-scan` β€” static MCP security findings
+- `harness-threat-model` β€” enterprise-review-grade threat model
diff --git a/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md b/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md
new file mode 100644
index 0000000000..cbc20b4ebd
--- /dev/null
+++ b/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md
@@ -0,0 +1,47 @@
+---
+name: harness-mcp-scan
+description: Static security scan of a harness's declared MCP surface via `harness mcp-scan <path>`. Reads `.mcp/servers.json` + `.harness/claims.json`. Pure-read, no dispatch. Exits 1 on findings at or above `--fail-on` severity.
+argument-hint: "[--path .] [--fail-on low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+Calls `harness mcp-scan` to enumerate every declared MCP server + tool
+and flag policy / permission / dependency issues. Never executes any
+tool; pure static analysis.
+
+## Algorithm
+
+Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
+
+1. Shell `npx -p metaharness@latest harness mcp-scan <path> --json`.
+2. Parse `findings[]` with `{ severity, id, server, tool, message }`.
+3. `--fail-on <severity>`: exit 1 when any finding is at or above that
+ level. Default `high`.
+4. Output JSON (default) or markdown table.
+
+## Severity rank
+
+| Severity | Rank |
+|---|---:|
+| low | 1 |
+| medium | 2 |
+| high | 3 |
+
+`--fail-on high` (default) only fails on HIGH; `--fail-on medium` also
+fails on MEDIUM; `--fail-on low` fails on any finding.
+
+## CI integration
+
+```yaml
+- name: MCP static scan
+ run: node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --fail-on high
+```
+
+The exit code is the only thing CI watches; the JSON output goes to
+artifacts for human review.
+
+## Graceful degradation
+
+When `harness` binary is unavailable (no network, blocked registry),
+emits structured `{ degraded: true, reason: 'metaharness-not-available' }`
+and exits 0. Ruflo continues β€” ADR-150 architectural constraint.
diff --git a/plugins/ruflo-metaharness/skills/harness-mint/SKILL.md b/plugins/ruflo-metaharness/skills/harness-mint/SKILL.md
new file mode 100644
index 0000000000..566ed20f40
--- /dev/null
+++ b/plugins/ruflo-metaharness/skills/harness-mint/SKILL.md
@@ -0,0 +1,72 @@
+---
+name: harness-mint
+description: Scaffold a custom AI agent harness via `metaharness new <name> --template <id> --host <id>`. Defaults to DRY-RUN (no writes) unless --confirm is passed. Refuses to write to the calling repo root or anywhere inside it. Honors ADR-150 architectural constraint + ruflo's "destructive-action confirmation" pattern.
+argument-hint: "--name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]"
+allowed-tools: Bash
+---
+
+The one write-capable skill in the plugin. Every other skill is
+pure-read. This one calls `metaharness new`, which writes a new
+directory tree.
+
+## Safety (load-bearing)
+
+1. **Dry-run by default.** Without `--confirm`, the script prints what
+ it would do and exits 0 without touching disk.
+2. **Refuses project root.** If `--target` resolves to the current
+ working directory OR any path inside it, the script errors out with
+ exit 2. Target must be an absolute path OUTSIDE the calling repo
+ (default is a fresh `/tmp/ruflo-mint-<ts>-<name>/` dir).
+3. **Refuses existing target.** Won't overwrite β€” must scaffold into a
+ non-existent dir.
+4. **Subprocess + 60s timeout.** No library import, no in-process
+ execution. The mint stays sandboxed from ruflo's runtime.
+
+## Algorithm
+
+Implementation: [`scripts/mint.mjs`](../../scripts/mint.mjs).
+
+1. Validate `--name`, `--template`. Default `--host` to `claude-code`.
+2. Resolve `--target` (default: temp dir).
+3. Run safety checks (no project-root writes; target must not exist).
+4. Without `--confirm`: emit dry-run plan, exit 0.
+5. With `--confirm`: shell `npx metaharness new <name> --template <id>
+ --host <id> --target <abs> --yes`.
+
+## Templates
+
+`minimal`, `vertical:coding`, `vertical:devops`, `vertical:support`,
+`vertical:legal`, `vertical:research`, `vertical:trading`, `vertical:health`,
+`vertical:education`, `vertical:sales`, `vertical:business`,
+`vertical:crm`, `vertical:marketing`, `vertical:advertising`,
+`vertical:ai`, `vertical:agentics`, `vertical:ruview`, `vertical:gaming`,
+`vertical:repo-maintainer`, `vertical:exotic`.
+
+## Hosts
+
+`claude-code`, `codex`, `pi-dev`, `hermes`, `openclaw`, `rvm`,
+`copilot`, `opencode`, `github-actions`.
+
+## Example dry-run
+
+```
+$ node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
+# harness-mint (dry-run)
+
+- action: metaharness new
+- name: my-harness
+- template: vertical:coding
+- host: claude-code
+- target: /tmp/ruflo-mint-1718560000-my-harness
+- confirm: false
+- willWrite: false
+
+Re-run with `--confirm` to actually scaffold.
+```
+
+## Why dry-run by default
+
+Ruflo's behavioral rules say "executing actions with care" β€” destructive
+or repo-touching actions need confirmation. The dry-run output makes the
+WHAT visible before the WHEN. A human sees `target`, decides, then
+adds `--confirm` if happy.
diff --git a/plugins/ruflo-metaharness/skills/harness-score/SKILL.md b/plugins/ruflo-metaharness/skills/harness-score/SKILL.md
new file mode 100644
index 0000000000..dc1114d8b5
--- /dev/null
+++ b/plugins/ruflo-metaharness/skills/harness-score/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: harness-score
+description: 5-dimension harness readiness scorecard from `metaharness score <path>`. Returns harnessFit / compileConfidence / taskCoverage / toolSafety / memoryUsefulness + estCostPerRunUsd + scaffoldReady. Pure-read; subprocess invocation; degrades gracefully when MetaHarness is absent (ADR-150 architectural constraint).
+argument-hint: "[--path .] [--alert-on-fit-below 70] [--format table|json]"
+allowed-tools: Bash
+---
+
+Surfaces the upstream `metaharness score` CLI as a ruflo skill. Use when
+Claude Code needs to assess whether a repo is ready for harness adoption
+before recommending the user run `npx ruflo init` or `harness-mint`.
+
+## Algorithm
+
+Implementation: [`scripts/score.mjs`](../../scripts/score.mjs).
+
+1. Shell out to `npx metaharness score <path> --json` (single subprocess,
+ 60s hard timeout).
+2. Parse the JSON shape: `{ harnessFit, compileConfidence, taskCoverage,
+ toolSafety, memoryUsefulness, estCostPerRunUsd, recommendedMode,
+ archetype, template, scaffoldReady, hardConstraints }`.
+3. If `--alert-on-fit-below N`: exit 1 when `harnessFit < N`.
+4. Output JSON (default) or markdown table.
+
+## Phase-0 baseline (ruflo's own scorecard, measured 2026-06-16)
+
+| Dimension | Value |
+|---|---:|
+| harnessFit | 82/100 |
+| compileConfidence | 100 |
+| taskCoverage | 79 |
+| toolSafety | 100 |
+| memoryUsefulness | 40 |
+| estCostPerRunUsd | $0.048 |
+| recommendedMode | CLI + MCP |
+| archetype | typescript-sdk-harness |
+| template | vertical:coding |
+| scaffoldReady | true |
+
+Ruflo passes its own readiness check. `memoryUsefulness: 40` is the
+weakest dimension β€” track this as a leading indicator for future memory
+work in the AgentDB layer.
+
+## CI integration
+
+```bash
+node plugins/ruflo-metaharness/scripts/score.mjs --alert-on-fit-below 70 --format json
+```
+
+Exit 1 fails the build. Pair with `harness-genome` for the full
+7-section view.
+
+## Graceful degradation (ADR-150 architectural constraint rule #3)
+
+When `metaharness` is not installed and `npx` can't fetch it (offline,
+no network, registry unreachable), the script emits:
+
+```json
+{
+ "degraded": true,
+ "reason": "metaharness-not-available",
+ "hint": "Install metaharness manually with `npm i -D metaharness` or run `npx metaharness@latest --version` to verify network access."
+}
+```
+
+and exits 0. Ruflo continues to function β€” this is the architectural
+constraint in action.
diff --git a/plugins/ruflo-metaharness/skills/harness-threat-model/SKILL.md b/plugins/ruflo-metaharness/skills/harness-threat-model/SKILL.md
new file mode 100644
index 0000000000..53d746cb11
--- /dev/null
+++ b/plugins/ruflo-metaharness/skills/harness-threat-model/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: harness-threat-model
+description: Enterprise-review-grade threat model from `harness threat-model <path>`. Categorizes MCP-surface threats; emits `worst: 'clean'|'low'|'medium'|'high'` + per-threat findings. Pure-read.
+argument-hint: "[--path .] [--fail-on clean|low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+The companion to `harness-mcp-scan` for enterprise security reviews.
+Where mcp-scan is a per-server static lint, threat-model produces a
+categorized report suitable for sharing with an InfoSec team.
+
+## Algorithm
+
+Implementation: [`scripts/threat-model.mjs`](../../scripts/threat-model.mjs).
+
+1. Shell `npx -p metaharness@latest harness threat-model <path> --json`.
+2. Parse `{ worst, findings[] }`.
+3. `--fail-on <severity>`: exit 1 when `worst >= fail-on`. Default `high`.
+
+## Severity rank
+
+| Severity | Rank |
+|---|---:|
+| clean | 0 |
+| low | 1 |
+| medium | 2 |
+| high | 3 |
+
+## When to use
+
+- Pre-launch review: include the JSON output in the release-readiness
+ packet sent to security.
+- Periodic audit: schedule via the planned `oia-audit` background
+ worker (ADR-150 Phase 2) to detect MCP-surface drift.
+
+## Graceful degradation
+
+Same pattern as the other skills: when `harness` is absent, emit
+`{ degraded: true }` and exit 0. ADR-150 architectural constraint.
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index be90a37e51..3b6878b427 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -112,7 +112,8 @@
"@claude-flow/memory": "^3.0.0-alpha.20",
"@claude-flow/plugin-gastown-bridge": "^0.1.3",
"@claude-flow/security": "^3.0.0-alpha.10",
- "@metaharness/router": "^0.3.2",
+ "@metaharness/router": "~0.3.2",
+ "metaharness": "~0.1.11",
"@ruvector/attention": "^0.1.32",
"@ruvector/attention-darwin-arm64": "0.1.32",
"@ruvector/diskann": "^0.1.0",