sd0x-dev-flow

sd0x-dev-flow

Language: English | 繁體中文 | 简体中文 | 日本語 | 한국어 | Español

The harness layer for Claude Code.

Let the model choose the path. Keep "done" verifiable.

v4 gives Claude discretion inside a closed, test-pinned anchor set; hooks are digest-bound reminders that survive compaction, and Codex reviews independently.

Full control plane on Claude Code. Skills-only distribution for Codex CLI and other compatible agents.

99 bundled · 99 public skills · 16 agents — ~4% of Claude's context window

Quick Start

# Claude Code — full control plane
/plugin marketplace add sd0xdev/sd0x-harness
/plugin install sd0x-dev-flow@sd0xdev-marketplace

# Configure your project
/project-setup

One command auto-detects framework, package manager, database, entrypoints, and scripts. Installs a subset of rules and hooks; the full plugin bundles 16 rules + 6 hooks. Use --lite to only configure CLAUDE.md (skip rules/hooks).

# Codex CLI / Cursor / Windsurf / Aider — skills only
npx skills add sd0xdev/sd0x-harness

Then, inside Codex CLI, generate the AGENTS.md kernel and install the commit-msg hook. The pre-push gate is opt-in — add --with-push-gate to install it too:

$codex-setup init

Method	Tools	Coverage
Plugin install	Claude Code	Full (99 bundled skills, hooks, rules, auto-loop)
npx skills add	Codex CLI, Cursor, Windsurf, Aider	Skills only (99 public skills)
$codex-setup init	Codex CLI	AGENTS.md kernel + commit-msg hook (pre-push gate opt-in)

Requirements: Claude Code 2.1+ | Node.js 18+ | jq (pre-edit-guard and post-edit-format parse their hook payload with it — without jq both exit 0, so the sensitive-path guard and auto-formatting are silently off) | Codex CLI (optional to install the plugin; the default reviewer for the /codex-* review gates — on codex_fail — the adapter's start or resume exiting 1, and nothing else — the gate is carried by a contract-aware fallback reviewer under the same mechanism, fail-closed per family contract with [REVIEWER_FALLBACK] recorded; a missing adapter, a configuration error, an unfinished run, or an alloc/cleanup failure dispatches no fallback, records no marker and leaves the gate open, and only when every carrier is exhausted does the review surface ⚠️ Need Human instead of a verdict)

Codex exec setup

The review loop talks to Codex through codex exec, driven by a small adapter. There is no MCP server to register: this plugin no longer dispatches through codex mcp-server.

1. In a shell — install the Codex CLI (>= 0.149.0) and sign in:

codex --version

2. In Claude Code — install the transport adapter into this project. This is a slash command, not a shell command; typed into a terminal it would try to run an absolute path:

/sd0x-dev-flow:install-scripts codex-exec.js

Step 2 is optional: the first review that needs the adapter auto-installs it, using the same three-level lookup precommit-fast uses for its runner. Run it explicitly when you would rather the install not happen inside a review.

Model and reasoning effort now live in a Codex profile, not on a registration command. Name one in rules/auto-loop-project.md:

## Codex Profile

review

That name resolves to $CODEX_HOME/<name>.config.toml — the profile-v2 form codex exec -p layers on top of your base user config (codex exec --help: "Layer $CODEX_HOME/<name>.config.toml on top of the base user config"). So a review profile holding model_reasoning_effort = "high" gives the review loop the depth the old -c override gave it, and leaves your interactive Codex sessions alone. Leaving ## Codex Profile empty is fine: the adapter then passes no -p and Codex uses its own default configuration.

The adapter pins the sandbox and the approval policy itself for every dispatch, so neither is a setup decision — see skills/codex-code-review/references/codex-transport.md for the full contract.

Why v4

Frontier models can plan, batch, and recover from structured state — they no longer need the harness to dictate every next command. v4 moves from choreography to contracts: the harness stopped scripting the model's moves and started defining what must be true when the work is declared done, without relaxing a single safety or review anchor.

Dimension	v3 (choreography)	v4 (contracts)
Hook role	Emit the next command to run	Print reminders + [AUTO_LOOP_STATE] facts — change class, per-plane verdict state
Completion	Scripted step sequence ("fix → immediately re-review")	Terminal completion invariant: every gate the change class requires has passed after the last edit
Rule force	Uniform — every rule reads as mandatory	Three tiers: Anchor (never), Default (deviate with a stated signal), Guidance (advisory)
Review depth	Maximum by default	Risk-scaled tiers (fast / standard / thorough); security and data integrity always escalate
Stall detected / round cap hit	Hand off to the human	First hit: structured self-diagnosis + one bounded adjustment, then resume — unless a human exit applies (security/data-integrity, architecture-level change, requirement ambiguity); the same change hitting the cap again after its diagnosis: always human

The non-negotiable core lives in a closed Anchor Register (rules/discretion.md) that no project override can downgrade — resolution is Anchor-first, and a test suite fails by design if a Register entry is removed. Inside that boundary, ownership is explicit:

Owner	Owns
Model	Batching, timing, review depth escalation, Default-tier deviations (stated, then keep working)
Harness	Digest-bound reminder state, git-level guards (commit-msg by default, pre-push opt-in), the closed anchor set
Human	Irreversible approvals (push, commit, merge) and the enumerated exit points

The model owns the path. The harness owns the evidence and non-negotiable boundaries. The human retains irreversible authority.

What's New in 4.4

If you notice review quality drop after upgrading to 4.4.0 — real defects slipping through, or reviews converging too eagerly — please open an issue. This release changes review judgment, and field reports are the only way to validate it.

The plain-language version: the auto-loop used to let reviews dig ever deeper — a reviewer would flag a weak test, the fix added a stronger guard, the next round attacked that guard, and so on. We measured a real case: 9 review rounds where 7 of 8 blocking findings were about the test guards' own strength, and none were about the delivered change. 4.4 draws a line: once a property is demonstrated in both directions on its real path, further hardening of that property is non-blocking unless an AC or security invariant requires it.

What changed	Before	After
Where assurance stops	A guard could always be asked to guard the guard	A refusing test proves both directions on the actual path — that representative proof is the boundary; deeper hardening is a non-blocking Nit unless an AC or security invariant demands it
The "Prevention" field	Read as "every fix must add another guard artifact" — the seed of the spiral	An explanation of which existing control catches the class; usually the regression test the fix already ships
Review dispatch	Re-dispatches could accumulate "attack X next" directions, anchoring reviewers deeper each round	A fixed three-part contract: frozen task (task, baseline, ACs, user-supplied focus), current facts, fixed review contract — attack lists are a prohibited pattern
Reviewer framing	"Focus on finding issues"	"Focus on material defects" — plus an assurance boundary and a boundary check replacing the open-ended gap check
Design thinking	Left to review, after the code exists	Nudged at write time: when the shape is non-obvious, name the simplest design chosen and why — questions, not quotas

Why we believe this is right (and why we still want your reports): IFScale measures model-specific adherence degradation as instruction density rises from 10 to 500 simultaneous instructions; context-rot research finds longer contexts and topically related distractors reduce reliability; and Vercel's agent evals found an always-present documentation index scored 100% where a skill with explicit trigger instructions scored 79% — instruction load and unclear contracts have measurable costs. The auto-loop core is untouched: the terminal completion invariant, edit-reopens-gate, sub-threshold discipline, stall diagnosis, and every safety anchor remain exactly as they were.

What This Harness Does

Harness engineering is the discipline of engineering everything around the LLM — tool loops, context management, hooks, state machines, safety layers — as opposed to training the model itself. Mitchell Hashimoto coined the term in Feb 2026; Anthropic engineering and Martin Fowler have published on it; arXiv 2603.05344 formalizes it.

sd0x-dev-flow is a reference implementation. Each row below maps a canonical harness sub-problem to concrete code you can study:

#	Harness sub-problem	sd0x-dev-flow implementation	Code evidence
1	Tool loop control	Terminal completion invariant — every gate a change class requires must pass after the last edit; the model chooses when and how to run them	rules/auto-loop.md + scripts/review-state.js
2	Digest-bound reminder state	Verdicts are noted by the model (node scripts/review-state.js note <plane> <pass|fail>) and bound to the tree digest — an edit re-opens its plane's reminder because the digest changed; gate sentinels (✅ Ready / ## Overall: ✅ PASS) stay behaviour-layer signals	scripts/review-state.js + rules/auto-loop.md (§ Gate Sentinels, § Enforcement)
3	Context recovery across compaction	Git baseline (branch + uncommitted files) and owed-gate reminders re-injected after SessionStart(compact)	hooks/post-compact-auto-loop.sh
4	Lifecycle interceptors	5 hook event types dispatched to 6 scripts — 4 advisory reminder hooks, an auto-formatter, and one blocking security guard (SessionStart additionally runs scripts/namespace-hint.sh): PreToolUse / PostToolUse / Stop / SessionStart / UserPromptSubmit	hooks/ (6 scripts) + .claude/settings.json