Metadata-Version: 2.4
Name: sdd-kit
Version: 0.2.0
Summary: Spec-Driven Development toolkit — AI builds from your spec, inside VS Code chat (@sdd).
Author: SDD Kit contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/dpfam27/sdd-kit
Project-URL: Repository, https://github.com/dpfam27/sdd-kit
Project-URL: Issues, https://github.com/dpfam27/sdd-kit/issues
Keywords: spec-driven,ai,vscode,copilot,scaffold,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0

# SDD Kit — Spec-Driven Development

> Tell the AI what you want to build. It writes the spec, scaffolds the code, runs tests, and reports back. You just review.

SDD Kit is a VS Code chat participant (`@sdd`) that turns a one-sentence idea into a working project — by writing the **spec first** and then generating code from it.

It uses your existing **GitHub Copilot** subscription. No extra API keys, no extra bills.

---

## Install (2 steps)

```bash
pip install sdd-kit
sdd install-extension
```

That's it. Reload VS Code and you'll see `@sdd` in the chat panel.

**Requirements**
- Python 3.10+ (for `pip install sdd-kit`)
- VS Code 1.85+ with the **GitHub Copilot** extension signed in
- The `code` (or `cursor`) CLI on your PATH
  *VS Code → Cmd+Shift+P → "Shell Command: Install 'code' command in PATH"*

> **Why pip?** The CLI bundles a copy of the `.vsix` and installs it via the `code` CLI, so you don't have to download anything manually or trust a Marketplace upload.

---

## Quickstart — 60 seconds

1. Open any folder in VS Code.
2. Open the chat panel (Ctrl/Cmd+Alt+I).
3. Type:
   ```
   @sdd /init a sales analytics dashboard
   ```
4. Answer 6–8 questions about stack, users, MVP scope.
5. SDD Kit writes 4 spec docs into `docs/` and scaffolds the project.

That's the loop. From here, ask `@sdd` to do anything else with the slash commands below.

---

## The commands — what they do and when to use them

`@sdd` exposes 9 slash commands. **`/init` runs once per project. The others are tools you reach for whenever you need them.**

### `/init` — Start a new project

> Use once, at the beginning. Turns "an idea" into "a real folder with spec docs and starter code".

```
@sdd /init a CRM for solo lawyers
```

Asks you: stack? who uses it? what's in the MVP? what's out of scope?
Writes: `docs/constitution.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/FEATURE_SPEC_MVP.md`, plus initial code.

### `/plan` — Get a checklist before doing the work

> Use when you want SDD to think before it touches code. Outputs `docs/PLAN.md` with goal, assumptions, numbered checklist, risks, and acceptance criteria. **Writes no code.**

```
@sdd /plan migrate auth from sessions to JWT
```

Read the plan, edit it if you want, then run `/build` to execute it.

### `/design` — Add or rework a feature in the spec

> Use when you want a new feature, *before* writing code. Updates the architecture & feature docs first.

```
@sdd /design add invoice export to PDF
```

### `/ux` — Design UI/UX

> Use when a feature needs screens, flows, or a component system. Outputs `docs/UX_SPEC.md` (user flows + screen inventory + nav map + accessibility) and `docs/UI_COMPONENTS.md` (design tokens + component catalog). **Writes no UI code yet — `/build` does that.**

```
@sdd /ux design the onboarding flow for new admins
```

### `/build` — Implement code from the spec

> Use after `/design`, or when a feature is in the spec but not built yet. Reads the spec, writes the code.

```
@sdd /build the invoice export feature
```

### `/test` — Write or fix tests

> Use after `/build`, or whenever tests are missing/red.

```
@sdd /test
```

### `/refactor` — Clean up code, staying aligned with the spec

> Use when the code works but is messy. SDD reads the architecture rules and refactors without breaking contracts.

```
@sdd /refactor the auth module
```

### `/review` — Audit code against the spec

> Use before merging or shipping. Outputs a `REVIEW.md` with drift, gaps, and risks.

```
@sdd /review
```

### `/update-doc` — Sync docs back to the code

> Use after manual code changes that diverged from the spec. SDD detects drift and rewrites the docs to match reality.

```
@sdd /update-doc
```

---

## Why "spec-driven"?

Most AI coding tools jump straight to code, and the code becomes the only source of truth. That works for snippets, not for projects you have to maintain.

SDD Kit keeps a **spec** (`docs/constitution.md` + friends) as the source of truth:

- Every `/build`, `/refactor`, `/test` reads only the spec sections it needs (not the whole codebase) — so it stays fast and on-topic.
- Every `/review` compares code against the spec — so drift is visible.
- Every `/update-doc` resyncs the spec — so the docs never go stale.

In short: the spec is the contract, the code is one implementation, and SDD keeps them in sync.

---

## Project layout after `/init`

```
my-project/
├── docs/
│   ├── constitution.md       # name, stack, users, rules, MVP scope
│   ├── PRD.md                # problem, goals, success metrics
│   ├── ARCHITECTURE.md       # folders, components, API, data model
│   └── FEATURE_SPEC_MVP.md   # feature-by-feature breakdown
└── …scaffolded code…
```

Additional docs created on-demand by other skills:

```
docs/
├── PLAN.md             # ← /plan
├── UX_SPEC.md          # ← /ux
├── UI_COMPONENTS.md    # ← /ux
├── TEST_PLAN.md        # ← /test
└── REVIEW.md           # ← /review
```

---

## Troubleshooting

**"No language model available"** — Install GitHub Copilot and sign in (GitHub icon in the Activity Bar). SDD Kit will use whichever model Copilot offers — Claude, GPT-4o, or others.

**`sdd install-extension` says "couldn't find code CLI"** — In VS Code: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH". Same with Cursor.

**`@sdd` doesn't appear in chat** — Reload VS Code (Cmd+Shift+P → "Developer: Reload Window") after installing the extension.

---

## License

Apache-2.0.
