Specdown
A Markdown-first executable specification system. One document is the spec, the test, and the report.
New to specdown? Read the chapters below in order — each builds on the previous one.
Fundamentals
How to write and run specs.
- Overview — install, first spec, and why specdown exists
- Spec Syntax — executable blocks, variables, check tables, hooks
- Configuration —
specdown.jsonformat and defaults - CLI — commands, flags, and filtering
Adapters and Models
Connecting specs to code and formal properties.
- Adapter Protocol — NDJSON process protocol for any language
- Alloy Models — embedding and verifying formal models
Correctness
Ensuring specs and documents are well-formed.
- Validation Rules — parse-time error checking
- Traceability — document traceability with typed edges
Reporting and Internals
What specdown produces and how it works.
- HTML Report — multi-page report structure and failure diagnostics
- Internals — architecture and core/adapter boundary
- Best Practices — patterns, pitfalls, and when to use Alloy