sdd-kit 2.0.3

Spec-Driven Development CLI with AI-assisted context assembly from enterprise lakehouses

sdd-kit v2.0

Spec-Driven Development CLI — AI-assisted context assembly from enterprise lakehouses

pip install sdd-kit     # coming soon (PyPI)
uv tool install -e .    # install locally now

---

What is sdd-kit?

sdd-kit is a Python CLI that enforces Spec-Driven Development (SDD) by intelligently assembling AI context from your enterprise data lakehouse (Databricks/Snowflake). Every command keeps token usage under 8,000 tokens and works fully offline.

Two workflows:

• New projects: sdd init → sdd /gather → sdd /specify → sdd /plan → sdd /integrate
• Existing projects: sdd onboard → sdd /audit → sdd /specify-next → sdd /plan-next

---

Installation

Requirements

• Python 3.11+
• uv (recommended) or pip

Option A: Install locally (available now)

# Clone the repo
git clone https://github.com/yourcompany/sdd-kit.git
cd sdd-kit

# Install with uv (recommended)
uv tool install -e .

# Or install with pip
pip install -e .

# Verify
sdd --help
sdd doctor

Option B: Install from PyPI (coming in v2.0.0 release)

pip install sdd-kit
# or
uv tool install sdd-kit

---

Quick Start

New Project

# 1. Create a new SDD project (≤45s)
sdd init my-project --domain banking

# 2. Open your project and fill in the context
cd my-project
# Edit gather-context.yaml — add your Silver tables, data sources, business goals

# 3. Interactive gather (≤3m)
sdd /gather

# 4. Generate spec.md (≤60s, requires ANTHROPIC_API_KEY)
export ANTHROPIC_API_KEY=sk-ant-...
sdd /specify

# 5. Generate plan.md + tasks.md (~2m)
sdd /plan

# 6. Generate integration skeleton from live Silver schema
sdd /integrate

# 7. Validate spec completeness
sdd /validate

Existing Project

# 1. Onboard without touching any existing files (≤30s)
cd existing-project
sdd onboard

# 2. Audit existing codebase (≤90s)
sdd /audit

# 3. Fill context (pre-populated from audit)
sdd /gather

# 4. Generate delta spec (not a rewrite — additive only)
sdd /specify-next --goals "Add real-time transaction monitoring"

# 5. Generate delta plan
sdd /plan-next

# 6. Reverse-engineer existing integrations
sdd /integrate --retro

---

All 16 Commands

New Project Commands

Command	What it does	Time	Offline?
sdd init <name> --domain <domain>	Create .sdd/, .clinerules, gather-context.yaml	≤45s	✅
sdd /gather	Fill gather-context.yaml interactively	≤3m	✅
sdd /specify	Generate spec.md (AI + Gold context)	≤60s	--dry-run
sdd /plan	Generate plan.md + tasks.md (2 AI calls)	~2m	--dry-run
sdd /integrate	Generate integration skeleton from Silver schema	~1m	--dry-run
sdd /validate	Validate spec.md — exit 0 (pass) or 1 (fail)	~30s	✅
sdd /estimate	Show token budget breakdown for all commands	~10s	✅
sdd sync-kb --domain <domain>	Sync Gold knowledge cache from lakehouse	≤30s	labeled
sdd upload-kb [file]	Classify + upload learning doc to Bronze	≤45s	--dry-run

Existing Project Commands

Command	What it does	Time	Offline?
sdd onboard	Add .sdd/ to existing project (surgical)	≤30s	✅
sdd /audit	Audit codebase → audit.md + findings	≤90s	--dry-run
sdd /specify-next	Delta spec for next phase	≤60s	--dry-run
sdd /plan-next	Delta plan + tasks for next phase	≤60s	--dry-run
sdd /integrate --retro	Reverse-engineer existing integrations	≤90s	--dry-run

Skills & Diagnostics

Command	What it does
sdd skills list	List all 9 skills with availability status
sdd skills inspect <name>	View a skill file (Layer 2 detail)
sdd skills refine <name>	Edit a skill file in $EDITOR
sdd doctor	Check environment (Python, uv, git, API keys)
sdd version	Show sdd-kit version
sdd estimate [task]	Token budget breakdown (offline)

---

Configuration

Environment Variables

# Required for AI commands (specify, plan, audit, etc.)
export ANTHROPIC_API_KEY=sk-ant-...

# Optional: Databricks (for Gold/Silver lakehouse access)
export DATABRICKS_HOST=https://adb-xxx.azuredatabricks.net
export DATABRICKS_TOKEN=dapi...
export SDD_BRONZE_CATALOG=bronze
export SDD_BRONZE_SCHEMA=sdd

# Optional: Model selection (default: claude-3-5-sonnet-20241022)
export SDD_MODEL=claude-3-5-sonnet-20241022

# Optional: Platform selection (default: mock for safety)
export SDD_PLATFORM=databricks   # mock | databricks | snowflake

Supported Domains

banking | ecommerce | retail | logistics | healthcare | generic

---

How It Works

3-Zone Knowledge Architecture

Zone 0: sdd_kit/core/           (bundled in pip, ~15 MB)
├─ constitution.md              (reference — NOT loaded per turn)
├─ ai-prompts/                  (specify-prompt.md, plan-prompt.md, ...)
│   └─ Load ONLY the task prompt per call (~800 tokens)
└─ templates/                   (spec-template.md, plan-template.md, ...)

Zone 1: ~/.sdd/cache/           (local Gold mirror, ≤500 MB)
├─ domain-marts/{domain}/       (synced from lakehouse)
├─ schema-snapshots/            (Silver cache for offline use)
└─ versions.json

Zone 2: project/.sdd/local-kb/  (~10 MB, always available)
├─ data-models.md
├─ integration-learnings.md
├─ gotchas.md
└─ decisions.md

Token Budget (8,000 tokens max per AI call)

Command	Zone 0	Gold	Zone 2	Output	Total
/specify	800	3,000	700	1,500	8,000
/audit	800	2,000	—	3,200	8,000
/specify-next	800	2,500	—	2,700	8,000
/plan	800	2,000	—	2,000	8,000

12 SDD Rules (loaded once per session)

01. THINK BEFORE CODING — State assumptions. Ask if unclear.
02. SIMPLICITY FIRST — Minimum code that solves the problem.
03. SURGICAL CHANGES — Touch only what the task requires.
04. GOAL-DRIVEN EXECUTION — Define "done" before starting.
05. NO SILENT FAILURES — Required input missing? Stop and report.
06. CANONICAL DATA FIRST — Use Silver schema names. Never invent.
07. CONTEXT BUDGET DISCIPLINE — No full files. 8K max.
08. EXISTING PROJECTS ARE NOT BROKEN — Recommend delta only.
09. SKILLS BEFORE IMPROVISING — Load skill file first.
10. FAILURES ARE SKILL INPUTS — Log and update skill to prevent.
11. SINGLE AGENT BEFORE SUB-AGENTS — Don't delegate until tested.
12. OFFLINE IS FIRST-CLASS — All commands work offline. Label stale data.

---

Project Structure After sdd init

my-project/
├── .sdd/
│   ├── .clinerules             # AI agent rules (Cursor/Antigravity)
│   ├── company/                # Zone 0 core (copied from package)
│   ├── local-kb/               # Zone 2 (filled by /gather, /integrate --retro)
│   │   ├── data-models.md
│   │   ├── integration-learnings.md
│   │   └── gotchas.md
│   ├── logs/                   # Token usage logs per session
│   └── meta.json               # Project metadata
├── gather-context.yaml         # Fill this before /specify
├── spec.md                     # Generated by /specify
├── plan.md                     # Generated by /plan
├── tasks.md                    # Generated by /plan
└── src/
    └── integrations/
        └── integration-skeleton.py  # Generated by /integrate

---

Skills System (Progressive Disclosure)

Skills are markdown files that guide AI on HOW to do each task. They load on-demand — not every turn.

sdd skills list          # See all 9 skills + availability
sdd skills inspect specify-skill   # Read the skill detail
sdd skills refine audit-skill      # Edit a skill (Rule 10)

9 built-in skills:

• specify-skill — How to generate spec.md
• plan-skill — How to generate plan.md + tasks.md
• audit-skill — How to audit existing codebases
• specify-next-skill — How to write delta specs
• plan-next-skill — How to write delta plans
• integrate-skill — How to generate integration skeletons
• validate-skill — How to validate specs
• classify-skill — How to classify KB documents
• retro-integrate-skill — How to reverse-engineer integrations

---

Offline Mode

Every command works offline. When the lakehouse is unreachable:

• Gold retrieval falls back to ~/.sdd/cache/ (labeled as stale)
• Silver schemas use snapshots (labeled as stale)
• Commands with --dry-run skip the AI call entirely

Pre-cache for offline use:

sdd sync-kb --domain banking --platform databricks

---

Development

git clone https://github.com/yourcompany/sdd-kit.git
cd sdd-kit

# Setup
uv sync

# Run tests
uv run pytest tests/unit/ -v
uv run pytest tests/integration/test_offline_mode.py -v

# Lint
uv run ruff check sdd_kit/ tests/

---

Roadmap

Version	Status	What
v2.0.0	🔨 Building	16 commands, Databricks, offline-first
v2.1.0	📅 Planned	PyPI publish, Snowflake adapter
v2.2.0	📅 Planned	MCP server (chatbot integration)
v2.3.0	📅 Planned	Sub-agents for /integrate + /validate

---

License

MIT © 2026 Your Company