Quickstart on 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:

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)

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:

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:

Quickstart on 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#

Step 2a — Status & disposition

Status lifecycle#

Step 2b — Version pins

How version pins work#

Suppression#

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)#