Open source · v0.2.0 · MIT
An AI agent has one advantage over a human: it forgets everything between turns. This project turns your engineering rules into files the agent cannot skip, and gates it cannot talk its way past.
npx create-sdd-ai-stack my-app// WHAT IT IS
Spec-Driven Development started as a discipline: write down what the system must do before writing the code. This project applies it to the agent itself — the spec, the rules and the acceptance criteria all become files, and the agent is a worker executing them rather than an author inventing them.
// Without a spec
// With SDD
01
PLAN.md holds exactly one task in flight, sized so it fits in an attention span. If it takes more than an hour, it is split before it starts.
02
stacks/*.md is the engineering knowledge: architecture, language, testing, security. Routed by index so the agent reads the minimum necessary.
03
A task closes only when the green terminal output is pasted. Not described. Pasted, with the real counts.
// WHY IT WORKS
Not opinions. Each one is a property of the repository that either holds or does not, and most of them can be checked by a script.
16.5ktokens
The mandatory read order costs ~16.5k tokens before the first line of code. That is why every doc opens with a router, and why the spine is compressed. An agent that reads 40 files to answer one question hallucinates by file 30.
4CI gates
Branch protection on main, a coverage floor at 95/85/90, npm audit at high severity, and a job that fails if an action is pinned to a deprecated runtime. A green build is not the same as a correct change.
0dead code
The first audit found the reference feature imported by nothing. It is now wired, behind real auth, with E2E proving the auth rejection writes no row. A template that violates its own conventions teaches the wrong lesson.
98.5% line coverage
Coverage is a gate with a floor in the file, not a number in someone's memory. Lowering it requires a written reason next to the change.
// PRACTICES
Every practice here exists because its absence produced a bug that a test now prevents.
PLAN.md holds exactly one `[-]` task. Two means the agent stopped wrong. Micro-scoping is not bureaucracy: an agent that loses the thread mid-task writes code nobody asked for.
If it takes more than 1 hour, split it in two before starting.
Commands prove the code compiles. Criteria prove the code is right. The task template asks for Given/When/Then, the 401 that writes no row, the forbidden role, the repository that throws.
Every criterion needs a test that would fail without the change.
The browser is untrusted. Authentication, then authorization, then validation, then mutation, then cache — in that order, on the server. A disabled auth stub in a template is a trap, so this one is wired and tested.
Authorization lives in the data layer, not only in the UI.
`next dev` does not minify and takes a different render path. A green E2E against dev proves nothing about production.
E2E runs against `next build && next start`, on Chromium and Firefox.
An unmeasurable function is a function nobody ran. Every generated slice compiles on the first run; the parts that need a human decision fail at runtime, loudly, not at build time.
Every new export must be imported somewhere. Grep it.
A token-saving tool may shorten your prose. It may never shorten the evidence block. Full command, full exit code, real counts.
Paste the output. Describing it is not the same as running it.
// AI IN THE LOOP
The failure mode of agentic development is not a model that is wrong. It is a model that is confidently, fluently, unaccountably wrong — and nobody can tell from the diff which parts were invented.
| Layer | The human | The agent |
|---|---|---|
| The spec | Decides the why and the acceptance criteria. | Reads PLAN.md, takes the single `[-]` task, stops at the boundary. |
| The rules | Writes the convention once, as prose, in the right file. | Opens only the doc the router points at. Does not invent a convention that is not written down. |
| The code | Owns the architecture and the trade-off. | Implements inside the vertical slice, hexagonal arrows inward, one reason to change per file. |
| The evidence | Decides whether the claim is credible. | Runs the gate, pastes the real output, and refuses to mark a task done on a red test. |
// What the laws forbid
// INSTALL
The CLI has zero runtime dependencies. It copies files, creates a directory, and gets out of the way.
// Create a project
# the whole thingnpx create-sdd-ai-stack my-app# skip the install, it is slownpx create-sdd-ai-stack my-app --no-install# rules only, into a project you already havenpx create-sdd-ai-stack . --rules-only// What lands
my-app/├── src/ Next.js 16 App Router + Tailwind v4 + Biome│ ├── app/ routing only — no business logic│ ├── features/example the live vertical slice, wired and tested│ ├── shared/ ui (shadcn) · lib · server (auth, env)│ └── proxy.ts the network boundary├── tests/ unit · integration · e2e├── SDD/ the rules — the product│ ├── AGENTS.md agent laws + delivery flow│ ├── specs/ PLAN.md, tasks, history│ ├── stacks/ 25 rule files, one spine│ └── SKILLS/ scripts that check the rules└── AGENTS.md shortcut → ./SDD/AGENTS.md// Options
--rules-only
Install only the rules, into an existing project. No app.
--submodule [url]
Install ./SDD as a git submodule, so `git submodule update` syncs the rules.
--git
git init plus the first commit, using your own git identity.
--shortcuts <mode>
auto (symlink with stub fallback), stub, or symlink. AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md, .clinerules, GEMINI.md.
--install
Run npm install for you. Off by default.
--template <name>
next (default) or none.
// First run of the generated app
cd my-appnpm installnpx playwright install chromium firefoxnpm run dev# the gate, before you believe yourselfnpm run typecheck && npm run lint \ && npm run test && npm run build// INDICATIONS
The shortcuts point at one file. Whichever agent you use, it reads the same laws.
// Agents, wired on the first run
// Recommended
Token compression and spend observability for your own agent runs. Same compression law as the rule files: prose may be compressed, evidence may not.
The E2E layer. Tests run against the production build on two engines, which is why a passing suite means the build works.
Lint and format in one binary, fast enough to run on every save. `next lint` was removed in Next 16; run your linter directly.
Components copied into your repo, so you own the code. `components.json` ships pre-configured, so the first `npx shadcn add` does not ask for a layout.
One schema, both sides. The client check is a courtesy; the server is the only source of truth.
// Stacks with a rule file
// CONTRIBUTE
Most of this repository is prose. That makes contribution unusually cheap: a better sentence in the right file is a real improvement.
The fastest fixes come with a failing command. If a rule led an agent astray, say which rule and what it did instead.
Open an issue →A new stack is one markdown file following the pattern, listed in stacks/README.md. Spine first: map it to clean-code.md, do not duplicate it.
See the pattern →A rule nobody checks is a rule nobody follows. If you can write a script that fails when the rule is broken, that is the highest-value contribution here.
See the existing checks →// Local development
git clone marcelinosandroni/sdd-ai-stack && cd sdd-ai-stacknpm installnpm test # the CLI suitenpm run check:coveragenpm run check:docs# prove the template still buildsnode bin/create-sdd-ai-stack.mjs .sandbox --no-install --yescd .sandbox && npm install && npm run build// House rules for a pull request
// Need help or found something?