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

# 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 ~/forge-harness
cd ~/forge-harness

# 3. Start a session
claude

✅ Claude reads CLAUDE.md and asks what project to connect or what task to start. Say "Connect a project" → hub scans ../, finds .git directories, creates tracks/{project}/.

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 is the goal it is built toward. In practice it works in four ways:

① Assemble — FH runs a cluster of harnesses at optimized token cost and hands you the right one for the project. You don't wire up skills one by one; you get a harness — its plugins, skills, and agents included — assembled to fit.

② Forge (the quality gate) — every change earns its way through adversarial · phantom · regression gates. This is not "check more." It is a responsibility router: as automation rises, human sign-offs get fewer but heavier, so the gate spends your attention only where a change is irreversible. Quality is the lever; the speed is the result.

③ Sidecar — capability itself stays on the frontier. FH dispatches across multiple LLMs (Claude, Codex, Gemini, local) so raw power is never tied to one model or one generation. The point is not patching each model's weak spots — that scaffolding dies as models improve. It is riding the frontier's evolution: shed what the substrate now does natively, absorb what it ships next. Decorrelation is today's trust lever (a cross-family panel beats a single model's ceiling); co-evolution is the structure.

④ Self-evolving loop — the harness gets better without being rebuilt, in two directions: outward, where each session's lessons compound into the hub so the next project starts faster, and inward, where it catches and repairs its own defects (the 4-axis gate, bidirectional verify, per-user adaptation).

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

Self-healing here isn't a claim — it's in the commit log. This very README's voice rules were fixed mid-session by FH catching its own drift: a tone miss → diagnosis → a cross-family challenger that attacked its own first fix → re-fix → floor-tier re-verification → memory update. A harness repairing its own defect, on the record — not a slogan.

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

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.

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.

38 skills · 8 agents

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

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 §Model setup evidence note 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 the best available tier with an explicit below-floor flag in its output — degraded delivery is visible, never silent (tier-floor resolution: knowledge/shared/harness-core/multi_model_sidecar_strategy.md §Tier-floor).

opusplan caveat (measured): its Opus engagement is not guaranteed — in a measured 10-turn run it used Opus on 0 turns (CC classifies few turns as "plan-mode"). If you want Opus on every turn, pin /model opus (22/22 turns Opus in the follow-up run). Sub-agent dispatch model is set by the dispatch's own model parameter; the session model/plan-mode does not propagate to sub-agents.

By role: running FH (field projects, gates, routine dev) → /model sonnet + let the floors escalate. Editing the harness itself (Mode D) → pin the strongest model you have — harness self-development is where tier depth measurably pays (design-increment finding), while operation does not. Sub-agent token costs are CC-visible in the session jsonl under message.model.

Measured, not asserted (worked examples): on a blind rule-application battery, operating FH is near model-flat — every Claude tier measured scores 94–100% (Fable, Opus 4.8, Sonnet 4.6 and 5, Haiku 4.5); the few lost points are format discipline, never a trap or gate-class miss. The tiers separate only on above-rubric design increments (developing the harness, not running it) — which is why the default is Sonnet with tier-floored dispatch covering the depth-sensitive turns, and a pinned stronger model is recommended only for harness-editing sessions.

This is stated as an invariant, not a per-model leaderboard. Two structural laws, neither of which a new release overturns:

1. Operation flattens across tiers — the rules-in-context do the work, so every tier ceilings on rule-application (Sonnet 5 tied Opus 4.8 at the battery ceiling in a 2026-07-03 replication).
2. Depth (design increments) is tier-ordered, and the order is fixed within a generation — a lower tier never overtakes the higher of the same generation (tiers are priced to be worth it, so the vendor keeps them ordered). Across generations a newer lower-tier model can surpass an older higher-tier one (Sonnet 5 ≥ Opus 4.8 on operation is exactly this cross-generation case) — but the current top tier of any generation still wins its own depth turns.

So the doctrine is permanent, not perishable: default to the mid tier for operation; escalate to the current top tier for depth. Re-measurement is warranted only when a new model becomes a field-main candidate (a one-time cross-generation threshold check), never to re-confirm same-generation tier order — that is guaranteed by design. Details + dated runs: docs/OUTPUT_EVIDENCE.md §Validation signals.

If you use external CLIs (Gemini, Codex, gh copilot) as sidecars, their costs are billed to their own quota and not visible in CC's token display.

Hardware tiers (local sidecars are optional accelerators)

FH needs no local LLM — the baseline is whatever runs Claude Code. Local models are optional, for the canary / cheap-breadth rungs only:

Local tiers are canaries, never the terminal verdict — measured: the floor model missed a subtle adversarial case the frontier caught (and even a 27–32B local scored 1/4 on it). They lower the cost of breadth; the verdict stays frontier.

Multi-Model Sidecar

Run Gemini, Codex, or gh copilot as independent reviewers alongside Claude. The point is context isolation: a reviewer that did not co-create the work is cold to its froth — whoever sits outside the collaboration tends to catch what the co-author, now an advocate for the shared result, glides past. It's symmetric, not a model-ranking: when you co-build with Gemini, a fresh Claude catches its froth; when you co-build with Claude, a fresh sidecar catches Claude's.

In one internal case study, layering reviewers surfaced progressively more issues — a single in-session pass missed items that cross-session personas caught, and an external-CLI reviewer surfaced a few the Claude personas shared a blind spot on. Treat it as a worked example, not a benchmark: the gain scales with task complexity and how much you co-created the artifact, and an isolated reviewer also adds false positives you have to triage. Whether the net is worth it on a given task is an empirical, per-use question.

Claude-side token cost does not increase when the extra reviewer is an external CLI — it bills to its own quota.

Research

FH papers — the methodology below is documented, not just asserted:

• v1.0 — methodology · Zenodo (DOI 10.5281/zenodo.20397566). 2-layer design, 6-axis framework, 4-agent orchestration, and the compounding loop, with empirical evidence.
• cs.SE companion — governance-gate methodology · published Zenodo (DOI 10.5281/zenodo.20680081 · latest v1.1 10.5281/zenodo.20740038 · CC-BY-4.0) · arXiv submitted (cs.SE, in moderation).
• cs.AI companion — "Governance Dividend" · in preparation.

External convergence:

• "Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems" — arXiv April 2026
• "Code as Agent Harness" — arXiv May 2026
• Stanford IRIS Lab: "Meta-Harness" — +7.7pts at 4× fewer tokens

Learn more