Skip to main content

RQML Tooling

The schema and the Reference describe what a conforming RQML document is. This section covers the reference toolchain that reads, validates, and checks those documents in practice.

It is a small TypeScript suite, published to npm, built around one engine: everything else is a thin surface over it, so a verdict is identical no matter how you ask for it.

PackageWhat it isUse it from
@rqml/coreThe engine: parse, validate, lint, trace, impact, coverage, drift, link recordingYour own TS/JS code, editors, agents
@rqml/cli (rqml)The command-line interface, agent-loop commands, and CI gateA terminal, CI, save/commit hooks
@rqml/mcpA Model Context Protocol server exposing the engine as toolsCoding agents (Claude, etc.)

There is also @rqml/schema — the canonical XSDs and example documents that @rqml/core bundles, published to the stable /schema/rqml-2.1.0.xsd URL.

Design principles​

These properties hold across every tool, because they all run the same engine:

  • Deterministic. No language model sits in the verdict path. The same document and codebase always produce the same result — so the rqml check gate is reproducible and usable as audit evidence. Models are confined to authoring RQML, never to judging it.
  • Offline. The schema is bundled, so validation needs no network access — it runs on every editor save, agent turn, and CI job.
  • One engine, many surfaces. The CLI, the MCP server, the VS Code extension, and third-party integrations all call @rqml/core. There is one implementation of how RQML is parsed and checked, so the surfaces never disagree.
  • Node 18+. The toolchain targets modern Node; the engine avoids Node-only built-ins in its parse/lint/trace paths so it stays embeddable.

Quick taste​

# one-off check of a spec in the current directory
npx @rqml/cli check

# or wire the engine into your own tool
npm install @rqml/core

The agent loop​

Beyond validating and gating, the toolchain serves the middle of a spec-first task — choosing work, reading one artifact, and recording what was done — so an agent never hand-edits trace XML or loads the whole spec into context:

rqml show REQ-PAY-001          # one requirement: statement, acceptance, traces
rqml impact REQ-PAY-001        # what is affected if it changes?
# … implement …
rqml link REQ-PAY-001 src/payments/capture.ts   # record the implements edge + drift baseline
rqml check                     # the gate — validation + coverage + drift

The link step also records a content hash of the implementation in .rqml/baseline.json, so a later rqml check catches code that changed after it was linked — not just code that disappeared.

This loop is the Code and Verify half of the five-stage RQML development process; the earlier stages (Spec, Design → ADRs, Plan) produce the spec and the artifacts in .rqml/ that this loop draws on.

Head to @rqml/core for the library API, @rqml/cli for the command line, or @rqml/mcp to give a coding agent RQML tools.