Spec-Driven Development workflow: specs, plans, gates, status and logbook tools. Bilingual EN/ES.
io.github.juanklagos/sdd-mcp MCP Server
This MCP server supports a spec-driven development workflow using specs, plans, gates, and status/logbook tools. It provides a bilingual EN/ES experience. The project centers on requiring written specs before any code is produced, with a script that checks this rule during runs.
🛠️ Key Features
Spec-driven development workflow
Tools for specs, plans, gates, and status/logbook
Enforces “no code until you approve a written spec” via a script check
Bilingual EN/ES documentation
🚀 Use Cases
Coordinating spec, plan, and gate progression for development
Tracking status and maintaining a logbook for workflow history
Applying a GitHub template aligned with spec-driven development
⚡ Developer Benefits
Written-spec approval as a workflow gate
Automated verification of the rule at each run
Shared workflow structure for AI/coding agents and documentation-based development
⚠️ Limitations
Focused on the spec-driven development process (specs, plans, gates, status/logbook), not general-purpose tooling.
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.
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):
SDD flow demo: create a spec, validate the structure, pass the gate
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.
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...):
text
Using https://github.com/juanklagos/spec-driven-development-template, guide me step by step with SDD for my project.
My project is: [describe your project in plain language].
If my project is new, initialize from this template and GitHub Spec Kit as the base workflow.
If it already exists, adapt it without breaking current behavior.
No code before approved spec and consistent plan.
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
flowchart LR
A["💡 Idea in plain language"] --> B["📋 spec.md approved"]
B --> C["🗺️ plan.md consistent"]
C --> D["✅ tasks.md prioritized"]
D --> E["🚦 Gate + explicit consent"]
E --> F["⚙️ Implementation"]
F --> G["🔍 Validation + logbook"]
Every feature gets a numbered spec bundle, and every session leaves a trace in bitacora/ (the logbook):
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)
flowchart TD
A["Your project root (code)"] --> B["spec/"]
B --> C["idea/"]
B --> D["specs/ (numbered bundles)"]
B --> E["bitacora/ (logbook)"]
B --> F["scripts/ (gate + validation)"]
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:
bash
npx @juanklagos/sdd-mcp@latest connect
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 @latest matters — without it, npx can serve an old cached version with fewer tools.
Working on this template itself?npm install && npm run build && npm run mcp:start runs the server from source.
SDD Builder (visual, drag-and-drop): build once with npm run builder:build, then SDD_PROJECT_ROOT=/path/to/your/project npm run mcp:http:start and open http://127.0.0.1:3334/builder — compose your specs as connected cards, where every card is a real specs/NNN/ bundle on disk. Inside this template repository the builder is blocked by design (no target-project work in the template root), so always point SDD_PROJECT_ROOT at a real workspace. See the visual guide.
Already using SDD and want the latest?npx @juanklagos/sdd-mcp@latest upgrade --project-root . --dry-run shows 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 --http instead. 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 open http://127.0.0.1:3334/dashboard for 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.
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.
