Spec-Driven Development workflow: specs, plans, gates, status and logbook tools. Bilingual EN/ES.
The io.github.juanklagos/sdd-mcp MCP server supports a Spec-Driven Development workflow focused on managing specs, plans, gates, status, and logbook artifacts. It provides bilingual English/Spanish (EN/ES) coverage for the described workflow elements.
🛠️ Key Features
Spec-driven development workflow centered on specs, plans, and gates
Tools for status tracking
Logbook tooling
Bilingual EN/ES support
🚀 Use Cases
Managing specification artifacts as part of a development process
Planning and gating work with explicit “gates” control points
Recording and reviewing progress via status and logbook tooling
⚡ Developer Benefits
Consistent workflow around specs, plans, gates, status, and logbook
EN/ES bilingual support aligned to the workflow’s documentation/output
⚠️ Limitations
Limited documented detail beyond the workflow scope and bilingual support
Learn Spec-Driven Development, then use it on real projects. One rule, and a gate that stays shut until you approve a spec — and tells you on every run exactly what it checked.
Spec-Driven Development (SDD) means writing and approving a clear specification before any code exists, so that scope and decisions outlive the chat window they were born in. 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: enforcement scripts, rules your agent reads, an MCP server, and a compact spec/ sidecar you drop into a codebase that already exists.
The workflow engine underneath is GitHub Spec Kit. This repo is the practical layer around it.
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 client supports MCP, this repo ships a local sdd-mcp server that turns the SDD workflow into guided commands (/start-project, /create-spec ...).
bash
npm install
npm run build
npm run mcp:start
No clone? Point your MCP client straight at npm: {"command": "npx", "args": ["-y", "@juanklagos/sdd-mcp"]}.
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.
SDD Desk (the same builder, as a desktop app):download it for macOS, Windows or Linux. It carries its own Node runtime, so nothing has to be installed first, and while it is open the app is your project's MCP server — point your agent at the URL it shows you. The builds are not code-signed: macOS and Windows ask you to authorise the app once, with a warning that sounds alarming, so it suits people who do not mind doing that. If you would rather not, npx @juanklagos/sdd-mcp@latest --http gives you the same builder in your browser with no warning at all.
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 read-only executive view (gate verdict, KPI tiles, per-spec progress, dependency warnings) in your language, with no build step. The template root is not a workspace, so running it from here reports exactly that.
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.
