| 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
- Copy the template:
assets/spec-template.md → specs/<spec-id>/spec.md
- Fill YAML frontmatter (all required fields)
- Write structured Markdown body
- Run validator:
python scripts/validate_specs.py
- Fix any consistency errors
Modifying an Existing Spec
- Edit the spec directly (no delta-docs)
- Update
updated date and increment version if needed
- Update relationship fields if structure changed
- Run validator to ensure consistency
- 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
- Kontext - Problem, motivation
- Ziele - Goals
- Nicht-Ziele - Explicit exclusions
- Glossar - Terms
- Anforderungen - Requirements (R1, R2...)
- Akzeptanzkriterien - Acceptance criteria
- Schnittstellen - APIs, events
- Datenmodell - Entities, states
- Constraints - Performance, security
- Risiken - Risks + mitigation
- 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
