reqmd

Step 0 — Installation

Mon, 01 Jan 0001 00:00:00 +0000

Three ways to get reqmd on your machine. Pick one.

Option 1 — `go install` (fastest)#

If you already have Go on your $PATH:

go install github.com/dVoo/reqmd/cmd/reqmd@latest

The binary lands in $(go env GOBIN) (or $(go env GOPATH)/bin).

Step 1 — Get started

Mon, 01 Jan 0001 00:00:00 +0000

Scaffold a new requirements project and run your first validation.

Scaffold#

reqmd init my-project/

This creates:

my-project/
 schema.yaml # JSON Schema with x-reqmd config
 requirements.md # example file with two sample requirements

Validate#

reqmd check my-project/

You should see both sample requirements pass validation:

Step 1a — CI integration

Mon, 01 Jan 0001 00:00:00 +0000

Run reqmd in CI for validation gates and structured reports.

JSON validation report#

reqmd check --json 02-trace-your-spec/

Produces a structured JSON report with per-requirement pass/fail and trace check results:

{
 "version": 1,
 "exit_code": 0,
 "summary": {
 "total": 5,
 "valid": 5,
 "invalid": 0,
 "parse_errors": 0,
 "warnings": 1
 },
 "documents": [...],
 "parse_errors": []
}

The exit_code field mirrors the process exit code: 0 (all valid), 1 (validation errors), 2 (parse error).

Step 2 — Trace your spec

Mon, 01 Jan 0001 00:00:00 +0000

Build a multi-level spec tree with trace links between levels.

This is the heart of reqmd: a four-level V-model with bidirectional traceability, validated by the parser.

02-trace-your-spec/
 stakeholder/ # Stakeholder needs (top of V)
 schema.yaml
 goals.md # STK-GOAL-001: Fast Boot
 system/ # System requirements
 schema.yaml # upstream: ../stakeholder/
 features.md # SYS-001 traces to STK-GOAL-001
 software/ # Software requirements
 schema.yaml # upstream: ../system/
 components.md # SW-001 traces to SYS-001
 tests/ # Test specifications (bottom of V)
 schema.yaml # upstream: ../software/
 boot-test.md # TEST-001/002 trace to SW-001 and SYS-001

How trace links work#

Each requirement has a trace attribute listing its upstream IDs. reqmd validates that every trace target exists:

Use cases

Mon, 01 Jan 0001 00:00:00 +0000

reqmd is a tool for teams who need to write, link, and verify requirements. This page walks through the real workflows where reqmd adds value, then clearly states what is out of scope.

What reqmd does#

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.

Cheat sheet

Mon, 01 Jan 0001 00:00:00 +0000

A quick reference for every reqmd command and every schema.yaml option. Each command shows real output from the bundled spec/ tree. Bookmark this page.

Command overview#

`reqmd check` — validate requirements and trace links#

The main command. Recursively finds all schema.yaml files under the given directory and validates every .md file with requirement attr blocks.

reqmd check spec/ # validate everything under spec/
reqmd check spec/ --json # JSON output for CI parsing
reqmd check spec/ --results ci-out/ # load verification results
reqmd check spec/ --results ci-out/ --results reviews/
reqmd check file.md -s schema.yaml # single-file mode
reqmd check spec/ --relaxed-versions # demote version-pin errors to warnings

Exit codes: 0 = all valid, 1 = validation errors, 2 = parse error.

Step 2a — Status & disposition

Mon, 01 Jan 0001 00:00:00 +0000

Two built-in attributes control how requirements behave in trace coverage and how deferred work is tracked.

Status lifecycle#

Every requirement has a status — either draft or approved (default when omitted). Only approved requirements count as upstream coverage providers.

## REQ-001: System boot
```attr
status: approved
trace: [STK-001]


A `draft` requirement can be referenced by a `trace` but does **not** satisfy a `requires-trace-from:` expectation. This lets you stage work-in-progress without breaking coverage checks.

Try it: in [Step 2](/quickstart/02-trace-your-spec/), the `SYS-001` requirement shows:

⚠ SYS-001 no upstream trace: no approved requirement from “software” traces to this item (1 draft downstreams ignored)

Benchmarks

Mon, 01 Jan 0001 00:00:00 +0000

reqmd is fast enough to run on every commit, every save, and every pull request — without anyone noticing the wait. This page shows the real numbers and explains what drives them.

The headline#

The tool’s own spec — 249 requirements across 6 document directories — validates in 16 milliseconds. That’s faster than a page load. For context, a typical project spec is in the hundreds, not the thousands.

Step 2b — Version pins

Mon, 01 Jan 0001 00:00:00 +0000

Pin trace references to a specific upstream version and detect when the upstream changes.

How version pins work#

A downstream requirement can pin the upstream version it was last verified against using the ~N suffix:

## UP-001
```attr
status: approved
version: 3


```markdown
## DN-001
```attr
status: approved
trace: [UP-001~2] # verified against UP-001 v2, but UP-001 is now v3


When the upstream `version` is bumped, the pin becomes stale and reqmd flags the downstream as needing re-verification.

## Findings

| Condition | Meaning | Level | Demote with |
|-----------|---------|-------|-------------|
| `pin < upstream.version` | Outdated — upstream bumped, downstream needs re-verify | **ERROR** | `--relaxed-versions` |
| `pin > upstream.version` | Predated — downstream claims a non-existent version | **ERROR** | (never — data integrity) |
| `pin == upstream.version` | Current | — | — |
| No pin | No version check applies | — | — |

## Try it

The spec tree in [Step 2](/quickstart/02-trace-your-spec/) doesn't use version pins, so no version-pin findings fire. To see it in action, add `version: 1` to an upstream requirement and `~1` to a downstream trace, then bump the upstream to `version: 2`:

```sh
reqmd check 02-trace-your-spec/
# ❌ DN-001 version-pin: outdated — UP-001 is at version 2, pinned to ~1

# Demote to WARNING (CI-friendly: fails on predated, warns on outdated)
reqmd check --relaxed-versions 02-trace-your-spec/
# ⚠ DN-001 version-pin: outdated — UP-001 is at version 2, pinned to ~1

Suppression#

Suppress the check per-requirement:

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Questions about reqmd, grouped by topic: what it is, how to use it, and how it fits your workflow.

What is reqmd?#

What does reqmd do?

reqmd is a command-line tool for writing, linking, and checking requirements and verification measures in plain Markdown. You write each requirement as a heading, a small YAML block, and some prose. reqmd checks every cross-reference — broken links, missing coverage, circular dependencies, stale version pins — and tells you what's wrong. It also exports to HTML, CSV, and graph formats.

Step 2c — Repin

Mon, 01 Jan 0001 00:00:00 +0000

Bulk-update version-pin (~N) trace references to match the upstream’s current version. The reqmd repin command proposes or applies the changes for you.

When to use#

After bumping a spec version (Version pins) you’ll see a wave of version-pin: outdated findings. repin rewrites the affected trace: lines in place so the pins catch up to the upstream — without you having to hand-edit every requirement.

Dry-run by default#

# See what would change — no files are written
reqmd repin 02-trace-your-spec/
# /path/to/dn.md DN-001 UP-001 → UP-001~3
# /path/to/dn.md DN-002 UP-002 → UP-002~7
# 2 outdated, 0 unpinned, 0 predated across 1 files.

The default mode is dry-run. The output is one line per affected requirement (file REQ-ID bare-ref → ref~newPin) plus a one-line summary. Nothing is written to disk.

Step 3 — Export

Mon, 01 Jan 0001 00:00:00 +0000

Export the spec tree from Step 2 to CSV, HTML, and graph formats.

CSV export#

reqmd export csv 02-trace-your-spec/ -o csv-out/

Produces one CSV per document directory (stakeholder-requirements.csv, system-requirements.csv, etc.) with columns: ID, Title, all schema attributes, Body, Rationale.

Step 3a — Live preview

Mon, 01 Jan 0001 00:00:00 +0000

Serve a live-reloading HTML preview while you edit your spec tree.

Start the server#

reqmd serve 02-trace-your-spec/

This opens a browser at http://localhost:8080 showing the HTML export with live reload. Every time you save a .md or schema.yaml file, the browser auto-refreshes via SSE (Server-Sent Events).

Step 3b — Baseline diff

Mon, 01 Jan 0001 00:00:00 +0000

Compare requirement baselines between two git tags — no checkout needed.

How it works#

reqmd baseline diff <tag1> <tag2> extracts the repository at each tag via git archive | tar, parses both versions through the standard pipeline, and produces a semantic diff:

Requirements: added (+), removed (-), modified (~) with attribute-level detail
Schemas: new/removed properties, changed required fields
Submodules: added/removed/updated submodule pins

The command always exits 0 — the diff is informational, not validation.

Step 4 — Custom templates

Mon, 01 Jan 0001 00:00:00 +0000

Define your own requirement schema with a custom reqmd init preset.

What’s in this folder#

04-custom-templates/
 preset/ # the custom preset directory
 schema.yaml.tmpl # Go template for schema.yaml
 example.md.tmpl # Go template for the example .md file

This preset defines a custom requirements template with:

Step 5 — Verification results (CTRF)

Mon, 01 Jan 0001 00:00:00 +0000

Load automated test results in CTRF format and run outcome-gated checks against your spec tree.

What’s in this folder#

05-verification-results-ctrf/
 boot-tests.ctrf.json # CTRF report: TEST-001 passed
 coverage.json # NOT a CTRF file; auto-skipped silently

How CTRF maps to requirements#

CTRF test entries map to measures (requirements with a verify attribute) via the x-reqmd.id extra field:

Step 6 — Review documentation

Mon, 01 Jan 0001 00:00:00 +0000

Load manual verification results (review, inspection, analysis, demonstration) recorded as markdown with a user-supplied schema.

What’s in this folder#

06-review-documentation/
 schema.yaml # schema for manual results
 design-review-results.md # VR-001: design review for TEST-002 (pass)

Manual results format#

Manual results are markdown files with attr blocks, just like requirements — but the schema declares result-specific attributes:

reqmd

Step 0 — Installation

Option 1 — go install (fastest)#

Step 1 — Get started

Scaffold#

Validate#

Step 1a — CI integration

JSON validation report#

Step 2 — Trace your spec

How trace links work#

Use cases

What reqmd does#

Cheat sheet

Command overview#

reqmd check — validate requirements and trace links#

Step 2a — Status & disposition

Status lifecycle#

Benchmarks

The headline#

Step 2b — Version pins

How version pins work#

Suppression#

FAQ

What is reqmd?#

Step 2c — Repin

When to use#

Dry-run by default#

Step 3 — Export

CSV export#

Step 3a — Live preview

Start the server#

Step 3b — Baseline diff

How it works#

Step 4 — Custom templates

What’s in this folder#

Step 5 — Verification results (CTRF)

What’s in this folder#

How CTRF maps to requirements#

Step 6 — Review documentation

What’s in this folder#

Manual results format#

Option 1 — `go install` (fastest)#

`reqmd check` — validate requirements and trace links#