guide4 passed0 failed1 expected14 Mar 2026 10:37

Overview

specdown is a Markdown-first executable specification system. A single Markdown document serves as both a readable specification and an executable test.

Install

go install

go install github.com/corca-ai/specdown/cmd/specdown@latest

Homebrew

brew install corca-ai/tap/specdown

Getting Started

Create a project

specdown init

This creates a configuration fileexplains and example specs in the current directory. Run this from the project root so that specdown.json sits next to .git/.

Scaffold a fresh project and verify files exist
rm -rf .tmp-test/init-overview && mkdir -p .tmp-test/init-overview && cd .tmp-test/init-overview && specdown init >/dev/null 2>&1

run:shell

$ test -f .tmp-test/init-overview/specdown.json && echo yes
yes
$ test -f .tmp-test/init-overview/specs/index.spec.md && echo yes
yes
$ test -f .tmp-test/init-overview/specs/example.spec.md && echo yes
yes

run:shell

What a spec looks like

This document is itself a spec — the blocks below are executed when you run specdown run, and their results appear in the HTML reportexplains. A green left border means the block passed:

$ echo hello
hello

run:shell

This block intentionally mismatches. It appears red and counts as a failure, but !fail prevents it from causing a non-zero exit code:

$ echo hello
hello
goodbye (expected)

run:shell

Run specs

specdown run

Specs are parsed, executed via adaptersexplains, and results are rendered as an HTML reportexplains. See the CLI referenceexplains for all flags. Use -dry-run to validate syntax without executing.

$ cd .tmp-test/init-overview && specdown run -dry-run 2>&1 | grep 'spec(s)'
... (1 line)total: 2 spec(s), 0 case(s)

run:shell

Install Claude Code skill

specdown install skills

This installs the /specdown skill with syntax reference, adapter protocol, and best practices.

Why

When documents and test code are separated, properties stated in documents may not be verified, and tests verify behavior but do not explain design intent.

specdown solves this by making a single Markdown document serve as prose, executable tests, and optional formal modelsexplains. Alloy models let you prove that a property holds for every case within a bounded scope — not just the examples you happened to test. Combined in one document, prose explains intent, executable blocks confirm implementation, and Alloy models guarantee structural properties.

The next chapter, Spec Syntaxexplains, covers the full authoring surface: executable blocks, variables, check tables, and hooks.