Agents drift from the spec. RQML fails the build.
Your agent drafts the spec. rqml link pins each requirement to the code
and tests that realize it. When they drift apart, rqml check fails the
build — and, with the plugins, the agent's turn. No language model in the
verdict path.
Built for codebases where an agent writes much of the code — and someone still has to know what the system is supposed to do.
AGENTS.md:npx @rqml/cli init
Six weeks later, the agent quietly rewrote auth. rqml check noticed.
Spec-driven tools like Spec Kit and Kiro get you a spec. RQML makes it binding:
~/myproject ❯ rqml show REQ-AUTH-001## REQ-AUTH-001 — Verify session tokenskind: req (FR) · status: approved · priority: must The API MUST reject any request whose session token fails signatureverification, with status 401. # the agent implements it, then records the link~/myproject ❯ rqml link REQ-AUTH-001 src/auth.ts#verifyToken✓ REQ-AUTH-001 ← src/auth.ts#verifyToken (E-IMPL-AUTH-001, implements, baseline recorded) ~/myproject ❯ rqml check✓ check pass (standard) — requirements.rqml # six weeks later, an agent refactors auth without touching the spec…~/myproject ❯ rqml check error (drift) [changed-implementation]: implements edge "E-IMPL-AUTH-001" points at "src/auth.ts#verifyToken", which has changed since approval.✗ check fail (standard) — requirements.rqml # exit 2
No AI checks the AI — a checksum does. Drift means pinned code changed and
nobody re-reviewed the link; the gate forces a look. rqml check is a
pure function of your repository — same input, same verdict, on your laptop and in
CI. The model proposes; the toolchain disposes.
Start in three steps
A useful spec fits on one screen; a serious one scales to thousands of requirements with goals, scenarios, state machines, and a typed traceability graph.
Scaffold —
npx @rqml/cli initdrops arequirements.rqmland anAGENTS.mdin your project rootCheck —
npx @rqml/cli checkvalidates the schema, checks that every requirement is linked to code and tests, and catches implementation driftDevelop with your coding agent of choice — it works from the spec, records trace links with
rqml link, and you gate CI withrqml check
Tip: rqml skeleton keeps the structure valid while your agent
drafts, and the Claude Code and Codex plugins run the whole
loop for you.
A complete, valid spec
<rqml xmlns="https://rqml.org/schema/2.2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://rqml.org/schema/2.2.0
https://rqml.org/schema/rqml-2.2.0.xsd"
version="2.2.0" docId="DOC-HELLO-001" status="draft">
<meta>
<title>Hello World CLI</title>
<system>hello</system>
</meta>
<requirements>
<req id="REQ-HELLO-001" type="FR" title="Print greeting"
status="draft" priority="must">
<statement>
The program MUST print "Hello, world!" to standard output
and exit with status code 0.
</statement>
</req>
</requirements>
</rqml>
The header boilerplate is scaffolded by rqml init and maintained by
your agent — what you review is the statement.
Drop it into your coding agent
The Claude Code and Codex plugins run the whole loop for you:
every session opens anchored on your spec, every edit is validated in the same
turn, and the turn is gated on rqml check — the same verdict your
CI runs.
Claude Code plugin
Anchor, validate, and gate Claude in every session. Six /rqml:* commands
for the Spec → Design → Plan → Code → Verify workflow, plus the bundled MCP tools and an
RQML authoring skill.
npm install -g @rqml/cli
# then, inside Claude Code:
/plugin marketplace add rqml-org/rqml-claude
/plugin install rqml@rqml
Codex plugin
The same loop for OpenAI Codex: session anchoring, in-turn spec validation, and a
stop-time rqml check gate.
npm install -g @rqml/cli
# then, inside Codex:
codex plugin marketplace add rqml-org/rqml-codex
# enable the RQML entry, then trust its hooks
On a different host? The RQML Agent Skill brings the same workflow to any skill-compatible agent, and the VS Code extension adds in-editor authoring and export. Plugins enforce; these assist.
One engine, every surface
One open-source engine — Apache‑2.0, published on npm, no telemetry — powers the CLI, an MCP server, and the agent plugins.
The loop an agent runs — read one requirement, check the blast radius, implement, record the link, pass the gate:
rqml show REQ-PAY-001 # one requirement: statement, acceptance criteria, trace neighborhood
rqml impact REQ-PAY-001 # what is affected, transitively, if this changes?
rqml link REQ-PAY-001 src/payments/capture.ts # implements edge + content-hash baseline
rqml check # validation + coverage + drift; exit 0 or it isn't done
Under the hood it's three npm packages — explore the tooling →
@rqml/cli—init,validate,status, and thecheckgate, plus the agent loop:show,impact,link,skeleton.@rqml/core— the engine: parse, validate, lint, trace, impact, coverage, drift. Embed it in your own tools.@rqml/mcp— thirteen Model Context Protocol tools backed by the same engine, for any MCP-capable agent.
It eats its own dog food.
The RQML repository is specified in RQML — requirements.rqml in the
repo root. Every shipped feature was specified before it was built and is traced
to the code that implements it. The repo gates its own CI
with rqml check. Read the self-spec →
Yes, it's XML — deliberately. Requirements are documents, not data records, and XML is boring in useful ways: schemas, mixed content, deterministic validation. Why XML →
Need requirement-to-test traceability you can show an auditor? The trace graph is plain XML in your repo — the VS Code extension renders it as a traceability map and exports documents.
What RQML is not
- Not a code generator. It never writes your code — your agent does that. RQML is what keeps the agent honest.
- Not AI-powered. No model runs in the verdict path. Verdicts are reproducible functions of your repo.
- Not a platform. Plain files in your repo and a small npm package — no server, no dashboard, no account.
- Not ceremony.
metaplus one requirement is a valid spec. Everything else is optional and added when it earns its keep.