ai-sdd: AI-Assisted Spec-Driven Development

Spec-Driven Development, Reimagined for AI

AI multiplies whatever you feed it. Feed it structure — specs, designs, tasks — and it multiplies your velocity. Feed it chaos, and it multiplies your mistakes.

ai-sdd brings structured Spec-Driven Development (SDD) to Claude Code, Cursor, Gemini CLI, Codex CLI, GitHub Copilot, Qwen Code, and Windsurf — implementing the AI-SDD methodology.

The Director–Executor–Contract philosophy keeps you in control:

• Director — You provide intent, constraints, and approval at every phase
• Executor — The AI implements within the boundaries you defined
• Contract — Specifications (requirements, design, tasks) are the shared language that keeps both aligned

What you get:

• ✅ Spec-as-Code — Requirements, design, and tasks live as versioned Markdown files inside your repository, right alongside the code
• ✅ Spec-first guarantees — Approve requirements and design upfront, then AI implements exactly as specified
• ✅ Parallel execution ready — Tasks decomposed for concurrent implementation with dependency tracking
• ✅ Team-aligned templates — Customize once, all agents output docs that fit your approval process
• ✅ Project Memory — AI remembers your architecture, patterns, and standards across sessions
• ✅ 7 agents, unified workflow — Same spec-driven process across Claude, Cursor, Gemini, Codex, Copilot, Qwen, Windsurf

🚀 Installation

# Run in your project root directory
cd your-project
npx ai-sdd

# ✅ That's it! Now run: /sdd:spec-init <what-to-build>

Installation takes 30 seconds. Supports 7 agents (Claude (Commands / Subagents), Cursor, Gemini, Codex, Copilot, Qwen, Windsurf) × 12 languages.

✨ Quick Start

For New Projects

# Launch AI agent and start spec-driven development immediately
/sdd:spec-init Build a Retirement Calculator              # AI creates structured plan
/sdd:spec-requirements retirement-calculator              # AI asks clarifying questions
/sdd:spec-design retirement-calculator                    # Human validates, AI designs
/sdd:spec-tasks retirement-calculator                     # Break into implementation tasks
/sdd:spec-impl retirement-calculator                      # Execute with TDD

For Existing Projects (Recommended)

# 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   # AI creates enhancement plan
/sdd:spec-requirements guest-checkout                      # AI asks clarifying questions
/sdd:validate-gap guest-checkout                           # Optional: Analyze existing vs requirements
/sdd:spec-design guest-checkout                            # Human validates, AI designs
/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 in 10 minutes:

• ✅ requirements.md — EARS-format requirements
• ✅ design.md — Architecture with Mermaid diagrams
• ✅ tasks.md — Implementation tasks with dependencies

🎯 Use Cases

🎨 Customization

Customize templates and rules in .sdd/settings/ to match your team's workflow:

• templates/ — Define document structure for requirements, design, and tasks — PRD-style, API-focused, or any format your team already uses
• rules/ — Define AI generation principles, acceptance criteria style, and judgment criteria

Common use cases: PRD-style requirements with business context and priority, API/database-focused design documents, BDD or EARS acceptance criteria, domain-specific naming standards, custom approval gates.

🔌 Tool Integrations & Spec-as-Code

A note on integrations and Spec-as-Code

ai-sdd supports optional Jira and Azure DevOps integrations for teams that already rely on those tools. However, one of the most innovative aspects of ai-sdd is the Spec-as-Code philosophy: requirements, design, and tasks live as versioned Markdown files inside your repository, right alongside the code they describe. This means your specs travel with every branch, every pull request, and every release — giving you a complete, auditable history of every decision made during development.

It is highly recommended to treat your version-controlled specs in git as the source of truth, and use Jira or Azure DevOps as a secondary view for stakeholders who prefer a board-based interface. The spec files are always the authoritative record.

Use /sdd:steering-custom to activate an integration. The AI will display a setup guide in chat and create the configuration file for you.

Jira Cloud

/sdd:steering-custom jira

Creates .sdd/steering/jira.md. Team lead fills in the shared settings once and commits — every team member inherits the config on pull.

Credentials (every member) — generate an API token at id.atlassian.com and set two env vars locally:

Linux / macOS (~/.bashrc or ~/.zshrc):

export JIRA_EMAIL="you@example.com"
export JIRA_TOKEN="your-api-token"

Windows (PowerShell — permanent, restart terminal after):

[System.Environment]::SetEnvironmentVariable("JIRA_EMAIL","you@example.com","User")
[System.Environment]::SetEnvironmentVariable("JIRA_TOKEN","your-api-token","User")

Credentials are never stored in any file. The AI reads them directly from environment variables at runtime.

Azure DevOps

/sdd:steering-custom azure-devops

Creates .sdd/steering/azure-devops.md. Supports all three ADO process templates.

Credentials (every member) — generate a PAT at dev.azure.com (scope: Work Items → Read & write) and set it locally:

Linux / macOS (~/.bashrc or ~/.zshrc):

export ADO_PAT="your-personal-access-token"

Windows (PowerShell — permanent, restart terminal after):

[System.Environment]::SetEnvironmentVariable("ADO_PAT","your-personal-access-token","User")

Credentials are never stored in any file. The AI reads them directly from environment variables at runtime.

⚙️ Advanced Installation

Choose Your Agent

npx ai-sdd --claude         # Claude Code (11 commands) [default]
npx ai-sdd --claude-agent   # Claude Code Subagents (12 commands + 9 subagents)
npx ai-sdd --cursor         # Cursor IDE
npx ai-sdd --gemini         # Gemini CLI
npx ai-sdd --codex          # Codex CLI
npx ai-sdd --copilot        # GitHub Copilot
npx ai-sdd --qwen           # Qwen Code
npx ai-sdd --windsurf       # Windsurf IDE

Choose Your Language

npx ai-sdd                  # Default English
npx ai-sdd --lang pt        # Portuguese
npx ai-sdd --lang ja        # Japanese
npx ai-sdd --lang zh-TW     # Traditional Chinese
npx ai-sdd --lang es        # Spanish
# Supports: en, ja, zh-TW, zh, es, pt, de, fr, ru, it, ko, ar

Advanced Options

# Preview changes before applying
npx ai-sdd --dry-run

# Custom specs directory
npx ai-sdd --sdd-dir docs

📚 Documentation & Support

📖 Learn More

Book: AI-Assisted SDD: Spec-Driven Development with Gemini, Claude, and ai-sdd

Available in English, Portuguese, and Japanese on 8+ bookstores worldwide. Written by Leonardo Sampaio, this comprehensive guide covers the complete SDD methodology — from the Director–Executor–Contract philosophy and EARS requirement format to brownfield adoption and multi-agent strategies.

Website: ai-sdd.com

💡 About the SDD Methodology

AI-Assisted Spec-Driven Development is a methodology that structures how humans and AI collaborate to build software — built on four phases:

1. Requirements — EARS-format specifications that leave no room for ambiguity
2. Technical Design — Architecture, data models, and component diagrams
3. Task Breakdown — Granular implementation tasks with explicit dependencies
4. TDD Implementation — AI executes within the boundaries you approved

Learn more about the methodology in the AI-Assisted SDD book.

Author

Leonardo Sampaio — Principal Architect at CI&T, Computer Scientist with 20+ years of experience.

LinkedIn · YouTube · Amazon Author Page

License

AI-SDD is an independent framework maintained by its author.

CI&T is recognized as an early Design Partner of the AI-SDD framework.

See LICENSE.md for full details.