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 preserve gate receipts across compaction, and Codex reviews independently.

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

98 bundled · 98 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 15 rules + 8 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

# Generate AGENTS.md + install git hooks (run inside Claude Code)
/codex-setup init

Requirements: Claude Code 2.1+ | 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)

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 emit [AUTO_LOOP_STATE] blocks (change class, gate receipts, round/cap, tier) 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. 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, though the cap-specific human exits stay in force (security and data-integrity changes skip the diagnosis entirely; a stall diagnosed as architecture-level or requirement ambiguity goes to the human).

Enforcement has two modes:

A second reviewer is available via /codex-review-branch --dual and is off by default. See docs/hooks.md for mode 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: Track file change
    C->>X: Codex review (sandbox, researches repo itself)
    X-->>C: Findings + gate sentinel
    H->>H: Parse sentinel into code_review.passed
    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: Strict mode: incomplete gate → 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], persisted with a TTL so they are not re-raised next session) 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 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 cap-specific human exits stay binding: 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 — in strict mode, incomplete gate = blocked.

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

15 rules + 8 hooks. The rules are tiered contracts: discretion.md resolves every instruction in the 12 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 hooks are fact publishers and guardrails: they record gate receipts and re-inject state after compaction; stop-guard blocks incomplete-review stops in strict mode, while pre-edit-guard rejects sensitive-path edits in any mode.

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