spec-driven-development

name

spec-driven-development

description

Specification-Driven Development (SDD) workflow for creating, modifying, and validating specs. Use when (1) creating new specs, (2) modifying existing specs, (3) checking spec consistency (parent/child, depends_on/used_by relationships), (4) answering questions about spec structure or format, (5) setting up a specs/ directory. Specs are the single source of truth - when code and spec diverge, the spec is correct.

Spec-Driven Development

Workflow

Creating a New Spec

1. Copy the template: assets/spec-template.md → specs/<spec-id>/spec.md
2. Fill YAML frontmatter (all required fields)
3. Write structured Markdown body
4. Run validator: python scripts/validate_specs.py
5. Fix any consistency errors

Modifying an Existing Spec

1. Edit the spec directly (no delta-docs)
2. Update updated date and increment version if needed
3. Update relationship fields if structure changed
4. Run validator to ensure consistency
5. Git tracks all changes

Quick Reference

Required YAML Fields

Field	Description
id	Unique identifier (kebab-case)
title	Human-readable title
status	draft / active / deprecated
owner	Responsible team/person
created	Creation date (YYYY-MM-DD)
updated	Last change date
version	SemVer-like (major on breaking change)
scope	core / feature / module

Relationship Fields

Field	Direction	Symmetric Partner
parents	up	children
children	down	parents
depends_on	needs	used_by
used_by	needed by	depends_on

Consistency rule: If A has children: [B], then B must have parents: [A].

Markdown Body Structure

1. Kontext - Problem, motivation
2. Ziele - Goals
3. Nicht-Ziele - Explicit exclusions
4. Glossar - Terms
5. Anforderungen - Requirements (R1, R2...)
6. Akzeptanzkriterien - Acceptance criteria
7. Schnittstellen - APIs, events
8. Datenmodell - Entities, states
9. Constraints - Performance, security
10. Risiken - Risks + mitigation
11. Offene Punkte - Open questions

Commands

Validate all specs:

python .agents/skills/spec-driven-development/scripts/validate_specs.py

Validate specific directory:

python .agents/skills/spec-driven-development/scripts/validate_specs.py --path ./specs

Detailed Reference

For complete guidelines including:

• Full YAML schema
• Index file structure
• Multi-spec projects
• Lifecycle details

See references/spec-guidelines.md