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. Unless a step says otherwise, the commands assume you are in the repo’s quickstart/ directory — run cd quickstart from the repo root first. The full source for every step lives in the quickstart/ directory of the repo.

Beyond the spec itself: the companion reqmd-code tool extracts requirement IDs from C, C++, Go, Python, and Rust source via tree-sitter, and emits them as a reqmd-import/v1 exchange bundle; reqmd-import renders that bundle into your spec tree. After you’ve written the spec for a feature, run the two together and the implementation gets IDs in the same namespace — closing the loop from spec to code.

• Step 0 — Installation

  Install reqmd in 30 seconds from a prebuilt binary or a source build, then verify the install against the bundled 274-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.

• Step 15 — Custom importers

  Import requirements from DOORS, codeBeamer, or any CSV/API — and extract proxy requirements from source code — through one shared exchange format.