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.

You write requirements the way you already write documentation: in a text editor, in Git, in a pull request. reqmd adds the trace checks that a human reviewer would do — but mechanically, on every commit.

Use cases#

Spec-first development

Write the requirement, then the test, then the code. Traceability is enforced by the parser, not remembered by humans. The same pull request carries the spec change, the trace update, and the implementation — reviewed in one diff.

Step 2 — Trace your spec →

Requirements with status and lifecycle

Every requirement is draft or approved, and carries a disposition: implemented, deferred, or rejected (with a mandatory reason). The schema enforces the lifecycle; the trace checks enforce that a draft requirement cannot satisfy an upstream coverage expectation.

Step 2a — Status & disposition →

Traceability in CI

Drop reqmd check into GitHub Actions or GitLab CI. Exit code 0/1/2 maps to pass/fail/parse-error. --json output is shaped for parsing. Per-check suppression and a baseline diff for comparing two tagged releases. Five lines of YAML, done.

Step 1a — CI integration →

Version pinning and impact tracking

A downstream requirement can pin the upstream version it was verified against (SYS-001~3). When the upstream version is bumped, the pin becomes stale and the downstream needs re-verification. This is the engineering work of tracking what a version bump actually breaks.

Step 2b — Version pins →

Verification result roll-up

Load test results from CI (CTRF JSON) or manual reviews (Markdown). The --results flag runs missing-verdict and failing-verdict checks — an approved measure with no result, or a latest result that is fail. HTML export shows color-coded verdict badges on every measure.

Step 5 — CTRF results →

Live stakeholder review

Run reqmd serve while editing. The browser refreshes on every save, with trace links resolved and verdict badges color-coded. Reviewers read the spec as a website — with search, filters, and a light/dark toggle. No server framework, no SPA build.

Step 3a — Live preview →

Submodule-based spec integration

Compose specs from multiple git submodules. Use document-id/ID qualified references and baseline diff to see what changed between tags. Merge specs across teams without losing provenance.

Step 3b — Baseline diff →

Source-code traceability

The companion reqmd-import tool walks Go and Python source with tree-sitter and writes per-package .md requirements into your spec tree. Every function and type gets an ID in the same namespace as your spec — the same reqmd check that catches broken upstream refs also catches broken implementation refs.

reqmd-import →

Custom schemas per document

Each document directory carries its own schema.yaml. Define required fields, enums, ID prefixes, and per-directory metadata. Use reqmd init presets or build your own. The data model adapts to any V-model workflow.

Step 4 — Custom templates →

AI-assisted spec authoring

An agent reads llms.txt, edits *.md in the same tool-call budget as code, runs reqmd check, parses the JSON verdict, and iterates. The check is 16 ms even on the bundled 249-req spec. Drop in a copy-pasteable AGENTS.md and you're done.

AI & agents →

What reqmd is good at#

These are the things reqmd does well, and that show up in every use case above:

Bidirectional trace verification. Every requirement ID across every document, every trace link, every requires-trace-from expectation, every ~N version pin is checked mechanically. Broken references, circular dependencies, missing coverage — all caught on every commit.

Status lifecycle and disposition. A requirement is either in progress (draft) or signed off (approved); either actively developed (disposition: implemented), or parked with a reason (deferred / rejected, both with mandatory reasons). The lifecycle is enforced by the schema and the trace checks.

Documented rationale. Every requirement can carry a Rationale: paragraph alongside the body. The HTML export shows it. Reviewers see the why, not just the what — the engineering work of being able to answer “why is this requirement here?” six months from now.

Version pinning. A downstream requirement can pin the upstream version it was verified against. When the upstream version is bumped, the pin becomes stale and the downstream needs re-verification. This is the engineering work of tracking what a version bump actually breaks.

CI-gated quality. Stable exit codes, JSON output, per-check suppression. Every pull request that touches a spec, the agent (or the human) runs reqmd check and gets a pass/fail answer. No manual review of trace quality is required because the check is mechanical.

Live HTML review. A traceable HTML export with bidirectional links, document chain, theme toggle, and search. Reviewers can read the spec as a website. The engineering work is making the spec legible to the people who didn’t write it.

What is out of scope for reqmd#

reqmd is a requirements authoring and traceability tool. It is not a project management tool, a risk management tool, or a process compliance framework. The following categories of work are explicitly out of scope — reqmd will not grow features for them:

Project management. Sprint planning, task assignment, effort estimation, milestone tracking, burndown charts. reqmd stores requirements, not tasks or schedules. Use a project tracker (Jira, Linear, GitHub Issues) for that.

Risk management. Risk registers, risk assessment matrices, risk mitigation tracking. reqmd can store a requirement that says “mitigate risk X” — but it does not model risk as a first-class object, does not compute risk priorities, and does not track mitigation status. Use a dedicated risk tool or a spreadsheet.

Process compliance and audit trails. Named approvers, sign-off records, electronic signatures, audit logs, regulatory submission packages. reqmd produces a validated artifact (the checked spec), not a compliance record. If your process requires named approvers and audit trails, use a tool designed for that.

Supplier monitoring and procurement. Supplier scorecards, purchase-order tracking, supplier qualification records. Not a spec problem.

Measurement and process improvement. KPI dashboards, process metrics, maturity assessments, CMMI levels. reqmd validates artifacts, not the organization that produced them.

Notification and review threading. Active notification registries, affected-party tracking, review-thread tools, comment management. The HTML export is a passive publication — it shows the spec, it does not manage a conversation about it. Use a code review tool or a wiki.

Configuration and build management. Version control of binaries, artifact repositories, build pipelines, release packaging. reqmd works with your VCS (it reads git tags for baseline diffs), but it is not a configuration management tool.

If your team does this work, reqmd can store the requirements that result from it — e.g. “REQ-001: the build pipeline shall produce a signed artifact.” But reqmd does not do the work. No tool should pretend to conjure organizational process from a text file.