guide3 passed0 failed

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 init-overview && mkdir -p init-overview && cd init-overview && specdown init >/dev/null 2>&1

run:shell

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

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 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.

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