Specs-Driven Development for AI-paired coding, in plain markdown. One task file. Three sections. Plan → Implement → Walkthrough.

You and your AI agent stop arguing about what to build, lock alignment in a single doc, then ship one numbered step at a time — with a hard pause for human verification before any code commit. When the work merges, the plan folds into a living feature spec and the task file gets archived. That's it. No fleet of role-playing agents, no story points, no phase gates.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   1. PLAN       │───▶│  2. IMPLEMENT   │───▶│ 3. WALKTHROUGH  │
│                 │    │                 │    │                 │
│ Goal +          │    │ Step-by-step    │    │ What shipped +  │
│ Constraints +   │    │ checklist with  │    │ what was cut +  │
│ Files touched + │    │ commit hashes.  │    │ decision-log    │
│ Steps +         │    │                 │    │ entry pasted    │
│ Out of scope.   │    │ HARD STOP for   │    │ into the living │
│                 │    │ human local     │    │ feature spec.   │
│ Reviewed and    │    │ verification    │    │                 │
│ approved BEFORE │    │ before every    │    │ Task file moved │
│ a single line   │    │ code commit.    │    │ to archive for  │
│ of code lands.  │    │                 │    │ historical ref. │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        ▲                                              │
        └──────── next feature starts the loop ────────┘

One markdown file (docs/tasks/<area>-<slug>.md) carries the work from idea to merge. The living spec (docs/features/<area>.md) carries the system's truth forever.

1. Plan alignment happens before code, not after. The Plan section forces you and the agent to agree on Goal, Constraints, Files touched, Steps, and Out of scope. Reviewers — including future-you — read one section, not a sprawling story tree.

2. The agent can't drift. Steps are numbered. Each step gets a commit hash next to its checkbox. If the agent strays, you point at the step number. There's nowhere to hide.

3. Tests verify code; humans verify features. The hard rule: code commits require local human verification, not just green tests. Tests prove correctness of what was tested. They don't catch iOS auto-zoom on number inputs, opacity transitions on mobile Safari, or the wrong button color shipping to prod. The verification gate is non-negotiable.

4. Living specs replace dead PRDs. features/<area>.md is the source of truth: a checklist of - [x] shipped, - [ ] planned, - [~] in-progress capabilities, each with a (file:line) pointer. PRDs go stale; checklists with line numbers don't.

5. History without clutter. Completed task files move to docs/archive/tasks/ — frozen at the state when the work shipped. The tasks/ folder is always in-flight. The archive answers "how did we get here?" without polluting the active workspace.

6. It's just markdown. No DSL. No YAML config. No agent role files. No story-point estimation. No sprint ceremonies. Anyone with a text editor can read, write, and diff this. Any AI agent — Claude Code, Cursor, Aider, plain ChatGPT — can drive the loop.

If you're shipping enterprise software with auditors, you might want the heavier framework. If you're a developer who wants AI-paired coding to feel structured but not bureaucratic, SDD-Lite is the floor that keeps things from collapsing into chaos.

Copy SDD-Lite into your repo:

# from your project root
cp -r /path/to/SDD-Lite/docs/CONTRIBUTING.md docs/
cp -r /path/to/SDD-Lite/docs/tasks docs/
cp -r /path/to/SDD-Lite/docs/archive docs/
cp -r /path/to/SDD-Lite/.claude .

Then create your feature areas:

mkdir -p docs/features
# Create one .md file per feature area, e.g.:
# docs/features/auth.md
# docs/features/billing.md
# docs/features/dashboard.md

Each feature file follows the four-section shape: Overview → Capabilities → Decision log → References. See examples/leagues.md for a worked one.

That's the whole install. Nothing to compile, nothing to run.

This is the actual flow you and your AI agent will run dozens of times. Every prompt is short.

You:

/plan-feature <area> <slug> <one-line description of the feature>

For example:

/plan-feature billing seat-based-pricing Add per-seat pricing tier with monthly invoicing

The agent invokes the plan-feature skill, scaffolds docs/tasks/billing-seat-based-pricing.md from _TEMPLATE.md, pre-fills the Goal section, and adds a - [~] Seat-Based Pricing — see [tasks/...] placeholder under "Active work" in docs/features/billing.md.

The agent will not write code. It will not invent steps. The Plan's Constraints, Files touched, Steps, and Out of scope sections stay as placeholders, waiting for you.

You:

Read docs/features/billing.md to understand the current surface, then
fill in Constraints, Files touched, Steps, and Out of scope on the new
task. Don't write code yet — just the plan.

The agent surveys the current code, drafts the plan, and shows you the file. This is your first checkpoint. Read it. Push back.

Step 4 conflates two things — split it. And add a constraint that the
new pricing tier must not regress free-tier signup latency.

Iterate until the plan reads like something you'd ship from. Heavy frameworks have you do this across five documents; SDD-Lite has you do it in one section.

When the plan is right:

Plan looks good. Start step 1 — and remember the local-verify rule:
write the code, run the test suite, show me the diff, then STOP. Don't
commit until I run it locally and say so.

The agent writes the code for step 1 only. It runs the tests. It shows you the diff and explicitly waits.

You run it locally — start your dev server, click through the affected pages, stress-test edge cases. Tests catching it isn't enough; eyeballs catch what tests miss.

If it looks right:

Looks good. Commit.

The agent commits, ticks step 1 in the task file with the commit hash:

- [x] 1. Scaffold seat-based pricing model (commit `5e313f4`)
- [ ] 2. Wire checkout flow

If it doesn't look right:

The empty-state copy is wrong — it should say "Invite your first seat"
not "No seats yet". Fix and re-show the diff.

The agent fixes, re-runs tests, shows the diff again. The commit doesn't land until you say so.

Next.

…or:

Start step 2.

The agent picks up the next unchecked step, writes the code, runs tests, stops, waits.

When all steps are done, the agent fills in the Walkthrough section: what shipped (with file.py:123 pointers), what was cut, follow-ups, and a one-sentence decision-log entry.

You:

Walkthrough looks right. Fold the bullets into docs/features/billing.md,
add the decision-log entry, and move the task file to docs/archive/tasks/.

The agent does all three in one commit. The task file is now historical record. The feature spec is the new truth.

SDD-Lite/
├── README.md                                   # this file
├── docs/
│   ├── CONTRIBUTING.md                         # the framework — read this first
│   ├── tasks/
│   │   ├── _TEMPLATE.md                        # copy this for new tasks
│   │   └── README.md                           # tasks/ lifecycle
│   └── archive/tasks/README.md                 # archive conventions
├── .claude/skills/plan-feature/SKILL.md        # /plan-feature scaffolding skill
└── examples/
    ├── leagues.md                              # worked features-spec example
    └── leagues-create-edit-flexibility.md      # worked task example (Plan + Implement)

CONTRIBUTING.md is the spec. _TEMPLATE.md is what you copy. SKILL.md is what your agent invokes. The two examples/ files show what real artifacts look like in production.

1. /plan-feature <area> <slug> <description>           # scaffold
2. Read features/<area>.md, fill in the plan.          # align
3. Plan looks good. Start step 1. Stop before commit.  # implement
4. Looks good. Commit.                                 # ship

Four prompts. One markdown file. Living feature specs. Archived history. No agent fleet. No story points. No bureaucracy.

That's SDD-Lite.