Specdown

A Markdown-first executable specification system. One document is the spec, the test, and the report.

This page is itself a spec — it was executed by specdown run to produce the report you are reading. Separate docs and tests always drift apart: properties stated in documents go unverified, and tests confirm behavior but never explain design intent. specdown weaves natural language, executable acceptance tests, and optional Alloy models into one Markdown file — prose explains intent, executable blocks confirm implementation, and formal models guarantee structural properties.

Inspired by Ward Cunningham's FIT and Donald Knuth's Literate Programming.

See It Work

A passing block renders with a green left border:

$ echo "specifications as code"

specifications as code

run:shell

A block marked !fail expects failure — it renders red but does not break the build:

$ echo actual

actual

expected (expected)

run:shell

Green border = pass. Red border = failure. That's the whole idea: write prose, embed executable examples, get a verified report. See the source Markdown that produced this page.

Chapters

Fundamentals

Overview — install and first spec
Spec Syntax — shell blocks, doctest blocks, variables, check tables, hooks
Configuration — specdown.json format and defaults
CLI — commands, flags, and filtering

Adapters and Models

Adapter Protocol — NDJSON process protocol for any language
Alloy Models — embedding and verifying formal models

Correctness

Validation Rules — parse-time error checking
Traceability — document traceability with typed edges

Reporting and Internals

HTML Report — multi-page report structure and failure diagnostics
Internals — architecture and core/adapter boundary
Best Practices — patterns, pitfalls, and when to use Alloy