Metadata-Version: 2.4
Name: sdd-kit
Version: 2.0.3
Summary: Spec-Driven Development CLI with AI-assisted context assembly from enterprise lakehouses
Author-email: SDD Team <sdd@company.com>
License: MIT
Project-URL: Homepage, https://github.com/yourcompany/sdd-kit
Project-URL: Repository, https://github.com/yourcompany/sdd-kit
Project-URL: Documentation, https://github.com/yourcompany/sdd-kit#readme
Project-URL: Bug Tracker, https://github.com/yourcompany/sdd-kit/issues
Keywords: sdd,cli,ai,databricks,snowflake,specification,lakehouse,mcp
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.31.0
Requires-Dist: databricks-sdk>=0.20.0
Requires-Dist: sentence-transformers>=2.2.2
Requires-Dist: tiktoken>=0.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: mcp>=1.0.0

# 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)

```bash
# 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)
```bash
pip install sdd-kit
# or
uv tool install sdd-kit
```

---

## Quick Start

### New Project

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
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:
```bash
sdd sync-kb --domain banking --platform databricks
```

---

## Development

```bash
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
