SDD CLI

A project management tool native to Specification-Driven Development (SDD) methodology, where specifications (not issues) are the primary artifact.

What is Specification-Driven Development?

SDD is a methodology where:

• Specifications are first-class citizens, not issues or tickets
• Plans are derived from specifications
• Tasks are atomic units of work derived from plans
• Git is the source of truth for all artifacts

Installation

Quick Install

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/sdd-tools/spec-cli/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/sdd-tools/spec-cli/master/install.ps1 | iex

Other Methods

Go Install:

go install github.com/sdd-tools/spec-cli/cmd/sdd@latest

From Source:

git clone https://github.com/sdd-tools/spec-cli.git
cd spec-cli
make build
./bin/sdd --version

Updating

Once installed, SDD CLI can update itself:

sdd update              # Check and prompt to install
sdd update --yes        # Install without prompting
sdd update --check      # Only check, don't install

The CLI also checks for updates in the background and notifies you when a new version is available.

Quick Start

# Initialize SDD in your project
cd your-project
sdd init

# Create a new specification
sdd spec new my-feature

# Derive a plan from the spec
sdd plan derive my-feature

# Show project status
sdd status

# Start the Web UI
sdd serve

Commands

Core Commands

Command	Description
sdd init	Initialize .sdd/ directory with optional integrations
sdd status	Show project status and progress
sdd serve	Start the Web UI at localhost:3000
sdd version	Show version information
sdd update	Check for and install updates

Specification Management

Command	Description
sdd spec list	List all specifications
sdd spec show <id>	Show a specification
sdd spec new <id>	Create a new specification

Plan Management

Command	Description
sdd plan list	List all plans
sdd plan show <id>	Show a plan
sdd plan derive <spec-id>	Derive a plan from a specification

Task Management

Command	Description
sdd task list	List all tasks
sdd task start <id>	Run pre-flight checks before starting work
sdd task check <id>	Run implementation checks on work in progress
sdd task validate <id>	Run full validation across all layers
sdd task done <id>	Mark a task as done (runs validation gates)
sdd task done <id> --force	Mark done, skipping validation
sdd task reset <id>	Reset a task to not done

ADR Management

Command	Description
sdd adr list	List all ADRs
sdd adr show <id>	Show an ADR
sdd adr new <title>	Create a new ADR

Validation & Monitoring

Command	Description
sdd validate	Validate all specs, plans, and ADRs
sdd validate --fix	Auto-fix fixable issues
sdd validate --verbose	Show all checks including passed
sdd validate --json	Output results as JSON
sdd spec validate <id>	Validate a specific specification
sdd plan validate <id>	Validate a specific plan
sdd plan complete <id>	Mark plan as complete (with validation)
sdd monitor	Watch project progress in real-time
sdd monitor --interval 2	Custom refresh interval

AI Optimization

Command	Description
sdd suggest <task-id>	Get context-aware implementation suggestions
sdd learn show	Show recent validation history
sdd learn stats	Show validation gate statistics
sdd learn clear	Clear validation history
sdd agents generate	Generate AGENTS.md from codebase analysis
sdd agents show	Display current agent configuration
sdd patterns analyze	Analyze codebase for patterns

AI Mode Output: Add --ai-mode to any command for structured JSON output optimized for AI agents.

Template Auto-completion:

• sdd spec new --ai-complete - Auto-complete spec sections based on codebase patterns
• sdd plan derive --ai-complete - Generate smart tasks from spec analysis

Integrations

Command	Description
sdd install --list	List available integrations
sdd install agent-os	Install Agent OS workflows
sdd install design-os	Install Design OS planning tool
sdd install claude-integration	Install Claude Code slash commands

Integrations

SDD CLI supports several integrations to enhance your workflow:

Agent OS

Structured workflows for AI coding agents. Provides methodical approaches for agents to work through specifications.

sdd install agent-os

Design OS

Product planning and design tool for creating comprehensive specifications.

sdd install design-os

Claude Code Integration

Installs 20 slash commands for use with Claude Code:

Core Workflow:

Command	Description
/sdd-workflow	Complete SDD workflow guide
/sdd-spec	Manage specifications
/sdd-plan	Manage implementation plans
/sdd-task	Manage tasks
/sdd-adr	Manage architecture decisions
/sdd-status	View project progress
/sdd-validate	Validate project structure
/sdd-monitor	Watch progress in real-time
/sdd-derive-plan	Derive plan from specification

AI Optimization:

Command	Description
/sdd-suggest	Get implementation suggestions
/sdd-learn	View validation history
/sdd-agents	Generate agent configuration
/sdd-patterns	Analyze codebase patterns

Quality Validation:

Command	Description
/sdd-test	Run tests with coverage
/sdd-security	Security scanning
/sdd-arch	Architecture validation
/sdd-docs	Documentation validation
/sdd-observability	Observability checks
/sdd-perf	Performance validation
/sdd-sync	Sync meta.yaml files

sdd install claude-integration
sdd install claude-integration --update  # Refresh existing installation

The Claude integration is automatically installed during sdd init. Use --no-claude to skip.

Claude Code Plugins

During sdd init, SDD CLI detects useful Claude Code plugins and offers to configure them:

• compound-engineering - Engineering workflows and code review
• context7 - Documentation lookup
• testing-suite - Automated testing tools

Use --with-sdd-plugins to install recommended plugins without prompting.

Project Structure

After running sdd init, your project will have:

your-project/
├── .sdd/
│   ├── config.yaml      # Configuration
│   ├── specs/           # Specifications (*.md)
│   ├── plans/           # Plans derived from specs (*.md)
│   └── adrs/            # Architecture Decision Records (*.md)
├── .claude/
│   └── commands/sdd/    # Claude Code slash commands (if installed)
├── CLAUDE.md            # Claude Code project guide (if installed)
└── ... your code

Specification Levels

SDD supports three levels of specifications:

Level	Use Case	Detail
micro-spec	Small changes, bug fixes	Minimal: what, why, acceptance criteria
standard-spec	Features, enhancements	Requirements, acceptance criteria, edge cases
full-spec	Major features, systems	Complete: context, requirements, API, testing, rollout

File Format

All SDD artifacts use Markdown with YAML frontmatter:

---
id: my-feature
title: My Feature
type: standard-spec
status: draft
owner: developer
created: 2025-01-01
---

# Feature: My Feature

## Context
...

## Requirements
...

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

Quality Gates

SDD CLI enforces quality through a six-layer validation stack:

Layer	Trigger	Purpose
1. Spec Validation	sdd spec validate	Validates specification completeness
2. Plan Validation	sdd plan validate	Validates plan structure and task definitions
3. Task Pre-Exec	sdd task start	Pre-flight checks before starting work
4. Implementation	sdd task check	Code quality checks during development
5. Task Completion	sdd task done	Validates task is ready to be marked done
6. Plan Completion	sdd plan complete	Validates all tasks done before completing plan

Task Workflow with Validation

# Before starting work - run pre-flight checks
sdd task start my-task

# During development - check code quality
sdd task check my-task

# Before marking done - full validation report
sdd task validate my-task

# Mark complete (validation runs automatically)
sdd task done my-task

# Skip validation if needed
sdd task done my-task --force

Validation Checks

Pre-Execution (Layer 3):

• Task exists in a plan
• Task is not already completed
• Plan is active (not completed or abandoned)
• Referenced specification is approved

Implementation (Layer 4):

• Task exists and is in progress
• Uncommitted changes detected
• No hardcoded secrets in changed files
• Linting passes (go vet, eslint, ruff, etc.)

Completion (Layer 5):

• Task exists
• All subtasks are completed
• Plan is still active

Web UI

SDD includes a built-in Web UI for visualizing project progress:

sdd serve

Opens at http://localhost:3000

Features:

• Visual progress tracking
• Spec/plan/task navigation
• Real-time updates
• Integration status

Architecture

• Single Go binary with embedded Web UI
• Git as source of truth (no database required)
• Markdown + YAML frontmatter for all artifacts
• Svelte 5 + SvelteKit for the Web UI
• Background update checking with 24-hour cache

Development

# Install dependencies
make deps

# Build everything
make build

# Run tests
make test

# Run linter
make lint

# Development mode
make dev-cli ARGS="status"
make dev-ui

License

BSL (Business Source License) / Fair Source - free for individuals and teams of 5 or fewer, paid for larger commercial teams.

Contributing

No Contributions needed.