ai-sdlc-kit

Spec-driven SDLC skills that make AI coding agents work like a real engineering team — and leave the developer understanding every change.

What is it?

ai-sdlc-kit installs a set of skills for Claude Code, Cursor, Windsurf, and Gemini CLI that turn one coding agent into a small engineering team with separated roles:

diagnose & teach → spec in verifiable tasks → write the tests first → build to the tests → independent QA gate → ship

Two ideas drive the design:

1. The developer must understand everything. /plan walks you through the problem in plain language — "when the user does X, this function runs, it should return Y but returns Z, and here's the line that causes it" — plus the solution options and why one wins. Every feature keeps a human-readable walkthrough.md next to its machine-readable spec.md. You finish able to trace the code and defend the decisions.
2. No agent grades its own homework. Each stage runs as its own fresh agent: the tester writes tests from the spec before the code exists, the builder can't touch those tests, and QA never sees the builder's reasoning. The final diff is written to survive review by an outside frontier model.

Install

# Python
pip install ai-sdlc-kit        # or: uv tool install ai-sdlc-kit

# Node
npm install -g ai-sdlc-kit     # or one-off: npx ai-sdlc-kit install --agent claude

Both give you the same ai-sdlc command and the same skills — pick whichever ecosystem you already have.

Use

ai-sdlc install --agent claude   # or cursor / windsurf / gemini / all

This copies the skills into your agent's skills directory. They then appear as slash commands: /sdlc-init, /roadmap, /plan, /spec, /test, /build, /qa, /ship, /automate, /mentor.

ai-sdlc list         # see bundled skills
ai-sdlc --version    # print the installed version

Monorepo, or no Python project at the root? Not a problem — ai-sdlc install only copies skill files into .claude/skills/ (or your agent's folder); it never reads pyproject.toml or anything else at the target. Install the CLI once with pipx install ai-sdlc-kit or uv tool install ai-sdlc-kit, then run it at your repo root — or from anywhere with --target /path/to/root.

Getting started

Every project starts with /sdlc-init — run it once, in your agent, inside your project folder. It writes:

• .sdlc/PROJECT.md — project facts, real commands, your git workflow (it asks how you branch/commit; answer or take the default), and the agent tier map (which stages run on a strong vs mid model)
• .sdlc/CRAFT.md — the code rulebook: pinned stack versions with modern-idiom rules, folder structure, style (including the always-on simplicity rules: minimal comments, no essay docstrings, boring beats clever), config and security rules
• .sdlc/STATE.md — the feature tracker
• AGENTS.md at the repo root — a short pointer so any coding tool (Claude Code, Cursor, Codex, Windsurf…) lands on the same rules before writing code

It works two ways: give it a PRD (/sdlc-init <path>) for a new project, or run it bare on an existing codebase and it detects your stack from lockfiles and a handful of source files. Either way it shows you the rules for approval before writing anything.

The pipeline

Every feature or bug lives in .sdlc/specs/<name>/ as exactly two files:

• walkthrough.md — for humans: the problem, the traced flow, the chosen solution, and every decision with its "why", in plain language.
• spec.md — for machines: tasks, file whitelists, contracts, verify commands. No prose.

The stages, each in its own fresh agent:

1. /plan <ticket> — the conversation. It reads the real code and explains: what the ticket means, what actually happens (with file:line traces), why, and the production-grade ways to fix or build it — with pros/cons when options genuinely compete. You push back and refine; when you agree, it writes walkthrough.md. It never writes code.
2. /spec <feature> — turns the agreed direction into ≤ 8 small, independently verifiable tasks.
3. /test <feature> — a separate tester writes the test suite from the spec's contracts, before any implementation exists. For a bug, the first test reproduces it and fails — proof the cause was understood. The developer model never writes the tests that will judge its code.
4. /build <feature> — implements task-by-task until the tester's tests flip red → green. It may never edit those tests; if one looks wrong it files a challenge and /test adjudicates against the spec.
5. /qa <feature> — a fresh agent re-runs everything, checks for regressions, and scans the diff for PR-readiness: no debug leftovers, no dead code, no hardcoded config, code a mid-level dev can trace. Failures become fix-tasks /build executes.
6. /ship <feature> — commits per your git workflow; /ship <feature> --pr pushes and opens a PR whose description (why / what changed / how to test) stands alone for any outside reviewer — human or another company's frontier model.

Pick the path that matches what you're doing:

Hands-free mode

/automate <x> runs the whole pipeline back-to-back with zero stops except real blockers (a verify failing after 3 attempts, an unfixable regression). Its one branch point is at the start:

• You already planned — a walkthrough.md you agreed in /plan exists → automate adopts your plan and continues from whatever stage is next. It never re-litigates an agreed decision.
• Nothing exists — it plans itself, always taking the recommended production-standard option, and records every choice in the walkthrough marked (auto) so you can audit the whole run afterwards.

Every stage still runs as its own fresh agent on its configured tier — automation never collapses the roles back into one context.

Other controls:

• Skip a stage — /sdlc-init --skip-ship (or --skip-qa, --skip-test) drops a stage from handoffs and /automate; toggle any time with --unskip-<stage>. Invoking a skipped skill directly still runs it.
• Bug memory — /qa keeps .sdlc/BUGS.md, a plain-English log: what went wrong, why, how to avoid it. /plan, /spec, and /build read it on every run so the same bug never ships twice.
• Agent tiers — the Agents: line in PROJECT.md maps each stage to strong or mid. Tiers, not vendor names: map them to whatever models your tool offers. Thinking stages (plan, spec, test, qa) default to strong; implementation runs on mid.

Learning a codebase

The other skills build software; /mentor teaches it. Point it at a topic ("teach me Kafka") or at the repo you're sitting in ("teach me this codebase") and it builds a curriculum, then teaches one lesson per session — never dumping the whole course at once — quizzing you at the end of each and only advancing once you pass.

For a codebase it reads the repo first, then runs a short course of one or two modules:

• Map & Run — what the project does, a guided tour of the directories, getting it running locally, and one core flow traced end-to-end through the real files.
• Work On It — the subsystems that change most often (picked from git log), the repo's conventions, and how a change actually ships here: branch, tests, CI, PR.

Every lesson cites real file:line locations and the exercises happen inside the repo — run it, trace it, write a failing test. The final project is a real change with tests passing, so you finish able to contribute rather than just able to describe the code.

State lives in curriculum/<topic>/ (tracker, lessons, quizzes, projects), so progress survives across days and machines. Say next to continue, quiz me for a cumulative check, or status to see where you are.

Changelog

• 0.2.0 — pipeline redesign: new /plan (diagnose & teach a ticket in plain language, no code) and /test (independent tester writes the tests from the spec before build) skills; specs split into human walkthrough.md + machine spec.md under .sdlc/specs/<feature>/; every stage runs as its own fresh agent with configurable model tiers; /automate adopts an agreed plan and runs with zero stops; git-workflow rules and AGENTS.md stubs from /sdlc-init; /ship --pr opens a self-explanatory pull request
• 0.1.8 — PyPI and npm realigned on one version number, so pip and npm always ship the same kit
• 0.1.7 — new /mentor skill: a long-term, file-tracked teacher for any topic, with a codebase mode that onboards you to a repo well enough to contribute to it
• 0.1.6 — same kit on npm: npm install -g ai-sdlc-kit (zero-dependency Node CLI); releases now publish to PyPI and npm together
• 0.1.5 — /automate hands-free flow, stage skipping (--skip-qa / --skip-ship), plain-English bug log (.sdlc/BUGS.md) that feeds future specs, and specs now open with a mental-model section (what / why / how) presented in chat
• 0.1.4 — code-craft rulebook: .sdlc/CRAFT.md pins stack versions + modern idioms, enforces folder structure (one concern per file), env-based config with .env.example, and a security baseline across /spec, /build, /qa
• 0.1.3 — added a Getting started section: how to actually invoke the skills for a new project, an existing codebase, or a single feature
• 0.1.2 — automated PyPI releases via GitHub Actions trusted publishing
• 0.1.1 — cleaner README, professional package presentation
• 0.1.0 — initial release: 6 core skills + architecture-diagram, pip-installable CLI

Related prior art: github/spec-kit.