# Harness

> Use when a substantial request needs verified, non-repetitive output. Triggers on: "이거 제대로 해줘", "검증까지 해서", "하네스 돌려줘", "run the harness", "do this properly with verification", "6단계로 처리해줘", "메타스크립트로". Not for trivial edits or Q&A.

- Skill: `newkayak12/harness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add newkayak12/harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/newkayak12/harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: newkayak12 (https://skillmd.com/u/newkayak12)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/newkayak12/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`](../../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.