ai-sdd: AI-Assisted Spec-Driven Development

Transform AI coding agents into spec-driven developers

One command. Hours instead of weeks. Requirements → Design → Tasks → Implementation.

Stop losing development time to scattered context and unclear specifications. ai-sdd brings structured Spec-Driven Development (SDD) to Claude Code, Cursor, Gemini CLI, Codex CLI, GitHub Copilot, Qwen Code, and Windsurf, based on the methodology from AI-Assisted SDD book.

What you get:

• ✅ Spec-first guarantees — Approve requirements/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
• ✅ Hours instead of weeks — Feature planning goes from days to hours with AI-assisted specs

🚀 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 simple Hangman game          # AI creates structured plan
/sdd:spec-requirements hangman                      # AI asks clarifying questions
/sdd:spec-design hangman                            # Human validates, AI designs
/sdd:spec-tasks hangman                             # Break into implementation tasks
/sdd:spec-impl hangman                              # 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

| Scenario | Workflow | |----------|----------| | New feature (greenfield) | spec-init → spec-requirements → spec-design → spec-tasks → spec-impl | | Enhance existing code (brownfield) | steering → spec-init → (validate-gap →) spec-design → (validate-design →) spec-tasks → spec-impl | | Team process alignment | Customize templates once in .sdd/settings/templates/ → all agents follow same format |

🎨 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

Keep your specs and project management tools in sync — automatically. As each SDD phase completes, ai-sdd can create and update work items without any manual copy-paste.

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.

| SDD Phase | Jira Action | |---|---| | spec-init | Creates Epic | | spec-requirements | Creates Stories — one per requirement | | spec-design (approved) | Updates Epic description with key design decisions | | spec-tasks | Creates Subtasks — one per task |

Setup in 3 steps:

1. Shared config (team lead, once) — fill in jira_base_url and jira_project_key in .sdd/steering/jira.md, then commit and push.

2. Personal 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="[email protected]"
   export JIRA_TOKEN="your-api-token"

   Windows (PowerShell — permanent, restart terminal after):

   [System.Environment]::SetEnvironmentVariable("JIRA_EMAIL","[email protected]","User")
   [System.Environment]::SetEnvironmentVariable("JIRA_TOKEN","your-api-token","User")

3. Run /sdd:spec-init <feature> — Jira stays in sync from there.

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.

| SDD Phase | Azure Boards Action | Work Item (Agile / Scrum / CMMI) | |---|---|---| | spec-init | Creates Epic | Epic | | spec-requirements | Creates work items — one per requirement | User Story / PBI / Requirement | | spec-design (approved) | Updates Epic description | — | | spec-tasks | Creates Tasks — one per task | Task |

Setup in 3 steps:

1. Shared config (team lead, once) — fill in ado_organization, ado_project, and ado_process in .sdd/steering/azure-devops.md, then commit and push.

2. Personal 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")

3. Run /sdd:spec-init <feature> — Azure Boards stays in sync from there.

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

This comprehensive guide by Leonardo Sampaio covers the complete SDD methodology, practical examples, and best practices for AI-assisted development.

💡 About SDD Methodology

Spec-Driven Development (SDD) is a systematic approach to software development that emphasizes:

1. Clear Specifications First - Define what you're building before writing code
2. AI-Assisted Planning - Leverage AI to generate comprehensive requirements and design documents
3. Structured Workflow - Follow a proven path from requirements to implementation
4. Team Alignment - Ensure everyone works from the same specifications
5. Quality Gates - Validate specifications before implementation begins

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

Author

Leonardo Sampaio - 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.