Metadata-Version: 2.4
Name: ai-sdlc-kit
Version: 0.1.0
Summary: Spec-driven SDLC skills for AI coding agents — Claude Code, Cursor, Windsurf, Gemini CLI
Project-URL: Homepage, https://github.com/xajeel/AI-SDLC
Author: xajeel
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude-code,cursor,sdlc,skills,spec-driven
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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):

```markdown
# 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":"test@example.com","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](https://github.com/github/spec-kit).
