SDD Kit

Specifications as The Single Source of Truth

sdd-kit is a product engineering framework and workflow designed to manifest abstract vision into high-fidelity software.
It transforms how we build software by prioritizing intent over implementation.
It turns the abstract vision into a centralized, human & machine-readable specification (your project's ultimate source of truth).
Here, the code is merely a transient artifact; the specification is the real product.
Master the intent. Own the result.

• 🌟 The Philosophy
• 📂 The Sacred Tree
• 🚀 SDD Lifecycle
• 💡 SDD-Kit vs Spec-Kit
• 🛠️ Quickstart
• 📑 Prompt Reference
• 🤖 Supported AI Agents
• 🔄 Project Adaptability
• 🤝 Contributing
• Maintainers
• License

Traditional software development often leads to "documentation rot" — where the specs and the code drift apart.
sdd-kit enforces a unidirectional flow of truth:

1. Intent Capture: You state your vision (the 'why') and define what needs to be built.
2. The Sacred Spec Tree: Your intent is "ventilated" into a structured specs/ directory.
3. AI Execution: Agents use this high-context, unpolluted specification to generate implementation with surgical precision.

The toolkit organizes your project to separate intelligence (specs) from execution (code and ephemeral AI logs).

PROJECT/
├── .github/
│   └── instructions/
│       └── sdd-instructions.md  # (LAW) Governing principles & SDD-Kit workflow rules.
│
├─── specs/
│    ├── product-vision.md     # (STRATEGY) The "Why", Personas, Tone.
│    ├── product-definition.md # (SCOPE) The "What". Functional Map & Epic-Modules list.
│    ├── system-context.md     # (MAP) System boundaries & external actors.
│    ├── decisions/            # (MEMORY) Immutable ADRs.
│    ├── domain/               # (RULES) Pure business logic (No UI).
│    ├── features/             # (FLOWS) User stories & UI interactions.
│    └── technical/            # (PLUMBING) Singleton technical truths.
│        ├── architecture/      # (BLUEPRINTS) Logical system design via C4 Model (Context, Containers, Components).
│        ├── stack.md           # (FOUNDATION) Core technologies, versions, and technical constraints.
│        ├── project-structure.md # (PHYSICAL MAP) The literal file/folder organization of the codebase.
│        ├── db-schema.md       # (DATA) Centralized DBML source of truth for database architecture.
│        └── api/               # (INTERFACES) API Contracts & OpenAPI specifications.
│
├── .sdd/
│   ├── runs/                 # (TRASH) Ephemeral execution artifacts (plans, tasks, execution logs).
│   └── backlog/              # (STATE) Persistent implementation backlog & status (implicit, agent-managed).
│
└── src/                      # 🛠️ Artifacts: The generated or maintained code

• Code is Transient: Your src/ folder is a disposable artifact. It can be refactored, migrated, or regenerated overnight.
• Intent is Permanent: Your specs/ tree (The Sacred Tree) is your project's soul. It captures the Strategy, Domain Rules, and User Flows in a format that AI Agents can navigate with 100% certainty.
• True Vibe Coding: "Vibing" only works when the foundation is rock-solid. By centralizing the Data Schema (DBML), API Contracts, and Product Vision, sdd-kit gives agents a God-view of your project, allowing them to implement complex features with zero context-drift.

Build on solid ground. Define the core DNA of your project before a single line of code is written.

• Strategy: Define Product Vision and Scope.
• Technology: Set the Tech Stack and Technical Constraints in stack.md.
• Architecture: Run sdd architect to create/update C4 views (Context, Containers, Components) under specs/technical/architecture/.
• Data & API: Generate the initial DB Schema (DBML) and Interface Contracts (OpenAPI).

Instead of scattered tickets, every new feature is integrated into the centralized specs/ directory.

• Intent Capture: The CLI captures your raw idea and structures it via sdd feature.
• Routing: Logic is "ventilated": domain rules go to domain/ while user flows go to features/.
• Continuous Enrichment: As you specify features, your Schema and API contracts evolve automatically.
• Architecture Alignment: When a feature changes boundaries or containers, revisit sdd architect to update the logical blueprints.

The critical checkpoint between design and execution. Before moving to implementation, run sdd gap to generate an Implementation Gap Report:

• Drift Detection: Identify specifications that have no matching items in the backlog.
• Artifact Health: Surface stale or missing execution artifacts under .sdd/runs/ and .sdd/backlog/.
• Alignment: Ensure the "Sacred Tree" and the "Execution Area" are perfectly synchronized.

Turn structured specifications into code using AI agents that finally have the full context.

• Standard Mode: sdd plan → sdd tasks → sdd implement.
• Auto-Pilot ("Vibe" Mode): Run sdd vibe. It natively uses gap analysis and freshness checks to automate the entire chain (Plan → Tasks → Implement) with high-confidence results.

sdd-kit is heavily inspired by SpecKit. We admire their pioneering work in moving the industry toward a Spec-Driven Development paradigm. While we have kept a similar CLI vocabulary to make the transition seamless, SDD-kit introduces a fundamental and major architectural evolution: Centralization vs. Fragmentation.

In traditional toolkit approaches, specifications are often "drowned" in countless subdirectories. This makes it nearly impossible to quickly answer fundamental questions: What is the core product vision? What is the current tech stack? What are the overarching domain rules?

sdd-kit solves this by providing:

• Instant Overview: The specs/ directory is a high-level map of your entire business intelligence.
• Unpolluted Context: Agents don't have to hunt for information; everything from Product Vision to DBML schema is exactly where it should be.
• The "Sacred Tree" Advantage: While others manage features in silos, SDD-Kit manages a living, breathing blueprint of your entire system.

The "Vibe" Difference: While other tools generate code from local prompts, sdd-kit allows for true Vibe Coding. Because the AI agent can read the entire "Sacred Tree," it understands the ripples a feature causes across the DB, API, and Domain Rules, making autonomous execution reliable.

1. Download the latest release from the repo.
2. Unzip it inside your project root. This contains all prompts and agent configs to start interacting with sdd-kit directly within your IDE chat (Github Copilot, etc.).

# 1. Initialize your project 
# This creates the sacred tree /specs structure.
/sdd.init

# 2. Specify your Product Vision
/sdd.specify-strategy "I want to build a simple accounting software to track my daily expenses"

# 3. Specify your Technical Foundation
/sdd.specify-tech "Full stack modern NextJs app; follow NextJs folder convention. Postgres Database"

# 4. Design the Architecture (New in v0.0.2)
# Generates the logical C4 blueprints (Context, Containers, Components).
/sdd.architect

# 5. Global Rebalancing and "Ventilation"
# Usually performed once after the initial vision to organize requirements and architecture into the Sacred Tree.
/sdd.dispatch

# 6. Generate Project Skeleton
# Usually performed once, Scaffolds the directory structure based on technical & architectural specs.
/sdd.scaffold

# 7. Define a New Intent
# Refine feature specifications, domain rules, and API contracts.
/sdd.feature "Add PDF export for monthly reports"

# 8. Bridge the Gap (New in v0.0.2)
# Ensure every spec is tracked and detected in the backlog before execution.
/sdd.gap

# 9. Review the Ventilated Specs
# Verify the logic in /specs/ before the agent touches the code.

# 10. Execute (Vibe Mode)
# Automatically chains: sdd plan -> sdd tasks -> sdd implement.
# Natively architecture-aware and health-checked.
/sdd.vibe

The toolkit includes a suite of specialized prompts located in .github/prompts/. Each command corresponds to a specific phase of the SDD Lifecycle.

SDD-Kit is designed to work with modern AI coding assistants.

• 🟢 Greenfield: Start from scratch and define your "Sacred Tree" before a single line of code is written.
• 🟡 Incremental: Add features to an existing SDD-Kit project. The AI performs impact analysis across the entire tree.
• 🔴 Legacy: We are currently developing sdd reverse, a reverese engineering agent to scan existing codebases and automatically regenerate your "Sacred Tree."

Spec Driven Development (SDD) is an open methodology for those who believe the future of software lies in the clarity of intent transposed into clear and centralized specifications, rather than the volume of syntax.

We welcome contributions to the sdd-kit toolkit! You can help us evolve the framework by:

• 🤖 Improving existing AI Agents and prompt logic.
• 📑 Sharing new Specification Templates for complex domains.
• 🛠️ Expanding support for more IDEs and AI coding assistants.
• 📖 Improving documentation and sharing SDD success stories.

Check our CONTRIBUTING.md (coming soon) for more details on how to get started.

• TurhanOz (@TurhanOz)

This project is licensed under the Apache License 2.0.

While Spec Driven Development (SDD) is a broader industry paradigm, the sdd-kit framework and workflow is a unique transposition and materialization of this concept by Turhan Oz.

This toolkit represents a specific conviction in how SDD should be implemented, featuring original architectural and procedural innovations such as:

• Intent Capture & Ventilation: The systematic process of "ventilating" abstract intent into unpolluted, specialized layers (Strategy, Domain, Features).
• The "Sacred Tree" Structure: A centralized, dual-audience (human & machine) specification structure acting as the permanent Single Source of Truth.
• Architecture Orchestration: The central design of system blueprints (ADRs, Data Schemas, API Contracts, and Architectural design, C4 Modeling) as prescriptive specifications.
• Technical Singleton Patterns: Enforcement of global technical truths to prevent context drift.
• Native Backlog & State Integration: Integrated tracking of implementation states within the SDD lifecycle.
• Ephemeral Artifact Management: Automated lifecycle and isolation of AI-generated execution logs.
• Spec-Driven Realignment: Methodology for strategically realigning existing projects towards a centralized "Sacred Tree" architecture.

Please refer to the NOTICE file for the full definitions of these intellectual property rights.

We chose the Apache 2.0 License to provide our users and contributors with a robust legal framework, including a clear grant of patent rights and protection against patent litigation.

See the LICENSE and NOTICE files for the full legal text.