sddx

Loop-based Spec-Driven Development for Claude Code: dense specs with mandatory oracles, hook-enforced TDD, parallel git worktrees, and hash-chained receipts. Process over intelligence, proof over promises.

Hooks hard-block implementation writes before a failing test exists, every goal requires an executable oracle, and every finished task leaves a hash-chained receipt in the repo. See why sddx exists for the full problem/mechanism breakdown.

Install

Bun is required — it is the only supported runtime, and no installer installs it for you:

curl -fsSL https://bun.sh/install | bash

Then install sddx from npm and set up a repository:

npm install -g @glapsfun/sddx     # or: bun add -g @glapsfun/sddx
cd your-repo
sddx init

No install needed to try it: npx @glapsfun/sddx init or bunx @glapsfun/sddx init. The package is scoped as @glapsfun/sddx; the command it installs is plain sddx.

sddx init asks four short questions, previews every file it would touch, and does nothing until you approve:

• Runtime scope — global (an sddx on your PATH) or project (a lockfile-backed dev dependency, so the whole team runs the same version).
• Adapters — claude installs Claude Code skills, agents, and the TDD-gate hooks into .claude/, project-locally. No plugin, no global config.
• Interaction mode — whether a human approves the plan before anything runs.

For CI and scripts, the same choices are flags:

sddx init --yes --runtime global --adapter claude

Check everything landed with sddx doctor. Migrating from the old marketplace plugin? See docs/how-to/migrate-from-plugin.md.

Privacy

The sddx runtime makes zero network calls. All state is local files (.sddx/ under version control) and local git.

There is exactly one exception, and it is never silent: installing the package itself, and — if you choose the project-pinned runtime scope — the single dependency install sddx init runs after you confirm it. Nothing on a hot path (session start, hooks, gates) ever reaches the network.

Quickstart

mkdir demo && cd demo && git init
git commit --allow-empty -m init

Then follow Getting started — a one-node run, one command at a time, ending in a verified receipt. A single task is not a special mode: it is a run with one node, and it gets the same goal, run branch, worktree, oracle, and receipt as any other. That is the loop /sddx:run drives for you inside Claude Code. Every command there (and in every guide below) is also a copy-paste-able scaffold under examples/.

Documentation

New to sddx?

• Getting started — your first verified task, by hand from the CLI
• Your first parallel run — two tasks, two worktrees

How-to guides

• Install sddx
• Model DAG dependencies
• Configure retry and skip/block
• Choose an oracle type
• Verify and audit receipts
• Ship a goal as a PR
• Tune config
• Troubleshooting
• Migrate to sddx 4.0 — old-to-new command mappings

Reference

• Spec reference
• CLI reference
• Hooks & the TDD gate
• Receipts schema
• Config reference

Understand the design

• Why sddx
• Design principles
• How it compares
• Architecture
• Interaction modes: human-in-the-loop and unattended

Runnable examples

• examples/ — one scaffold per feature above, replayed in CI

Project

• Releasing
• Contributing
• Changelog
• Security

Development

Dev setup, everyday commands, and the quality gates live in CONTRIBUTING.md; the release process is in docs/RELEASING.md.