Structure for AI-assisted development
AI coding assistants are powerful but chaotic. You prompt, you get code, but then what? No documentation of decisions, no way to verify the code matches what you needed, and a codebase that's impossible to explain to teammates.
SDD brings structure to AI-assisted development. Every change starts with a spec, gets broken into a plan, and ends with verified implementation. Specialized agents handle each concern instead of one AI doing everything poorly.
claude plugin marketplace add https://github.com/LiorCohen/sdd
claude plugin install sdd/sdd I want to initialize a new project # Initialize a new project
/sdd I want to create a new feature # Create a spec
/sdd I want to approve the spec # Review spec, create plan
/sdd I want to approve the plan # Approve plan, enable implementation
/sdd I want to start implementing # Execute the plan
/sdd I want to verify the implementation # Verify it matches the spec
Get started with the tutorial →
Every change lives in a markdown specification before it lives in code:
changes/2026/01/15/user-auth/
├── SPEC.md # What you're building (acceptance criteria)
└── PLAN.md # How to build it (phased implementation)
Specs include frontmatter metadata, acceptance criteria in Given/When/Then format, and references to domain concepts.
| Type | Purpose | Structure |
|---|---|---|
| feature | New functionality | 6 phases |
| bugfix | Fix existing behavior | 4 phases |
| refactor | Restructure without changing behavior | 4 phases |
| epic | Multiple features grouped under one goal | Child changes in changes/ subdirectory |
Instead of one general-purpose AI, SDD uses 7 specialized agents:
| Agent | Model | Purpose |
|---|---|---|
| api-designer | sonnet | Design OpenAPI contracts |
| backend-dev | sonnet | Node.js backend (CMDO architecture) |
| frontend-dev | sonnet | React components (MVVM architecture) |
| db-advisor | opus | Database performance review |
| devops | sonnet | Kubernetes, Helm, CI/CD, Testkube |
| tester | sonnet | Integration and E2E test automation |
| reviewer | opus | Code review and spec compliance |
| Command | Purpose |
|---|---|
/sdd |
Context-aware hub — reads project state and guides you |
/sdd I want to create a new feature |
Create new change spec |
/sdd I want to import an external spec |
Import changes from external spec |
/sdd I want to approve the spec |
Approve spec, create plan |
/sdd I want to approve the plan |
Approve plan, enable implementation |
/sdd I want to start implementing |
Execute implementation plan |
/sdd I want to verify the implementation |
Verify implementation matches spec |
/sdd I want to generate config for local |
Generate merged config for an environment |
/sdd set up the database |
Direct system operations via natural language |
/sdd-help |
Interactive tutor for SDD concepts |
SDD commands create many files. To reduce permission prompts, add this to your .claude/settings.local.json:
{
"permissions": {
"allow": [
"Write(changes/**)",
"Write(specs/**)",
"Write(components/**)",
"Edit(changes/**)",
"Edit(specs/**)",
"Edit(components/**)",
"Bash(git *)",
"Bash(npm *)"
],
"deny": [
"Write(.env*)",
"Edit(.env*)"
]
}
}See Permissions Setup for full configuration options.
- Getting Started - First project tutorial
- Workflows - Feature, bugfix, and refactor workflows
- Commands - Full command reference
- Agents - What each agent does
- Components - Component types reference
- Configuration Guide - Config system details
- Permissions Setup - Reduce permission prompts
When you run /sdd I want to initialize a new project, you get:
your-project/
├── changes/ # Change specifications (YYYY/MM/DD/<name>/)
├── specs/
│ ├── INDEX.md # Registry of all specifications
│ ├── SNAPSHOT.md # Current product state
│ ├── domain/
│ │ ├── glossary.md # Domain terminology
│ │ └── definitions/ # Domain definitions
│ └── architecture/ # Architecture decisions
├── components/
│ ├── config/ # Configuration (YAML + TypeScript types)
│ ├── contract/ # OpenAPI specs (workspace package)
│ ├── server/ # Node.js backend
│ ├── webapp/ # React frontend
│ ├── database/ # PostgreSQL migrations
│ ├── helm/ # Kubernetes charts
│ └── testing/ # Testkube definitions
└── .github/workflows/ # CI/CD pipelines
- CMDO Backend - Controller Model DAL Operator with strict layer separation
- MVVM Frontend - Model-View-ViewModel with TanStack ecosystem
- Contract-First API - OpenAPI specs generate TypeScript types
- Immutability Enforced -
readonlyeverywhere, no mutations - OpenTelemetry - Structured logging, metrics, and tracing
See CONTRIBUTING.md for guidelines.
MIT