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

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.

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:

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.

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:

Most harness projects cover 2–4 of these. sd0x-dev-flow covers all 10 — which makes the code useful as a study target, not just a tool.

How It Works

flowchart LR
    P["🎯 Plan"] --> B["🔨 Build"]
    B --> G["🛡️ Gate"]
    G --> S["🚀 Ship"]

    P -.- P1["/codex-brainstorm<br/>/feasibility-study<br/>/tech-spec"]
    B -.- B1["/feature-dev<br/>/bug-fix<br/>/codex-implement"]
    G -.- G1["/codex-review-fast<br/>/precommit<br/>/codex-test-review"]
    S -.- S1["/smart-commit<br/>/push-ci<br/>/create-pr<br/>/pr-review"]

Everything orbits one rule — the terminal completion invariant: work on a change may be declared complete only when every gate its change class requires has passed after the last edit in that class. Code edits require an independent review — Codex by default, or a validated contract-aware fallback reviewer when Codex is unavailable — then /precommit; .md docs require /codex-review-doc. When to run them, how to batch edits, and how deep to review are the model's calls — the invariant constrains the end state, not the choreography.

Hooks report facts, not orders: they print reminders and an [AUTO_LOOP_STATE] fact line (change class, per-plane verdict state) and the model owns the decision. What blocks comes from the tier (fast P0 · standard P0/P1 · thorough P0/P1/P2); findings below that line are logged and the loop proceeds rather than opening another round. A stall — three review rounds that close nothing, counted by the model — or, as a backstop, hitting the round cap triggers a structured self-diagnosis (architecture problem? doc too long? attention diffusion?) and one bounded adjustment before the loop resumes, rather than an automatic hand-off; the human exits stay in force whichever trigger fired (security and data-integrity changes skip the diagnosis entirely; a stall diagnosed as architecture-level or requirement ambiguity goes to the human).

There is no enforcement mode (hook-lightweighting, 2026-08-13): every review-layer hook is a reminder that exits 0. The reviewer's report is what establishes the verdict; the model then records it (node scripts/review-state.js note <plane> <pass|fail>, digest-bound — an edit re-opens its plane) to retire the reminder. A verdict never noted still stands — it just keeps its reminder alive — and the honest way to silence a reminder is to run the gate and note the outcome. The guards outside the review layer keep their teeth: pre-edit-guard still blocks sensitive-path edits (when jq is available; without it the guard does not fire), and the git-level guards remain hard where installed (commit-msg-guard by default, pre-push-gate opt-in).

A second reviewer is available via /codex-review-branch --dual and is off by default. See docs/hooks.md for hook and dependency details.

sequenceDiagram
    participant D as Developer
    participant C as Claude
    participant X as Codex exec
    participant H as Hooks

    D->>C: Edit code
    H->>H: Reminder state re-opens (digest changed)
    C->>X: Codex review (sandbox, researches repo itself)
    X-->>C: Findings + gate sentinel
    C->>C: note the verdict (review-state.js)
    C->>C: Gate on the tier's blocking severity

    alt Blocking findings
        C->>C: Fix them (sub-threshold: log and move on)
        alt R-a threshold (3 replies; override 2–6) or R-b context overrun
            C->>X: Fresh first dispatch on a new thread (frozen baseline rides along)
            X-->>C: Fresh report
            C->>C: Reconcile old findings onto the fresh report, re-derive the gate
            C->>C: Record [THREAD_ROTATED] (old → new threadId)
        else Under threshold
            C->>X: codex exec resume <threadId>
            X-->>C: Re-verify
        end
        Note over C,X: Rotation keeps the frozen scope baseline; stall streaks and round caps continue unreset
    end

    C->>C: /precommit (auto)
    C-->>D: ✅ All gates passed

    Note over H: Stop: owed gates re-reminded — never blocked

Feature Spotlight: Tiered Review

One reviewer — Codex — runs everywhere by default. The tier decides how much rigour a change gets, and what a reviewer finding has to be before it re-opens the loop:

The configured tier is a baseline, not a ceiling — the model escalates when the change warrants it, and security or data-integrity changes are always reviewed at thorough whatever is configured.

80 is a passing grade. Findings below the tier's blocking severity are logged ([NIT_DEFERRED] — a reporting convention in the review report; nothing persists it) and the loop proceeds to /precommit — no extra fix pass, no extra review round. /codex-review-branch picks them up when the change is next reviewed at depth.

The round caps above are deliberately loose, because a cap cannot tell a converging loop from a churning one — it stops both at the same number. What tells them apart is the evidence: three consecutive review rounds that close no findings — counted by the model from the review reports, normally many rounds before the cap — trigger the diagnosis below. The cap is left as the runaway backstop.

The round caps above are the tier defaults — a project ## Max Rounds override (3–50) takes precedence. Hitting the cap is a diagnosis point, not an automatic hand-off: the model classifies the stall (architecture, doc too long, attention diffusion, unverified claims, tier mismatch, requirement ambiguity), makes one bounded adjustment, and resumes. The human exits stay binding whichever trigger fired: security/data-integrity changes skip the diagnosis and go straight to the human, a stall classified as architecture-level or requirement ambiguity exits to the human, and the same change hitting the cap a second time after its diagnosis always does. (Architecture-level changes, feature removal, or a user request to stop exit to the human at any point — cap or no cap.)

A second reviewer is available via /codex-review-branch --dual and is off unless the flag is passed — worth its doubled token and wall-clock cost on a release or a security review, not on a typical fix. Under --dual, findings are severity-normalized, deduplicated (file + issue key, ±5 line tolerance) and source-attributed.

Gate: ✅ Ready or ⛔ Blocked — behaviour-layer signals the model acts on; the verdict is noted into the reminder state.

When to Use

Workflow Tracks

flowchart TD
    subgraph feat ["🔨 Feature Development"]
        F1["/feature-dev"] --> F2["Code + Tests"]
        F2 --> F3["/verify"]
        F3 --> F4["/codex-review-fast"]
        F4 --> F5["/precommit"]
        F5 --> F6["/update-docs"]
    end

    subgraph fix ["🐛 Bug Fix"]
        B1["/issue-analyze"] --> B2["/bug-fix"]
        B2 --> B3["Fix + Regression test"]
        B3 --> B4["/verify"]
        B4 --> B5["/codex-review-fast"]
        B5 --> B6["/precommit"]
    end

    subgraph docs ["📝 Docs Only"]
        D1["Edit .md"] --> D2["/codex-review-doc"]
        D2 --> D3["Done"]
    end

    subgraph plan ["🎯 Planning"]
        P1["/codex-brainstorm"] --> P2["/feasibility-study"]
        P2 --> P3["/tech-spec"]
        P3 --> P4["/codex-architect"]
        P4 --> P5["Implementation ready"]
    end

    subgraph ops ["⚙️ Operations"]
        O1["/project-setup"] --> O2["/repo-intake"]
        O2 --> O3["Develop"]
        O3 --> O4["/project-audit"]
        O3 --> O7["/best-practices"]
        O3 --> O5["/risk-assess"]
        O4 --> O6["/next-step --go"]
        O5 --> O6
        O7 --> O6
    end

Cookbook

Real-world scenarios showing which skills to combine and in what order.