Instruction file imported from madebyaris/bantuaku (
.cursor/rules/sdd-system.mdc). Copyright stays with the author.
SDD (Spec-Driven Development) System Overview
This project implements a comprehensive Spec-Driven Development workflow using three core commands that work together to transform ideas into structured implementation plans.
Core Philosophy
Spec-Driven Development emphasizes creating detailed, executable specifications before writing code, ensuring:
- Requirements are clear before implementation
- Technical decisions are well-planned and documented
- Development tasks are structured and manageable
- Team collaboration is enhanced through shared understanding
PLAN Mode Integration
All SDD commands now follow a plan-approve-execute workflow inspired by Cursor's PLAN mode:
Workflow Pattern:
User Command → Analysis → Create Plan → User Approval → Execute → Document
Key Principles:
- Analysis First - Read, understand, ask questions before planning
- Present Plans - Show what will be created/modified before doing it
- User Control - Wait for approval before any file changes
- Transparency - Explain reasoning and approach in plans
- Thoughtful Execution - Deliberate, well-considered actions
Benefits:
- Visibility - See what will happen before it happens
- Control - Approve or modify plans before execution
- Quality - More thoughtful specifications and plans
- Safety - No surprise changes or modifications
- Learning - Understand AI reasoning and approach
Cursor 2.1 Enhancements
Interactive Question UI:
- Questions appear automatically in interactive interface
- Answer directly in UI for faster workflow
- Better UX and mobile-friendly
Plan Search (⌘+F):
- Search within generated plans
- Navigate large plans efficiently
- Find specific sections quickly
AI Code Reviews:
- Automatic code review after implementation
- Issues appear in sidepanel
- Fix bugs directly in editor
- Integrated into
/implementworkflow
Instant Grep:
- All codebase searches are instant
- Faster
/researchcommand - Multiple parallel searches possible
Background Planning:
- Create plans in background while working
- Useful for complex
/sdd-full-planprojects - Compare multiple plan options
Multi-Agents:
- Execute up to 8 tasks in parallel
- Independent tasks run simultaneously
- No file conflicts (isolated environments)
Team Commands:
- Define SDD commands in dashboard
- Share with entire team
- Centralized management
Voice Mode:
- Control SDD commands with voice
- Hands-free workflow
- Accessibility improvement
SDD 2.5: Agile-Compatible Lightweight Workflow (Default)
Primary Approach (80% of features)
/brief - 30-Minute Planning
Transform ideas into actionable development plans in 30 minutes
- Time: 30 minutes total planning before coding
- Output: Single feature-brief.md with essential context
- Philosophy: "Just enough" planning to start coding confidently
- Key Elements: Problem/users, quick research, requirements, next actions
/evolve - Living Documentation
Keep specifications aligned with reality during development
- Purpose: Continuous updates as discoveries are made during coding
- Output: Updates existing feature-brief.md with changelog
- Philosophy: Specifications as living documents that evolve with code
Advanced Approach (20% of complex features) - SDD 2.0
For complex, high-risk, or multi-team features requiring comprehensive planning:
Full Workflow: /research → /specify → /plan → /tasks → /implement
- Use When: Feature complexity high, multiple stakeholders, significant architectural impact
- Time Investment: 4-6 hours upfront planning
- Output: Complete documentation suite (research.md, spec.md, plan.md, tasks.md)
Decision Framework
Start with /brief unless feature meets ANY of these criteria:
- Multiple teams involved
- Architectural changes required
- High business risk/compliance needs
- Uncertain technical approach
- 3+ week development timeline
Upgrade from brief to full SDD if complexity discovered during implementation
Use /sdd-full-plan (or /pecut-all-in-one) when:
- Planning entire application or major system
- Need comprehensive roadmap with kanban structure
- Want structured task hierarchy (epic → task → subtask)
- Require VSCode extension integration
- Managing multi-phase projects
File Organization
The system uses a context-engineering approach with:
- Active tasks: specs/active/[task-id]/ - Tasks currently in development
- Task artifacts: research.md, spec.md, plan.md, tasks.md, todo-list.md, progress.md
- Roadmap registry: specs/todo-roadmap/ - Project roadmaps with kanban structure
- roadmap.json: VSCode extension compatible kanban board
- roadmap.md: Human-readable markdown view
- tasks/: Individual task JSON files
- execution-log.md: Task execution history
- Templates: .sdd/templates/ - Reusable document templates
- Configuration: .sdd/config.json - System settings and preferences
- Guidelines: .sdd/guidelines.md - Development methodology guide
Task ID Convention
- Use semantic slugs:
user-auth-system,payment-integration,dashboard-redesign - Avoid generic numbering:
feat-001(legacy approach) - Focus on meaningful, searchable identifiers
Quality Assurance
Each phase includes comprehensive review checklists and validation rules to ensure:
- Specifications are clear and testable
- Plans are technically sound and scalable
- Tasks are actionable and properly estimated
- Documentation maintains consistency across the project
Implementation & Todo-List Execution
CRITICAL FOR AI ASSISTANTS:
Todo-lists are NOT suggestions - they are executable checklists that MUST be followed systematically.
Todo Execution Rules
- Read entire list before starting
- Execute in order - respect dependencies
- Mark completion:
- [ ]→- [x] - Document blockers - never skip silently
- Update progress continuously
For AI Models (Cursor, ChatGPT, Claude)
- Todo-list is your implementation roadmap
- Each unchecked item is a required task
- Check off items as you complete them
- Document any deviations with rationale
- Ask before skipping or changing approach
Reference: .sdd/IMPLEMENTATION_GUIDE.md
Full Project Planning (NEW)
/generate-rules Command
Automatically generate comprehensive coding rules based on technology stack detection and codebase analysis:
- Technology Detection: Auto-detects languages and frameworks from package files
- Codebase Analysis: Analyzes patterns and project complexity
- Rule Generation: Creates hierarchical rule files following 10X dev principles
- Best Practices: Includes language/framework-specific best practices
- Project-Specific: Extracts patterns from your codebase
Output: Rule files in .cursor/rules/ organized by language, framework, and category.
See: Generate Rules Guide for complete documentation.
/sdd-full-plan & /pecut-all-in-one Commands
Create comprehensive project roadmaps from A to Z with:
- Epic-level organization - Main phases and milestones
- Task hierarchy - Epics → Tasks → Subtasks
- Kanban board structure - To Do, In Progress, Review, Done columns
- Dependency management - Automatic blocking and unblocking
- SDD command integration - Each task maps to appropriate SDD command
- VSCode extension ready - Compatible with Taskr Kanban and custom extensions
Command Usage
# Create full project roadmap
/sdd-full-plan [project-id] [description]
/pecut-all-in-one [project-id] [description]
# Execute specific task from roadmap
/execute-task [task-id]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 approach
Output Structure
specs/todo-roadmap/[project-id]/
├── roadmap.json # Kanban data
├── roadmap.md # Human-readable view
├── tasks/ # Task details
└── execution-log.md # Execution tracking
Integration with Existing SDD
- Roadmaps link to
specs/active/for implementation - Tasks execute via existing SDD commands (
/brief,/implement, etc.) - Progress tracked in both roadmap and individual specs
- Bidirectional linking maintained
See: .sdd/ROADMAP_FORMAT_SPEC.md for complete specification
Collaboration Support
The system supports multi-developer workflows with:
- Assignee tracking for features and tasks
- Progress monitoring through status updates
- Kanban board management with roadmaps
- Review workflows with feedback integration
- Audit trails for change management