In the next 10 minutes you can go from a fresh reqmd install to a fully traced V-model spec tree, validated and exported. Work through the steps in order — lettered steps are optional detours.
The seven steps#
| Step | Folder | What you’ll learn |
|---|---|---|
| 0 | Installation | go install, build from source, or prebuilt binary |
| 1 | Get started | Scaffold a new project and run your first validation |
| 1a | CI integration | JSON reports, exit codes, GitHub Actions |
| 2 | Trace your spec | Build a four-level V-model with trace links |
| 2a | Status & disposition | The draft/approved lifecycle and deferred/rejected workflow |
| 2b | Version pins | Pin traces to a specific upstream version; detect when stale |
| 2c | Repin | Bulk-update ~N version pins with reqmd repin --yes |
| 3 | Export | CSV, HTML, and graph export formats |
| 3a | Live preview | reqmd serve with live-reloading HTML |
| 3b | Baseline diff | Compare requirements between two git tags |
| 4 | Custom templates | Define your own schema with a custom reqmd init preset |
| 5 | Verification results (CTRF) | Load automated test results and run outcome-gated checks |
| 6 | Review documentation | Load manual review, inspection, and analysis results |
Suggested paths#
New users: 00 → 01 → 02 → 03 → 04 → 05 → 06
CI/automation focus: 00 → 01 → 01a → 02 → 03b → 05
Status & lifecycle focus: 00 → 01 → 02 → 02a → 02b → 05 → 06
Prerequisites#
Build the reqmd binary:
go build -o reqmd ./cmd/reqmdEach 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 Go and Python 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 1a — CI integration
Run reqmd in CI for validation gates and structured reports.
- Step 2 — Trace your spec
Build a multi-level V-model spec tree with trace links between levels.
- Step 2a — Status & disposition
The status lifecycle and the disposition workflow for deferred and rejected requirements.
- Step 2b — Version pins
Pin trace references to a specific upstream version and detect when the upstream changes.
- Step 2c — Repin
Bulk-update version-pin (~N) trace references to match the upstream's current version with reqmd repin --yes.
- Step 3 — Export
Export the spec tree to CSV, HTML, and graph formats.
- Step 3a — Live preview
Serve a live-reloading HTML preview while you edit your spec tree.
- Step 3b — Baseline diff
Compare requirement baselines between two git tags — no checkout needed.
- Step 4 — Custom templates
Define your own requirement schema with a custom reqmd init preset.
- Step 5 — Verification results (CTRF)
Load automated test results in CTRF format and run outcome-gated checks against your spec tree.
- Step 6 — Review documentation
Load manual verification results (review, inspection, analysis, demonstration) recorded as markdown with a user-supplied schema.