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

Prerequisites

Node.js (latest LTS)
AI Code Assistant installed: Claude Code, Antigravity CLI (agy), Cursor, 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 agy, 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.

Custom Steering

/sdd:steering-custom extends the .sdd/steering/ files your agent reads as project memory. Most templates capture patterns from a one-time codebase scan. Two of them work differently — they deserve a closer look.

None of this is required. The default flow — requirements → design → tasks → implementation — works with zero custom files. These are for when the defaults stop being enough.

Standard templates, generated once from your codebase:

api-standards testing security database error-handling authentication deployment cross-repo jira azure-devops

Living documentation

Research Notes

The answers the code can't give you.

Every other template is generated once from a code scan. This one starts nearly empty and grows across every conversation — what a field really means, which system writes where, stakeholder answers, undocumented quirks. Facts that took real effort to discover, captured once so your agent never re-learns them the hard way.

research-notes.mdgrows across conversations

## orders table — status columnsession 3

Only the payment webhook writes orders.status; the API only reads it.

## nightly sync — retry behaviorsession 11

Retries 3× with a fixed 5s delay, then drops the batch silently — a ~15s outage can lose data.

## staging vs prodsession 19

Staging caches for 60s, prod for 10s — a known difference, not a config bug.

Ask your agent "Create research notes steering" → .sdd/steering/research-notes.md

Opt-in styling

Diagram Conventions

Design diagrams that show what changed.

By default, design.md diagrams are plain Mermaid — structure only, no color. Add this file once and every diagram gains meaning: new components in green, modified in blue, untouched in gray, external systems in pale yellow, grouped in module swimlanes.

Ask your agent "Create diagram conventions steering" → .sdd/steering/diagram-conventions.md

Reach for research notes when your agent keeps asking questions someone already answered. Reach for diagram conventions when design reviews need to show what a change touches at a glance. Until then, the defaults are exactly right.

Learn more

ai-sdd.com npm i ai-sdd

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