From Scattered Chats to Structured Specs
Building with AI agents? Watch context vanish between sessions? Features taking weeks when they should take hours?
What I Built
ai-sdd transforms AI coding agents into spec-driven developers with one command.
It installs slash commands (/sdd:spec-init, /sdd:spec-requirements, /sdd:spec-design) that guide AI agents through a proven four-phase workflow: Requirements → Design → Tasks → Implementation.
Works across 7 platforms: Claude Code, Cursor, Gemini CLI, Codex CLI, GitHub Copilot, Qwen Code, and Windsurf.
The core problem: AI agents are powerful at generating code but terrible at remembering context. Specifications scattered across chat logs. Architecture forgotten between sessions. Weeks of back-and-forth re-explaining the same decisions.
The solution: Persistent .sdd/ directories store specifications and project memory. AI agents load your architecture automatically in every session—no more re-explaining.
Demo
🔗 Links
- GitHub: https://github.com/leosamp/ai-sdd
- NPM: https://www.npmjs.com/package/ai-sdd
- Book: AI-Assisted SDD on Amazon
- Learn More: https://leo.it/sdd
🚀 Quick Start
# Install (choose your platform)
npx ai-sdd@latest --claude --lang en
# Then in your AI agent, run:
/sdd:spec-init "user authentication with OAuth2"
/sdd:spec-requirements user-auth
/sdd:spec-design user-auth
/sdd:spec-tasks user-auth
/sdd:spec-impl user-auth
Specs are stored in .sdd/specs/{feature-name}/ with full traceability.
No credentials required - local-first tool, zero configuration.
The Story Behind It
After months of building with AI agents, I kept hitting the same wall: context loss.
Every new chat session meant re-explaining my architecture. Every feature request turned into weeks of back-and-forth because specifications lived scattered across conversations.
I realized AI agents needed what human developers have had for decades: structured specifications.
So I built two things:
The methodology: I published "AI-Assisted SDD: Spec-Driven Development for Claude, Gemini, and ChatGPT"—documenting a proven approach adapted from traditional software engineering for AI agents.
The framework: I built ai-sdd to implement this methodology across all major AI platforms with one unified workflow.
The problem was universal—developers across 7 different platforms all struggling with scattered context and lost specifications. Now features that took weeks take hours.
Technical Highlights
Core Stack: Node.js/TypeScript CLI with custom template engine supporting 7 AI platforms and 12 languages (84 configurations).
Key Innovations:
EARS-Format Requirements
AI agents generate unambiguous requirements using Easy Approach to Requirements Syntax:
WHEN [trigger]
THEN the system SHALL [action]
WHERE [constraints]
Project Memory System
Architecture, tech stack, and patterns persist in .sdd/steering/ files. AI agents auto-load context in every session—they remember your project forever.
Approval Checkpoints
Three-phase workflow: Requirements → Design → Tasks. AI agents cannot implement until you approve specs. Prevents costly rework.
Parallel Task Execution
Tasks marked with (P) for parallel execution. Dependencies tracked automatically. Maximum efficiency.
Why It's Unique:
- First unified SDD tool across 7 AI platforms
- File-based, Git-friendly specs (not locked in chat logs)
- Zero configuration, no API keys
- Methodology-backed by published book
- Open source (MIT license)
Use of Mux (Additional Prize Category)
I used Mux AI to streamline video production for this submission:
Mux Features Used:
1. Video Hosting & Optimization
- Uploaded 60-second video (1920x1080)
- Automatic adaptive bitrate streaming + CDN delivery
- Fast global load times with zero configuration
2. AI Auto-Captioning
- One-click caption generation for accessibility
- ~95% accuracy on general content
- Manual corrections for technical terms: "ai-sdd", "EARS-format",
/sdd:spec-init - Downloaded VTT file for reuse across platforms
3. AI Transcript Generation
- Full transcript for SEO and accessibility
- Used transcript in this post and social media captions
4. Seamless Embed
- Liquid tag syntax worked perfectly in DEV.to
- Responsive player, user-initiated playback
- Tested across desktop and mobile browsers
Developer Experience
Mux was ridiculously easy:
- Sign up (free, no credit card)
- Upload video
- Wait ~2 minutes
- Enable AI features (one click)
- Copy playback ID
The AI captioning saved hours of manual transcription. Mux removed all video infrastructure complexity—encoding, CDN, player compatibility—so I could focus on building ai-sdd instead of becoming a video expert.
For any video-centric project, Mux is a no-brainer.
Key Features
| Traditional AI Dev | With ai-sdd |
|---|---|
| ❌ Specs scattered in chat logs | ✅ Structured .sdd/specs/ directory |
| ❌ Context lost between sessions | ✅ Persistent project memory |
| ❌ Weeks of back-and-forth | ✅ Hours with approved specs |
| ❌ Ad-hoc requirements | ✅ EARS-format precision |
| ❌ Sequential execution | ✅ Parallel task execution |
Try ai-sdd Today
Stop losing context. Stop repeating yourself. Stop wasting weeks on features that should take hours.
npx ai-sdd@latest --claude --lang en
/sdd:spec-init "your feature description here"
Transform your AI agent into a spec-driven development partner.
What's your biggest pain point working with AI coding agents? Share below! 👇
SOCIAL SHARE CARD GENERATOR