Spec Driven Development Template

⚡ Start in 30 Seconds

This framework uses GitHub Spec Kit as the primary workflow reference. Use this repository as the practical layer around that base:

• GitHub Spec Kit = reference workflow engine
• this repository = starter structure, sidecar installation, AI rules, MCP, and project guidance

1. Open AI_START_HERE.md or START_HERE_NON_TECH.md if you are non-technical.
2. Copy/paste this prompt:

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.

1. Choose your level and continue:

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

🔌 Connect via MCP

If your AI client supports MCP, this repository now includes a local sdd-mcp server and shared project config.

If you want the simplest explanation first:

• Easy MCP Guide

Important distinction:

• GitMCP or similar can help an AI read and understand this public repository for free.
• It does not replace this framework's own sdd-mcp behavior.
• Use GitMCP for remote repo context and sdd-mcp for the real guided SDD workflow.

Quick path:

1. Build the server:

npm install
npm run build

1. Use one of these configs:

• Claude Code project config: .mcp.json
• Cursor example: packages/sdd-mcp/examples/.cursor/mcp.json
• Codex example: packages/sdd-mcp/examples/codex.config.toml

1. Read in this order:

• docs/en/43-easy-mcp-guide.md
• docs/en/41-complete-mcp-reference.md
• docs/en/33-mcp-server-guide.md
• docs/en/40-command-results-reference.md

🎬 Fast Adoption Flow

flowchart LR
  A["Describe project in plain language"] --> B["Create SDD base"]
  B --> C["Approve first spec"]
  C --> D["Align plan and tasks"]
  D --> E["Validate + gate"]
  E --> F["Implement only after explicit consent"]

Use a complete example:

• examples/002-mcp-end-to-end/README.md

🚨 Mandatory Rule Before Coding

This template enforces policy + gate checks:

# standalone framework workspace
./scripts/check-sdd-policy.sh .
./scripts/check-sdd-gate.sh .

# compact sidecar inside a real project
./spec/scripts/check-sdd-policy.sh .
./spec/scripts/check-sdd-gate.sh .

Hard stop:

• No code before approved spec.md and consistent plan.md.
• Record explicit user consent before execution/implementation starts:
  • sidecar: ./spec/scripts/confirm-user-consent.sh "User approved scope X"
  • standalone: ./scripts/confirm-user-consent.sh "User approved scope X"

Reference files:

• sdd.policy.yaml
• INSTRUCTIONS.md
• template-context/core-instructions/AGENT_OPERATING_SYSTEM.md

🎯 Problem vs Solution

🧭 Template vs Real Project

• This repository is a framework/template.
• It uses GitHub Spec Kit as the base operating reference for the command sequence and SDD flow.
• The professional productization path is: framework root + packages/sdd-core + packages/sdd-mcp.
• Your product work should run in your target project using this structure.
• For real projects, prefer a compact spec/ sidecar inside the project and keep code in the project root.
• Do not clone or copy the full framework repository into the target project unless you explicitly want a full standalone workspace.
• Inside this repository, use www/<project-name>/ as the clean container when the target project should live here.
• The user may choose another target path; if the runnable project lives inside this repository, keep it under www/ to avoid mixing framework and product work.
• If you adapt an existing project, integrate idea/specs/bitacora without breaking current behavior.

🗺️ 3-Level Learning Path

flowchart LR
  A["Beginner"] --> B["Intermediate"]
  B --> C["Advanced"]
  A --> D["First idea + first spec"]
  B --> E["Consistent team sessions"]
  C --> F["Governance + quality gates"]

🏗️ Anatomy of an SDD Project

Full folder-by-folder map:

• docs/en/42-project-organization-map.md

flowchart TD
  A["Framework Root"] --> B["idea/"]
  A --> C["specs/"]
  A --> D["bitacora/"]
  A --> E["docs/"]
  A --> F["scripts/"]
  A --> G["packages/"]
  A --> H["www/"]
  H --> I["target-project/"]
  I --> J["spec/"]

Mandatory folders:

• idea/: project intent and scope
• specs/: numbered specifications
• bitacora/: execution trace and handoffs
• docs/: usage guides and references

For real target projects, those SDD folders usually live under ./spec/:

• ./spec/idea/
• ./spec/specs/
• ./spec/bitacora/

Mandatory spec bundle (for each feature):

1. spec.md
2. plan.md
3. tasks.md
4. history.md

👤 Non-Technical Path

• Start here: AI_START_HERE.md
• Ultra-simple starter: START_HERE_NON_TECH.md
• Follow level path: docs/en/18-complete-3-level-path.md
• Use ready prompts:
  • docs/en/19-prompt-matrix-by-goal.md
  • docs/en/26-validated-prompt-bank.md

🛠️ Technical Path

[!TIP] Default professional path: install only the compact spec/ sidecar in real projects. Use a full copy only when you explicitly need a standalone workspace.

📚 Documentation Discovery

• Essentials: Structure · Workflow
• AI: Supported Agents · Lovable Guide
• MCP: Complete Reference
• MCP Easy Mode: Easy Guide
• MCP Hosted Onboarding: Model
• MCP Client Examples: Visual Guide
• MCP Free External Options: Guide
• MCP GitMCP Connection: Step-by-step
• Sidecar Prompts: Exact prompts for spec/ mode
• MCP Setup: Server Guide
• MCP Results: Command Reference
• Client Setup: Recipes
• Versioning: Strategy
• Roadmap: Public Roadmap
• Organization: Project Map
• Media Kit: Assets and Positioning
• Historical Release Prep: v1.3.0 prep notes
• Quality: Stage Checklists · ADR

⚖️ Legal & Authorship

• License: PolyForm Noncommercial 1.0.0
• Legal guide: docs/en/31-legal-framework-and-commercial-use.md
• Changelog: CHANGELOG.md
• Author: Juan Klagos (AUTHORS.md)