FAQ

reqmd is designed for Git-based review. The spec lives in a Git repository (either next to the code or in a dedicated repo). Every change to a requirement, a trace link, a schema, or a verification result is a commit. Here's the typical workflow:

1. Author. Open a branch. Edit the .md files — add a requirement, update a trace link, change a status. Commit and push.
2. Check locally. Run reqmd check spec/ before pushing. If it exits non-zero, fix the issues.
3. Open a pull request. The diff shows exactly what changed: the requirement text, the trace link, the schema. Reviewers see the same diff they'd see for a code change.
4. CI runs the check. A GitHub Action (or GitLab CI job) runs reqmd check --json spec/ on the PR. If it fails, the PR is blocked. The JSON output can be posted as a comment or an annotation.
5. Review. Reviewers read the diff, check the trace links, run reqmd serve spec/ for a live preview if they want to see the rendered spec with links resolved.
6. Merge. Once the check passes and the review is approved, merge. The spec is now consistent — no broken links, no missing coverage, no stale version pins.

The key advantage over a database-backed RM tool: the review happens in the same pull request interface the team already uses for code. The diff is the review artifact. The check is the gate. No separate tool, no separate login, no separate review state to track.

reqmd builds a trace graph from every trace: link in every requirement, then checks it in one pass:

• Broken references — a trace: pointing to an ID that doesn't exist anywhere.
• Missing coverage — a requirement with requires-trace-from that no downstream requirement traces to.
• Circular dependencies — a chain of traces that loops back to itself.
• Version pin staleness — a downstream pinned to SYS-001~3 but the upstream is now version 5.
• Missing verdicts — an approved measure with no verification result.
• Failing verdicts — the latest result for a measure is fail.

Broken references, cycles, and failing verdicts are errors (exit code 1). Missing coverage and missing verdicts are warnings (exit code 0, but shown in the output).

Every requirement has a status: draft (work in progress) or approved (signed off). Only approved requirements count as coverage providers — a draft requirement can be referenced by a trace but does not satisfy a requires-trace-from expectation.

Requirements can also carry a disposition: implemented (actively developed), deferred (parked, with a reason), or rejected (not doing it, with a reason). When a document directory sets mandatory-disposition: true, every requirement must have a disposition.

Two formats, both loaded with the --results flag (repeatable):

• CTRF JSON — from automated test runs. The x-reqmd.id field in each test maps it to a requirement ID. reqmd reads the pass/fail/skipped verdict and the timestamp.
• Manual results (Markdown) — for reviews, inspections, analyses. Each result is a Markdown file with an attr block carrying outcome, verifier, verified-at, and a trace back to the measure it verifies.

reqmd synthesizes one pseudo-requirement per result and runs two new checks: missing-verdict (approved measure, no result) and failing-verdict (latest result is fail). The HTML export shows color-coded verdict badges on every measure card.

There is no separate web UI; the HTML export is the web UI. Run reqmd serve spec/ for a live-reloading preview, or reqmd export html spec/ -o docs/ and host the resulting docs/ directory as a static site.

The HTML export includes card-based layout, upstream/downstream trace links, a document chain tab strip for V-model navigation, status filters, theme toggle, and (with --results) color-coded verdict badges on measure cards.

Yes, for everything except baseline diff. The spec tree is plain files; no Git required to validate, list, or export. baseline diff is the one command that calls git archive to read a tagged snapshot — every other command operates on whatever directory you point it at.

Configuration management — the discipline of controlling, versioning, and composing a multi-team spec across component boundaries — is a core systems engineering practice. In reqmd, it's built on Git submodules. Each team owns their own requirements repo as a git submodule, and a top-level repo assembles them into a single tree that reqmd check validates as a whole.

A typical layout:

spec-monorepo/
  stakeholder/        ← submodule: git@github.com:team/stakeholder-spec.git
  system/             ← submodule: git@github.com:team/system-spec.git
  software/           ← submodule: git@github.com:team/software-spec.git
  tests/              ← submodule: git@github.com:team/test-spec.git

Each submodule is a normal reqmd document directory with its own schema.yaml. The top-level repo just holds the submodule references — no spec content of its own. When a team updates their spec, they push to their repo and the top-level repo bumps the submodule pin.

Cross-repo trace links work out of the box. A requirement in system/ can trace to a requirement in stakeholder/ by ID — reqmd resolves it across the submodule boundary because all submodules are on disk under the top-level directory. Use qualified references (document-id/ID) if two submodules share ID prefixes.

The baseline is the submodule pins. When you need to compare two baselines, reqmd baseline diff v1.0 v2.0 reads the submodule pins at each tag and reports what changed — added, removed, and modified requirements across all submodules, plus which submodule pins were updated. No separate configuration management tool needed; git is the tool.

Review workflow works the same as a single repo. A PR that bumps a submodule pin shows the exact diff of the submodule's spec changes. Reviewers see what changed, CI runs reqmd check on the assembled tree, and the merge updates the baseline.

Use the companion reqmd-import tool. It walks your Go or Python source code with a tree-sitter grammar and writes per-package .md requirements into your spec tree. Every function, type, and method gets a requirement ID in the same namespace as your spec.

The extracted code requirements are marked external: true and live in an imported/ sub-tree. They don't need upstream traces (they're not authored by hand), but they do trace to the real implementation. The result: the same reqmd check that catches a broken spec reference also catches a broken implementation reference — if a function is renamed or deleted, the trace from the spec to that function becomes a broken reference.

The full traceability chain becomes: stakeholder need → system requirement → software requirement → test specification → test result → code implementation. Every link is a plain-text reference that reqmd validates mechanically.

reqmd-import is a separate Go module with its own release cadence. It supports Go and Python today; Rust and Zig are reserved for future work.

Each document directory has a schema.yaml that defines the required attributes, their types, and reqmd-specific options. A minimal example:

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "my-requirements"
title: "My Requirements"
type: object
required:
  - priority
properties:
  priority:
    type: string
    enum: [Critical, High, Medium, Low]
additionalProperties: false
x-reqmd:
level: system-requirements
document-id: system
id-prefix: SYS-
upstream:
level: stakeholder-needs
sources:
- ../01-stakeholder/

See the cheat sheet for the full list of x-reqmd options and all commands.

No, the format is fixed to YAML. The schema.yaml filename and the YAML dialect are hard-coded. You can hand-author the file in JSON-compatible YAML and it will round-trip fine; extensions like x-reqmd work the same.

Why YAML? The data is small (a few hundred lines per directory at most), human-authored, and benefits from comments.

Not built in. The recommended path is reqmd init with a custom preset and a one-time script that produces the Markdown files. For ongoing imports, write a small script that walks the Excel/Word file and emits one Markdown file per requirement.

The reqmd-import source-code extraction tool is the closest existing project — it extracts requirement IDs from Go and Python source via tree-sitter.

No native integration. The common pattern is to put the issue-tracker key in a custom attribute (e.g. jira: PROJ-123) and search via reqmd ls --json or reqmd stats --json. The issue tracker is a downstream consumer of the spec, not a source.

reqmd check reports a cycle as an error (with the cycle path) and exits non-zero. There is no auto-resolution; cycles are a modeling problem to fix in the source.

Not supported yet. The data model is compatible; the importer is what's missing. A future reqmd-import reqif subcommand is the most likely path.

Yes, no database, no daemon, no state. Each check is self-contained. Pin the version in CI. The recommended CI invocation:

- run: go install github.com/dVoo/reqmd/cmd/reqmd@
- run: reqmd check --json requirements/ > report.json
- run: reqmd check requirements/ --results ci-artifacts/

Use --json for programmatic parsing, plain output for human review.

Yes. Based on the measured linear scaling (~50 req/ms on 12 cores), 50,000 requirements would take ~2.5 seconds for check. Even 720,000 requirements finish in under 10 seconds. The bottleneck is file I/O, not the graph. See the benchmarks page for the full numbers.

Three severity levels:

• ✅ — passes schema validation and all required trace checks.
• ⚠ — passes schema validation but has a warning (broken reference, untraced, missing verdict). Warnings do not affect the exit code.
• ❌ — fails schema validation or has an error (cycle, missing required attribute, failing verdict). Errors exit non-zero.

Only errors affect the exit code. Warnings are informational.

reqmd export graph writes a LadybugDB database for Cypher queries. It pulls in a Cgo dependency, so it's gated behind a build tag:

go build -tags ladybug -o reqmd ./cmd/reqmd

Without the tag, export graph is not built. The rest of the CLI works exactly the same.