ai-sdlc-kit 0.1.0

Spec-driven SDLC skills for AI coding agents — Claude Code, Cursor, Windsurf, Gemini CLI

AI-SDLC v2 — Spec-Driven Skills for AI Coding Agents

A lean, token-efficient Software Development Life Cycle for AI coding agents (Claude Code, Cursor, Windsurf, Gemini CLI). Six skills that make an agent work the way a senior engineer does: understand → decide → plan in verifiable steps → build with checks after every step → gate → ship.

Designed so that even a small model can execute reliably: the planning skill (run once, ideally with a strong model) removes every judgment call up front, and the execution skills are mechanical loops with hard stop conditions.

---

Design principles (what changed from v1)

v1 problem	v2 fix
Huge token use	Skills are 4–10× smaller; artifacts have hard size budgets; every skill reads only the files it names — never "scan the codebase"
Implementation files full of code, impossible to review	Specs contain instructions + contracts (signatures, shapes, exact steps) — never code bodies. You review decisions and contracts, not walls of code
QA didn't catch bugs	Checks are defined at plan time (every task has a Verify command, every goal an acceptance check). QA just executes them — nothing left to a model's mood
Too many files per feature	One spec file per feature. Plan, decisions, tasks, and QA log all live in .sdlc/specs/<feature>.md
Features silently broke each other	/build runs the full test suite every 2 tasks (not only at the end); /qa treats any regression as an automatic FAIL
Style drift, copied bugs	Every task names a Pattern: file the new code must mirror; PROJECT.md carries ≤ 12 checkable convention rules
Black-box output	Every spec opens with What & why (plain-English story of the feature) and a Decisions section: what each component is, what was chosen, why, and what was rejected — written to pass the "12th-grader test", so you can explain the design to anyone

---

Install

Copy the folders inside skills/ into your agent's skills directory at the project root:

Agent / IDE	Path
Claude Code	.claude/skills/
Cursor	.cursor/skills/
Windsurf	.windsurf/skills/
Gemini CLI	.gemini/skills/

The skills appear as slash commands: /sdlc-init, /roadmap, /spec, /build, /qa, /ship.

---

The flow

/sdlc-init                     one-time setup            → .sdlc/PROJECT.md + STATE.md
    │
/roadmap   (optional)          whole project → features  → .sdlc/ROADMAP.md
    │
/spec <feature>                plan one feature          → .sdlc/specs/<feature>.md
    │                          (research, decisions, tasks with contracts + verify commands)
/build <feature>               implement task-by-task    → code; verify gate after EVERY task,
    │                                                      full-suite checkpoint every 2 tasks
/qa <feature>                  mechanical gate           → verdict appended to the spec;
    │                                                      failures become fix-tasks for /build
/ship <feature>                safe commit               → feature branch only, STATE.md updated

The /build → /qa → /build loop is the self-healing part: QA never fixes code, it appends F1, F2… fix-tasks to the spec, and /build executes them like any other task.

The six skills

Skill	Does	Reads	Writes
sdlc-init	One-time project setup: stack, layout, commands, conventions, boundaries	manifests + a few source files, or PRD, or your answers	PROJECT.md, STATE.md
roadmap	Splits a PRD into ordered, shippable features (what + order, never how)	PROJECT.md, the PRD	ROADMAP.md
spec	Plans one feature: researches unknowns, records decisions, writes ≤ 8 tasks with Files / Pattern / Do / Verify	PROJECT.md, STATE.md, only the files the feature touches	specs/<feature>.md
build	Executes the spec exactly: whitelist files, mirror patterns, verify after every task, checkpoint every 2	PROJECT.md, the spec, only listed files	code + spec checkboxes
qa	Re-runs all verifies + acceptance checks + full suite + diff scan; PASS/FAIL verdict; failures → fix-tasks	PROJECT.md, the spec, the diff	QA log in the spec
ship	Branch guard, explicit staging, conventional commit from the spec, records update. Never pushes	the spec	git commit, STATE.md, ROADMAP.md

Bonus: architecture-diagram — renders a self-contained HTML/SVG architecture diagram (unchanged from v1).

---

The .sdlc/ folder — 4 file types, that's all

.sdlc/
├── PROJECT.md          # ≤ 80 lines: stack, layout, commands, conventions, boundaries
├── STATE.md            # one table: feature | spec | status | shipped date (+ cross-feature notes)
├── ROADMAP.md          # optional: ordered feature list for a whole project
└── specs/
    └── <feature>.md    # everything about one feature: goal, decisions, touches,
                        # tasks (with checkboxes = live progress), acceptance checks, QA log

A spec file looks like this (abridged):

# user-auth
Status: building
Goal: Email+password auth issuing JWT access/refresh tokens
Done when:
- POST /v1/auth/login returns tokens for valid credentials
- Protected routes return 401 without a valid token

## What & why — plain English
When someone signs up, we store their account with a scrambled (hashed) password —
we never keep the real one. When they log in, we check the password and hand back
two digital passes: a short-lived access token shown on every request, and a
longer-lived refresh token used to get a new pass when the old one expires.
Any protected page simply refuses visitors without a valid pass.

## Decisions
- **JWT tokens** — a JWT is a signed digital pass the server can verify without a
  database lookup. Chose: 15-min access token + rotating 7-day refresh token.
  Why: servers don't have to remember who is logged in, so the app scales by just
  adding more servers. Rejected: cookie sessions — they need shared session
  storage, which complicates scaling.
- **bcrypt (cost 12)** — a slow-by-design password scrambler, so stolen data is
  useless to attackers. Why: the battle-tested standard. Rejected: argon2 —
  slightly stronger but adds a native dependency our stack doesn't need.

## Touches
- Edits: src/main.py (register router)
- Mirrors: src/routes/items.py, src/services/items.py
- Risk: shared error handler in src/exceptions.py

## Tasks
### [x] T1 — User model + migration
Files: CREATE src/models/user.py, CREATE migrations/…
Pattern: src/models/item.py
Do:
- Table users: id UUID pk, email unique not-null, password_hash str, created_at
- Migration with upgrade + downgrade
Verify: `uv run alembic upgrade head` → applies cleanly

### [ ] T2 — Auth service
Files: CREATE src/services/auth.py
Pattern: src/services/items.py
Do:
- register(email, password) -> User — reject duplicate email with ConflictError
- login(email, password) -> TokenPair(access: str, refresh: str)
- Hash with bcrypt cost 12; never log passwords
Verify: `uv run pytest tests/auth -q` → pass

## Acceptance checks
- [ ] `curl -s -X POST :8000/v1/auth/login -d '{…}'` → 200 with access + refresh tokens
- [ ] `curl -s :8000/v1/items` (no token) → 401

## QA log
### QA 2026-07-12 — PASS
Task verifies: 5/5 · Acceptance: 3/3 · Suite: 42 passed · Regressions: 0
Try it:
1. Run `uv run uvicorn src.main:app`, POST /v1/auth/register with {"email":"[e-mail]","password":"Pass123!"}
2. Expect 201 and a user id; then login with the same credentials → 200 with two tokens

Notice: an implementer needs no other document, a reviewer reads Decisions + contracts in minutes, the checkboxes are resumable progress state, and QA's checklist was fixed the moment the spec was written.

---

Why this works with small models

1. Judgment happens once, at spec time. Use your best model for /spec. After that, /build and /qa are deterministic loops — pick task, read 2–3 listed files, follow exact bullets, run a command, check a box.
2. Whitelists instead of freedom. A task's Files: list is a hard boundary; needing another file is a stop-and-report, not an improvisation.
3. Patterns instead of taste. "Mirror src/services/items.py" keeps style consistent without describing style.
4. Verification is a command, not an opinion. Every task and every acceptance criterion is proven by running something and comparing output.
5. Tiny context. PROJECT.md ≤ 80 lines, one spec per feature, skills that forbid whole-codebase scans — the model's window stays small and focused.

Roadmap for this kit

• pip / npm installer that copies skills into the right folder per agent and scaffolds .sdlc/
• Optional CI hook: run /qa checks headlessly on pull requests

Related prior art: github/spec-kit.