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"

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

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.
namespec-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:

  1. Have a corresponding specification entry
  2. Result in a focused commit
  3. 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

  1. Read the relevant spec from docs/specs/
  2. Create focused todo items (1 todo = 1 atomic change)
  3. Implement following the spec exactly
  4. Validate implementation matches spec

Phase 3: Documentation Sync

After each implementation:

  1. Update CHANGELOG.md with the change
  2. Update spec if implementation revealed necessary changes
  3. 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":

  1. Generate spec from template
  2. Save to docs/specs/X.md
  3. Add entry to PRD.md
  4. Create initial CHANGELOG entry

Implement from Spec

When user says "implement X" or "build X":

  1. Read docs/specs/X.md
  2. Break into atomic todos
  3. 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":

  1. Read current spec
  2. Analyze implemented code
  3. Report discrepancies
  4. 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

  1. Atomic Changes: Each todo should be completable in one commit
  2. Spec First: Always update spec before major implementation changes
  3. Traceability: Every commit message should reference the relevant spec
  4. 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