🌱 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...):

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 (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.md and a consistent plan.md. A script enforces this, and implementation starts only once your consent is on record.

./scripts/check-sdd-policy.sh .   # multi-agent policy files are aligned
./scripts/check-sdd-gate.sh .     # spec approved + plan consistent + consent recorded
./scripts/confirm-user-consent.sh --spec 001-<slug> "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, listed on the GitHub Marketplace:

- uses: juanklagos/spec-driven-development-template@v2.8.0
  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, and every session leaves a trace in bitacora/ (the logbook):

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

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

Apply it to a real project

Fastest start (no clone needed):

npx @juanklagos/create-sdd-project@latest my-app

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:

[!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.

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)"]