SDD Tool

Spec-Driven Development CLI - AI-Powered Specification Workflow


> 🇰🇷 한국어 문서 (Korean)

📚 Documentation | 🚀 Getting Started | 📋 CLI Reference

Overview

SDD Tool is a command-line interface designed to work with Claude Code for implementing Spec-Driven Development (SDD) methodology. Through slash commands, you collaborate with AI to write specifications and implement features.

$3

- Specifications First: Write specifications before writing code
- AI Collaboration: Automate workflow through Claude Code slash commands
- RFC 2119 Keywords: Use SHALL, MUST, SHOULD, MAY to clarify requirements
- GIVEN-WHEN-THEN Scenarios: Define requirements using scenario-based approach
- Constitution: Define core principles of your project

---

Installation

``bash
npm install -g sdd-tool
`

Verify installation:

`bash
sdd --version
`

---

Quick Start

`bash


1. Initialize your project (creates slash commands + Git/CI-CD setup)

sdd init

2. Start Claude Code

claude

3. Begin workflow with slash command

/sdd.start
`

---

Complete Workflow

`
┌─────────────────────────────────────────────────────────────┐
│ SDD Slash Command Workflow │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. /sdd.start → Start workflow │
│ │ │
│ ▼ │
│ 2. /sdd.constitution → Define project principles │
│ │ │
│ ▼ │
│ 3. /sdd.spec → Write/edit spec (spec.md) │
│ │ │
│ ▼ │
│ 4. /sdd.plan → Create implementation plan │
│ │ │
│ ▼ │
│ 5. /sdd.tasks → Break down into tasks │
│ │ │
│ ▼ │
│ 6. /sdd.prepare → Verify sub-agents/skills │
│ │ │
│ ▼ │
│ 7. /sdd.implement → Sequential implementation │
│ │ │
│ ▼ │
│ 8. /sdd.validate → Validate specifications │
│ │
└─────────────────────────────────────────────────────────────┘
`

---

Slash Commands (20 Total)

Automatically generated in .claude/commands/ when you run sdd init.

$3

| Command | Description | Example |
|---------|-------------|---------|
| /sdd.start | Unified entry point | /sdd.start |
| /sdd.constitution | Project principles | /sdd.constitution React-based todo app |
| /sdd.spec | Write/edit spec (unified) | /sdd.spec user authentication |
| /sdd.plan | Implementation planning | /sdd.plan |
| /sdd.tasks | Break down into tasks | /sdd.tasks |
| /sdd.prepare | Verify sub-agents/skills | /sdd.prepare |
| /sdd.implement | Sequential implementation | /sdd.implement |
| /sdd.validate | Spec validation | /sdd.validate |

> Note: /sdd.spec automatically determines whether to create new specs or modify existing ones, guiding you through the appropriate workflow.

$3

| Command | Description |
|---------|-------------|
| /sdd.impact | Analyze change impact |
| /sdd.transition | Switch between new ↔ change workflows |

$3

| Command | Replacement | Description |
|---------|-------------|-------------|
| /sdd.new | /sdd.spec | New feature spec |
| /sdd.change | /sdd.spec | Existing spec modification |

$3

| Command | Description |
|---------|-------------|
| /sdd.analyze | Analyze requests and estimate scope |
| /sdd.quality | Calculate spec quality score |
| /sdd.report | Generate project report |
| /sdd.search | Search specs |
| /sdd.status | Check project status |
| /sdd.list | View items list |
| /sdd.sync | Verify spec-code synchronization |
| /sdd.diff | Visualize spec changes |
| /sdd.export | Export specs (HTML, JSON) |

$3

| Command | Description |
|---------|-------------|
| /sdd.research | Technical research document |
| /sdd.data-model | Data model documentation |
| /sdd.guide | Workflow guide |

$3

| Command | Description |
|---------|-------------|
| /sdd.chat | Interactive SDD assistant |
| /sdd.watch | File watch mode |
| /sdd.migrate | Migration from external tools |
| /sdd.cicd | CI/CD configuration |
| /sdd.prompt | Output prompt |

---

Detailed Workflow Steps

$3

Entry point that analyzes project status and guides next actions:

`
/sdd.start
`

- New project: Recommends writing Constitution
- Existing project: Shows workflow menu

$3

Define your project's core principles:

`
/sdd.constitution React-based todo management app
`

AI analyzes .sdd/constitution.md and guides you through:
- Core Principles
- Technical Principles
- Forbidden Practices

$3

Write feature specifications with AI:

`
/sdd.spec user authentication
`

AI generates through conversation:
- spec.md - Feature specification (RFC 2119 + GIVEN-WHEN-THEN)

$3

Create an implementation plan:

`
/sdd.plan
`

- Technical decisions and rationale
- Implementation phases
- Risk analysis and mitigation

$3

Break requirements into executable tasks:

`
/sdd.tasks
`

- Each task completable within 2-4 hours
- Task dependencies marked
- Priority levels: HIGH (🔴), MEDIUM (🟡), LOW (🟢)

$3

Verify Claude Code tools needed for implementation:

`
/sdd.prepare
`

Features:
- Analyzes tasks.md to auto-detect required tools
- Checks existence of sub-agents (.claude/agents/)
- Checks existence of skills (.claude/skills/)
- Auto-generates missing tools

Detection Targets:

| Keyword | Sub-Agent | Skill |
|---------|-----------|-------|
| test, testing | test-runner | test |
| api, rest | api-scaffold | gen-api |
| component | component-gen | gen-component |
| database | - | db-migrate |
| documentation, doc | - | gen-doc |
| review | code-reviewer | review |

Also available via CLI:

`bash
sdd prepare user-auth # Interactive
sdd prepare user-auth --dry-run # Preview
sdd prepare user-auth --auto-approve # Auto-generate
`

$3

Sequential implementation based on tasks:

`
/sdd.implement
`

AI reads tasks.md and guides TDD-style implementation:
1. Change task status to "in progress"
2. Write tests
3. Implement code
4. Mark task as "completed"

$3

Validate specifications:

`
/sdd.validate
`

- Check RFC 2119 keyword usage
- Verify GIVEN-WHEN-THEN format
- Confirm required metadata fields

---

Interactive Mode: /sdd.chat

Execute SDD tasks naturally:

`
/sdd.chat
`

Example conversation:

`
You: I want to build a user authentication feature
AI: I'll help you create a user authentication spec. Let me ask a few questions...
1. What authentication method? (JWT, Session, OAuth)
2. Social login needed?
...
`

---

Spec File Format

$3

`markdown
---
id: user-auth
title: "User Authentication"
status: draft
created: 2025-12-24
constitution_version: 1.0.0
---

User Authentication

> JWT-based user authentication system

Requirements

$3

- The system SHALL support email/password login
- The system SHOULD return specific error messages on login failure

Scenarios

$3

- GIVEN a valid user account exists
- WHEN valid email and password are entered
- THEN a JWT token is returned
- AND token expiration time is set
`

$3

| Keyword | Meaning |
|---------|---------|
| SHALL / MUST | Absolute requirement |
| SHOULD | Recommended (exceptions allowed) |
| MAY | Optional |
| SHALL NOT | Absolutely forbidden |

---

CLI Commands

Terminal commands (in addition to slash commands):

$3

`bash
sdd init # Project initialization (interactive Git/CI-CD setup)
sdd init --skip-git-setup # Skip Git/CI-CD configuration
sdd init --auto-approve # Auto-approve all settings
sdd validate # Validate specs
sdd status # Check status
sdd list # View list
`

$3

`bash
sdd new # Create new feature (common domain)
sdd new -d # Create with domain (v1.3.0)
sdd new --all # Create spec + plan + tasks
sdd prepare # Verify sub-agents/skills
`

v1.3.0 Domain-based Structure:
- Without domain: creates in common folder
- Path: .sdd/specs///spec.md
- Example: sdd new login -d auth → .sdd/specs/auth/login/spec.md

$3

`bash
sdd change # Create change proposal
sdd change apply # Apply change
sdd impact # Analyze impact
`

$3

`bash
sdd quality # Quality analysis
sdd report # Generate report
sdd search # Search specs
`

$3

`bash
sdd sync # Verify spec-code sync
sdd sync user-auth # Sync specific spec
sdd sync --ci --threshold 80 # CI mode (threshold)
sdd sync --json # JSON output
sdd sync --markdown # Markdown report

sdd diff # Show spec changes (working directory)
sdd diff --staged # Show staged changes
sdd diff abc123 def456 # Compare commits
sdd diff --stat # Statistics summary
sdd diff --json # JSON output
`

$3

`bash
sdd export user-auth # Export single spec to HTML
sdd export --all # Export all specs
sdd export --format json # JSON format
sdd export --format markdown # Merged markdown
sdd export -o ./docs/specs.html # Specify output
sdd export --theme dark # Dark theme
sdd export --no-toc # Exclude table of contents
`

$3

`bash
sdd domain create auth # Create new domain
sdd domain list # List domains
sdd domain show auth # Show domain details
sdd domain link auth user-login # Link spec to domain
sdd domain depends order --on auth # Set domain dependencies
sdd domain graph # Show dependency graph (Mermaid)
sdd domain graph --format dot # DOT format
`

$3

`bash
sdd context set auth # Set context
sdd context set auth order # Multiple domains
sdd context set auth --include-deps # Include dependencies
sdd context show # Show current context
sdd context specs # List specs in context
sdd context clear # Clear context
`

$3

`bash
sdd reverse scan # Scan project structure
sdd reverse scan --depth deep # Deep analysis
sdd reverse extract # Extract spec drafts
sdd reverse extract --ai # AI-powered intent inference
sdd reverse review # Review extracted specs
sdd reverse finalize # Finalize approved specs
`

$3

`bash


Install Git Hooks

sdd git hooks install # Install pre-commit, commit-msg, pre-push
sdd git hooks uninstall # Remove hooks

Configure commit template

sdd git template install # Install .gitmessage template

Complete Git workflow setup

sdd git setup # hooks + template + .gitignore/.gitattributes

CI/CD configuration

sdd cicd setup github # Create GitHub Actions workflow
sdd cicd setup gitlab # Create GitLab CI config
sdd cicd check # Validate CI environment
`

---

Claude Code Structure

`
your-project/
├── .sdd/
│ ├── constitution.md # Project constitution
│ ├── AGENTS.md # AI workflow guide
│ ├── domains.yml # Domain definitions (v1.2.0)
│ ├── .context.json # Current context (v1.2.0)
│ ├── specs/ # Feature specifications (v1.3.0: domain-based)
│ │ ├── common/ # Default domain (no domain specified)
│ │ │ └── feature-name/
│ │ │ ├── spec.md
│ │ │ ├── plan.md
│ │ │ └── tasks.md
│ │ └── auth/ # Domain-grouped specs
│ │ └── login/
│ │ ├── spec.md
│ │ ├── plan.md
│ │ └── tasks.md
│ ├── changes/ # Change proposals
│ ├── archive/ # Completed changes
│ └── .reverse-drafts/ # Reverse extraction drafts (v1.2.0)
│
└── .claude/
├── commands/ # Slash commands (20 total)
│ ├── sdd.start.md
│ ├── sdd.spec.md
│ └── ...
├── agents/ # Sub-agents
│ ├── test-runner.md
│ └── api-scaffold.md
├── skills/ # Skills (v1.2.0)
│ ├── dev-implement.md
│ ├── dev-test.md
│ ├── sdd-reverse.md
│ ├── sdd-domain.md
│ ├── sdd-context.md
│ └── ...
└── settings.json # Skill settings (v1.2.0)
`

---

Development

`bash
git clone https://github.com/JakeB-5/sdd-tool.git
cd sdd-tool
pnpm install
pnpm run build
pnpm test
`

$3

`bash
pnpm run docs:dev # Development server
pnpm run docs:build # Build docs
pnpm run docs:preview # Preview docs
`

$3

`bash
pnpm run test:coverage # Coverage report
``

---

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

---

Changelog

See CHANGELOG.md for detailed changes.

---

License

MIT License - See LICENSE for details.