sd0x-dev-flow

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

The harness layer for Claude Code.

Quality gates that AI can't skip. A reference implementation of AI Agent Harness Engineering for Claude Code — hook-enforced review gates, state-machine gates that survive context compaction, and fail-closed safety where it counts.

98 bundled · 98 public skills · 15 agents — ~4% of Claude's context window

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.

Why sd0x-dev-flow?

Quick Start

# Install plugin
/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).

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"]

The auto-loop engine enforces quality gates automatically — after code edits, the review command dispatches Codex in the same reply. 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. In strict mode, hooks enforce fail-closed semantics: if the gate is incomplete, stop-guard blocks. 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:

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.

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.

How We Compare

When to Use

Install

Codex CLI / Other AI Agents

# Install individual skills via Agent Skills standard
npx skills add sd0xdev/sd0x-dev-flow

# Generate AGENTS.md + install hooks (in 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)

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

Development (33)

Review (Codex MCP) (15)

Verification (13)

Planning (17)

Documentation & Tooling (20)

Rules & Hooks

15 rules (always-loaded conventions) + 8 hooks (automated guardrails).

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:

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

Command (entry) → Skill (capability) → Agent (environment)

• Commands: User-triggered via /...
• Skills: Knowledge bases loaded on demand
• Agents: Isolated subagents with specific tools
• Hooks: Automated guardrails (format, review state, stop guard)
• Rules: Always-on conventions (auto-loaded)

For advanced architecture details (agentic control stack, control loop theory, sandbox rules), see docs/architecture.md.

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