🌟 What is this?

Spec-Driven Development (SDD) means writing and approving a clear specification before any code is written — so decisions, scope, and quality survive beyond a chat window. In 2026 it is the dominant practice for building software with AI agents.

This repository is two things at once:

1. A school — a bilingual (EN/ES), level-based path to learn SDD from zero, even if you don't program.
2. A toolkit — a ready-to-use structure to apply SDD in real projects: enforcement scripts, AI agent rules, a local MCP server, and a compact spec/ sidecar for existing codebases.

It uses GitHub Spec Kit as the reference workflow engine; this repo is the practical layer around it (starter structure, guidance, rules, and validation).

🔭 Want the industry map? Read SDD in 2026: state of the art and how this template compares.

🚪 Choose your door

Three entry points, one for each kind of visitor:

Then pick your learning level:

• Beginner: docs/en/13-quick-guide-non-programmers.md
• Intermediate: docs/en/14-intermediate-guide.md
• Advanced: docs/en/15-advanced-guide.md

⚡ Start in 30 seconds

Copy/paste this prompt into your AI assistant (Claude, Cursor, Copilot, Gemini...):

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:

Install in any project as a plugin (no cloning):

/plugin marketplace add juanklagos/spec-driven-development-template
/plugin install sdd@sdd-template

• VS Code / Copilot: the same flows as prompt files in .github/prompts/.
• Any agent (32+ 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

No code before an approved spec.md and a consistent plan.md.

This is not just prose — it is machine-checked:

./scripts/check-sdd-policy.sh .   # multi-agent policy files are aligned
./scripts/check-sdd-gate.sh .     # spec approved + plan consistent + consent recorded

Before implementation starts, explicit user consent is recorded:

./scripts/confirm-user-consent.sh "User approved scope X"

(In sidecar projects the same scripts live under ./spec/scripts/.)

Enforce it in CI too — this repo doubles as a GitHub Action:

- uses: juanklagos/spec-driven-development-template@main
  with:
    path: "."      # project root (sidecar or standalone auto-detected)
    strict: "true"

Reference files: sdd.policy.yaml · INSTRUCTIONS.md · AGENT_OPERATING_SYSTEM.md

🎬 How it works

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:

1. spec.md — what and why (approved by you)
2. plan.md — how (consistent with the spec)
3. tasks.md — concrete steps
4. history.md — how it evolved

And every session leaves a trace in bitacora/ (logbook): decisions, handoffs, next step.

See the real flow (create spec → validate → gate), regenerated automatically on every release:

Full walkthrough example: examples/002-mcp-end-to-end

🧭 Apply it to a real project

Three ways to use the template, from lightest to heaviest:

[!TIP]
Default professional path: install only the compact spec/ sidecar. Never copy the full framework into a real codebase unless you explicitly want standalone mode.

Everyday commands (sidecar mode shown; same scripts exist at root in standalone mode):

Folder anatomy, project map and layout details: docs/en/42-project-organization-map.md

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 so the SDD workflow becomes guided commands (/start-project, /create-spec ...).

npm install
npm run build
npm run mcp:start

• 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

Three essential reads:

1. Workflow — the SDD flow step by step
2. Structure — what each folder is for
3. SDD in 2026: state of the art — the industry map and where this template stands

Everything else: the full documentation index organizes all 51 guides (EN/ES) by topic: learning path, prompts, MCP, quality, team mode, legacy migration, legal.

⚖️ Legal & authorship

• License: PolyForm Noncommercial 1.0.0 — legal guide
• Changelog: CHANGELOG.md
• Author: Juan Klagos (AUTHORS.md)