Harness

harness — six-stage engine: Plan → SetGoal → Implement → Test → QualityGate → Report

The harness raises the floor, not the ceiling: every substantial request goes through six staged roles so repetition and weak answers get filtered out regardless of the main-session model. Planning and judging are pinned to Opus. Code/repo execution and deterministic verification run on Claude by default — codex_provider defaults to "off" and no external provider is contacted unless a run opts in. When codex_provider IS enabled, every Implement/Test stage delegates to Codex. implement_provider: "codex" / test_provider: "codex" are trace hints, not prerequisites. Sonnet is then only a thin Workflow controller/fallback/report role, not the actor.

Process

0. Graph path (default when the graph-engineering MCP is connected). Hand the raw request to the graph engine and drive the node graph it returns — invoke graph:orchestrate. graph_open({request, cwd, isolated, allocation: "balanced", host_vendor, host_model}) builds plan → setgoal → critique and expands per-subgoal implement/test/gate nodes server-side; you loop graph_next → graph_run (vendor executes; blocks) or graph_submit (you executed it) until the run stops. The spec, handoffs, evidence and verdicts stay on disk; tools return one-line verdicts, so a long retry loop never fills your context and no node can poll a CLI through Bash. Reason to prefer it: measured E2E, the Workflow path's transport subagents cost more tokens than the reasoning stages (6.87M vs 2.06M input), with zero edits made by the transport layer. Fall through to step 1 only when the graph tools are absent.

1. Pass the raw request to the engine (B, Workflow fallback): Workflow({ scriptPath: "harness/engine/pipeline.js", args: { request: "<the request>", context: "<optional constraints>", max_retries: 2 } }) The engine itself plans, authors + critiques the goal-spec, executes subgoals with repo-skill-equipped executors, verifies each deterministically, gates each and the assembled whole, and writes the report.

   • In the Workflow path, codex_provider: "auto" / "required" makes Codex the default route for every Implement/Test stage. A minimal Sonnet controller invokes harness:codex-control, resolves engine/codex-exec-adapter.mjs, and runs a separate local Codex CLI process. On success it only converts Codex output into the normal HANDOFF or evidence JSON. With codex_provider: "auto" a failed route may explicitly degrade to Sonnet fallback; required mode reports provider failure instead. Use codex_provider: "off" to force plain Sonnet implementation and verification.
   • If Dynamic Workflow (DW) is off or the Workflow tool is unavailable (plain Agent SDK, some harnesses, CI): do NOT skip the engine — follow engine/fallback.md instead. First form a role-isolated Agent Team with a thin team lead and separate Plan, SetGoal/Critic, Implement, Test, QualityGate, and Report teammates. Teammates exchange work through files in a run directory (not the lead's context), and engine/fallback-check.mjs remains the objective done-signal. Use the runtime's team primitive when available; otherwise explicitly compose the same logical team from role-separated agents. When Workflow IS available, ignore fallback.md — the pipeline.js path above is unchanged. In fallback mode only, the run auto-detects a local codex CLI; when ready, Implement/Test subgoals route to separate codex exec --json processes while Claude keeps Plan, SetGoal, QualityGate, and Report.
   • If the active orchestrator is Codex itself: do not call codex, codex-exec-adapter.mjs, or codex-runner.mjs recursively. Follow the repository AGENTS.md contract and perform Plan → SetGoal → Implement → Test → QualityGate → Report directly with native Codex tools.

2. M (meta): when the fixed six stages can't express the control flow the request needs — tournament/judge-panel, staged escalation, loop-until-dry discovery, per-finding refuters — or the user explicitly asks ("메타스크립트로", "커스텀 파이프라인으로"), generate the pipeline instead of using the fixed one:

   1. Copy templates/meta-skeleton.js into the scratchpad and rewrite ONLY the [META] Work block (and meta) to the control flow the request needs.
   2. Keep the skeleton's five contract points verbatim: judge ≠ actor; model/provider pins (plan/judge=opus, execute/test=provider-routed, report=sonnet); every loop bounded; deterministic Test agent (Bash/Read evidence, never the actor's narrative); goal-level match_pct >= 90 gate before Report.
   3. Run it: Workflow({ scriptPath: "<scratchpad>/meta-<slug>.js", args: { request, context?, max_retries? } }). Default to B when in doubt — M earns its cost only when the control flow itself is the problem.

3. A (manual): the user hands you a ready-made bespoke script → run it as-is.

4. Relay the returned report to the user. Surface failed[] and a failing goal_gate honestly. Eval and retry already happened inside the engine.

What Claude does

• Phrases args.request faithfully (add known constraints via args.context).
• Invokes the engine; relays report, all_passed, failed[], goal_gate.

What you do

• State the request and its bar. Receive the final report.
• (Optional) watch progress via /workflows — six phase groups are visible.

Optional skill integrations

The engine statically mounts three skills — agents:agent-task-decomposer (Plan), think:devils-advocate (SetGoal critic + QualityGate), completion:verification-before-completion (Test). Codex-enabled Implement/Test stages also mount harness:codex-control to resolve the CLI adapter across plugin, repo-local, and embedded installs. Beyond those, SetGoal MAY optionally map the repo's harness-aware skills — each rewritten dual-mode to run standalone AND as a harness executor — into subgoals when the task fits. None is required; the harness runs without them and each also works on its own:

• write:writing-plans — produce a gate-ready plan / goal-spec-shaped decomposition.
• planning:executing-plans — pre-flight plan gate + executor routing.
• agents:subagent-driven-development — fresh-subagent-per-task execution with two-stage review.
• develop:test-driven-development — drive an Implement subgoal test-first (evidence gate).
• write:writing-skills — author a convention-compliant skill; its pressure test can back a QualityGate.
• agents:dispatching-parallel-agents — allocate independent work across best-fit personas.
• think:brainstorming — diverge/converge before a spec when the request is under-specified.

These are opt-in: SetGoal picks them by relevance from the whole catalogue, so they need no pre-wiring, and using none of them is a valid run.

Related

• harness/goal-spec.md — spec schema (authored by the SetGoal stage) + authoring rules
• harness/skills/codex-control/SKILL.md — adapter discovery contract for Codex CLI delegation
• graph:orchestrate — default orchestration: the harness flow as a node graph owned by the local graph-engineering MCP (graph/mcp/broker.mjs)
• graph:install — connect or verify that MCP without copying the graph engine
• harness/engine/pipeline.js — the fixed six-stage engine (Workflow path)
• harness/engine/fallback.md — DW-off/Workflow-less fallback: same six stages via a role-isolated Agent Team sharing state through a run directory
• harness/engine/fallback-check.mjs — deterministic completion check for a fallback run (the objective done-signal)
• harness/engine/codex-exec-adapter.mjs — CLI bridge that detects Codex and captures codex exec --json events for Claude-orchestrated Workflow Implement/Test delegation and fallback runs
• harness/engine/codex-runner.mjs — legacy/external automation runner; active Codex sessions should not invoke it recursively
• harness/templates/meta-skeleton.js — Mode M starting point (contract + [META] block)
• harness/templates/ — bespoke-pipeline reference
• harness/hooks/ — opt-in PreToolUse gate: projects list gated paths in .claude/harness-gate.json; editing them without engaging the harness is denied (fail-open on any ambiguity).
• harness/skills/install/ — project scaffolding; remove/ reverses it and patch/ prepares synchronized patch-version metadata.