claude-sdd

claude-sdd

Spec-Driven Development automation for Claude Code - Bring Kiro-like workflow to your projects.

Features

✅ Spec-Driven Development - Complete templates for requirements, design, and tasks
✅ File Watcher - Automatic prompt generation as you code
✅ Task Management - Interactive CLI for creating and tracking tasks
✅ Git Integration - Automated hooks for commit quality
✅ Code Review - Automated review checklists
✅ Health Monitoring - Track project health and spec alignment
✅ Claude Code Integration - Optimized for Claude Code workflow

Installation

Global Installation (Recommended)

npm install -g claude-sdd

Project Installation

npm install --save-dev claude-sdd

Quick Start

# 1. Initialize your project
csdd init

# 2. Create your first task
csdd task create

# 3. Start file watcher (in a separate terminal)
csdd watch

# 4. Use prompts with Claude Code
# Check .claude-hooks/auto-prompts.txt for generated prompts

Commands

Project Setup

csdd init                    # Initialize spec-driven development
csdd init --force            # Overwrite existing files

File Monitoring

csdd watch                   # Start file watcher
csdd watch --debounce 3000   # Custom debounce time (milliseconds)

Task Management

csdd task create             # Create new task (interactive)
csdd task list               # List all tasks
csdd task list --status done # Filter by status
csdd task show TASK-001      # Show task details
csdd task complete           # Mark task complete (interactive)
csdd task complete TASK-001  # Mark specific task complete

Code Quality

csdd review                  # Generate review checklist
csdd sync                    # Sync specs with codebase
csdd health                  # Full health check
csdd status                  # Quick status

Project Structure

After initialization:

your-project/
├── .specs/
│   ├── requirements.md      # Feature requirements (EARS format)
│   ├── design.md            # Technical design
│   ├── tasks.md             # Implementation tasks
│   ├── decisions.md         # Architecture Decision Records
│   └── changelog.md         # Project changelog
├── .claude/
│   ├── config.json          # Configuration
│   ├── context.md           # Project context
│   ├── prompts.md           # Prompt templates
│   └── steering.md          # Coding standards
├── .claude-hooks/
│   ├── logs/                # Activity logs
│   └── auto-prompts.txt     # Generated prompts
└── Makefile                 # Make commands

Workflow

1. Planning Phase

# Create requirements
csdd task create

# Use Claude Code:
"Based on my feature description, create user stories in .specs/requirements.md 
using EARS format acceptance criteria"

"Create technical design in .specs/design.md based on requirements"

"Break down the design into tasks in .specs/tasks.md"

2. Implementation Phase

# Start watcher
csdd watch

# Implement tasks
# Claude Code:
"Implement TASK-001 from .specs/tasks.md"

# File watcher generates prompts automatically
# Check .claude-hooks/auto-prompts.txt

3. Review Phase

# Generate review checklist
csdd review

# Claude Code:
"Review my implementation against this checklist"

# Mark task complete
csdd task complete TASK-001

# Update documentation
"Add changelog entry for TASK-001"

4. Commit & Push

# Git hooks provide prompts automatically
git add .
# Pre-commit hook shows prompts

git commit -m "feat(auth): add JWT authentication (TASK-001)"

git push
# Pre-push hook shows checklist

Integration with Make

Use the generated Makefile:

make init        # Initialize
make watch       # Start watcher
make task-new    # Create task
make task-done   # Complete task
make review      # Review code
make health      # Health check

Configuration

Edit .claude/config.json:

{
  "watch": {
    "paths": ["src/**/*", "lib/**/*"],
    "ignored": ["**/node_modules/**"],
    "debounceMs": 2000
  },
  "quality": {
    "minTestCoverage": 80
  }
}

Best Practices

• Always start with specs - Don't code before documenting requirements
• Reference specs in prompts - "Following .specs/design.md, implement..."
• Keep specs updated - Run csdd sync regularly
• Use task IDs in commits - "feat(auth): implement JWT (TASK-003)"
• Review before committing - Run csdd review

Examples

Example 1: Building User Authentication

# 1. Initialize
csdd init

# 2. Define requirements
# Claude Code: "Create requirements for user authentication in .specs/requirements.md"

# 3. Design
# Claude Code: "Create technical design in .specs/design.md"

# 4. Create tasks
csdd task create
# Title: Implement JWT authentication
# Priority: High

# 5. Start watching
csdd watch

# 6. Implement
# Claude Code: "Implement TASK-001 from .specs/tasks.md"

# 7. Review
csdd review

# 8. Complete
csdd task complete TASK-001

Troubleshooting

File watcher not working

# Restart watcher
csdd watch

Git hooks not triggering

# Reinstall hooks
csdd init --force

Prompts file too large

# Archive old prompts
move .claude-hooks\auto-prompts.txt .claude-hooks\auto-prompts-backup.txt

What Makes This Special

Unlike other tools, claude-sdd:

✅ One package - Everything included
✅ Zero config - Works out of the box
✅ Claude optimized - Designed for Claude Code
✅ Spec-driven - Maintains context across sessions
✅ Production ready - Battle-tested workflow

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Support

• Documentation: Check .claude/prompts.md for example prompts
• Issues: Report bugs via GitHub Issues

Transform your Claude Code workflow with spec-driven development! 🚀