AI-SDD CLI — Spec-Driven Development in Your Terminal

Prerequisites

Node.js (latest LTS)
AI Code Assistant installed: Claude Code, Cursor, Gemini CLI, Codex CLI, GitHub Copilot, Qwen Code, Windsurf

Installation

# Open your terminal and go to your project directory, or create a new one
mkdir my-new-project
cd my-new-project
npx ai-sdd  # Select your AI code agent from the list

# Start your AI Assistant
claude  # or gemini, etc.

# That's it! Talk to your agent:
# Start a specification for a Retirement Calculator web app

Two Paths

# Launch your AI agent and start spec-driven development immediately
/sdd:spec-init "Build a Retirement Calculator"  # Spec is initiated
/sdd:spec-requirements retirement-calculator     # Requirements are generated
/sdd:spec-design retirement-calculator           # Design is created
/sdd:spec-tasks retirement-calculator            # Break into implementation tasks
/sdd:spec-impl retirement-calculator             # Execute with TDD

# First establish project context, then proceed with development
/sdd:steering                                  # AI learns existing project context

/sdd:spec-init "Add Guest Checkout to existing e-commerce"
/sdd:spec-requirements guest-checkout
/sdd:validate-gap guest-checkout               # Optional: Analyze existing vs requirements
/sdd:spec-design guest-checkout
/sdd:validate-design guest-checkout            # Optional: Validate design integration
/sdd:spec-tasks guest-checkout                 # Break into implementation tasks
/sdd:spec-impl guest-checkout                  # Execute with TDD

Generated Output

Generated in about 10 minutes:

requirements.md

EARS-format requirements

design.md

Architecture with Mermaid diagrams

tasks.md

Implementation tasks with dependencies

Use Cases

Instead of running commands, talk to your AI agent. Approve each phase before moving to the next.

You "Start a spec for a Retirement Calculator"

AI Generates requirements.md — reviews it with you

You "Requirements look good — approve them"

AI ✅ Requirements approved. Generating design.md...

You "Design is solid — approve it"

AI ✅ Design approved. Breaking into tasks.md...

You "Tasks are correct — approve them"

AI ✅ Tasks approved. Implementing with TDD...

What to commit (and what not to)

npx ai-sdd scaffolds the agent tooling — .claude/, CLAUDE.md, .sdd/settings/. The specs and steering files are created separately, as you run the spec commands and steering commands. Those are your project's shared language. Commit the artifacts, not the tooling.

Add these lines to your .gitignore:

# AI-SDD agent files (Claude Code — regenerate with `npx ai-sdd`)
CLAUDE.md
.claude/
.sdd/settings/

Each developer runs npx ai-sdd to scaffold agent files locally.

Keep .sdd/specs/ and .sdd/steering/ in version control.

Some teams prefer to commit CLAUDE.md and .claude/commands/ to share agent instructions and custom slash commands. Choose what works for your team — the spec and steering files are designed to be committed as your spec-as-code audit trail.

Learn more

ai-sdd.com npm i ai-sdd

A framework for AI agents that implements Spec-Driven Development (SDD)