Sdd MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Sdd MCP listing page.
🌱 Spec-Driven Development Template
Learn Spec-Driven Development, then use it on real projects.
One rule: no code until you approve a written spec. A script checks that rule every time you run it, and prints exactly what it looked at.
🇺🇸 English · 🇪🇸 Español
Non-technical start · Quickstart · AI agent start · Commands · Community
What is this?
Spec-Driven Development (SDD) means writing and approving a clear specification before any code exists. What you decided ends up in a file, instead of buried in a chat you will close and never find again. By 2026 it is how most people build software with AI agents.
This repo does double duty.
It is a school: a bilingual (EN/ES) path that starts from zero, with guides, an interactive course and a tutor you can talk to. You do not need to know how to program to get through it.
It is also a toolkit for real work: scripts that check the rule, instruction files your AI assistant reads, a connector so your AI tool can run the workflow itself (MCP, the Model Context Protocol), and a single spec/ folder you add to a project that already has code — without moving any of it.
The step-by-step commands come from GitHub Spec Kit. This repo adds the guides, the checks and the templates on top of them.
The flow in action — create a spec, validate, pass the gate (regenerated on every release):
What changes in practice: decisions stop living in chat history and move into specs/. The gate stays closed until spec.md and plan.md exist, agree, and you record your consent — a script checks that, not somebody's memory. A new teammate or a new agent lands in a folder layout they already recognize. And bitacora/ keeps the session log, so six months later you can still find out why something was done the way it was.
Want the industry map? Read SDD in 2026: state of the art and how this template compares.
Choose your door
- Non-technical (founder, PM, curious): START_HERE_NON_TECH.md — a guided start with no jargon in it.
- Developer: QUICKSTART.md — the commands to scaffold and validate, about five minutes.
- AI agent, or you pasting into one: AI_START_HERE.md — operating rules plus copy/paste prompts for each level.
Then pick your learning level. Every guide on the docs site carries its level badge:
- 🟢 Beginner: quick guide for non-programmers
- 🟡 Intermediate: team discipline guide
- 🔴 Advanced: governance and standardization
[!TIP] If you would rather learn by doing, take the interactive course (GitHub Skills format): 4 steps, ~35 min, auto-graded by Actions. Your exam is the real SDD gate.
Start in 30 seconds
Copy/paste this prompt into your AI assistant (Claude, Cursor, Copilot, Gemini...):
Built-in commands for your AI agent
If you use Claude Code, this repo ships slash commands out of the box. Start with /sdd:help:
| Command | What it does |
|---|---|
/sdd:help | Tells you what stage you are in and the single next step |
/sdd:new | Guided start: idea → first spec ready for approval |
/sdd:spec | Create or refine a spec bundle with EARS criteria |
/sdd:gate | Runs the gate — approval, plan consistency, consent — and records yours |
/sdd:decision | One decision, written down in bitacora/decisiones/: what, why, what was rejected, when to revisit |
/sdd:close | Validates and closes the session with the output contract |
/sdd:tutor | A conversational SDD course by levels, graded by the real validation scripts |
Install in any project as a plugin (no cloning):
- VS Code / Copilot: the same flows as prompt files in
.github/prompts/. - Any agent (39 tools): portable Agent Skill at skills/sdd-workflow/SKILL.md.
- AI context: llms.txt indexes all docs for coding agents (regenerate with
./scripts/generate-llms-txt.sh).
The golden rule
[!IMPORTANT] No code before an approved
spec.mdand a consistentplan.md. A script enforces this, and implementation starts only once your consent is on record.
(In sidecar projects the same scripts live under ./spec/scripts/.)
Enforce it in CI too. This repo doubles as a GitHub Action, listed on the GitHub Marketplace:
Reference files: sdd.policy.yaml · INSTRUCTIONS.md · AGENT_OPERATING_SYSTEM.md
How it works
Every feature gets a numbered spec bundle, and every session leaves a trace in bitacora/ (the logbook):
spec.md— what and why (approved by you)plan.md— how (consistent with the spec)tasks.md— concrete stepshistory.md— how it evolved
Full walkthrough example: examples/002-mcp-end-to-end
Apply it to a real project
Fastest start (no clone needed):
It asks a few questions and scaffolds the recommended spec/ sidecar, or a full workspace, from the latest template.
Three ways to use the template, from lightest to heaviest:
| Mode | When | Command |
|---|---|---|
Compact spec/ sidecar ⭐ | Real or existing project: SDD artifacts in ./spec/, code stays in your project root | ./scripts/install-spec-sidecar.sh /path/to/project --profile=recommended |
Internal workspace www/ | The runnable project should live inside this template repo | ./scripts/create-www-project.sh my-project codex |
| Full standalone copy | You explicitly want the whole framework as your workspace | ./scripts/init-project.sh /path/to/project --profile=full |
[!TIP] The professional default is the compact
spec/sidecar and nothing else. Never copy the full framework into a real codebase unless you actually want standalone mode.
Everyday commands (sidecar mode shown; the same scripts exist at root in standalone mode)
| Action | Command |
|---|---|
| New spec | ./spec/scripts/new-spec.sh "my-feature" "Owner" |
| Validate structure | ./spec/scripts/validate-sdd.sh . --strict |
| Policy check | ./spec/scripts/check-sdd-policy.sh . |
| SDD gate | ./spec/scripts/check-sdd-gate.sh . |
| Status dashboard | ./spec/scripts/generate-status.sh |
Folder anatomy and layout details: project organization map
Connect via MCP (optional, advanced)
If your AI tool supports MCP (the Model Context Protocol), it can run this workflow itself: create specs, check the gate, write the logbook. One command sets it up, in your project's folder:
It finds the clients you have — Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, opencode — and writes the configuration into each one's own file. It merges into what you already have and never overwrites it. Add --dry-run first to see what it would touch. Then restart your client.
- Prefer doing it by hand? Point your client at npm:
{"command": "npx", "args": ["-y", "@juanklagos/sdd-mcp@latest"]}. The@latestmatters — without it,npxcan serve an old cached version with fewer tools. - Working on this template itself?
npm install && npm run build && npm run mcp:startruns the server from source. - SDD Builder (visual, drag-and-drop): build once with
npm run builder:build, thenSDD_PROJECT_ROOT=/path/to/your/project npm run mcp:http:startand openhttp://127.0.0.1:3334/builder— compose your specs as connected cards, where every card is a realspecs/NNN/bundle on disk. Inside this template repository the builder is blocked by design (no target-project work in the template root), so always pointSDD_PROJECT_ROOTat a real workspace. See the visual guide. - Already using SDD and want the latest?
npx @juanklagos/sdd-mcp@latest upgrade --project-root . --dry-runshows what would change before changing it: framework files get repaired, yours are never written without--apply. See the upgrade guide. - SDD Desk (the same builder, as a desktop app): download it for macOS, Windows or Linux. Nothing else has to be installed: the app includes everything it needs. While it is open, your AI assistant can connect to it — copy the address the app shows you and paste it into your assistant's settings. One caveat: the app is not digitally signed, so the first time you open it macOS or Windows shows a scary-looking warning and asks you to allow it. If you would rather not deal with that, run
npx @juanklagos/sdd-mcp@latest --httpinstead. Same tool, in your browser, no warning. - Visual dashboard: point the server at a project —
SDD_PROJECT_ROOT=./www/my-project npm run mcp:http:start— then openhttp://127.0.0.1:3334/dashboardfor a page you can look at but not edit: whether the gate is open, a few headline numbers, how far each spec has got, and which specs are waiting on another one. In your language, with nothing to compile. This folder — the template itself — is not a project, so if you run it here it will tell you so. - Easiest explanation first: Easy MCP Guide
- Client configs:
.mcp.json(Claude Code) · Cursor · Codex - Complete reference: docs/en/41-complete-mcp-reference.md
Note: GitMCP (free, remote) helps an AI read this public repo; the local sdd-mcp runs the real guided workflow. They complement each other: GitMCP guide.
Documentation
Browse online: the documentation site has every guide with search, an EN/ES language picker and level badges.
If you only read three:
- Workflow — the SDD flow step by step
- Structure — what each folder is for
- SDD in 2026: state of the art — the industry map and where this template stands
Everything else: the full documentation index organizes all 53 guides (EN/ES) by topic.
Community
- Docs site: juanklagos.github.io/spec-driven-development-template
- Questions, ideas, show-and-tell: GitHub Discussions
- Bugs and concrete proposals: Issues
- Interactive course: aprende-sdd — learn by doing, auto-graded by Actions
- Finished a tutor level?
/sdd:tutorrecords it in your logbook and hands you a completion badge for your README
Legal & authorship
- License: MIT — use it anywhere, including commercially and inside a company, free and without asking. Keep the copyright notice. Legal guide
- What you write with the templates is yours: TEMPLATE-OUTPUT.md
- Publishing a release / Publicar una versión: RELEASING.md
- Changelog: CHANGELOG.md · Latest release: v2.8.0
- Copyright (c) 2026 Juan Carlos Alvarez Lagos (AUTHORS.md)
If this saves you one bad sprint, a ⭐ helps other people find it.
🌱 No code before approved spec and consistent plan.