Quickstart

In the next 10 minutes you can go from a fresh reqmd install to a fully traced V-model spec tree, validated, verified, and exported.

The steps are ordered from easy, everyday use to more specific topics. Steps 2–9 and 11–12 all build on the same example: a car’s boot sequence spec traced through the V-model — stakeholder need → system requirement → software component → tests → verification results.

reqmd in one glance#

Five commands cover the everyday loop:

reqmd init my-project/            # scaffold a new spec tree
reqmd check my-project/           # validate every requirement + trace link
reqmd ls my-project/              # list all requirements
reqmd stats my-project/           # attribute-value breakdown per document
reqmd export html my-project/ -o out/   # share as a browsable HTML report

Command details, flags, and reference tables live in the cheat sheet — the quickstart links to it instead of repeating it.

The steps#

Suggested paths#

New users: 00 → 01 → 02 → 03 → 04 → 05 → 11 → 12

CI/automation focus: 00 → 01 → 02 → 06 → 09 → 11

Status & lifecycle focus: 00 → 01 → 02 → 05 → 07 → 11 → 12

Product-line / variant focus: 00 → 01 → 02 → 03 → 09 → 14

Prerequisites#

Build the reqmd binary:

go build -o reqmd ./cmd/reqmd

Or download a pre-built binary from the GitHub Releases page (Linux, macOS, Windows).

Each step’s page shows the exact commands to run. Paths are relative to the project root. The full source for every step lives in the quickstart/ directory of the repo.

Beyond the spec itself: the companion reqmd-import tool extracts requirement IDs from C, C++, Go, Python, and Rust source via tree-sitter. After you’ve written the spec for a feature, run reqmd-import extract and the implementation gets IDs in the same namespace — closing the loop from spec to code.

• Step 0 — Installation

  Install reqmd in 30 seconds with go install, build from source, or download a prebuilt binary. Then verify the install against the bundled 249-requirement spec.

• Step 1 — Get started

  Scaffold a new requirements project and run your first validation.

• Step 2 — Trace your spec

  Build the four-level V-model boot-sequence example with trace links between levels.

• Step 3 — Export

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

• Step 4 — Live preview

  Serve a live-reloading HTML preview of the boot-sequence spec while you edit it.

• Step 5 — Status & disposition

  The status lifecycle and the disposition workflow for deferred and rejected requirements.

• Step 6 — CI integration

  Run reqmd in CI for validation gates and structured reports.

• Step 7 — Version pins

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

• Step 8 — Repin

  Bulk-update version-pin (~N) trace references to match the upstream's current version with reqmd repin --yes.

• Step 9 — Baseline diff

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

• Step 10 — Submodule-friendly configuration

  Keep independently maintained requirement documents portable with stable document-id references instead of hard-coded parent paths.

• Step 11 — Verification results (CTRF)

  Load automated test results in CTRF format and run outcome-gated checks against the boot-sequence spec.

• Step 12 — Review documentation

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

• Step 13 — Custom templates

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

• Step 14 — Variant management

  One spec tree, many configurations: tag requirements with a variant attribute and scope every reqmd command with --filter.