A game-changing Spec-Driven Development (SDD) toolkit for Cursor IDE
Transform chaotic feature ideas into structured, production-ready implementations
🚀 Quick Start • 📖 Documentation • 🎯 Examples • 🤝 Contributing
- 🎯 What is Spec-Driven Development?
- ✨ Key Features
- 🚀 Quick Start
- 📋 The Three Core Commands
- 📁 Project Structure
- 🎯 Example Workflow
- 💡 Best Practices
- 🔧 Configuration
- 🤝 Team Collaboration
- 📚 Advanced Usage
- 🎉 Benefits
Stop coding blindly. Start building with purpose.
Spec-Driven Development is a revolutionary methodology that emphasizes creating detailed, executable specifications before writing a single line of code. This approach ensures that:
- 🎯 Requirements are crystal clear before implementation begins
- 🏗️ Technical decisions are well-planned and documented
- 📋 Development tasks are structured and manageable
- 🤝 Team collaboration is enhanced through shared understanding
- 🚀 Delivery is faster with fewer iterations and scope changes
All SDD commands now integrate with Cursor's PLAN mode for enhanced control and visibility:
Every Command: User Request → Analysis → Present Plan → Approve → Execute
What This Means:
- 👁️ See before create - Review what will be generated before any files are made
- ✅ Approve or modify - Change the approach before execution
- 🧠 Learn the reasoning - Understand AI's thinking and decisions
- 🛡️ Safety first - No surprise file changes or modifications
- 🎯 Better quality - More thoughtful, deliberate specifications
Example Flow:
- You run
/brief checkout-flow Quick checkout for guest users - AI analyzes requirements and existing patterns
- AI presents a plan showing brief structure, research approach, and what will be created
- You review and approve (or request changes)
- AI executes, creating the feature brief as planned
- Result:
specs/active/checkout-flow/feature-brief.mdcreated with full visibility
|
|
🚀 Scenario: Adding user avatar upload to existing app
Why Perfect: Familiar technology, single team, clear requirements, low risk
Brief Focus: 30-minute planning → start coding immediately → evolve during development
📋 Scenario: Have requirements, need implementation approach
Why Good: Product requirements defined, research external solutions, study best practices
Research Focus: Industry analysis, competitor study, technology comparisons
🏗️ Scenario: Payment processing with PCI compliance
Why Full SDD: Multiple teams, regulatory requirements, architectural changes, high business risk
Full Workflow: Comprehensive research → detailed specs → complete planning → structured tasks
SDD 2.5 (Brief): Perfect for 80% of features - rapid development with essential planning
SDD 2.0 (Full): For 20% of complex features requiring comprehensive coordination
All SDD commands now use Cursor's PLAN mode - a deliberate, plan-approve-execute pattern that gives you full control.
Every command follows a 4-phase workflow:
graph LR
A[1. Analysis] --> B[2. Create Plan]
B --> C[3. User Approves]
C --> D[4. Execute]
D --> E[5. Document]
Phase 1: Analysis (Readonly)
- AI reads relevant files and context
- Asks clarifying questions if needed
- No file modifications yet
Phase 2: Present Plan
- Shows what will be created/modified
- Explains reasoning and approach
- Previews structure and content
- Waits for your approval
Phase 3: Execute
- Creates or modifies files as planned
- Follows approved approach exactly
- Maintains quality standards
Phase 4: Document
- Updates tracking files
- Records decisions made
- Sets up for next phase
Traditional approach (old):
/brief checkout-flow Quick checkout for guests
→ Boom! feature-brief.md created immediately
→ Hope it's what you wanted...With PLAN Mode (new):
/brief checkout-flow Quick checkout for guests
AI: "Let me analyze this..."
→ Checks existing patterns
→ Identifies missing info
→ Asks: "Should guests be able to save cart for later?"
AI: "Here's my plan:"
→ Will create: specs/active/checkout-flow/feature-brief.md
→ Structure: Problem, Users, Requirements, Approach, Next Actions
→ Research: Will examine existing checkout patterns (15 min)
→ Key requirements: Guest checkout, cart persistence, session handling
You: "Looks good, but also add abandoned cart recovery"
AI: "Updated plan, creating now..."
→ Creates feature-brief.md with your additions
→ Full visibility, full controlFor Solo Developers:
- 🔍 Catch issues before implementation
- 📚 Learn from AI's reasoning process
- 🎯 Ensure requirements are understood correctly
- ⚡ Modify approach before wasting time
For Teams:
- 👥 Review plans collaboratively before approval
- 📋 Shared understanding of what will be created
- 🛡️ Risk reduction through oversight
- 📝 Clear audit trail of decisions
For Project Managers:
- 👁️ Visibility into planning approach
- ✅ Approval gate before work begins
- 📊 Better estimation through plan review
- 🎯 Alignment with business goals
| Command | What Plan Shows | Why It Matters |
|---|---|---|
/brief |
Brief structure, research scope, requirements outline | Ensures 30-min planning is focused on right things |
/evolve |
Before/after changes, changelog entry, impact | Prevents accidental overwrites of important context |
/research |
Search strategy, areas to examine, time allocation | Focuses research on most valuable patterns |
/specify |
Spec structure, requirements preview, user stories | Catches missing requirements early |
/plan |
Architecture approach, tech decisions, design rationale | Validates technical direction before deep planning |
/tasks |
Task breakdown strategy, effort estimates, dependencies | Ensures comprehensive coverage of all work |
/implement |
Todo-list preview, execution order, file changes | Shows implementation roadmap before coding |
/upgrade |
Brief expansion strategy, new documents, content mapping | Prevents information loss during escalation |
You can modify any plan before approval:
AI: "Plan: I'll create 5 user stories focusing on happy path..."
You: "Add error scenarios and edge cases too"
AI: "Updated plan with error handling user stories..."
→ Proceeds with enhanced plan- Review plans thoroughly - This is your chance to course-correct
- Ask questions - If plan is unclear, ask for clarification
- Request changes - Don't approve if something seems off
- Learn from plans - Understand AI reasoning for better collaboration
- Use iteratively - Plans get better as AI learns your preferences
- Quick Start Guide - Get started with PLAN mode in 5 minutes
- Detailed Examples - Real scenarios and walkthroughs for each command
- Implementation Summary - Technical details of the integration
Plan entire applications and systems from A to Z with comprehensive roadmaps!
Use /sdd-full-plan (or /pecut-all-in-one) to create complete project roadmaps with:
# Create full project roadmap
/sdd-full-plan blog-platform Full-featured blog with CMS and analytics
# Or use the memorable alias
/pecut-all-in-one ecommerce-platform Multi-vendor marketplace📊 Kanban Board Structure:
- To Do, In Progress, Review, Done columns
- Epic-level organization
- Task hierarchy (Epic → Task → Subtask)
- Dependency management
🎯 Smart Complexity Detection:
- Simple (< 3 weeks): 3-5 tasks, Brief approach
- Medium (3-8 weeks): 8-12 tasks, Mixed SDD
- Complex (8-20 weeks): 15-20 tasks, Full SDD 2.0
- Enterprise (20+ weeks): 20+ tasks, Multi-phase
🔗 SDD Integration:
- Each task maps to appropriate SDD command
- Tasks link to
specs/active/for implementation - Progress tracked in roadmap and specs
- Execute tasks with
/execute-task
🎨 VSCode Extension Ready:
- Compatible with Taskr Kanban
- JSON format ready for custom extensions
- Visual kanban board in markdown
/sdd-full-plan blog-platform Full-featured blog with CMS, user management, comments, and analyticsAI Creates:
specs/todo-roadmap/blog-platform/
├── roadmap.json # Kanban board data
├── roadmap.md # Human-readable view
├── tasks/
│ ├── epic-001.json # Research & Foundation
│ ├── epic-002.json # Core Blog Features
│ ├── task-002-1.json # User Authentication
│ └── ...
└── execution-log.md # Execution tracking
Roadmap Includes:
- 📋 5 Epics (Research, Core, Engagement, Admin, Deployment)
- 🎯 20 Tasks organized by phase
- ⏱️ 240 hour estimate
- 📊 6-week timeline
- 🔗 SDD command mappings
# Execute first epic
/execute-task epic-001
# AI automatically:
# 1. Determines it's a research phase
# 2. Runs: /research epic-001 [description]
# 3. Creates: specs/active/epic-001/research.md
# 4. Updates: roadmap.json status
# 5. Logs: execution-log.md
# Continue with next task
/execute-task task-001-1## 📅 Kanban Board
### 🔵 To Do (15)
- Epic 1: Research & Foundation
- Task 1-1: Research CMS patterns (8h)
- Task 1-2: Define architecture (16h)
- Task 1-3: Create specification (16h)
- Epic 2: Core Blog Features
- Task 2-1: User authentication (24h)
- Task 2-2: Post creation (32h)
### 🟡 In Progress (3)
- Task 1-1: Research CMS patterns
### 🟣 Review (2)
- Task 0-1: Initial setup
### 🟢 Done (0)✅ Complete Project View - See entire project at a glance
✅ Structured Planning - Epic → Task → Subtask hierarchy
✅ Dependency Management - Automatic blocking and unblocking
✅ Progress Tracking - Visual kanban board
✅ SDD Integration - Each task uses appropriate SDD command
✅ Team Coordination - Assignee tracking and status updates
✅ VSCode Ready - Extension-compatible JSON format
Use /sdd-full-plan when:
- 🏗️ Planning entire application or system
- 📊 Need visual roadmap with kanban board
- 👥 Managing multi-developer team
- 🎯 Want structured task hierarchy
- ⏱️ Timeline > 3 weeks
- 🔄 Require dependency tracking
Use /brief when:
- ⚡ Quick feature addition
- 👤 Single developer
- 📝 Timeline < 3 weeks
- 🎨 Well-understood scope
- Full Plan Command Docs - Complete documentation
- Roadmap Format Spec - JSON schema and structure
- Full Plan Examples - Detailed examples at all complexity levels
Clone this repository to transform your development workflow:
git clone https://github.com/madebyaris/spec-kit-command-cursor.git
cd spec-kit-command-cursor🎉 Zero configuration required! The .cursor/commands/*.md files contain the SDD command definitions, and .cursor/rules/*.mdc provides minimal system context. Cursor automatically recognizes these commands when you open the project.
💡 Pro Tip: SDD 2.0 works best with existing projects or when you have a PRD/requirements document to guide research.
Transform any feature idea using the proven SDD workflow:
# 🚀 Default: 30-minute planning then start coding (80% of features)
/brief user-auth-system JWT authentication with login/logout functionality
# Start coding immediately after 30-minute brief!
# 🔄 Update specs as you discover things during development
/evolve user-auth-system Added password strength validation based on security review
# 🏗️ For complex features: Use full SDD 2.0 workflow (20% of features)
/research payment-system → /specify → /plan → /tasks → /implement🎊 That's it! 30 minutes of planning → start building immediately!
| Command | Purpose | Time | Output |
|---|---|---|---|
🚀 /brief |
Idea → 30min Plan | 30 min | Feature brief ready for coding |
🔄 /evolve |
Update during development | 2-5 min | Living documentation updates |
| Command | Purpose | Time | Output |
|---|---|---|---|
🗺️ /sdd-full-plan |
Complete A-Z Roadmap | 15-60 min | Full project kanban board |
🎯 /pecut-all-in-one |
Alias for sdd-full-plan | 15-60 min | Complete roadmap |
⚡ /execute-task |
Run roadmap task | Variable | Execute with SDD commands |
| Command | Purpose | Time | Output |
|---|---|---|---|
🔍 /research |
Investigate → Context | 60 min | Patterns & findings |
🎯 /specify |
Ideas → Requirements | 90 min | Detailed specification |
🏗️ /plan |
Requirements → Technical design | 120 min | Implementation plan |
📋 /tasks |
Design → Actionable tasks | 60 min | Development roadmap |
⚡ /implement |
Plan → Code | Variable | Todo-list & execution |
| Command | Purpose | When | Output |
|---|---|---|---|
⬆️ /upgrade |
Brief → Full SDD | Complexity discovered | Complete planning suite |
"Good artists copy, great artists steal (and improve)"
Purpose: Investigate existing codebase patterns and gather comprehensive context before specification.
Usage:
/research <task-id> <research-topic>Examples:
# Existing project: Research internal patterns
/research user-auth-system JWT authentication with existing patterns
# PRD-based: Research external solutions
/research payment-system Stripe vs PayPal integration patterns for subscription SaaS🚀 What it creates:
- 📄
specs/active/user-auth-system/feature-brief.md(single document) - 🎯 Problem statement & success metrics
- 🔍 Quick pattern research & technology decisions
- 📝 Essential requirements & user stories
- 🏗️ Implementation approach & next actions
- ⏱️ Ready to code in 30 minutes!
"Keep specs aligned with reality as you code"
Purpose: Update feature briefs continuously during development to maintain alignment between specs and implementation.
Usage:
/evolve <task-id> <change-or-discovery>Example:
/evolve user-auth-system Added password strength validation after security review🔄 What it creates:
- 📝 Updates existing
feature-brief.mdwith new information - 📋 Adds changelog entries with reasoning
- 🎯 Maintains spec-implementation alignment
- ⚡ Takes 2-5 minutes during development
For features requiring comprehensive planning (multiple teams, architectural changes, high risk):
"Seamlessly scale up when complexity emerges"
Purpose: Convert lightweight brief to comprehensive SDD 2.0 planning when complexity is discovered.
Usage:
/upgrade <task-id> <reason-for-upgrade>Example:
/upgrade checkout-flow Discovered PCI compliance and multi-payment provider needs⬆️ What it creates:
- 🏗️ Expands brief into full SDD 2.0 suite
- 📄 research.md, spec.md, plan.md, tasks.md
- 🔄 Preserves all existing decisions
- 📈 Scales planning when needed
"Comprehensive specifications for complex features"
Purpose: Transform vague feature ideas into detailed, testable requirements.
Usage:
/specify <feature-name> <description>Example:
/specify user-auth-system Implement JWT-based authentication system with login/logout✨ What it creates:
- 📄
specs/active/user-auth-system/spec.md - 📝 Comprehensive requirements document
- 👤 User stories with acceptance criteria
- 📊 Success metrics and edge cases
- ✅ Quality assurance checklist
"Architecture is the foundation of great software"
Purpose: Convert specifications into detailed technical implementation strategy.
Usage:
/plan <feature-name>Prerequisites: 📋 Must have existing spec.md file
Example:
/plan user-auth-system🚀 What it creates:
- 🏗️
plan.mdwith system architecture - ⚙️ Technology stack recommendations
- 🗄️ Database schema and API contracts
- 🔒 Security and performance considerations
- 🔗 Integration points and dependencies
"A journey of a thousand miles begins with a single step"
Purpose: Break down technical plans into actionable development tasks.
Usage:
/tasks <feature-name>Prerequisites: 🏗️ Must have existing plan.md file
Example:
/tasks user-auth-system📋 What it creates:
- ✅
tasks.mdwith prioritized task breakdown - 🔄 Implementation phases and dependencies
- ⏱️ Effort estimates and success criteria
- 📈 Progress tracking template
- 🎯 Definition of done for each task
"The best plan is worthless without execution"
Purpose: Execute the planned implementation with maximum efficiency and continuous flow.
Usage:
/implement <task-id>Prerequisites: 🏗️ Must have existing plan.md file
Example:
/implement user-auth-system⚡ What it creates:
- ✅
todo-list.mdwith comprehensive execution plan - 🔄 Continuous implementation flow
- 📈 Progress tracking and updates
- 🎯 Pattern reuse strategy
- 💻 Implementation artifacts and code
your-project/
├── .sdd/ # SDD system configuration
│ ├── config.json # Settings and preferences
│ ├── guidelines.md # Development process guide
│ ├── templates/ # Document templates
│ │ ├── spec-template.md
│ │ ├── plan-template.md
│ │ └── tasks-template.md
│ └── utils.js # Helper utilities (optional)
├── specs/ # All feature specifications
│ ├── 00-overview.md # Project overview
│ ├── index.md # Feature status dashboard
│ ├── active/ # Features in development
│ │ ├── feat-001-user-auth/
│ │ │ ├── spec.md # Requirements
│ │ │ ├── plan.md # Technical plan
│ │ │ ├── tasks.md # Implementation tasks
│ │ │ └── progress.md # Development tracking
│ │ └── feat-002-photo-gallery/
│ ├── completed/ # Delivered features
│ └── backlog/ # Future features
├── src/ # Your actual code
├── .cursor/ # Cursor configuration
│ ├── commands/ # Command definitions
│ │ ├── specify.md # /specify command
│ │ ├── plan.md # /plan command
│ │ └── tasks.md # /tasks command
│ └── rules/ # Minimal system rules
│ └── sdd-system.mdc # SDD overview (token-efficient)
└── README.md # This file
Edit templates in .sdd/templates/ to match your project needs:
# Example customization in spec-template.md
## Project-Specific Section
- **Team Lead**: {{TEAM_LEAD}}
- **Sprint**: {{CURRENT_SPRINT}}
- **Epic**: {{EPIC_REFERENCE}}Modify .sdd/config.json for your workflow:
{
"settings": {
"defaultFeaturePrefix": "feat-",
"autoNumberFeatures": true,
"requireReviews": true,
"collaborationMode": true
},
"workflow": {
"phases": ["specify", "plan", "tasks", "implement", "review", "complete"]
}
}See SDD in action! From idea to implementation in minutes.
🎬 Scenario 1: Adding Feature to Existing App
"I want to add a user rating system to my existing e-commerce app"
/specify user-ratings Allow users to rate items on 1-5 scale with optional comments and display average ratings✨ Result: Creates comprehensive specification
📁 specs/active/feat-003-user-ratings/
└── 📄 spec.md # Complete requirements with user stories & acceptance criteria
/plan user-ratings🚀 Result: Creates detailed implementation strategy
📁 specs/active/feat-003-user-ratings/
├── 📄 spec.md
└── 🏗️ plan.md # Architecture, tech stack, database schema, APIs
/tasks user-ratings📋 Result: Creates actionable development roadmap
📁 specs/active/feat-003-user-ratings/
├── 📄 spec.md
├── 🏗️ plan.md
└── ✅ tasks.md # Prioritized tasks with dependencies & estimates
Follow the tasks in priority order, updating progress.md as you go:
## 📈 Current Status: In Progress
- [x] Database schema design ✅
- [x] API endpoints ✅
- [x] Frontend rating component ✅
- [ ] 🔄 Integration testing (In Progress)
- [ ] ⏳ Performance optimization (Pending)🎉 Result: Feature delivered on time, on spec, with no surprises!
📋 Scenario 2: PRD-Based Development
"We have a PRD for a real-time chat system for our SaaS platform"
/research chat-system WebSocket vs Socket.io vs Pusher for real-time messaging in SaaS✨ Result: Creates comprehensive research
📁 specs/active/chat-system/
└── 📄 research.md # Competitor analysis, technology comparison, best practices
/specify chat-system Real-time messaging with typing indicators and file sharing🚀 Result: Creates detailed specification
📁 specs/active/chat-system/
├── 📄 research.md
└── 📄 spec.md # Requirements informed by research findings
/plan chat-system📋 Result: Creates implementation strategy
📁 specs/active/chat-system/
├── 📄 research.md
├── 📄 spec.md
└── 🏗️ plan.md # Architecture using researched technologies
/tasks chat-system/implement chat-system🎉 Result: Chat system built using researched best practices and proven patterns!
| Before SDD | After SDD |
|---|---|
| 😵 Unclear requirements | 🎯 Crystal clear specifications |
| 🤔 Guessing architecture | 🏗️ Well-planned technical design |
| 📝 Vague development tasks | ✅ Actionable roadmap with estimates |
| 🔄 Endless scope changes | 🎯 Focused delivery with minimal rework |
🎨 Think User-First
- Be specific about user needs & business value
- Include edge cases & error scenarios
- Define measurable success criteria
- Focus on "what" and "why", not "how"
✨ Pro Tip: Ask "What problem are we solving?" before writing code
🚀 Design for Success
- Justify technology choices based on requirements
- Consider scalability & future growth
- Address security & performance early
- Plan for testing & deployment from day one
✨ Pro Tip: Architecture decisions made now save hours later
⚡ Execute with Precision
- Keep tasks small (1-2 days max)
- Define clear dependencies between tasks
- Include testing tasks for each feature
- Estimate effort realistically
✨ Pro Tip: Small tasks = big wins and faster feedback loops
| Rule | Why It Matters | Impact |
|---|---|---|
| 📝 Spec before code | Prevents scope creep | 🚀 20% faster delivery |
| 🏗️ Plan before build | Reduces technical debt | 🔧 50% fewer refactors |
| ✅ Tasks before work | Improves team coordination | 🤝 Better collaboration |
- Assign ownership of specs, plans, and tasks
- Use progress.md for status updates
- Review and iterate on specifications
- Track dependencies between features
Update feature status in progress.md:
## Current Status: In Progress
- [x] Database schema design
- [x] API endpoints
- [ ] Frontend components (50% complete)
- [ ] Testing suiteUse reviews.md to track review feedback:
## Review Comments
- Security: Add input validation (Fixed ✅)
- Performance: Optimize database queries (In Progress)
- UI: Improve mobile responsiveness (Pending)"Feature not found" error:
- Check feature name spelling
- Ensure feature exists in
specs/active/
"Missing dependencies" error:
- Run commands in order:
/specify→/plan→/tasks - Check that required files exist
Template processing errors:
- Verify template files exist in
.sdd/templates/ - Check template syntax for variables
- Check guidelines: Read
.sdd/guidelines.md - Review examples: Look at existing features in
specs/active/ - Validate structure: Ensure directory structure matches expected format
Extend the system by adding new command files to .cursor/commands/:
# /review Command
Generate code review checklist based on specifications.
## Usage/review [feature-name]
## Purpose
Create comprehensive code review checklist based on feature specification and plan.
- Git hooks: Automatically update status on commits
- CI/CD: Validate implementations against specifications
- Project management: Sync with Jira, Linear, etc.
Track your SDD usage:
- Time savings from better planning
- Reduction in scope changes
- Quality improvements through structured approach
| Metric | Before SDD | After SDD | Improvement |
|---|---|---|---|
| ⏱️ Development Time | Baseline | Optimized | 🚀 20% Faster |
| 🔄 Scope Changes | Frequent | Minimal | 📉 80% Reduction |
| 🐛 Bugs in Production | High | Low | 🎯 60% Fewer |
| 🤝 Team Alignment | Poor | Excellent | ⭐ 95% Satisfaction |
🎯 For Developers:
- ✅ Clear roadmap reduces decision fatigue
- 🧠 Less time spent guessing requirements
- 🚀 Faster implementation with better focus
- 💪 Higher confidence in deliverables
👥 For Teams:
- 🤝 Improved communication & collaboration
- 📊 Better project visibility for stakeholders
- 🎯 Reduced rework and technical debt
- 🏆 Higher quality deliverables
Average 40-hour feature development:
| Phase | Time Saved | Value |
|---|---|---|
| 📋 Planning | 8 hours | $800 |
| 💻 Development | 6 hours | $600 |
| 🔄 Rework | 12 hours | $1200 |
| 🎉 Total Savings | 26 hours | $2600 |
git clone https://github.com/madebyaris/spec-kit-command-cursor.git |
Star this repo if SDD helps you! |
Help make SDD even better! |
# 🚀 Start with lightweight 30-minute brief (most features)
/brief hello-world Create a simple hello world feature to test the SDD workflow
# 🏗️ For complex features, use full SDD 2.0 workflow
/research payment-system → /specify → /plan → /tasks → /implementWe ❤️ contributions! Here's how you can help:
- 🐛 Report bugs - Found an issue? Open an issue
- 💡 Suggest features - Have ideas? Start a discussion
- 🔧 Submit PRs - Code improvements welcome!
- 📖 Improve docs - Help others learn SDD
- ⭐ Star this repo - Show your support!
- ✅ Issue #1: Token usage optimized (65-89% reduction)
- ✅ SDD 2.5: Lightweight 30-minute planning approach
- ✅ Living documentation with
/evolvecommand
MIT License - see LICENSE file for details.
- Inspired by GitHub's Spec-Kit
- Built for the amazing Cursor IDE community
- Special thanks to all contributors and early adopters!
Made with ❤️ by Aris