Spec-Driven SDLC
A spec-driven SDLC for teams using AI coding agents: nine stages, one committed artifact each, and the AI never merges the PR.
The idea
The bottleneck in AI-assisted development is no longer writing code. It's knowing whether the code being written is the right code.
So intent and requirements move to the front, into durable files, and a stage can't start until the previous one's artifact exists. Each stage leaves one named artifact, committed to version control. The artifact is the handoff.
It ships as a Claude Code plugin, so each stage triggers without being asked, and as one self-contained file, SPEC_SDLC.md, that works with any agent. It is based on Anthropic's AI-Native SDLC Playbook.
Nine stages, one artifact each
Stages 1 to 8 ship a feature. Stage 9 acts on the process itself. Three size tracks keep it proportionate: a typo fix doesn't get a nine-stage pass.
How it's distributed
The process is a gitignored clone inside your repo, not copied files.
.claude/skills/sdlc/: gitignored. The process, a git clone..claude/spec-sdlc.json: committed. Which process version this repo runs.CLAUDE.md,REVIEW.md,specs/0001-*/: yours, never synced.
That split is the whole design. CLAUDE.md, REVIEW.md and specs/ hold this repo's knowledge and must not sync. The process is a clone, so it updates with a pull instead of drifting. And the committed lock file is the only thing that says which process version produced a given pull request, which is what makes the audit trail work.
Two branches, one human decision
main: development. Retro pull requests land here.release: what product repos clone. A merge into it is a board decision, made by a human.
So a repo only ever runs process that has been approved.
Set it up
- Clone the process.
git clone -b release https://github.com/wodutoit/spec-sdlc-simple .claude/skills/sdlc - Trust the workspace. Restart Claude Code from the repository root and accept the trust dialog. A project-scope skills-directory plugin isn't loaded until the workspace is trusted.
- Bootstrap. Run
/sdlc:bootstrap. It gitignores the clone, asks your team a few questions (retro cadence, protected branches, your one test command, default review tier), writes the lock file, and seedsCLAUDE.mdandREVIEW.md. - Turn on branch protection. Protect
main: require a pull request and code-owner approval.
The plugin ships a hook that blocks gh pr merge, git merge, force pushes, protected-branch pushes and --no-verify. That is a backstop, not the control. It only holds where it's installed; branch protection holds everywhere.
Not using Claude Code? SPEC_SDLC.md is the entire process in one file, with every artifact template inline. You lose automatic stage triggering, the merge hook, the staleness check and the retro loop. You keep the process. The full instructions are in the repository on GitHub.
Adopt it gradually
Don't switch all nine stages on at once. Stages are ordered by dependency, and Intent has no prerequisites.
- Set up, then write one real
intent.md. See how it feels. CLAUDE.md: the fastest payoff, and cheap.- Stage 2 on your next real feature. Most of the value is here.
- Stage 4:
BUILD_PLAN.mdcommitted before the code. - Branch protection.
- Stages 6 and 7, then
REVIEW.md. - Stage 8 once you have monitoring worth reacting to; stage 9 once you have enough artifacts to find patterns in.
What to watch for
Working looks like: less rework after build starts, a higher first-pass merge rate, fewer "that's not what I meant" moments.
Failing looks like: artifacts written after the code as paperwork, everything tracked as large, everything tracked as small, specs nobody reads. All the same failure: the artifact stopped being the handoff and became a formality.
Costs to know about: the ten skills add roughly 700 tokens to every session where the plugin is enabled, used or not. Non-interactive sessions never accept the trust dialog, so the plugin doesn't auto-load there.
Get it
MIT licensed. The process, the plugin and the single-file version are all in the repository.