mcpField
H
harness-similarity

harness-similarity

github.com/ruvnetAgent workflows80.0k236 installsUpdated today
Repository

About harness-similarity

harness-similarity is a callable skill that compares harnesses using numerical, categorical, and agent-topology data. It is for ranking templates, deciding whether to fork or scaffold, and finding duplicate work; it also provides per-dimension results.

Key features

  1. 01Combines cosine, categorical, and Jaccard similarity
  2. 02Compares files or persisted memory records
  3. 03Provides per-dimension breakdowns
  4. 04Handles malformed input without throwing
  5. 05Exposes a CLI command and MCP tool

Use cases

  1. 01Choose between forking a harness and scaffolding
  2. 02Rank templates against a repository genome
  3. 03Find duplicate work across team harnesses
  4. 04Generate similarity confidence for a recommender

MCP support

The skill registers an MCP tool, `mcp__plugin_ruflo-core_ruflo__metaharness_similarity`, for invoking the harness similarity function.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ruvnet/ruflo --skill harness-similarity

After installing, type/harness-similarityin Claude Code to confirm it loaded.

Details

From the project README

Surfaces the production similarity function from scripts/_similarity.mjs as a callable skill. Use when an agent needs to:

  • decide whether to fork an existing harness vs scaffold a new one
  • rank candidate templates against a target repo's genome
  • diff two harnesses produced by different teams to find duplicate work
  • generate the confidence number that ADR-151 §3.2's Recommender wraps

Algorithm (from ADR-152 §Decision)

overall = 0.60·cosine + 0.25·categorical + 0.15·jaccard
  • cosine — over a 9-dim numerical vector of normalized scorecard + genome dims
  • categorical — fraction of 4 enum fields that match (repo_type, archetype, template, recommendedMode)
  • jaccard — |A ∩ B| / |A ∪ B| over the agent_topology[] array

The 3-component design is load-bearing: numerical cosine alone is too coarse (the iter-35 spike showed LEGAL vs DEVOPS at cosine=0.97 despite being unrelated verticals). Categorical + jaccard pull the composite to the correct ordering.

Reference outputs (iter-35 spike fixtures)

Pairoverallcosinecategoricaljaccard
LEGAL × LEGAL (self)1.00001.00001.00001.0000
LEGAL × SUPPORT0.82960.99870.75000.2857
LEGAL × DEVOPS0.58400.97340.00000.0000

Both invariants from ADR-152 §"Smallest demonstrable spike" hold:

  1. similarity(X, X) === 1 exactly
  2. similarity(LEGAL, DEVOPS) < similarity(LEGAL, SUPPORT) (vertical affinity)

Architectural constraint inheritance (ADR-150)

  • Removable — pure-TS function, zero static @metaharness/* imports.
  • Optional — no new dep in package.json.
  • Graceful — malformed inputs emit { degraded: true, reason } with exit code 2; never throws.
  • CI-gate — smoke step 17y locks the contract: module exports, spike fixtures reproduce, CLI dispatcher entry registered, MCP tool registered.

Usage

# File inputs
npx ruflo metaharness similarity --a a.json --b b.json

# Memory inputs (records persisted by oia-audit.mjs)
npx ruflo metaharness similarity --a-key harness-X --b-key harness-Y

# Per-dimension breakdown (used by ADR-151 §3.2 Recommender)
npx ruflo metaharness similarity --a a.json --b b.json --per-dimension

# Alert when too-dissimilar (used by ADR-151 §3.3 Drift Detection)
npx ruflo metaharness similarity --a a.json --b b.json --alert-below 0.5

Implementation

Production module: scripts/_similarity.mjs CLI skill: scripts/similarity.mjs MCP tool: mcp__plugin_ruflo-core_ruflo__metaharness_similarity (registered in v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts) Spike anchor: scripts/_spike-similarity.mjs (regression suite — invariants locked here)

Comments

Markdown supported