spec-driven-dev
Spec-Driven Development (SDD) agent for maintaining synchronized specifications, code, and documentation.Core principle: "1 Todo = 1 Commit = 1 Spec Update".Use this skill when:- Starting a new feature or task that needs specification- Implementing code based on existing specifications- Validating that code matches specifications- Updating CHANGELOG.md with changes- Managing PRD/specification documents- Ensuring traceability between requirements and implementationTriggers: "spec", "specification", "PRD", "requirements", "SDD", "spec-driven"
When & Why to Use This Skill
This Spec-Driven Development (SDD) agent automates the synchronization between product specifications, source code, and technical documentation. By enforcing the '1 Todo = 1 Commit = 1 Spec Update' principle, it ensures that PRDs, feature specs, and CHANGELOGs remain perfectly aligned with the implementation, providing full traceability and reducing technical debt in the software development lifecycle.
Use Cases
- Feature Bootstrapping: Automatically generating structured feature specifications and PRD entries from high-level requirements to establish a clear development roadmap.
- Atomic Implementation: Breaking down complex specifications into manageable, atomic tasks that ensure every code change is mapped to a specific requirement.
- Compliance & Validation: Auditing the codebase against existing specifications to identify discrepancies, ensuring the implementation never drifts from the intended design.
- Automated Documentation Maintenance: Keeping CHANGELOGs and project history updated in real-time as code is written, eliminating the manual overhead of documentation sync.
| name | spec-driven-dev |
|---|---|
| description | | |
| Core principle | "1 Todo = 1 Commit = 1 Spec Update". |
| Triggers | "spec", "specification", "PRD", "requirements", "SDD", "spec-driven" |
Spec-Driven Development (SDD)
Core Principle
1 Todo = 1 Commit = 1 Spec Update
Every task must:
- Have a corresponding specification entry
- Result in a focused commit
- Update relevant documentation
Workflow
Phase 1: Specification
Before writing code, create or update the specification:
docs/
PRD.md # Product Requirements Document
specs/
feature-x.md # Feature-specific specifications
CHANGELOG.md # All changes tracked here
Phase 2: Implementation
- Read the relevant spec from
docs/specs/ - Create focused todo items (1 todo = 1 atomic change)
- Implement following the spec exactly
- Validate implementation matches spec
Phase 3: Documentation Sync
After each implementation:
- Update CHANGELOG.md with the change
- Update spec if implementation revealed necessary changes
- Commit with message referencing the spec
File Structure
PRD.md Template
# Product Requirements Document
## Overview
[Brief description]
## Goals
- Goal 1
- Goal 2
## Features
### Feature A
- **Status**: [Planned | In Progress | Done]
- **Spec**: [Link to detailed spec]
- **Priority**: [High | Medium | Low]
## Non-Goals
[What this project will NOT do]
Feature Spec Template
See references/spec-template.md for the full template.
CHANGELOG.md Format
# Changelog
## [Unreleased]
### Added
- Feature description (spec: feature-x.md)
### Changed
- Change description
### Fixed
- Fix description
Commands
Create New Spec
When user says "create spec for X":
- Generate spec from template
- Save to
docs/specs/X.md - Add entry to PRD.md
- Create initial CHANGELOG entry
Implement from Spec
When user says "implement X" or "build X":
- Read
docs/specs/X.md - Break into atomic todos
- For each todo:
- Implement the change
- Validate against spec
- Update CHANGELOG.md
- Commit with spec reference
Validate Spec
When user says "validate spec" or "check spec compliance":
- Read current spec
- Analyze implemented code
- Report discrepancies
- Suggest spec or code updates
Validation Script
Use scripts/validate_spec.py to check:
- All features in PRD have specs
- All specs have implementation status
- CHANGELOG entries exist for completed features
- Code files reference their specs
Best Practices
- Atomic Changes: Each todo should be completable in one commit
- Spec First: Always update spec before major implementation changes
- Traceability: Every commit message should reference the relevant spec
- Living Documentation: Specs evolve with the code, not after
Context Preservation
To prevent information loss during Auto-Compact:
- All decisions documented in specs
- Rationale included in CHANGELOG
- Git history provides complete audit trail