compare-harnesses

Codex skill: diff two scaffolded harnesses — the ADR-031 Bundle JSON Pattern surfaced through Codex (iter 105 → iter 109).

What it does

Two-harness diff. Useful when you've forked an upstream template, when a support ticket says "mine and theirs scaffolded different things", or when a CI script wants a byte-equality check between a candidate scaffold and a known-good baseline.

Reports three sections:

1. Manifest meta — same name? same kernel? same surface?
2. Hosts — which host adapters each side ships (claude-code / codex / pi-dev / hermes / openclaw / rvm)
3. Files — added / removed / changed (per-file SHA-256 fingerprints; the cheapest possible byte-equality test)

Usage from Codex

/compare-harnesses a=./my-fork b=./upstream
/compare-harnesses a=./my-fork b=./upstream bundle=true

Equivalent CLI

harness compare ./my-fork ./upstream                  # text output
harness compare ./my-fork ./upstream --bundle         # ADR-031 schema-1 JSON

The --bundle form (ADR-031) emits a schema-1 JSON envelope so CI scripts can json-parse the verdict without re-parsing human text. The envelope shape is shared with harness diag --bundle, harness export-config, and harness audit --bundle:

{
  "schema": 1,
  "generatedAt": "2026-06-15T...",
  "a": "/path/to/a",
  "b": "/path/to/b",
  "meta": { "sameKernel": true, "sameSurface": true, "sameName": false },
  "hosts": { "a": ["claude-code"], "b": ["claude-code", "codex"], "verdict": "PASS" | "FAIL" },
  "files": { "added": [...], "removed": [...], "changed": [...] },
  "identical": false,
  "exitCode": 1
}

Errors are bundle-formed too ({ "schema": 1, "error": "no-manifest-in-a" }), so a CI script never has to dual-parse text + JSON. Object keys matching secret|token|key|password|passphrase are redacted via the canonical ADR-031 sanitisation regex before emission — safe to paste into a public GitHub issue.

Sample output (text mode)

harness compare — diffing /tmp/a /tmp/b

  name:              A=cmp-a   B=cmp-b   FAIL
  kernel:            A=0.1.0   B=0.1.0   PASS
  surface:           A=cli     B=cli     PASS
  hosts:             A=[claude-code] B=[claude-code,codex] FAIL

  added:             3 files
    + src/agents/codex-tester.ts
    + src/agents/codex-reviewer.ts
    + .codex/config.toml
  removed:           0 files
  changed:           1 file
    ~ .harness/manifest.json

DRIFT (exit 1)

When to use it

• You forked the project's upstream template, edited it, and want to know exactly what diverged before sending a PR upstream.
• A user files a "this doesn't work" bug; you run harness compare their-zip yours-zip --bundle > diff.json and attach the bundle to the issue.
• CI is the canonical place: a nightly job runs compare between today's scaffold output and a frozen baseline, fails the run on DRIFT.

Related skills

• diag-harness — single-harness kernel-version skew check (iter 66)
• validate-harness — release-readiness umbrella (iter 20)
• verify-witness — Ed25519 witness signature verification (iter 8)

See also

• ADR-030 — Discovery Loop — why new subcommands propagate to codex skills.
• ADR-031 — Bundle JSON Pattern — the envelope shape this skill's --bundle mode conforms to.

create-harness

This skill scaffolds an AI agent harness — your own focused, branded harness with its own npx <name> CLI, MCP server registration, memory namespace, learning loop, and marketplace identity.

When to use this skill

Use this skill when the user wants any of:

• A custom MCP-server-backed AI assistant (legal, trading, support, ops, …)
• A Claude Code plugin that bundles their own agents/skills/prompts
• A Codex skill that wraps a kernel + tools
• A pi.dev extension or Hermes agent runtime config
• A standalone npm package they can npm publish under their own scope

How to invoke

/create-harness

The skill asks for:

1. Harness name (kebab-case, e.g. legal-redline)
2. Description (one line)
3. Host(s) — Claude Code, Codex, pi.dev, Hermes (multi-select)
4. Template — minimal (default), vertical:trading, vertical:support, vertical:devops, vertical:legal, vertical:research, or eject-from-ruflo
5. Memory backend — AgentDB (default), SQLite-only, in-memory
6. Routing strategy — 3-tier (default) or single-tier
7. Marketplace — independent (no ruflo branding) or powered-by

Under the hood

Calls npx create-agent-harness <name> with the user's choices, copies the chosen template into the current directory, runs the post-generation smoke test, and emits a .harness/manifest.json so future updates can harness upgrade cleanly (copier-style regenerate-diff-merge).

Outputs

After scaffolding

The user can:

cd <name>
npm install
npm test
npm publish              # ship their harness to npm
# their users: npx <name> init

Notes for the model

• This is a deterministic operation — defer to create-agent-harness for the actual file creation, do NOT generate harness file contents yourself
• The witness manifest is required — do not skip it
• If the user asks for "ruflo for X" or "my own ruflo", recommend vertical:<X> templates first and offer minimal as the fallback
• Multi-host is supported but increases the harness's surface area — recommend single-host for first-time users unless they explicitly need multi-host

diag-harness

Codex skill: kernel-version skew check for a scaffolded harness — the ADR-027 diagnostic UX loop.

What it does

Single-question check: does my local @metaharness/kernel match what this harness was scaffolded against? That's the cross-machine compatibility question almost every "this harness doesn't work" support ticket turns out to be.

Reads .harness/manifest.json:

Resolves the local @metaharness/kernel via createRequire rooted at the harness's own package.json (real Node resolution). Computes the skew verdict and prints a copy-pasteable next step.

Usage from Codex

/diag-harness                           # cwd
/diag-harness path=./my-harness

Equivalent CLI

harness diag                            # cwd
harness diag ./my-harness               # explicit path
harness diag ./my-harness --json        # machine-readable for CI
harness diag ./my-harness --bundle      # support-ticket JSON (iter 90)

The --bundle form (iter 90) emits a single JSON snapshot of the diag report + sanitised manifest + @metaharness/* deps + Node/platform info — everything a maintainer needs to triage a bug report. Object keys matching secret|token|key|password|api_key are redacted so the bundle is safe to paste into a public GitHub issue.

Sample output

harness diag — checking /tmp/my-harness

  surface:              cli
  manifest kernel:      0.1.0
  installed kernel:     0.1.0

  PASS kernel versions match exactly

When to run

• After cloning someone else's harness — first thing
• After bumping @metaharness/kernel in a harness's package.json
• When harness doctor fails with cryptic shape errors (skew is the usual cause)
• In CI before any other harness subcommand — fail fast

Lifecycle position

scaffold (create-agent-harness)
    ↓
 your code lives in the harness
    ↓
 diag (this skill)           <- before anything else, check compatibility
    ↓
 doctor / validate / sign / publish

Related

• ADR-027 — CLI ↔ Web-UI integration (the parity contract diag enforces)
• iter 56 — manifest.meta.surface added
• iter 58 — manifest.meta.kernel_version stamped at scaffold time
• iter 66 — harness diag subcommand

example-harness

One-command scaffolding from the 18 published @metaharness/* example packages — the fastest path from a use-case to a working harness, no template/host flags to remember.

Where create-harness walks the full wizard, this skill maps a use-case straight onto a published npm wrapper. Each wrapper shells out to metaharness@latest with the correct --template + --host flags, so the result is byte-identical to the full CLI invocation.

Install

mkdir -p ~/.codex/skills/example-harness
curl -fsSL https://raw.githubusercontent.com/ruvnet/agent-harness-generator/main/.codex/skills/example-harness/skill.toml \
  -o ~/.codex/skills/example-harness/skill.toml

No MCP server needed — the wrapper packages run via npx.

Use

/example-harness

Codex prompts for the package + a directory name, then runs:

npx --yes @metaharness/<package>@latest <name>

The 18 packages

Host integrations (scaffold a workspace wired for one runtime)

Vertical workflows (ready-made multi-agent pods)

After scaffolding

cd <name> && npm install
npx harness doctor      # health-check
npx harness validate    # full umbrella gate

Every scaffold ships a .claude-plugin/plugin.json, so it also loads as a Claude Code plugin: claude -p --plugin-dir <name> "...".

Per-package deep-dive gists: see examples-packages/GISTS.md.

list-templates

Lists every harness template create-agent-harness can scaffold from.

Templates today (Iter 2)

Hosts each template supports

Roadmap

• Vertical packs ship as separate npm packages (@metaharness/vertical-trading, etc.) so each pack can be owned by a domain expert
• See ADR-013

oia-manifest

Codex skill: emit/validate the OIA cross-cutting manifest layer (ADR-034, iter 121 → iter 122).

What it does

Emits .harness/oia-manifest.json — the harness's self-assessment against the Open Intelligence Architecture (OIA) v0.1 9-layer reference model published by the Agentics Foundation at https://oia.agentics.org.

The manifest declares:

• 9 layer alignments — L1 physicalCompute → L9 humanAndBrowserInterface, each full / partial / none / not-applicable
• 6 horizontal spans — security · observability · identity · governance · policyEnforcement · interoperability, each full / partial / none with an implementation reference (file path or ADR number)
• 4 adjacent standards — mcp, a2a, acp, agentProtocol with current mode + wiring notes
• discoveryEndpoint + registryUrl (both null at v0.1; OIA has no registry yet)

Why a manifest, not a host adapter?

OIA at v0.1 has no runtime and no wire protocol — it's a vendor-neutral vocabulary for assessing system alignment. The right plug-in shape is a static cross-cutting manifest (ADR-034 Decision: Option B). It plugs in ABOVE the host adapter contract and BELOW the MCP policy gate.

Usage from Codex

/oia-manifest path=./my-harness
/oia-manifest path=./my-harness check=true
/oia-manifest path=./my-harness dry-run=true

Equivalent CLI

harness oia-manifest ./my-harness                # write .harness/oia-manifest.json
harness oia-manifest ./my-harness --check        # validate existing manifest
harness oia-manifest ./my-harness --dry-run      # stdout, no file write
harness oia-manifest ./my-harness --json         # stdout JSON

Verdict + exit codes (--check)

Sample manifest (excerpt)

{
  "schema": 1,
  "oiaVersion": "0.1",
  "harnessId": "my-bot@0.1.0",
  "layerAlignment": {
    "L4_toolsAndIntegrations": "full",
    "L7_governanceAndPolicy": "full"
  },
  "horizontalSpans": {
    "identity": { "status": "none", "implementation": null },
    "security": { "status": "full", "implementation": "mcp-policy.json + ADR-022" }
  },
  "adjacentStandards": {
    "mcp": { "mode": "local", "policyPath": ".harness/mcp-policy.json" }
  },
  "discoveryEndpoint": null,
  "registryUrl": null
}

Pre-emptive composition rule (ADR-034 §120)

If a future OIA identity primitive ever wants to widen an MCP permission, the composition is denied at the policy gate. The mcp-policy.json default-deny posture is not negotiable for external identity claims.

Related skills

• validate-harness (iter 22) — release-readiness umbrella
• threat-model (iter 114) — MCP threat-model for PR/compliance review
• diag-harness (iter 70) — kernel-version skew check

See also

• ADR-034 — OIA Integration
• ADR-022 — MCP primitive
• ADR-030 — Discovery Loop
• oia.agentics.org

publish-harness

Codex skill that runs the full smoke-test → witness-sign → npm publish pipeline for a generated harness.

What it does

1. Builds the harness with npm run build
2. Runs npm test to confirm green tests
3. Calls harness sign to produce a fresh witness manifest (requires WITNESS_SIGNING_KEY env)
4. Confirms harness verify accepts the freshly signed manifest
5. Either:
   • dry_run=true (default): runs npm publish --dry-run and reports tarball stats
   • dry_run=false: runs the real npm publish --provenance --access public

Usage from Codex

/publish-harness path=./my-harness
/publish-harness path=./my-harness dry_run=false

Equivalent CLI

cd ./my-harness
npm run build
npm test
harness sign
harness verify
npm publish --provenance --access public

Required env

• WITNESS_SIGNING_KEY — 64-hex-char ed25519 seed (fetch from GCP Secret Manager via harness secrets fetch WITNESS_SIGNING_KEY)
• NPM_TOKEN — npm registry credential (Codex skill assumes the host has it set, or fetches via harness secrets fetch NPM_TOKEN)

See also

• validate-harness — release-readiness gate (run this FIRST)
• harness-secrets — manage GCP-stored signing/publishing tokens

repo-genome

Codex skill: 7-section readiness scorecard for a local repo — the ADR-031 Bundle JSON Pattern surfaced through Codex (iter 110 → 114).

What it does

Answers a different question than analyze-repo:

• analyze-repo — "which archetype / template / agents fit this repo?"
• repo-genome — "is this repo READY for that harness, and what's the risk?"

Produces a 7-section report:

1. Repo profile — type, languages, build/test commands, ci presence
2. Agent topology — recommended roles (maintainer / tester / security / release)
3. MCP risk model — surface + numeric risk + policy posture
4. Test confidence — how strong are the test signals
5. Release readiness — buildable / testable / ci-wired
6. Recommended harness plan — template, archetype, hosts, agents, skills
7. Scorecard — risk_score, publish_readiness, test_confidence

LOCAL-only, deterministic, never executes repo code. Same invariant as analyze-repo (inherited via the shared inventory/profile pipeline).

Usage from Codex

/repo-genome path=./my-repo
/repo-genome path=./my-repo bundle=true
/repo-genome path=./my-repo out=./harness-genome.json

Equivalent CLI

harness genome ./my-repo                          # text report
harness genome ./my-repo --json                   # 6-field scorecard JSON
harness genome ./my-repo --bundle                 # ADR-031 schema-1 envelope
harness genome ./my-repo --out harness-genome.json # write scorecard to file

Sample 6-field output (--json)

{
  "repo_type": "rust_node_polyglot_mcp_ci",
  "agent_topology": ["maintainer", "tester", "security", "release"],
  "risk_score": 0.31,
  "mcp_surface": "local_default_deny",
  "test_confidence": 0.86,
  "publish_readiness": 0.78
}

When to use it

• Before scaffolding a harness — run genome first, decide whether the repo is ready or needs cleanup
• In CI on incoming PRs — post the genome report as a check; alert when risk_score crosses a threshold
• For support tickets — --bundle emits the full readiness snapshot sanitised for safe sharing

Related skills

• repo-analyze (iter — proposed) — the archetype-and-plan recommendation
• compare-harnesses (iter 109) — diff two scaffolded harnesses
• diag-harness (iter 70) — kernel-version skew check
• score-harness (iter 114) — post-scaffold harness scorecard

See also

• ADR-030 Discovery Loop
• ADR-031 Bundle JSON Pattern

upgrade-harness

Codex skill: drift detection + apply for a scaffolded harness.

What it does

Re-renders the template that produced the harness against the current generator version, using the same vars the original scaffold used. Computes a 3-bucket plan:

A clean change means the harness's version equals the original generation — apply safely. A conflict means the user edited the file post-scaffold; the apply step writes either Git-style inline markers or a .rej sidecar for manual merge.

Usage from Codex

/upgrade-harness                                       # dry-run on cwd
/upgrade-harness path=./my-harness
/upgrade-harness path=./my-harness apply=true
/upgrade-harness path=./my-harness apply=true conflict=rej

Equivalent CLI

harness upgrade ./my-harness                           # dry-run
harness upgrade ./my-harness --apply                   # apply, inline conflicts
harness upgrade ./my-harness --apply --conflict=rej    # apply, .rej sidecars

Lifecycle position

scaffold (create-agent-harness)
    ↓
 edit (you)
    ↓
 upgrade (this skill)   <- catches up to the latest template
    ↓
 sign / verify / publish

Exit codes

CI workflows can gate on exit 1 to flag unresolved conflicts.

validate-harness

Codex skill that runs the 5 release-readiness gates from harness validate.

What it checks

Each check reports PASS / FAIL / WARN with a one-line detail. Exits 1 if any FAIL.

Usage from Codex

/validate-harness
/validate-harness path=./my-harness
/validate-harness path=./my-harness skip_gcp=true
/validate-harness secret=NPM_TOKEN_DEV

Equivalent CLI

harness validate ./my-harness --skip-gcp --secret=NPM_TOKEN_DEV

Why this exists

Before iter 20, you needed to remember to run harness doctor, harness verify, harness secrets check, and node scripts/path-guard.mjs separately. This is the single release-readiness gate.

verify-witness

Codex skill: Ed25519 witness manifest verification for a scaffolded harness.

What it does

Reads .harness/witness.json, validates the Ed25519 signature against the embedded public key, and reports VALID / INVALID with a one-line reason.

Distinct from validate-harness:

• validate-harness is the umbrella — doctor + verify + path-guard + mcp + secrets
• verify-witness is only the signature check — fast yes/no for CI / federation handshakes / multi-signer workflows

Usage from Codex

/verify-witness
/verify-witness path=./my-harness
/verify-witness path=./my-harness strict=false

Equivalent CLI

harness verify ./my-harness

Why it's separate from validate-harness

When two harnesses federate (iter 9), they need to confirm each other's witness signatures BEFORE doing the full release-readiness check. Splitting this surface lets federation peers run a fast signature handshake without paying for the full validate sweep.

Also: CI workflows that only care about signature integrity (e.g. mirroring a published harness to a private registry) can call this skill instead of the heavier umbrella.

What's checked

Exit 0 = signature VALID. Exit 1 = INVALID / missing (strict mode).