Requirements that live with your code.
reqmd is a lightweight command-line tool for writing, validating, and tracing requirement specs in plain Markdown. No database, no server, no lock-in. Just text files and a check that runs in 200 ms.
## SYS-001 Temperature warning
attr:
status: approved
trace:
- STK-003~2
verify: test
priority: high
The system shall display a warning when
cabin temperature exceeds 40°C for more
than 5 seconds of continuous operation.
Rationale: Driver distraction from
sudden thermal events is a safety concern.reqmd reads a tree of Markdown files — each requirement is a heading,
a YAML attr block, and some prose — and checks every cross-reference,
every status, every version pin. It produces HTML, CSV, and graph exports,
loads verification results from CI or manual reviews, and closes the loop
from spec to code.
You write requirements the way you already write documentation: in a text editor, in Git, in a pull request. reqmd adds the trace checks that a human reviewer would do — but mechanically, on every commit, in 200 ms.
The tool is a single Go binary with no runtime dependencies. The data is plain text. The trace graph is ephemeral. There is nothing to install beyond the binary, nothing to migrate, nothing to lose.
From a blank directory to a traced V-model.
Scaffold
reqmd init creates a directory structure with a schema, preset templates, and a first requirement. Pick the results preset, or start from scratch.
Trace
Write requirements at each V-model level. Link them with trace:. reqmd checks every link: broken refs, cycles, missing coverage, stale version pins — all on every commit.
Verify
Load test results from CI (CTRF JSON) or manual reviews (Markdown). reqmd runs missing-verdict and failing-verdict checks, and renders verdict badges on every measure in the HTML export.
Export & review
Export to HTML with bidirectional trace links, CSV for spreadsheets, or a graph database for Cypher queries. Run reqmd serve for a live-reloading preview while you edit.
Where teams use it.
From spec-first development to CI-gated traceability to live review.
Spec-first development
Write the requirement, then the test, then the code. Traceability is enforced by the parser, not remembered by humans. The same pull request carries the spec change, the trace update, and the implementation — reviewed in one diff.
Trace your spec →Live stakeholder review
Run reqmd serve while editing. The browser refreshes on every save, with trace links resolved and verdict badges color-coded. Reviewers read the spec as a website — with search, filters, and a light/dark toggle. No server framework, no SPA build.
Traceability in CI
Drop reqmd check into GitHub Actions or GitLab CI. Exit code 0/1/2 maps to pass/fail/parse-error. JSON output is shaped for parsing. Per-check suppression and a baseline diff for comparing two tagged releases. Five lines of YAML, done.
From code to spec
The companion reqmd-import tool walks Go and Python source with tree-sitter and writes per-package .md requirements into your spec tree. Every function and type gets an ID in the same namespace as your spec — the same reqmd check that catches broken upstream refs also catches broken implementation refs.
requirements validated in ~200 ms on a 12-core laptop. The parser is parallel, the graph is ephemeral, the cache is in-memory. Linear scaling holds to 720k requirements.
See the benchmarks →Five minutes from go install to a validated spec.
Start with a single document. Scale to a full V-model. Drop it into CI.