specdown

Executable specifications in Markdown. One document is both a readable spec and a runnable test suite.

Quick Start

specdown init        # scaffold a new project
specdown run         # execute specs and generate reports

Install

Binary (recommended)

curl -sSfL https://raw.githubusercontent.com/corca-ai/specdown/main/install.sh | sh

Installs to /usr/local/bin, or ~/.local/bin if /usr/local/bin is not writable. Ensure the install directory is on your PATH.

Or download directly from Releases.

go install

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

Homebrew

brew install corca-ai/tap/specdown

From source

go build -o bin/specdown ./cmd/specdown

Verify installation

specdown version

Documentation

• Overview — install, first spec, and why specdown exists
• Self-Spec — the executable reference
• Live Report — self-spec execution results
• Best Practices — patterns, pitfalls, and anti-patterns
• Build & Run — building from source
• Agent Guide — project layout, working rules, and conventions

Example

See examples/pocket-board/ for a working project that uses shell blocks and Alloy models without any custom adapters.

License

MIT