Forge Harness

This document is for humans. AI operating rules → CLAUDE.md · Command reference → CHEATSHEET.md

Get started in 2 minutes

Prerequisite: Claude Code CLI — verify with claude --version

The consent-registry gate parses YAML, and it fails closed when it cannot — correctly, since an unvalidated consent record must not read as a clean one. But that fail-closed turns the whole of npm test (and prepublishOnly) red on a machine without PyYAML, and until 2026-08-12 the requirement was written down nowhere. It is written here now — and, as of this edit, only here: it is still absent from package.json, the cheatsheet and every other doc, so this block is the single place a new machine can learn it. That is an improvement over nowhere, not a fix:

python3 -m pip install --user pyyaml     # verify:  python3 -c 'import yaml; print(yaml.__version__)'

Why this is called out rather than left implicit: a release once shipped green from a session whose python3 happened to resolve to an unrelated project's virtualenv that had PyYAML, while the machine's own python3 did not. The gate was never bypassed — it passed, and the pass simply was not portable. Every verdict from that gate now prints the interpreter and PyYAML version it used, so a green states what produced it instead of leaving the reader to assume.

# 1. Install the plugin
claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
claude plugin install -s user fh-meta@forge-harness

# 2. Clone the hub
git clone https://github.com/chrono-meta/forge-harness.git ~/projects/forge-harness
cd ~/projects/forge-harness

# 3. Start a session
claude

✅ Then type a greeting ("hi") — the 🐿️ door menu appears on a typed greeting, not on launch alone. Say "Connect a project" → hub scans ../, finds .git directories, creates tracks/{project}/. For full initial setup (hooks · gates · baseline — each item individually approved, declining is respected and recorded), ask for /install-wizard. Already cloned somewhere else? That path is your hub — read every ~/projects/forge-harness in the docs as your actual clone path.

Your first 15 minutes — what success looks like, and what to do with it:

1. You'll know setup worked when a greeting ("hi") shows the 🐿️ door menu, and "Connect a project" creates tracks/{your-project}/.
2. Then grab an immediate win in the same session: say "accelerate this project" (ranked plan of skills/plugins worth wiring, install-gated) or "run /context-doctor" (token-waste scan).
3. One honest note: FH's core payoff is compounding — session records, harvested learnings, cross-session memory. It shows from session 2 onward. Day one gives you the menu, the acceleration plan, and governance gates; don't judge the compounding on day one.

Unfamiliar words on the way? → knowledge/shared/GLOSSARY.md.

Plugin only (no clone):

claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git  # once
claude plugin install -s user fh-meta@forge-harness
cd ~/projects/{your-project} && claude

⚠️ Plugin-only is partial synergy. You get the skills and agents, but not the hub-side orchestration — the CLAUDE.md governance (active onboarding, the 4-axis gate, mode branching; automation layer) and the compounding context (tracks/ memory accumulation, harvest-loop learning; methodology layer). Each skill runs the same in isolation; what's missing is the orchestration that makes them compound across sessions. Clone the hub (above) when you want the full set, not just the tools.

Which entry path is for you?

What it is

forge-harness is structured as two distinct layers:

The methodology layer is the portable core — persistent hub, accumulating learnings, curating cross-project knowledge. The automation layer makes it frictionless when running Claude Code.

Where this sits (2026): "harness engineering" is now a public paradigm — and basic agent orchestration is rapidly commoditizing into standard infrastructure. FH deliberately stakes nothing on that plumbing. Its durable layer is what does not commoditize: the governance gates (adversarial · phantom · regression), drift control, and the cross-project compounding loop. Routing and dispatch are means; the gate and the loop are the asset.

forge-harness/   ← the hub (persistent brain)
├── knowledge/   → shared across all projects
└── tracks/      → work records per project

Project A  ──→  connect hub in CLAUDE.md
Project B  ──→  connect hub in CLAUDE.md

What makes it a harness, not a toolbox

Start with what a harness is for: it reads your intent and forges it into a machined form — rules an AI reliably follows, or deterministic code that needs no model at all. You give intent and insight; the harness shapes them into something executable; you approve; it becomes machinery. The payoff is less trial-and-error on the human side: the request → feedback → regenerate loop doesn't disappear, it relocates — into the harness, run in parallel by agents and sidecars — so your time drops and your attention is spent only where a change is irreversible.

Scale is the second point. A skill, agent, or plugin is a tool. A harness is a level up — a star: one project's tools, rules, gates, and memory bound into a single working body. forge-harness is the galaxy those stars live in: it binds many harnesses onto a shared floor to prevent drift, and lets them evolve together instead of scattering.

This galaxy is more than a container. FH can run a field harness in simulation inside its own sandbox — expensive per run, cheaper in total, because the trial-and-error pools in one place and compounds — and when the simulation holds, it emits the project as an independent, specialized harness. That last step is the goal it is built toward, not a shipped feature — the incubation chamber has emitted once, and the run that produced it did not go through the full flow. Read the simulate-and-emit sentence as direction of travel; everything before it is in use today.

The five identities — what FH is for

These are not five modules, and they are not five shipped features either. They are the shapes the skills clump into — the name of something that was already there, spread across the skills and agents rather than layered on top of them. They sit at a different level from the problem table at the top of this page: that table is symptoms you might arrive with, this is what the hub is organized around.

A sixth row is deliberately absent from that table. Ⓑ Project Booster — FH's machinery accelerating another harness's own development — is real and graded, and it is not on the same layer as the five. It carries a letter instead of a number for exactly that reason. Each of the five keeps scope that sits outside boosting: ⑤ covers human intent generally (including work where no harness is involved at all), ① runs in the opposite direction (FH is the beneficiary), and ② births units — boosting comes after birth. So the relation is not containment.

🟥 The canon stops there on purpose and does not draw an arrow. Pinning a hierarchy makes the table drift from how the work actually runs, where one job rides ① and ⑤ together and the result flows into ②. Read "different scopes", not "one sits under another". Grades — Ⓑ's included — live in one file: ship_readiness_gate.md §Ⓑ-layering.

They are not equally finished, and you should not read the table as five working features. Maturity is tracked per identity on a four-step scale — aspirational → partial → RC (stood up in the lab) → REALIZED (walked outside) — with a dated line of evidence for each. Those grades are deliberately not copied here: a grade kept in two files goes stale in one, and this page exists in four languages, so a copy here would be four copies. Before you rely on any row above, read the current grades — that is one file: ship_readiness_gate.md. The short version if you only want one sentence, as of 2026-08-17: ①, ③, ⑤ and Ⓑ are graded green — demonstrated outside the lab; ② and ④ are release candidates — built and calibrated, not yet shown to walk in someone else's hands. If that sentence and the gate file disagree, the gate file is right and this line is stale.

Two properties cut across all five, and neither is a feature you switch on:

• It rides the frontier instead of patching it. FH dispatches across families (Claude, Codex, Gemini, local) — but the point is not papering over each model's weak spots, because that scaffolding dies as models improve. It is co-evolution: shed what the substrate now does natively, absorb what it ships next. Decorrelation is today's trust lever, and it is the load-bearing word on this page: deliberately making two checks fail differently — a reviewer from another model family, a run against a real target, an outside audit of your own record — so that what one is blind to, another is not. A cross-family panel beats a single model's ceiling for exactly that reason, not because it is bigger.
• It evolves in two directions. Outward, each session's lessons compound into the hub so the next project starts further along. Inward, it catches and repairs its own defects — the same gates, turned on the harness itself.

The whole thing is a division of labor: raw capability is the model's; assembly, trust, and evolution are the harness's.

How it is built — process → engines → identity

The five identities above are the surface. Two layers sit under them, and naming all three is what keeps "what FH does" from collapsing into one undifferentiated pile:

five identities   what a person can actually use          (surface — what you get)
      ↑ backed by
four engines      the capability that makes it possible   (capability — what it can do)
      ↑ produced by
three-stage       the ORDER those engines are forged in   (process — how it gets made)
  process
      └ stage ③ = the six-axis gate                     (§The six verification axes, below)

As a mnemonic: three-stage process · four engines · five identities · six-axis gate. ⚠️ But the six axes are not a fourth layer — they are what stage ③ of the three-stage process consists of. Read the four as parallel layers and you get back the very "the layers do not land" problem this section was written to fix.

The four engines. Each one is what some identity above is standing on. They were not invented for this page: the readiness gate had already been scoring every identity against these same four capabilities in a column of its own (ship_readiness_gate.md), so naming them was recognition rather than taxonomy-building.

They are written by name, never by number — the table order here and the prose order elsewhere differ, so "engine ④" decodes to two different engines depending on which you read.

judgment-circuit is the one that gets misread most, so state it flatly: it is a coordinate system for deciding, not a statement of who the harness is. The four items in its row are the whole of it. Do not shorten it to "the harness's soul" in English either — that word reads as persona, and the largest finding of the measurement behind this engine (105 runs, comparing prompts with and without an identity declaration) was precisely that the two are different things: adding "you are a ~" came out a net loss on the weakest model tested, and taking it out recovered ground. A one-word rename re-fuses exactly what that measurement separated. The figure itself is deliberately not quoted here — the source records it without a scale, and an unscaled number on a front page is decoration; it is in ship_readiness_gate.md with its context. Nor is a judgment circuit built in one sitting: FH hands a new harness a seed draft, and it fills in as that harness is actually used.

The three-stage process — this is an order of investment, not a menu:

① Circuit before design   the judgment circuit goes in FIRST — success · leaning · out-of-scope ·
                          never-do — not written up afterwards as a record of what you did

② Decorrelate in the      split the work into checks that fail DIFFERENTLY and run them at once.
   middle, to accelerate  Choose which differences matter — a second reviewer of the same kind is
                          not decorrelation, it is the same blind spot twice. Parallelism has no
                          direction of its own; the judgment circuit from ① is what picks.
                          This is a way of WORKING, not the end-of-line check in ③.

③ Burn it down at the     the six axes below. Adversarial review is ONE of them, not all of them —
   end, on six axes       adversariality is a **posture**, not an axis. It can ride on any axis, and
                          riding it does not make that axis see what it cannot see

The six verification axes — where "we reviewed it" usually turns out to mean only the first of them.

🟥 Axes are not divided by how adversarial they are. They are divided by what they were given. Hand two reviewers the same input and the same blind spot survives, however many of them you add. That is why the column that matters most below is what it gets:

You do not run all six every time, and that is the design — do not multiply them, choose:

one-line fix (typo · gitignore)     nothing burns. Not even ①'s circuit — when there is one answer,
                                    planting one is overhead
ordinary code change (reversible)   ⓔ first real use + ⓕ revert
verdict · gate code                 + ⓐ different family — verdict logic is what a reviewer who
                                    shares the author's optimism misses **structurally**
change that touches another         + ⓑ standpoint — bolt on three families and if all three eat
harness                             your framing, nobody asks "does that canon actually say so"
very large · irreversible           + ⓒ isolation + ⓓ third-party encounter. Burn all of it

⚠️ ⓓ third-party encounter is the most expensive and has the smallest unique yield. And yet that handful were all of the boundary-crossing kind (a rule someone else had already retired · someone else's repo importing your file). On small, reversible changes such items simply do not arise; on large irreversible ones those two are exactly what becomes an incident. That is where the cost earns itself.

Why this is not superseded by base-model advances — an axis is defined by its input, not by the reviewer's ability. A stronger model still cannot see information it was not given. Scaffolding sheds as models improve, but input-boundary decorrelation does not, and a single author cannot, by definition, step outside their own input. 🟥 Honest edge: if the agent fetches more input by itself with tools, the boundary blurs — an outside judgment held that "the store is never used in full" and "the swallowed exception" are catchable by ⓐ and ⓒ as well, since those reviewers grep for themselves. Conversely, "a rule another repo retired long ago" cannot be fetched by any tool — there is no reason to have access to that project's review history in the first place. That is where ⓓ remains.

🟥 Limits to read before citing this: the six-axis table is n=1 (one artifact · one session · one author). Whether the axes' non-overlap is structural or an accident of that day is unmeasured. And when the author's self-scoring was stripped out — 16 findings handed, with their provenance removed, to two classifiers from other families for blind judgment — 3 of the 5 the author had attributed to ⓓ were judged to belong to a different axis; those three were not "what the axis was needed for" but "what another axis missed". Discount the table's attributions accordingly.

Honest note — this is not a clean stack, and that is the point. Stage ① and stage ③ are made of the same material as the engines, so the lower layer uses the upper one. The contradiction resolves on subject: the engines are what FH applies to your work, while the process is the order FH uses when forging its own engines. If the method had been borrowed from outside it would be unrelated to the engines; the overlap is the fingerprint of dogfooding. Full canon, including the sample limits behind each claim: fh_three_layer_canon.md.

Self-healing here isn't a claim — check it. git log in this repo is the record, and the shape repeats: a miss is caught, the fix is attacked, and the attack often lands on the fix rather than on the original. One you can open by hash — cb74ea4, where a register-consistency rule was added to CLAUDE.md §Voice/Tone after the harness drifted register mid-session. A second, in the same change that added this section: a checker whose whole job is finding tests nothing runs was caught reporting a green count off a script's own comment, and then the guard written to fix that turned out to have no test that would fail if it were deleted — found by a different model family, not by the author, and closed with a fixture that does fail. Commit hashes on feature branches do not survive squash-merge, so that one is cited by its shape rather than by an ID that would rot.

Why it works

After a long co-authoring session with your AI, you and it share the same context — and the same blind spots. The reviewer worth having is the one who never saw your reasoning. You can get that by hand: paste the work into a fresh, empty chat. FH just turns that chore into one routine command.

• sidecar / agent dispatch → a reviewer with none of your session's context
• steel-quench · phantom-quench → that cold pass, on demand

It's model-agnostic: co-build with one AI, run the cold pass with any other. Whoever was absent from the original session is your cold reviewer — this is not a ranking of models.

What FH does not claim: the cold pass is your base model's own ability, not a detection engine FH adds — a plain prompt to a fresh instance does much of the same. FH's value is narrower and honest: it takes a method drawn from real practice and makes running that independent pass routine, instead of a chore you skip. The methodology is copyable; what FH packages is the workflow, not a secret sauce.

Governance layer for AI-generated code

FH wraps any coding agent (OpenCode, Codex, etc.) as a post-generation governance gate.

npx --package @chrono-meta/fh-gate fh-gate                    # default: Claude backend
FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-gate   # Codex backend
FH_BACKEND=auto npx --package @chrono-meta/fh-gate fh-gate "src/foo.ts" full
# → FH_GATE_VERDICT: PASS | PENDING | BLOCKED | ESCALATE

# or, via Homebrew (same content, no npx prefix needed after install):
brew tap chrono-meta/forge-harness && brew install forge-harness
fh-gate

fh-gate uses the same FH governance prompt for both runtimes. FH_BACKEND=claude runs claude --print; FH_BACKEND=codex runs codex exec; FH_BACKEND=auto prefers Codex when both CLIs are present — note that auto is fallback selection: it runs ONE leg. FH_BACKEND=cross runs BOTH families and unions their findings (a finding only one family saw is still a finding, so it unions rather than votes); the verdict is the most severe across legs. It costs ~2x, so it is for load-bearing verdict/gate/irreversible-surface changes, not a default. The output always declares which legs actually ran (FH_GATE_LEGS:, FH_GATE_DECORRELATED:) — on a machine with only one family, cross degrades to that single leg and says so, because a single-family result that reads as cross-checked is worse than an honest one.

For direct skill or agent execution outside Claude Code, use fh-run:

FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --skill phantom-quench --file docs/foo.md
FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --agent fh-commons:quench-challenger --file plugins/fh-meta/skills/foo/SKILL.md

To check whether a changed FH skill/agent surface still has a clean Codex adapter path, run:

npx --package @chrono-meta/fh-gate fh-codex-doctor --strict

fh-codex-doctor scans the canonical skill/agent registry and reports which units are Codex-native, adapter-required, Claude-native, or unclassified. It is a drift detector for the thin adapter boundary; it does not try to clone the Claude Code automation layer. When run from an FH checkout it scans the current working tree; outside a checkout it scans the installed package.

For Codex-primary work, keep using Codex's native goal/session features when available. fh-goal is only a portable wrapper for one-off non-interactive runs that should be followed by FH governance:

FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-goal --prompt "Implement X and update tests" --gate quick

The broader FH automation layer still depends on Claude Code for sub-agents, hooks, and slash commands. The portable path is shared documents plus runtime adapters, not separate Codex and Claude forks.

Recommended posture — Claude Code as orchestrator, others as sidecars. FH's automation layer (auto-firing hooks, sub-agent dispatch, onboarding, memory) is Claude-Code-native, so the fullest experience runs Claude Code as the main orchestrator with Gemini, Codex, or Antigravity (agy) as actively-used sidecars. You can also run a non-CC runtime as your main agent — you keep the full methodology layer and M1 skills (M1 = runs on any runtime as written; M2 = needs agent dispatch; M3 = Claude-Code-native — the portability tiers detailed in docs/codex-compat.md) through fh-gate/fh-run, but you do not get the autopilot layer: hooks don't auto-fire, M2 agent-dispatch steps need the adapter (or interactive approval), and M3 skills are reference-only. This is a deliberate two-layer boundary, not a gap to be closed. Per-runtime detail: docs/codex-compat.md (tier-by-tier) and multi_model_sidecar_strategy.md (sidecar engines, including the Gemini→agy succession at the 2026-06-18 EOL).

Empirical result (2026-05-31): Applied to OpenCode's AI-generated permission/arity.ts (163 lines, CI green). Current gate semantics classify this as BLOCKED: 2 A-grade findings CI didn't catch (short-token overflow in allowlist, executor tools absent from arity table).

Does the method actually add anything? A measured check (2026-07-14). We held the model fixed at a mid-tier floor and varied only the review method, on unseen gate snippets with planted default-toward-PASS (fail-open) holes. On eight subtle holes — authored by two other models so the test set wasn't tuned to our method — a plain review caught 5/8 (and two of those "catches" were the wrong bug, i.e. false confidence); the same model with FH's degrade-direction lens caught 6/8 with zero false alarms. The honest part: both single-model lanes missed the same two holes (a falsy error-sentinel, and a separator-negation parse). A different model family, same lens, caught both — so the FH stack (lens + cross-family + a mechanical pre-screen) reaches 8/8. The takeaway isn't a headline score; it's that the value comes from the decorrelated stack, because even a well-prompted single model has a correlated blind spot that only a different family closes. The two missed classes are now caught mechanically (a lint pre-screen), one layer earlier. Small sample (single draw); reps and harder holes are the stated next step. Method + full result: ship_readiness_gate.md.

Full spec: fh_integration_contract.md

The forge

forge-harness treats a project like steel — and the metaphor is literal, not decoration. Work is shaped, hardened by attack, and only then does it ship faster, for having survived.

All four movements ship. Temper was named before it was built — deliberately (see ETHOS.md) — and shipped once measurement runs validated it. Around the forge, two more signatures keep it running: harvest-loop (each session's lessons become permanent skills) and agent-composer (orchestrate the dispatch). The other skills wait until you need them — full list below.

40 skills · 8 agents

Count = non-deprecated skills (deprecated redirect stubs — kept only for old-name routing — excluded).

These bands are a rough self-check, not a measurement — no artifact defines the thresholds, and the earlier fixed numbers were calibrated against a smaller roster, so they quietly drifted as the roster grew. Using more skills is also not the goal; using the ones your work actually needs is.

Find a skill by what you're trying to do:

Full phrasebook — every skill + agent with its one-line definition and the plain-language phrase that triggers it: CHEATSHEET.md §12.

Model setup

Claude Code does not auto-select models by task complexity — you configure this once.

/model sonnet   # recommended default — FH dispatches stronger models itself where they matter

Why default Sonnet now works: measured (see Measured, not asserted below), operating FH is nearly model-flat — the rules in context do most of the work. What still needs a stronger model is a small set of depth-sensitive turns, and FH handles those itself: some skills and agents declare a model-tier floor (e.g. quench-challenger floors at opus) and are dispatched as sub-agents at the floor tier when your environment can reach it — your session model stays untouched. FH never switches your session model: a default you set by hand is followed; floors apply only to FH's own sub-agent dispatches. If your environment tops out below a floor (e.g. Sonnet-only API routing), the floored asset still runs at