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
| Method | Tools | Coverage |
|---|
| Plugin install | Claude Code | Full (98 bundled skills, hooks, rules, auto-loop) |
npx skills add | Codex CLI, Cursor, Windsurf, Aider | Skills only (98 public skills) |
/codex-setup init | Codex CLI | AGENTS.md kernel + git hooks |
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.
| Dimension | v3 (choreography) | v4 (contracts) |
|---|
| Hook role | Emit the next command to run | Publish [AUTO_LOOP_STATE] facts — change class, gate receipts, round/cap, tier |
| 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 |
| Round cap hit | Hand off to the human | First hit: structured self-diagnosis + one bounded adjustment, then resume — unless a cap-specific 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 | Gate freshness, receipts across compaction, strict-mode blocking, 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 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 + hooks/post-tool-review-state.sh |
| 2 | Sentinel-driven state machine | ✅ Ready / ⛔ Blocked / ## Overall: ✅ PASS gate sentinels parsed into their respective durable state planes; opt-in dual review additionally aggregates via a machine-facing REVIEW_GATE= marker | hooks/post-tool-review-state.sh (sentinel parser) + scripts/emit-review-gate.sh (dual-review REVIEW_GATE= producer) |
| 3 | Context recovery across compaction | [AUTO_LOOP_RESUME] stdout injection after SessionStart(compact) | hooks/post-compact-auto-loop.sh |
| 4 | Lifecycle interceptors | 5 hook event types dispatched to 8 scripts: PreToolUse / PostToolUse / Stop / SessionStart / UserPromptSubmit | hooks/ (8 scripts) + .claude/settings.json |
| 5 | Capability-based tool gating | Skill frontmatter allowed-tools — e.g., /ask has no Edit/Write | 89 of 98 public skills declare allowed-tools |
| 6 | Defense-in-depth safety |
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:
| Mode | Open gate at stop | Enforced by |
|---|
warn (plugin-runtime fallback) | Warning emitted; closing the gate stays the model's obligation | Behavior layer |
strict (default when installed via /project-setup) | Stop is blocked until the gate passes — fail-closed | Hook |
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:
| Tier | Use for | Blocks on | Round cap |
|---|
fast | Docs, config, small low-risk edits | P0 | 3 |
standard (default) | Ordinary features and bug fixes | P0, P1 | 5 |
thorough | Security, data integrity, releases, public API | P0, P1, P2 | 30 |
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
| Good Fit | Not Ideal |
|---|
| Solo or small-team projects with Claude Code | Teams not using Claude Code |
| Projects needing automated review gates | One-off scripts with no CI |
| Codex CLI / Cursor / Windsurf users (skills subset) | Projects requiring custom LLM providers |
| Repos where quality gates prevent regressions | Repos with no test infrastructure |
Workflow Tracks
| Workflow | Commands | Gate | Receipts |
|---|
| Feature | /feature-dev → /verify → /codex-review-fast → /precommit | ✅/⛔ | Hook-tracked (blocks in strict mode) |
| Bug Fix | /issue-analyze → /bug-fix → /verify → /precommit | ✅/⛔ | Hook-tracked (blocks in strict mode) |
| Auto-Loop | Code edit → /codex-review-fast → /precommit | ✅/⛔ | Hook-tracked (blocks in strict mode) |
| Doc Review | .md edit → /codex-review-doc | ✅/⛔ | Hook-tracked (blocks in strict mode) |
| Planning | /codex-brainstorm → /feasibility-study → /tech-spec | — | — |
| Onboarding | /project-setup → /repo-intake | — | — |
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.
| Scenario | Flow | Docs |
|---|
| First day in a repo | /project-setup → /repo-intake → /next-step | → |
| Implement a new feature | /feature-dev → /verify → /codex-test-review → /codex-review-fast → /precommit | → |
| Resolve PR review comments | /load-pr-review → fix → /codex-review-fast → /push-ci | → |
| Security pre-merge pass | /codex-security → /dep-audit → /risk-assess → /pre-pr-audit | → |
| Showcase: Validate direction | /deep-research → /best-practices → /feasibility-study → /codex-brainstorm | → |
| Showcase: Adversarial design | /codex-brainstorm (Nash equilibrium debate) → /codex-architect | → |
All 10 scenarios →
What's Included
| Category | Count | Examples |
|---|
| Skills | 98 public (98 bundled) | /project-setup, /codex-review-fast, /verify, /smart-commit, /deep-research |
| Agents | 15 | strict-reviewer, verify-app, coverage-analyst, architecture-designer |
| Hooks | 8 | pre-edit-guard, auto-format, review state tracking, stop guard, post-compact-auto-loop, post-skill-auto-loop, user-prompt-review-guard, session-init |
| Rules | 15 | auto-loop, auto-loop-project, codex-invocation, security, testing, git-workflow, self-improvement, context-management |
| Scripts | 18 | precommit runner, verify runner, dep audit, namespace hint, skill runner, commit-msg guard, pre-push gate, emit-review-gate, emit-plan-gate, build-codex-artifacts, resolve-feature (CLI + shell), classify-docs, detect-scope, migration-audit, security-redact, readme-catalog |
Minimal Context Footprint
~4% of Claude's 200k context window — 96% remains for your code.
| Component | Tokens | % of 200k |
|---|
| Rules (always loaded) | 5.1k | 2.6% |
| Skills (on-demand) | 1.9k | 1.0% |
| Agents | 791 | 0.4% |
| Total | ~8k | ~4% |
Skills load on-demand. Idle skills cost zero tokens.
Skill Reference
| Skill | Use when |
|---|
/project-setup | First-time project configuration |
/bug-fix | Fixing bugs and resolving issues |
/feature-dev | Implementing new features end-to-end |
/smart-commit | Committing changes with smart grouping |
/push-ci | Pushing code and monitoring CI |
/create-pr | Creating GitHub pull requests |
/codex-review-fast | Quick code review (diff only) |
/codex-review-doc | Reviewing documentation changes |
/codex-security | OWASP Top 10 security audit |
/verify | Running full test verification chain |
/precommit | Pre-commit quality gate (lint + build + test) |
/precommit-fast | Quick pre-commit (lint + test, no build) |
/codex-brainstorm | Adversarial brainstorming (Nash equilibrium) |
/tech-spec | Writing technical specifications |
/pr-review | PR self-review before merge |
Development (33)
| Skill | Description |
|---|
/ask | Context-aware Q&A with auto context gathering. |
/bug-fix | Bug fix workflow. |
/bump-version | Bump package and plugin version in sync. |
/code-explore | Pure Claude code investigation. |
/code-investigate | Dual-perspective code investigation. |
/codex-architect | Codex architecture consulting. |
/codex-implement | Implement features via Codex MCP. |
/codex-setup | Initialize sd0x-dev-flow infrastructure for Codex CLI and other non-Claude agents. |
/create-pr | Create or update GitHub PR with gh CLI. |
/debug | Interactive debugging workflow with hypothesis-driven probe loop. |
/deep-explore | Multi-wave parallel code exploration orchestrator. |
/epic-merge | Sequential squash-merge of stacked PR chains into an epic branch. |
/feature-dev | Feature development workflow. |
/feature-verify | Feature verification (READ-ONLY, P0-P5). |
/git-investigate | Git history investigation. |
/git-profile | Git identity and GPG signing profile manager. |
/install-hooks | Install plugin hooks into project .claude/ for persistent use without plugin loaded |
/install-rules | Install plugin rules into project .claude/rules/ for persistent use without plugin loaded |
/install-scripts | Install plugin runner scripts into project .claude/scripts/ for persistent use without plugin loaded |
/issue-analyze | GitHub Issue and PR review thread deep analysis with Codex blind verdict. |
/jira | Jira integration — view issues, generate branches, create tickets, transition status. |
|
Review (Codex MCP) (15)
| Skill | Description | Loop Support |
|---|
/codex-cli-review | Code review via Codex CLI with full disk access. | - |
/codex-code-review | Code review using Codex MCP. | - |
/codex-explain | Explain complex code via Codex MCP. | - |
/codex-review | Full second-opinion using Codex MCP (with lint:fix + build). | --continue <threadId> |
/codex-review-branch | Fully automated review of an entire feature branch using Codex MCP | - |
/codex-review-doc | Review documents using Codex MCP. | --continue <threadId> |
/codex-review-fast | Quick second-opinion using Codex MCP (diff only, no tests). | --continue <threadId> |
/codex-security | OWASP Top 10 security review using Codex MCP. | --continue <threadId> |
/codex-test-gen | Generate unit tests for specified functions using Codex MCP | - |
/codex-test-review | Review test case sufficiency using Codex MCP, suggest additional edge cases. | --continue <threadId> |
/doc-review | Document review via Codex MCP. | - |
/plan-review | Pre-ExitPlanMode adversarial plan review loop via Codex MCP. | - |
/security-review | Security review via Codex MCP. | - |
/seek-verdict | Independent second-opinion verification for any finding. | - |
/test-review | Test coverage review via Codex MCP. | - |
Verification (13)
| Skill | Description |
|---|
/best-practices | Industry best practices conformance audit with mandatory adversarial debate. |
/check-coverage | Comprehensive assessment of Unit / Integration / E2E three-layer test coverage, identify gaps and provide actionable ... |
/dep-audit | Audit dependency security risks |
/dev-security-audit | Comprehensive developer workstation security audit — scans for exposed credentials, compromised application data, per... |
/necessity-audit | Necessity audit for over-designed spec elements. |
/pre-pr-audit | Pre-PR confidence audit with 5-dimension scoring. |
/precommit | Pre-commit checks — lint:fix -> build -> test |
/precommit-fast | Quick pre-commit checks — lint:fix -> test |
/project-audit | Project health audit with deterministic scoring. |
/risk-assess | Uncommitted code risk assessment with breaking change detection, blast radius analysis, and scope metrics. |
/test-deep | Context-aware test orchestration. |
/test-health | Holistic test coverage measurement. |
/verify | Verification loop — lint -> typecheck -> unit -> integration -> e2e |
Planning (17)
| Skill | Description |
|---|
/architecture | Architecture design and documentation. |
/codex-brainstorm | Adversarial brainstorming via Claude+Codex debate. |
/deep-analyze | Deep-dive analysis of an initial proposal — research code implementation, produce an actionable roadmap and alternatives |
/deep-research | Universal multi-source research orchestration. |
/feasibility-study | Feasibility analysis from first principles. |
/fp-brief | First-principles briefing from technical documents. |
/orchestrate | Agent-driven workflow orchestration (v1 report-only). |
/post-dev-recap | Post-development recap wrapper. |
/project-brief | Convert a technical spec into a PM/CTO-readable executive summary. |
/recap-ask | Interactive Q&A over an existing recap document. |
/recap-doc | Post-development recap document generator. |
/req-analyze | Requirements analysis — problem decomposition, stakeholder scan, requirement structuring. |
/request-tracking | Request tracking knowledge base. |
/review-spec | Review technical spec documents from completeness, feasibility, risk, and code consistency perspectives. |
/tech-brief | Technical briefing for developer sharing. |
/tech-spec | Tech spec generation and review. |
/ui-first-principles | First-principles UI/IA reasoning: turns a <scenario> + API field set into JTBD analysis, principle-anchored field-p... |
Documentation & Tooling (20)
| Skill | Description |
|---|
/claude-health | Claude Code config health check + plugin sync. |
/contract-decode | EVM contract error and calldata decoder. |
/create-request | Create, update, or scan per-task request tickets for progress tracking. |
/de-ai-flavor | Remove AI artifacts from documents. |
/doc-refactor | Refactor documents — simplify without losing information, visualize flows with sequenceDiagram. |
/generate-runner | Generate a customized precommit runner for any ecosystem. |
/obsidian-cli | Obsidian vault integration via official CLI. |
/op-session | Initialize 1Password CLI session for Claude Code. |
/portfolio | Portfolio system knowledge base. |
/pr-review | PR self-review — review changes, produce checklist, update rules |
/pr-summary | List open PRs, filter automation PRs, group by ticket ID, format as Markdown. |
/refactor | Multi-target refactoring orchestrator. |
/runbook | Generate/update feature release runbook |
/safe-remove | Safely remove plugin assets (skill/agent/rule/script/hook) with dependency detection and reference cleanup. |
/sharingan | Replicate knowledge from any source as sd0x-dev-flow skill definition. |
/simplify | Wrap-up refactoring — simplify code, eliminate duplication, preserve behavior |
/skill-health-check | Validate skill quality against routing, progressive loading, and verification criteria. |
/statusline-config | Customize Claude Code statusline. |
/update-docs | Research current code state then update corresponding docs, ensuring docs stay in sync with code. |
/zh-tw | Rewrite the previous reply in Traditional Chinese |
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:
| Placeholder | Description | Example |
|---|
{PROJECT_NAME} | Your project name | my-app |
{FRAMEWORK} | Your framework | MidwayJS 3.x, NestJS, Express |
{CONFIG_FILE} | Main config file | src/configuration.ts |
{BOOTSTRAP_FILE} | Bootstrap entry | bootstrap.js, main.ts |
{DATABASE} | Database | MongoDB, PostgreSQL |
{TEST_COMMAND} | Test command | yarn test:unit |
{LINT_FIX_COMMAND} | Lint auto-fix | yarn lint:fix |
{BUILD_COMMAND} | Build command | yarn build |
{TYPECHECK_COMMAND} | Type checking | yarn typecheck |
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.
| Feature | Details |
|---|
| Agents | 2-3 parallel (web + code + community) |
| Synthesis | Claim registry with consensus detection |
| Validation | Conditional /codex-brainstorm debate |
| Scoring | 4-signal completeness model |
Full documentation
Architecture
Six layers, each owning one concern:
| Layer | Owns |
|---|
| Skills | Capabilities loaded on demand — the verbs (/feature-dev, /codex-review-fast, …) |
| Model | The route: batching, timing, review depth escalation, Default-tier deviations |
| Rules | Tiered contracts (Anchor / Default / Guidance) loaded every session |
| Hooks + state | [AUTO_LOOP_STATE] facts, durable gate receipts, recovery across compaction |
| Codex | Independent review — researches the repo itself, never handed a conclusion |
| Scripts + agents | Deterministic checks (precommit, guards) and isolated subagents |
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:
- Follow existing naming conventions (kebab-case)
- Include
When to Use / When NOT to Use in skills
- Add
disable-model-invocation: true for dangerous operations
- Test with Claude Code before submitting
License
MIT
Star History
