A self-evolving Software Development Life Cycle (SDLC) enforcement system for AI coding agents. Makes Claude plan before coding, test before shipping, and escalate when uncertain. Measures itself getting better over time.
Built on 15+ years of software engineering and founding engineering experience — battle-tested patterns from real production systems, baked into an AI agent that follows tried-and-true software quality practices so you don't have to enforce them manually.
Built and validated on frontier models. This harness is developed against Opus 5 as the driver, Fable 5 as the design authority, and GPT-5.6 Sol as the cross-model adversarial check. That is the only configuration behind which there is cycle data from real use.
Behavior on earlier or smaller drivers is unmeasured. Not "degraded," not "should still work" — nobody has run it and measured. The harness leans on the driver to hold a long plan, refuse its own shortcuts, and escalate when uncertain; how much of that survives on a weaker model is exactly the thing no one here has data on. If you run it elsewhere and measure something, that result is worth more than this paragraph.
Built for Claude Code. Using OpenAI's Codex CLI instead? Check out
codex-sdlc-wizard. Need privacy-first / any-backend (local Ollama, Azure OpenAI, hosted OSS)? Seeopencode-sdlc-wizard. (Full ecosystem.)
Requires Claude Code (Anthropic's CLI for Claude). Install it with the native installer — curl -fsSL https://claude.ai/install.sh | bash — which the official setup docs label Recommended and which keeps it auto-updating in the background. Never use sudo npm install -g @anthropic-ai/claude-code: sudo can leave the global module directory root-owned, which then breaks claude update and npm uninstall -g. Check for conflicting installs with which -a claude.
Run from your terminal or from inside Claude Code (! prefix):
npx -y agentic-sdlc-wizard@latest initThe @latest pin forces npm to fetch the newest version. Without it, npx may serve a stale CLI from your local cache (#358); init also nudges if it detects a gap.
Then start (or restart) Claude Code — type /exit then claude to reload hooks. Setup auto-invokes on first prompt — Claude reads the wizard doc, scans your project, and generates bespoke CLAUDE.md, SDLC.md, TESTING.md, and ARCHITECTURE.md. No manual commands needed.
Alternative install methods
curl (no npm install needed):
curl -fsSL https://raw.githubusercontent.com/BaseInfinity/claude-sdlc-harness/main/install.sh | bashHomebrew:
brew install BaseInfinity/sdlc-wizard/sdlc-wizard
sdlc-wizard initGitHub CLI extension:
gh extension install BaseInfinity/gh-sdlc-wizard
gh sdlc-wizard initFrom GitHub (no npm registry needed):
npx github:BaseInfinity/claude-sdlc-harness initInstall CLI globally:
npm install -g agentic-sdlc-wizard
sdlc-wizard initManual (advanced — partial, not an escape hatch): Download CLAUDE_CODE_SDLC_WIZARD.md to your project and tell Claude Run the SDLC wizard setup. This skips the live-session auto-invoke and generates your bespoke CLAUDE.md, SDLC.md, TESTING.md and ARCHITECTURE.md. It does not give you a working install. The document no longer contains the SDLC skill — Step 6 installs it by running the CLI (GH #513) — and only 2 of the 8 hooks have hand-typed templates here. So this path still needs npx; there is no npx-free route to a complete install. The default human path is npx init → restart CC → first-prompt auto-setup.
Health check & updates
npx agentic-sdlc-wizard check # Human-readable
npx agentic-sdlc-wizard check --json # Machine-readable (CI-friendly)Reports MATCH / CUSTOMIZED / MISSING / DRIFT for every installed file. Exits non-zero on MISSING or DRIFT — use in CI to catch setup regressions.
Check for content updates: Tell Claude Check if the SDLC wizard has updates — it reads CHANGELOG.md, shows what's new, and offers to apply changes.
You want Claude Code to follow engineering discipline automatically:
- Plan before coding (not guess-and-check)
- Write tests first (TDD enforced via hooks)
- State confidence (LOW = escalate to a model first, don't guess)
- Track work visibly (TaskCreate)
- Cross-model review before shipping (a different model checks the work — same-model self-review was removed in #486 after it reported all-green while an independent model found real P1s)
- Prove it's better (use native features unless you prove custom wins)
The wizard auto-detects your stack (package.json, test framework, deployment targets) and generates bespoke hooks + skills + docs. CI validates the generated assets; cross-stack setup-path E2E is on the roadmap.
Five layers working together:
Layer 5: SELF-IMPROVEMENT
Weekly/monthly workflows detect changes, test them
statistically, create PRs. Baselines evolve organically.
Layer 4: STATISTICAL VALIDATION
E2E scoring with 95% CI (5 trials, t-distribution).
SDP normalizes for model quality. CUSUM catches drift.
Layer 3: SCORING ENGINE
Multi-criteria scoring, 10/11 points. Claude evaluates Claude.
Before/after wizard A/B comparison in CI.
Layer 2: ENFORCEMENT
Hooks fire every interaction (~100 tokens).
PreToolUse reminds Claude to write tests first.
Layer 1: PHILOSOPHY
The wizard document. KISS. TDD. Confidence levels.
Run the CLI; setup reads it and writes a bespoke SDLC.
| Capability | What It Does |
|---|---|
| E2E scoring in CI | Every PR gets an automated SDLC compliance score (0-10) — measures whether Claude actually planned, tested, and reviewed |
| Before/after A/B testing | Compares wizard changes against a baseline with 95% confidence intervals to prove improvements aren't noise |
| SDP normalization | Separates "the model had a bad day" from "our SDLC broke" by cross-referencing external benchmarks |
| CUSUM drift detection | Catches gradual quality decay over time — borrowed from manufacturing quality control |
| Pre-tool TDD hooks | Before source edits, a hook reminds Claude to write tests first. CI scoring checks whether it actually followed TDD |
| Self-evolving loop | Weekly/monthly external research + local CI shepherd loop — you approve, the system gets better |
Claude can't grade its own homework. Have a different AI from a different company review Claude's work — different training, different blind spots, different biases. We use OpenAI's Codex CLI, and it's three commands to set up:
npm i -g @openai/codex
export OPENAI_API_KEY=sk-...
codex --version # confirm readyThat's it. Codex picks up your OpenAI account's best available model automatically — if you have GPT-5.6 Sol, it uses Sol; otherwise it falls back to Terra. No model config needed.
How to use it: when the change is high-stakes, write a one-file mission brief and run:
codex exec -c 'model_reasoning_effort="high"' -s danger-full-access \
-o .reviews/latest-review.md \
"Read .reviews/handoff.json and review per the checklist. Output findings + CERTIFIED or NOT CERTIFIED." \
< /dev/nullAlways append < /dev/null when running codex exec from a non-interactive parent (background, hooks, CI, Claude Code Bash tool). Without it, codex blocks on stdin reads even when the prompt is an argument — the process sits at S/0% CPU indefinitely with a 0-byte -o output file. Validated on codex-cli 0.130.0 / macOS 14, 2026-05-15.
Reviewer effort is high (changed from xhigh 2026-08-01, for cost and review-noise — not capability); escalate to xhigh for unusually risky PRs. See CLAUDE_CODE_SDLC_WIZARD.md for the full protocol (handoff format, round-2 dialogue loop, preflight docs). Real-world: this catches P0/P1 issues in 2-3 out of 10 reviews that Claude's self-review rated as clean.
The wizard ships a default recommendation, not a mandate. Swap to any Claude
model at any time — /model per session, or pin in .claude/settings.json.
Default: Opus 5 at high effort for complex projects, medium for routine
web/CRUD (Setup A).
Sonnet 5 at medium effort (Setup B) for simple or one-off work.
What has actually been exercised on this harness. Current Setup A — Opus 5
driving, Fable 5 advising, GPT-5.6 Sol gating — is what recent cycles run on.
Earlier defaults existed (Opus 4.6, June 2026 — see CHANGELOG.md) but predate
the current review setup, so none of that data transfers. The other lanes and
the claude-opus-4-6 / claude-opus-4-8 pins are configuration that should
work, not measured results.
/model opus # wizard's default (Setup A) — Opus 5, requires CC v2.1.219+
/model sonnet # Simple/one-off lane (Setup B) — native 1M context, lower cost
/model opusplan # Opus 5 plans (Shift+Tab), Sonnet executes — both Max-bundled (Setup C)
/model claude-opus-4-8 # pin explicitly for Opus 4.8's field-proven behavior instead of Opus 5
/model claude-opus-4-6 # pin explicitly for Opus 4.6's `max`-effort consistency profileOr pin in .claude/settings.json:
{ "model": "opus", "advisorModel": "fable", "effortLevel": "high" }Set effort per session with /effort, not a shell-rc or settings env var —
persisting it that way silently overrides a later /effort change once you
switch models.
The wizard defines four AI coding setups in AI_SETUP_LANES.md:
| Lane | Advisor | Driver | Reviewer | Escalation |
|---|---|---|---|---|
| A — Recommended (trial) | Fable 5 (advisorModel, fallback subagent) | Opus 5, high / medium |
GPT-5.6 Sol high | Opus 4.8 pinned or Fable review |
| B — Simple/One-Off | Fable 5 (advisorModel, fallback subagent) | Sonnet 5, medium→high→xhigh |
GPT-5.6 Sol high | Opus 4.8 xhigh or Fable review |
| C — Saver | Fable 5 or Opus 5 (advisorModel) | Opus 5 plans, Sonnet 5 executes | GPT-5.6 Sol high | None |
| D — Lite | None | Sonnet 5, medium |
None | None |
Setup D's whole point: the discipline of knowing when NOT to use discipline. When blast radius is low and you just need fast cheap hands, skip the SDLC overhead.
AI_SETUP_LANES.md carries the rest, so this section stays
short: the per-model effort table,
how to read Setup A precisely, the evidence behind the
4.6 / 4.8 / Sonnet 5 positions, and
how billing works
(1M context is GA at standard pricing; the June 15, 2026 split moved headless
surfaces off Max, interactive Claude Code stays on it).
Think Iron Man: Jarvis is nothing without Tony Stark. Tony Stark is still Tony Stark. But together? They make Iron Man. This SDLC is your suit - you build it over time, improve it for your needs, and it makes you both better.
The dream: Mold an ever-evolving SDLC to your needs. Replace my components with native Claude Code features as they ship — and one day, delete this repo entirely because Claude Code has them all built in. That's the goal.
WIZARD FILE (CLAUDE_CODE_SDLC_WIZARD.md)
- Setup guide, used once
- Lives on GitHub, fetched when needed
|
| generates
v
GENERATED FILES (in your repo)
- .claude/hooks/*.sh
- .claude/skills/*/SKILL.md
- .claude/settings.json
- CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md
(that's everything you get — the arrow below leaves your repo)
|
| the harness itself is validated by
v
CI/CD PIPELINE (this repo, NOT yours)
- E2E: simulate SDLC task -> score 0-10
- Before/after: main vs PR harness
- Statistical: 5x trials, 95% CI
- Model-aware: SDP adjusts for external conditions
The bottom box runs here, not in your project. tests/e2e/ is not part of the
published package, so npm pack ships none of it. That scoring pipeline is how this
repo proves a change to the harness is an improvement before releasing it — it is not
something you run, configure, or need an API key for. What lands in your repo is the
middle box: hooks, skills, settings and docs.
| Cadence | Source | Action |
|---|---|---|
| Weekly | Claude Code releases | PR with analysis + E2E test |
| Weekly | Community (Reddit, HN) | Issue digest |
| Monthly | Deep research, papers | Trend report |
Every update: regression tested -> AI reviewed -> human approved.
Like evaluating scientific method adherence - we measure process compliance:
| Criterion | Points | Type |
|---|---|---|
| TodoWrite/TaskCreate | 1 | Deterministic |
| Confidence stated | 1 | Deterministic |
| Plan mode | 2 | AI-judge |
| TDD RED | 2 | Deterministic |
| TDD GREEN | 2 | AI-judge |
| Self-review | 1 | AI-judge |
| Clean code | 1 | AI-judge |
40% deterministic + 60% AI-judged. 5 trials handle variance.
| Metric | Meaning |
|---|---|
| Raw | Actual score (Layer 2: SDLC compliance) |
| SDP | Adjusted for model conditions |
| Robustness | How well SDLC holds up vs model changes |
- Robustness < 1.0 = SDLC is resilient (good!)
- Robustness > 1.0 = SDLC is sensitive (investigate)
Tests aren't just validation - they're the foundation everything else builds on.
- Tests >= App Code - Critique tests as hard (or harder) than implementation
- Tests prove correctness - Without them, you're just hoping
- Tests enable fearless change - Refactor confidently
| Plugin | Purpose | Scope |
|---|---|---|
claude-md-management |
Required - CLAUDE.md maintenance | CLAUDE.md only |
claude-code-setup |
Recommends automations | Recommendations |
code-review |
Optional preflight input to cross-model review; PR review | Local + PRs |
Don't reinvent the wheel. Use native/built-in features UNLESS you prove your custom version is better. If you can't prove it, delete yours.
- Test the native solution — measure quality, speed, reliability
- Test your custom solution — same scenario, same metrics
- Compare side-by-side
- Native >= custom? Use native. Delete yours.
- Custom > native? Keep yours. Document WHY. Re-evaluate when native improves.
This applies to everything: native commands vs custom skills, framework utilities vs hand-rolled code, library functions vs custom implementations.
This isn't the only Claude Code SDLC tool. Here's an honest comparison:
| Aspect | SDLC Harness | everything-claude-code | claude-sdlc |
|---|---|---|---|
| Focus | SDLC enforcement + measurement | Agent performance optimization | Plugin marketplace |
| Hooks | 3 (SDLC, TDD, instructions) | 12+ (dev blocker, prettier, etc.) | Webhook watcher |
| Skills | 4 (/sdlc, /setup, /update, /feedback) | 80+ domain-specific | 13 slash commands |
| Evaluation | 95% CI, CUSUM, SDP, Tier 1/2 | Configuration testing | skilltest framework |
| CI Shepherd | Local CI fix loop | No | No |
| Auto-updates | Weekly CC + community scan | No | No |
| Install | npx -y agentic-sdlc-wizard@latest init |
npm install | npm install |
| Philosophy | Lightweight, prove-it-or-delete | Scale and optimization | Documentation-first |
Our unique strengths: Statistical rigor (CUSUM + 95% CI), SDP scoring (model quality vs SDLC compliance), CI shepherd loop, Prove-It A/B pipeline, comprehensive automated test suite, dogfooding enforcement.
Where others are stronger: everything-claude-code has broader language/framework coverage. claude-sdlc has webhook-driven automation. Both have npm distribution.
The spirit: Open source — we learn from each other. See COMPETITIVE_AUDIT.md for details.
| Document | What It Covers |
|---|---|
| ARCHITECTURE.md | System design, 5-layer diagram, data flows, file structure |
| CI_CD.md | All workflows, E2E scoring, tier system, SDP, integrity checks |
| SDLC.md | Version tracking, enforcement rules, SDLC configuration |
| TESTING.md | Testing philosophy, test diamond, TDD approach |
| CHANGELOG.md | Version history, what changed and when |
| CONTRIBUTING.md | How to contribute, evaluation methodology |
This wizard is one of three published siblings. Same enforcement philosophy, different agent / domain:
| Package | Agent / Domain | What It Does |
|---|---|---|
agentic-sdlc-wizard (repo) |
Claude Code / SDLC | This repo. Plan → TDD → cross-model review for code, with hooks + skills + CI scoring |
codex-sdlc-wizard (repo) |
OpenAI Codex / SDLC | Same SDLC enforcement, ported to Codex CLI (writes .codex/ + AGENTS.md) |
opencode-sdlc-wizard (repo) |
OpenCode / privacy-first | Same SDLC enforcement against ANY backend OpenCode supports — local Ollama, Azure OpenAI, Together, Groq, OpenRouter. Writes .opencode/ + AGENTS.md. |
claude-gdlc-wizard (repo) |
Claude Code / GDLC | Game Development Life Cycle — persona-driven playtest cycles, triangulated findings, ratchet-only-tightens |
All four are part of the broader XDLC ecosystem — generalized lifecycle enforcement across agents and domains.
Automation Station — a community Discord packed with software engineers bringing 40+ years of combined experience across every area of the stack.
Frontend · Backend · Infra · Embedded · Data · QA · DevOps
Share patterns, ask questions, compare notes on AI agents, automation, and SDLC tooling.
PRs welcome. See CONTRIBUTING.md for evaluation methodology and testing.
Three ways to report bugs, request features, or ask questions:
- In-session: run
/feedbackinside any Claude Code session using this wizard — auto-fills context and redacts secrets before filing - Issue templates: bug report, feature request, question
- Discussions: open-ended conversations at github.com/BaseInfinity/claude-sdlc-harness/discussions