sdd-kit

KO | EN

gitlite — search

#react #llm #android #machine-learning #linux #nodejs #windows #awesome #cli #vue #awesome-list #pytorch #mcp #openai

(★ 9)

a product engineering framework and workflow designed to manifest abstract vision into high-fidelity software.

sdd-kit Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
    <img src="./media/sdd-kit-logo.webp" alt="sdd-kit Logo" width="200" height="200"/>
    <h1>SDD Kit</h1>
    <h3><strong>Specifications as The Single Source of Truth</strong></h3>
</div>

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

---

## Table of Contents

- [🌟 The Philosophy](#-the-philosophy-spec-as-code)
- [📂 The Sacred Tree](#-the-sacred-tree-structure)
- [🧭 How the Model Fits Together](#-how-the-model-fits-together)
- [🗺️ Workflow at a Glance](#-workflow-at-a-glance)
- [🚀 SDD Lifecycle](#-the-sdd-lifecycle)
- [🔄 Rebuild from Specifications](docs/rebuild-from-specs.md)
- [📋 Backlog Items](#-backlog-items)
- [🔗 Traceability Alignment](docs/migrating-v0.0.3-traceability.md)
- [💡 SDD-Kit vs Spec-Kit](#-sdd-kit-vs-spec-kit)
- [🛠️ Quickstart](#️-quick-start)
- [📑 Prompt Reference](#-prompt-reference)
- [🤖 Supported AI Agents](#supported-ai-agents)
- [🔄 Project Adaptability](#-project-adaptability)
- [Testing & Evaluation](#testing--evaluation)
- [🤝 Contributing](#-contributing)
- [Maintainers](#maintainers)
- [License](#license)

---

## 🌟 The Philosophy: "Spec as Code"

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 "Sacred Tree" Structure

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

```text
PROJECT/
├── AGENTS.md                    # (ENTRYPOINT) Cross-agent map to the Sacred Tree (open standard).
│
├── .github/
│   └── instructions/
│       ├── sdd-instructions.md              # (KIT LAW) Governing principles & SDD-Kit workflow rules.
│       └── project-constitution.instructions.md # (PROJECT LAW) Core principles, TDD, DoR/DoD, patterns. Auto-loaded.
│
├─── specs/
│    ├── product-vision.md     # (STRATEGY) The "Why", Personas, Tone.
│    ├── product-definition.md # (SCOPE) The "What". Living module INDEX (M-XXX) → features/domains.
│    ├── system-context.md     # (MAP) System boundaries & external actors.
│    ├── roadmap.md            # (INTENTION) Priorities & milestones — hand-authored. Carries NO build state.
│    ├── decisions/            # (MEMORY) Immutable ADRs.
│    ├── drafts/               # (WIP) Raw specs awaiting routing into the tree.
│    ├── domain/               # (RULES) Pure business logic (No UI). Frontmatter id: D-XXX-NNN.
│    ├── features/             # (FLOWS) User stories & UI interactions. Frontmatter id: F-XXX-NNN.
│    └── 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) + executable Postman collections.
│
├── .sdd/
│   ├── runs/                 # (EPHEMERAL) Per-run execution artifacts (plan, tasks, map snapshot, logs).
│   ├── backlog/              # (STATE) Persistent execution status (todo/wip/done), agent-managed.
│   ├── memory/
│   │   └── implementation-map.md # (PROJECTION) Build dashboard — regenerated by /sdd.status. Never hand-edited.
│   └── templates/            # (SCAFFOLDS) Spec & artifact templates.
│
└── src/                      # 🛠️ Artifacts: The generated or maintained code
    └── <module>/AGENTS.md    # (BRIDGE) Specs pointer + compact feature navigation surface.
```

* **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.

---

## 🧭 How the Model Fits Together

The Sacred Tree has a hierarchy, while the traceability links form a graph across that hierarchy.
Keeping these two ideas separate makes the relationship between product intent, specifications,
planning, and implementation explicit.

### 1. Product hierarchy: modules group features and domain rules

`specs/product-definition.md` is the product scope index. It defines stable module codes (`M-*`)
and catalogs the feature (`F-*`) and domain (`D-*`) specifications that belong to each module.
Features and domain rules are therefore sibling specifications under the same module, not parent and
child documents.

```text
product-definition.md
└── Module M-AUTH
        ├── Feature F-AUTH-001  (user flow / behavior)
        ├── Feature F-AUTH-002  (user flow / behavior)
        └── Domain D-AUTH-001   (business rules / invariants)
```

Each feature or domain spec confirms its module through its frontmatter:

```yaml
id: F-AUTH-001
type: feature
module: M-AUTH
```

The module is the organizing relationship. The physical folders (`features/` and `domain/`) are
separate because user flows and business rules have different responsibilities:

- A **feature** describes a user-visible flow, acceptance criteria, and functional behavior.
- A **domain** describes reusable, invariant business rules. Features link to these rules instead of
    duplicating them.
- A **technical spec** describes a technical truth or constraint. It is not a child of a feature:
    features and domain specs may both reference the same technical spec.

### 2. Cross-links: relationships between sibling specs

The frontmatter traceability spine expresses relationships by stable IDs. For example:

```yaml
# Feature F-AUTH-001
links:
    domain: [D-AUTH-001]
    technical: [T-API-001]
    depends-on: [F-AUTH-000]

# Domain D-AUTH-001
links:
    technical: [T-DB-001]
    features: [F-AUTH-001]
```

These links mean:

| Link | Meaning |
|------|---------|
| `module` | The module that owns the spec; the module must exist in `product-definition.md`. |
| `domain` | Business rules consumed by a feature. |
| `features` | Back-links from a domain rule to the features that consume it. |
| `technical` | Technical truths required by either a feature or a domain rule. |
| `depends-on` | Logical precedence: the referenced spec must be addressed first. |

The links are intentionally broader than the folder hierarchy. A domain rule can require a database
or security technical spec, and a technical spec can be shared by several modules.

### 3. Planning is not part of the product hierarchy

Planning artifacts are derived from the specifications but live outside `specs/`:

```mermaid
flowchart TD
        V["product-vision.md<br/>Why"] --> PD["product-definition.md<br/>Scope and modules"]
        PD --> F["Feature / Domain specs<br/>What"]
        F --> G[".sdd/memory/product-dependency-graph.md<br/>Dependencies and critical path"]
        G --> R["roadmap.md<br/>Priority and milestones"]
        F --> P[".sdd/runs/.../plan.md<br/>How"]
        P --> T[".sdd/runs/.../tasks.md<br/>Atomic work"]
        T --> B[".sdd/backlog/...<br/>todo / wip / done"]
        T --> C["Code + nested AGENTS.md<br/>implements: [IDs]"]
        B --> M[".sdd/memory/implementation-map.md<br/>Derived build view"]
        C --> M
```

- `product-vision.md` captures **why** the product exists.
- `product-definition.md` captures **what is in scope** and groups it into modules.
- `.sdd/memory/product-dependency-graph.md` projects **what depends on what** across modules. It
    shows dependency confidence, critical path, and parallel work; it is regenerated by
    `sdd product-graph`, never hand-maintained.
- `roadmap.md` captures **when and with what priority** the team intends to address specs. It does
    not record implementation state.
- `.sdd/runs/.../plan.md` captures **how** a selected scope will be implemented. It is an execution
    artifact, not a new specification.
- `.sdd/backlog/` records durable execution state for the work item.
- `.sdd/memory/implementation-map.md` is regenerated by `sdd status`; it is a projection, never a
    hand-maintained source of truth.

### 4. Lifecycle status and build status are different

The `status` in a spec frontmatter describes document maturity only:

```yaml
status: draft | accepted | deprecated
```

The backlog describes implementation progress:

```text
todo | wip | done
```

For example, an `accepted` feature can still have a `todo` backlog item. This means the requirement
is approved, but implementation has not started. `sdd status` combines backlog status with code-to-spec
markers (`implements: [F-..., D-...]`) to derive the build view (`todo`, `wip`, `done`, `unplanned`,
or `unscheduled`). Build status must never be written into spec frontmatter or the product index.

### The short version

> Modules organize the product. Features and domain rules are sibling specs within a module.
> Technical specs are reusable technical truths referenced by features and domains. The roadmap
> expresses planning intention. Plans and tasks describe execution. The backlog records progress,
> and `implementation-map.md` projects the resulting build state.

---

## 🗺️ Workflow at a Glance

The sdd-kit workflow splits into a **one-time Genesis** (you build the foundations once) and a **repeating Build Loop** (you cycle through it for every feature). Governance commands are run on demand to keep the Sacred Tree and the execution area in sync.

```mermaid
flowchart TD
    subgraph G["🧬 Genesis — run once"]
        direction TB
        I["/sdd.init"] --> K["/sdd.constitution"] --> S1["/sdd.specify-strategy"] --> S2["/sdd.specify-tech"]
        S2 --> A["/sdd.architect"] --> D["/sdd.dispatch"] --> SC["/sdd.scaffold"]
    end

subgraph L["🔁 Build Loop — per feature"]
        direction TB
        F["/sdd.feature"] --> C["/sdd.clarify"] --> GAP["/sdd.gap  (= /sdd.status --snapshot)"]
        GAP --> V["/sdd.vibe  (= plan → tasks → implement)"]
    end

subgraph GOV["🌉 Governance — on demand"]
        direction TB
        MAP["/sdd.status"]
        ARCHA["/sdd.architect audit"]
        TA["/sdd.tree-audit"]
        ARCHU["/sdd.architect update"]
    end

**Frequency legend:** 🔂 Once · 🔁 Per feature (loop) · 🔄 On demand / periodic

> [!TIP]
> The fastest steady-state loop is **`/sdd.feature` → `/sdd.status` → `/sdd.vibe`**, repeated per
> feature. If status reports `Architecture confidence: review required`, run **`/sdd architect audit`**
> and then **`/sdd architect update`** before execution. Steps 15–17 are the manual equivalent of
> `/sdd.vibe` — use them when you want to inspect each stage. Use `/sdd architect update <scope>` only
> for a deliberate targeted reconciliation.

---

## 🚀 The SDD Lifecycle

### Phase 1: Genesis (Foundations)
Build on solid ground. Define the core DNA of your project before a single line of code is written.
* **Constitution**: Ratify your non-negotiable core principles via `sdd constitution` — TDD, coding philosophy, DoR/DoD, team patterns. Auto-loaded into every agent context.
* **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).

### Phase 2: Feature Design (Ventilation)
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 (living state)**: `/sdd.architect` is **not** a one-shot pass. The C4 views are the **current target state** and evolve on every architecture impact. `sdd feature`/`sdd dispatch` record a structured impact signal when they detect a new container, external system, boundary change, or responsibility split; they never modify C4 views or propose ADRs. `sdd status` reports build state plus architecture confidence. When it reports `review required`, run `sdd architect audit` to assess C4 coverage, stale views, and drift; it remains read-only. Then run `sdd architect update` to review pending signals, confirm structural ADRs, reconcile C4-only changes, and apply existing unreflected ADRs. Use `sdd architect update <scope>` only for a deliberate targeted run.

---

### 🌉 Governance Bridge: Build-Map Audit

#### The implementation map: one persistent Markdown view of build state

`sdd status` generates and replaces this file on every run. `sdd implement` and `sdd vibe` invoke it
automatically when their implementation phase completes:

```text
.sdd/memory/implementation-map.md
```

It answers two operational questions:

> Which specs are done, in progress, planned, missing from the backlog, missing from the roadmap,
> blocked, or ready to build now?
>
> Is the architecture target sufficiently reviewed to make a conformance claim?

It derives the answer from specs and their dependencies, `roadmap.md`, backlog status, and code-to-spec
markers. The file is persistent in the project until the next map run, but it is generated state: never
edit it by hand. Agents read it when their workflow needs the current build picture (for example,
`sdd plan` without a scope and `sdd vibe`); it is not automatically loaded into every agent context.

`sdd status` reports `Architecture confidence: verified` when there are no structured impact signals
awaiting architectural review and no unreflected architecture ADRs. If it reports `review required`,
the implementation state is still valid, but the project must not claim conformance to a fully
reviewed C4 target. Run `sdd architect audit`, then use `sdd architect update` to reconcile confirmed
changes.

#### `sdd status` versus `sdd gap`

| Command | Does | Writes |
|---|---|---|
| `sdd status` | Refreshes the build-state view and reports architecture confidence. Use `sdd status --full` to force a full scan. | `.sdd/memory/implementation-map.md` |
| `sdd architect audit [scope]` | Read-only C4 audit: coverage, stale views, dangling back-links, and drift. Run it when status reports `review required`. | `.sdd/runs/<run>/architecture-audit.md` |
| `sdd gap` (`sdd status --snapshot`) | Refreshes the same current view **and** archives an immutable, timestamped build-map snapshot; it is not a C4 audit. | `.sdd/memory/implementation-map.md` + `.sdd/runs/<run>/implementation-map-snapshot.md` |

The critical checkpoint between design and execution is `sdd gap`: it preserves the state that was
reviewed before implementation while keeping the current map up to date. Its audit highlights:
* **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.

> [!NOTE]
> `sdd gap` is no longer a separate scanner — it is the **snapshot (audit) mode** of `sdd status`. It
> shares the exact same cheap-signal scan, refreshes the persistent implementation map, then writes a
> frozen copy to `.sdd/runs/<run>/implementation-map-snapshot.md`.

---

### Phase 3: Execution (The Agent Era)
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 the implementation map and freshness checks to automate the entire chain (Plan → Tasks → Implement) with high-confidence results.

> [!TIP]
> **Zero Pollution**: AI thought processes and intermediate task lists are stored in `.sdd/runs/`.  
> Your `specs/` directory remains a clean, human-readable source of truth optimized for LLM context windows.

---

## 📋 Backlog Items

A backlog item is a durable unit of execution, not automatically a module, feature, or domain
document. It can group the feature and domain specifications delivered together, while each
specification belongs to at most one active backlog item. When an already completed specification
changes, re-plan it: the same backlog item is explicitly reopened with a recorded reason, receives
new run artifacts, and returns to `wip` only when the new work begins. Read the detailed guide in
[docs/BACKLOG.md](docs/BACKLOG.md).

---

## 🔗 Traceability Alignment

Projects created with sdd-kit v0.0.3 should follow the dedicated
[v0.0.3 Traceability Migration Guide](docs/migrating-v0.0.3-traceability.md). It separates the
one-time, review-first `/sdd specs align-traceability` bridge from the normal delivery workflow:
`/sdd status --full` to inspect implementation evidence, then `/sdd vibe <spec-id-or-module>` (or
`/sdd plan` -> `/sdd tasks` -> `/sdd implement`) to close implementation gaps. Alignment never
writes nested `AGENTS.md` markers; implementation does. This legacy migration bridge can be
retired when canonical traceability is the standard starting point for v1.0.0 projects.

---

## 💡 SDD-Kit vs. Spec-Kit

**sdd-kit** is heavily inspired by **[SpecKit](https://github.com/speckit/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.**

### 🔍 Closing the "Vision Gap"
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.

## 🛠️ Quick Start

### 1. Installation
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.).

### 2. Workflow Example

```bash
# 1. Initialize the Sacred Tree.
/sdd.init

# 2. Ratify the project constitution.
/sdd.constitution

# 3. Capture the initial product and technical intent.
/sdd.specify-strategy "I want to build a simple accounting software to track my daily expenses"
/sdd.specify-tech "Full stack modern NextJs app; follow NextJs folder convention. Postgres Database"

# 4. Establish the initial C4 target architecture, then organize specs and scaffold code.
/sdd.architect
/sdd.dispatch
/sdd.scaffold

# 5. Add a feature. This creates/refines specs; it never changes C4 views.
/sdd.feature "Add PDF export for monthly reports"

# 6. Inspect build state and architecture confidence.
/sdd status

# 7. When status reports "Architecture confidence: review required", inspect C4 coverage and drift.
/sdd architect audit

# 8. Reconcile confirmed architecture work. New ADRs are proposed for confirmation here.
/sdd architect update

# Optional: target only one known feature, module, or architecture scope.
/sdd architect update specs/features/reports/pdf-export.md

# 9. Archive the pre-execution build-map snapshot when useful.
/sdd.gap

# 10. Plan, task, and implement the approved scope.
/sdd.vibe
```

`sdd feature` logs an architecture-impact signal in its run. `sdd status` reports the implementation
map and whether architecture review is required. When it is, `sdd architect audit` diagnoses C4
coverage and drift without changing architecture. `sdd architect update` then reviews all pending
signals by default, proposes any structural ADR for explicit confirmation, and updates C4 views and
their accepted ADR `decisions:` back-links. `sdd architect update <scope>` is the optional targeted
form.

---

## 📑 Prompt Reference

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

| Phase | Command | Description |
| :--- | :--- | :--- |
| **I. Genesis** | `sdd init` | Initialize the Sacred Tree structure. |
| | **`sdd constitution`** | 🆕 **Project Constitution**: Interactively author/amend the core principles (TDD, DoR/DoD, coding philosophy, team patterns). Auto-loaded into every agent context. |
| | **`sdd architect`** | 🆕 **C4 Modeling & ADRs**: Generate architecture blueprints and decision records. |
| | `sdd specify-strategy` | Capture product vision, personas & scope → `product-vision.md`, `system-context.md`. |
| | `sdd specify-tech` | Set the tech stack & constraints → `technical/stack.md`, `project-structure.md`. |
| | `sdd scaffold` | Generate project skeleton from technical specs. |
| **II. Design** | `sdd feature` | Create or refine feature specifications, domain rules, and API contracts. |
| | `sdd clarify` | Resolve ambiguities in specs via AI interrogation. |
| | `sdd dispatch` | Global rebalancing and "ventilation" of domain/features/technical specs. |
| | `sdd tree-audit` | Audit `specs/` for misfiled execution artifacts. *(skill-routed)* |
| | **`sdd specs align-traceability`** | 🆕 **Traceability Alignment**: Migrate v0.0.3 specs to the v0.0.4 Spine with a reviewable, hash-checked plan. *(skill-routed)* |
| **🌉 Governance**| **`sdd gap`** | 🆕 **Build-map Snapshot**: Refresh the implementation map and archive a timestamped snapshot under `.sdd/runs/`. *(= `sdd status --snapshot`; not a C4 audit; skill-routed)* |
| | **`sdd product-graph`** | **Product Dependency Graph**: Generate or validate `.sdd/memory/product-dependency-graph.md`, the product-wide dependency, critical-path, and parallel-work projection. *(skill-routed)* |
| | **`sdd status`** | 🆕 **Implementation Map & Architecture Confidence**: Refresh `.sdd/memory/implementation-map.md`, the persistent generated view of done/wip/todo, unplanned or unscheduled specs, blockers, next-buildable work, and `verified` / `review required` architecture confidence. *(skill-routed)* |
| | **`sdd architect audit [scope]`** | **C4 Audit**: Read-only coverage and drift assessment, recommended when `sdd status` reports `review required`. |
| **III. Execution**| `sdd plan` | Generate a step-by-step implementation plan (Architecture-aware). |
| | `sdd tasks` | Break down the plan into atomic, agent-ready tasks. |
| | `sdd implement` | Execute the tasks, write code, and update the backlog. |
| | **`sdd vibe`** | **Auto-pilot**: Chains Plan → Tasks → Implement with built-in health checks. |

> [!TIP]
> **Pro-tip**: Run `sdd status` before `sdd vibe`. When it reports `review required`, run `sdd architect audit` and `sdd architect update` before implementation; run `sdd gap` when you also need a frozen build-map snapshot.

---

## Supported AI Agents

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

> [!NOTE]
> **GitHub Copilot** users: the workspace-level behavioral instructions for all sdd-kit agents
> are loaded automatically from `.github/instructions/sdd-instructions.md`. No manual configuration is
> needed — simply open the project in VS Code with the GitHub Copilot extension installed.

---

## 🔄 Project Adaptability

* **🟢 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."

---

## Testing & Evaluation

sdd-kit is a governance layer for AI agents, so its "tests" verify **structure and doctrine**, not
application behaviour. A deterministic harness (no LLM, no API cost) encodes the kit's golden rules
as `grep`-checkable checks:

* **Layer 0 — static integrity** (`sdd-kit/.sdd/scripts/lint.sh`): frontmatter validity, prompt↔skill
  mapping, dangling references, template hygiene.
* **Layer 2 — doctrine invariants** (`sdd-kit/.sdd/scripts/invariants.sh`): impl-independence purity,
  one-way pointers, traceability spine, C4↔ADR coherence.

```bash
bash sdd-kit/.sdd/scripts/lint.sh          # Layer 0
bash sdd-kit/.sdd/scripts/invariants.sh    # Layer 2
```

A CI workflow is provided at `.github/workflows/eval.yml` (not active yet — run the scripts locally
for now). The higher, generative layers (golden-path scenario, LLM-as-judge, human acceptance) are
not implemented yet.

👉 Full usage, options and check-by-check details: **[`sdd-kit/.sdd/scripts/README.md`](./sdd-kit/.sdd/scripts/README.md)**
· vision & roadmap: **[`testing-strategy.md`](./testing-strategy.md)**.

---

## 🤝 Contributing

**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.

> [!NOTE]
> By contributing to this project, you agree that your contributions will be licensed under the same **Apache License 2.0** terms. This ensures the methodology remains an open and protected standard for everyone.

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

---

## Maintainers

- TurhanOz ([@TurhanOz](https://github.com/TurhanOz))

---

## ⚖️ License & Intellectual Property

This project is licensed under the **Apache License 2.0**.

### Intellectual Property Notice
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](./NOTICE) file for the full definitions of these intellectual property rights.

### Why Apache 2.0?
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](./LICENSE) and [NOTICE](./NOTICE) files for the full legal text.

sdd-kit

sdd-kit Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

sdd-kit

sdd-kit Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README