sdd

# SDD (Spec-Driven Development) Plugin

A Claude Code plugin that provides a structured workflow for spec-driven development with ticks-based task tracking.

## Overview

This plugin enables a systematic approach to software development:

1. **Start with a specification** - Define what you're building before you build it
2. **Create trackable tasks (ticks)** - Break down the spec into atomic, testable tasks
3. **Commit with context** - Create well-documented PRs that reference specs and completed tasks

## Commands

### `/sdd:startspec [project-name]`

Start a new specification document with interactive dialogue.

- Creates a spec directory and file in `/docs/projects/<date>-<project-name>/`
- Can infer project name from branch or worktree name
- Guides you through defining requirements interactively

### `/sdd:checkspec [spec-file-path]`

Validate a specification document against the codebase and best practices.

- Verifies referenced files and APIs exist
- Checks technology alignment with existing stack
- Validates testing strategy is defined
- Produces a structured validation report with recommendations

### `/sdd:createplan [spec-file-path]`

Create ticks from a specification for trackable, test-driven implementation.

- Transforms specs into epics and tasks using the `tk` CLI
- Ensures each tick is atomic, testable, and AI-agent friendly
- Bundles tests with implementation tasks (test-first approach)
- Creates environment validation as "Phase 0"

### `/sdd:checkin-and-pr [spec-name or epic-id]`

Commit completed work and create a pull request with ticks summary.

- Verifies all ticks are complete
- Creates conventional commit messages
- Generates PR with ticks summary and spec references

## Workflow

### Starting a New Feature

```bash
# 1. Create the specification
/sdd:startspec dark-mode

# 2. Validate the spec
/sdd:checkspec

# 3. Create implementation tasks
/sdd:createplan

# 4. Work through tasks
tk next  # or tk run <epic-id> for autonomous execution

# 5. When done, create PR
/sdd:checkin-and-pr
```

### Working with Existing Specs

```bash
# Validate an existing spec
/sdd:checkspec docs/projects/2026-01-15-dark-mode/2026-01-15-dark-mode-spec.md

# Create tasks from a validated spec
/sdd:createplan docs/projects/2026-01-15-dark-mode/2026-01-15-dark-mode-spec.md
```

## Requirements

- **`tk` CLI** - The ticks task management tool must be installed
- **`gh` CLI** - GitHub CLI for creating pull requests
- **Git** - For version control

## File Structure

```
docs/projects/
  2026-01-15-dark-mode/
    2026-01-15-dark-mode-spec.md    # Main specification
    2026-01-15-dark-mode-notes.md   # Additional documents

.tick/                               # Ticks data (managed by tk)
```

## License

MIT