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 · 15 agents — ~4% of Claude's context window

Quick Start

# Claude Code — full control plane
/plugin marketplace add sd0xdev/sd0x-dev-flow
/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-dev-flow

Then, inside Codex CLI, generate the AGENTS.md kernel and install the git hooks:

$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 MCP (optional to install the plugin, required for the /codex-* review gates — Codex is the single reviewer, so without it a review emits ⛔ Blocked + ⚠️ Need Human rather than degrading)

Codex MCP registration

claude mcp add codex -- codex mcp-server -c 'model_reasoning_effort="high"'

-c 'model_reasoning_effort="high"' is the default here because reviewing is the workload that pays for depth (rules/auto-loop.md § Review Dispatch applies the same principle to agents/ frontmatter). It is a default, not a requirement — adjust or drop the value for your own effort/latency tradeoff. -c itself works whether it precedes or follows the mcp-server subcommand (both are documented, identically, by codex --help and codex mcp-server --help); after the subcommand is shown above only because that is the form codex mcp-server --help lists.

--profile cannot be used with codex mcp-server at all — codex --profile <name> mcp-server fails outright (codex-cli 0.146.0, verbatim):

Error: --profile only applies to runtime commands and `codex mcp`: `codex`, `codex exec`, `codex
review`, `codex resume`, `codex archive`, `codex delete`, `codex unarchive`, `codex fork`, `codex
mcp`, `codex sandbox`, and `codex debug prompt-input`.

mcp-server is not in that list, so a config profile cannot reach the review MCP server this way — set -c overrides directly on the registration command instead.

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 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 Codex review 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. A verdict exists when the model notes it (node scripts/review-state.js note <plane> <pass|fail>, digest-bound — an edit re-opens its plane), 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 (commit-msg-guard, pre-push-gate) remain hard.

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 MCP
    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)
        C->>X: --continue threadId
        X-->>C: Re-verify
    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.

All 10 scenarios →

What's Included

Minimal Context Footprint

~4% of Claude's 200k context window — 96% remains for your code.

Skills load on-demand. Idle skills cost zero tokens.

Skill Reference

Rules & Hooks

16 rules + 6 hooks. The rules are tiered contracts: discretion.md resolves every instruction in the 13 plugin-managed rule files to exactly one of Anchor / Default / Guidance, and the 2 user-owned override files resolve Anchor-first under their parent rules. The hook set is 4 advisory reminder hooks plus an auto-formatter and a blocking security guard. The reminder roles differ per hook: the Stop and post-compact hooks render owed-gate reminders from the digest-bound state (review-state.js), the prompt hook prints the [AUTO_LOOP_STATE] fact line, the post-skill hook prints a static gate-order line, and the post-compact hook also re-injects the git baseline; the review layer never blocks — pre-edit-guard still blocks sensitive-path edits (a security guard; it needs jq and does not fire without it), and the hard gates live at the git level (commit-msg-guard, pre-push-gate).

Customization: Edit auto-loop-project.md to override auto-loop behavior per project. Plugin updates won't conflict — see Rule Override Pattern.

For full rules, hooks, and environment variable reference, see docs/rules.md and docs/hooks.md.

Customization

Run /project-setup to auto-detect and configure all placeholders, or manually edit .claude/CLAUDE.md:

Overrides resolve Anchor-first: user-owned override files (auto-loop-project.md, testing-project.md) customize Default- and Guidance-tier behavior only — no project override can downgrade an entry in the Anchor Register, and an attempt is reported as a conflict rather than honoured.

Showcase: Multi-Agent Research

Run /deep-research to orchestrate 2-3 parallel researcher agents across web sources, codebase, and community knowledge — with claim registry synthesis and conditional adversarial debate.

Full documentation

Architecture

Six layers, each owning one concern:

For advanced architecture details (agentic control stack, control loop theory, sandbox rules), see docs/architecture.md — note that parts of it predate v4 and still describe the v3 choreography; rules/auto-loop.md and rules/discretion.md are the current source of truth.

Contributing

PRs welcome. Please:

1. Follow existing naming conventions (kebab-case)
2. Include When to Use / When NOT to Use in skills
3. Add disable-model-invocation: true for dangerous operations
4. Test with Claude Code before submitting

License

MIT

Star History