Open source

SDLC

SDLC is a spec-driven, test-driven, gate-checked development harness for building software with AI coding agents. I built it after getting tired of watching agents write a pile of plausible-looking code with no contract behind it, no failing test to aim at, and no checkpoint where anyone (human or critic agent) actually signed off.

Install it in a project, pick your coding agents, and it lays down the roles, skills, templates, and gate scripts that walk a build through discovery, architecture, backend, frontend, and integration in order, without letting anyone skip a step.

GitHub @levi-putna/sdlc

Quick start

Install it in a project

Run the wizard from your project root. It asks which coding agents you use, installs the framework, and points you at whatever comes next.

npx @levi-putna/sdlc init

Core principles

The rules agents and humans both follow

Spec before code

Every Stack, Brick, element, component, and screen gets a contract and a failing test before anyone writes an implementation.

Gated progression

Gate scripts scan the filesystem, run the tests, and report BLOCKED, ACTIVE, or COMPLETE. You don't move on until the gate says so.

Critic-gated quality

An adversarial critic agent has to approve each spec, each test set, and each code change before its gate opens.

Zero open questions

Every stage has to resolve its [AUTO] and [HUMAN] questions before advancing. Nothing gets waved through unresolved.

Framework agnosticism

Business logic in stacks/ carries no Next.js imports. The framework only binds at Stage 8, once the logic is proven on its own.

Targets

Supported coding agents

You choose your targets during sdlc init. Every target can run the full pipeline. What changes is how faithfully it's enforced.

Agent	Fidelity	How it's wired up
Claude Code	Full	Native subagents + skills via symlinks into .sdlc/
Cursor	Basic	Generated .cursor/rules/sdlc.mdc, skills symlinked in
Windsurf	Basic	Generated .windsurf/rules/sdlc*.md
GitHub Copilot	Basic	Generated .github/copilot-instructions.md
OpenAI Codex	Basic	Generated root AGENTS.md

NoteClaude Code is the only target with full fidelity. Every file in .sdlc/agents/ is a real, isolated subagent that the CLI can dispatch to via the Task tool, each with its own context window, and skills auto-activate when a stage needs them. Every other target gets basicfidelity: a rendered instructions file pointing at those same agent and skill docs, which the model has to notice, open, and follow manually, in the same shared conversation rather than an isolated one. There's no automatic parallelism across agents on a basic target, and the whole thing leans on the model actually reading the referenced file instead of a guaranteed dispatch. The pipeline still runs end to end either way, same stages, same gates, same tests. Claude Code just enforces the process structurally. Everywhere else, it relies on the model's own discipline to follow it.

Lifecycle

Four lanes, forking after setup

A greenfield build starts sequential, then forks. Setup runs once. Backend and frontend then build in parallel, each behind its own gate script, and converge in an integration lane once both sides have something to wire together. Once integration closes out, the pipeline is done and any further work goes through the change track instead of a full re-run.

S (Setup)

S0 Domain Discovery → S1 Requirements → S2 Architecture

B (Backend build)

B1–B7, Stacks and Bricks, TDD sextet

F (Frontend build)

F1–F8, design system and screen specs

I (Integration)

I1–I3, converges on F8 + B6, pipeline complete at I3

Change Track

C1–C4 / FC1–FC4 for targeted changes after launch

What "complete" means

Milestone	Meaning
`F8 complete`	Design system verified. Every page.md and page.stories.tsx is spec-approved.
`B6 complete`	architecture/api-contract.md is populated. Canonical API surface for the project.
`I3 complete`	Integration sextet green, Playwright passes, E2E-AUDIT.md approved. Pipeline done.

Three gate scripts enforce it

Script	Lanes it covers
`check-stage.js`	S (0–2) + B (3–9) + Change C1–C4
`check-stage-frontend.js`	F (F1–F8) + Change FC1–FC4
`check-stage-integration.js`	I (I1–I3)

Stages

What each stage is responsible for

Display labels like S0 or F6 are for readability. Gate scripts and stage files use plain numbers instead (--stage 6 means F6 on the frontend gate, but Stage 6 on the backend gate). Each stage's entry condition is simply the previous stage's gate reporting COMPLETE; its exit condition is its own gate reporting COMPLETE against the outputs below.

S lane: Setup

Runs once, sequential, no parallelism. Entry: the start of a greenfield build. Exit: S2 complete opens both the backend and frontend lanes at once.

Stage	Name	Responsible for	Output
`S0`	Domain Discovery	Interview-driven discovery of domain, regulatory context, safety posture, and constraints	`DOMAIN.md`
`S1`	Reconcile Requirements	Collate raw requirements, resolve conflicts, assign FR-* IDs, surface gaps	`REQUIREMENTS.md`
`S2`	Technical Architecture	Database schema, DI ports, AI strategy, capability matrix, tooling baseline	`architecture/*.md`

B lane: Backend build

Entry: after S2. Runs parallel with the F lane from Stage 3 onward. Exit: B6 populates api-contract.md, which is what the I lane is actually waiting on. B7 wraps up the remaining integration research afterwards.

Stage	Name	Responsible for	Output
`B1`	Generate Scope	Map every FR-* to Stacks and Bricks, produce the build inventory	`SCOPE.md`
`B2`	Setup Stacks & Bricks	Scaffold the directory tree for every Stack and Brick, discover LLM call points	`stacks/, architecture/*/config.json`
`B3`	Contracts & Tests	Write contract.ts and failing Vitest tests per Brick, honest TDD-red with no index.ts yet	`contract.ts, tests/`
`B4`	Business Logic Code	Implement pure TypeScript until every unit test passes, with no framework imports	`index.ts`
`B5`	Develop Flows	One Workflow SDK workflow per API endpoint, with retry	`workflows/, FLOWS.md`
`B6`	Framework & API Contract	Bind business logic to Next.js route handlers, Supabase, AI SDK, Workflow Devkit	`app/api/, architecture/api-contract.md`
`B7`	Integrations	Identify external service dependencies, mocking strategies, env config	`INTEGRATIONS.md`

Business logic lives in stacks/ as plain TypeScript with no framework imports, one Brick per use case. The framework layer (Next.js, Supabase, the Workflow SDK) only binds in at B6, once the logic underneath it has already proven itself against tests.

F lane: Frontend build

Entry: after S2 (specifically architecture/backend.md). Runs parallel with B, and doesn't need api-contract.md until the I lane. Exit: F8, the visual gate, closes the lane out.

Stage	Name	Responsible for	Output
`F1`	UI Architecture	Component taxonomy, design tokens, state strategy, Storybook conventions	`architecture/frontend.md`
`F2`	UI Requirements	Wireframes, breakpoints, accessibility, screen index, FR-UI-* IDs	`requirements-frontend.md`
`F3`	UI Scope	Map UI FRs to elements, components, screens, and hooks	`SCOPE-FRONTEND.md`
`F4`	Scaffold	5-file sets for elements/components; route folders with page.md shells only	`app/elements/, DESIGN-SYSTEM.md, SCREENS.md`
`F5`	Document Elements	Populate Name.md contracts, critic approval before any code is written	`Name.md per inventory item`
`F6`	Document Screens	Populate page.md and page.stories.tsx with mock props, critic approval	`page.md, page.stories.tsx`
`F7`	Build Components	Test-first implementation of every element and component	`Name.tsx, Name.test.tsx, Name.stories.tsx`
`F8`	Visual Gate	Reference screenshots, 3-viewport audit, stakeholder sign-off	`Name.png, VISUAL-AUDIT.md`

I lane: Integration

Entry: needs both F8 and B6 complete before it can start wiring frontend specs to the backend API surface. Exit: I3, once the integration sextet is green, Playwright passes, and E2E-AUDIT.md is approved. That's the whole pipeline done.

Stage	Name	Responsible for	Output
`I1`	Server Actions & Hooks	Client hooks and MSW mocks aligned to api-contract.md	`state-logic hooks, optional actions.ts`
`I2`	Route Build	Turn §Data Wiring into async Server Components, test-first	`page.tsx per route, PLATFORMS.md`
`I3`	E2E + Integration	Integration sextet, Playwright flows, e2e-verifier audit	`e2e/, E2E-AUDIT.md`

Gates

A gate is more than a checklist

Gate scripts check that files exist and tests pass, but the finer grained enforcement happens per Brick, through a strict, serial sextet. Nothing moves to the next link until the previous one is approved:

text

biz-spec-writer → biz-spec-critic → biz-test-writer → biz-test-critic → biz-code-writer → biz-code-critic

A spec-writer drafts the contract, a critic has to approve it before a test-writer touches it, the tests have to be approved before a code-writer implements anything, and the code itself gets reviewed before the Brick counts as done. The same shape applies to the frontend and integration sextets, just with different agent names. Combined with the zero-open-questions rule, that's what "gate-checked" actually means here: not just "did the file get written", but "did something adversarial sign off on it first".

Change track

Targeted changes after launch

Once the pipeline is complete, you don't re-run greenfield stages for a small change. You propose it in CHANGE.md or CHANGE-UI.md and work through four short stages instead. Escalate back to the full pipeline if the change adds new functional requirements, crosses stacks, or touches scope files.

Stage	What happens
`C1 / FC1`	Propose the change: scope, risk, what's explicitly out of scope
`C2 / FC2`	Update contracts and failing tests (or Name.md / page.md and critics)
`C3 / FC3`	Implement until tests pass
`C4 / FC4`	Full suite run, visual regression where relevant, then archive

Commands

CLI command reference

Command	Description
init	Wizard: pick your coding agents, install the framework
install	Check for and apply framework updates
diff	See what would change on the next install before running it
changelog	Print what's changed since your installed version
status	Pipeline progress across all four lanes, as a tree
next	Work out what's next and launch or copy the prompt for it
explain [step]	Explain a stage's purpose, inputs, outputs, and gate criteria
docs [path]	Browse every documentation artifact the pipeline has produced
contribute	Turn a local fix to .sdlc/ into a PR against the framework repo

Prefix every command with npx @levi-putna/sdlc.

Installing and updating

# Interactive wizard: pick agents, install, wire up requirements
npx @levi-putna/sdlc init

# Non-interactive: Claude Code only, no prompts
npx @levi-putna/sdlc init --yes

# Pick agents explicitly, install into a different directory
npx @levi-putna/sdlc init --agents claude,cursor --cwd ./apps/web

Keeping the framework current

# See what would change first
npx @levi-putna/sdlc diff

# Read what's new before updating
npx @levi-putna/sdlc changelog

# Apply the update, keeping local edits where they don't conflict
npx @levi-putna/sdlc install

# Force upstream to win on every conflict
npx @levi-putna/sdlc install --force

Checking progress

# Where is this project up to, across all four lanes?
npx @levi-putna/sdlc status

# Machine-readable, for scripting
npx @levi-putna/sdlc status --json

# What should I actually do next?
npx @levi-putna/sdlc next

status draws every stage across all four lanes as a tree, so you can see at a glance what's done, what's active, and what's still blocked waiting on the other side:

text

● Setup
│
● S0 - Domain Discovery
│
● S1 - Reconcile Requirements
│
● S2 - Technical Architecture
│
├──────────────────────────────┐
│                              │
◐ Backend                      ◐ Frontend
│                              │
● B1 - Generate Scope          ◐ F1 - UI Architecture
│                              │
● B2 - Setup Stacks & Bricks   ○ F2 - UI Requirements
│                              │
● B3 - Contracts & Tests       ○ F3 - UI Scope
│                              │
● B4 - Business Logic Code     ○ F4 - Scaffold
│                              │
◐ B5 - Develop Flows           ○ F5 - Document Elements
│                              │
○ B6 - Framework Tests & Code  ○ F6 - Document Screens
│                              │
○ B7 - Integrations            ○ F7 - Build Components
│                              │
│                              ○ F8 - Visual Gate
│                              │
└──────────────┬───────────────┘
               │
               ✗ Integration
               │
               ✗ I1 - Server Actions & Hooks
               │
               ○ I2 - Route Build
               │
               ○ I3 - E2E + Integration

● Complete   ◐ Active   ○ Pending   ✗ Blocked

next reads that same state and tells you what to actually do about it: which unblocked stage to pick up, and a ready-to-paste prompt for your coding agent. On Claude Code it can launch that agent directly instead of just printing the prompt.

Reading a stage's canonical doc

# Read a stage's purpose, inputs, outputs, and gate criteria
npx @levi-putna/sdlc explain s2
npx @levi-putna/sdlc explain f6

# Or pick one interactively
npx @levi-putna/sdlc explain

Browsing the artifacts

Every output in the stage tables further down (DOMAIN.md, api-contract.md, and so on) is browsable through docs without hunting through the filesystem yourself.

# Browse every artifact the pipeline has produced so far
npx @levi-putna/sdlc docs

# Jump straight to one
npx @levi-putna/sdlc docs architecture/api-contract.md

Workflow

The day-to-day loop

The CLI commands above manage the framework itself. Once it's installed, the day-to-day loop runs on status and next, not on the gate scripts directly:

Run status to see where the pipeline is and what's active
Run next for the unblocked stage. It offers you options and a ready-made prompt for your coding agent, or launches Claude Code straight into it if that's your target
Let the agent do the work: it invokes the gate script itself, resolves any interview questions that come up, and reports back once the stage is COMPLETE
Run status again to confirm, then repeat next for whatever unblocks

NoteThe gate scripts (check-stage*.js) are an internal contract between the CLI and the agent, not something you run yourself. The agent invokes them after every write to confirm a stage or sextet step actually landed, then reports the result back through the conversation. Your interface to the pipeline is status, next, explain, and docs.

Starting a greenfield build

Drop your raw, timestamped requirements into requirements/ and ask what's next. It picks up at Stage 0 automatically.

# Drop your raw requirements in, then ask what's next
mkdir -p requirements
npx @levi-putna/sdlc next   # picks up Stage 0: Domain Discovery

Making a targeted change

After the pipeline is complete, next recognises there's nothing left to build and switches to the change track instead of a full re-run.

# Full pipeline already complete, propose a targeted change instead
npx @levi-putna/sdlc next   # detects the completed pipeline, offers C1 / FC1

Get the CLI

Install via npx or from npm

Use npx to always pull the latest release, or install globally from npm. Node.js 18 or later is required.

Socket supply chain score for @levi-putna/sdlc

All tools and utilities

SDLC, Agent Kit, and whatever else I've built to make working with AI coding agents less painful.