req
____ _____ ___
| _ \| ____/ _ \ spec-memory for
| |_) | _|| | | | vibecoded projects
| _ <| |__| |_| |
|_| \_\_____\__\_\
session 1 session 2 session N
\ | /
\ req add, update, verify
\ | /
▼ ▼ ▼
╔════════════════════════════════════╗
║ project.req ║
║ + ║ ← survives
║ // REQ-NNNN: src/* ║ between
╚════════════════════════════════════╝ conversations
▲ ▲ ▲
/ / /
req brief, req next, req verify
/ | \
session 1 session 2 session N
req keeps software-project requirements in a single git-tracked JSON file (project.req) and mediates every change through a CLI that enforces requirements best practice. The file diffs cleanly, history is append-only, and an integrity hash catches hand edits before they corrupt your spec.
It exists because conversational coding loses track of requirements. The agent and the user have a session, they build something, the conversation ends. Without something that survives the conversation, the next session starts blind. req is what survives: a tool both humans and agents reach for, with hooks that nudge at commit time and a session-start brief that says "where are we right now?"
The mental model: where spec-memory and verification-memory meet
req is your project's spec-memory — what the system is supposed to do, surviving between conversations. A test/verification tool (your test runner, an evidence-dossier harness, your CI evidence trail) is your project's verification-memory — what the system was observed to do, and when.
They are two different memories, and they meet at one join key: (commit_sha, req_id). A requirement (req_id) describes intent; a verification record pins that intent to a concrete state of the code (commit_sha) where it was checked. That join is why the hooks, the // REQ-NNNN: markers, and req verify --cites exist — each one is a thread tying a requirement to the commit where it was implemented or verified. req test record and req stale live on this same join: a record is fresh when its commit_sha still matches the code behind its req_id, and stale when the code moved on.
Once that clicks, the hooks stop feeling like friction and start reading as what keeps the two memories from drifting apart. If you only take one idea from this README, take the join key.
TL;DR for agents
If you're an LLM agent reading this in someone else's project, the short story:
The pre-commit hook will catch you if you write code without citing a // REQ-NNNN: marker. The post-commit hook prints what just landed and suggests the next status change. The full agent guide is req help agents — written for you, not at you.
TL;DR for humans
That's it. The hooks make sure agents (and other humans) keep the spec and the code in sync. req brief is your dashboard; req lint is your quality audit; req review --gate is your CI check.
Mission
Make software requirements a first-class, machine-checked artifact that lives next to the code it governs — readable in a diff, enforceable in CI, and equally usable by humans and LLM agents — so that a project's intent and its implementation can never quietly drift apart.
Why req?
Requirements rot when they live in wikis, drift when they live in code comments, and become unreviewable when they live in a database. They evaporate entirely when they only existed in a chat that's now archived. req puts them in your repo as JSON, but stops anyone — human or agent — from editing them in ways that break the rules you'd want a senior engineer to enforce:
- One obligation per requirement, with a normative modal verb (
shall/must/should/will). - Append-only history with a required
--reasonon every change. - Integrity hash so silent corruption shows up immediately, not three weeks later.
- Code traceability via
// REQ-NNNNmarkers andreq coverage. - Git-native: pre-commit / post-commit hooks, merge driver for ID collisions, signature-based audit trail.
- Agent-shaped: a session-start
req brief, an MCP server (req mcp), and an AGENTS.md template that explains the workflow in the agent's voice. - Optional IEC 61508 safety layer: hazards, safety functions, and safety requirements with a derived SIL — off until a human signs on (see Functional safety).
The conformance checker IS the product. The CLI is the only legitimate way to mutate the file.
Install
Prebuilt binaries — grab the archive for your platform from the latest release, extract, and put req (or req.exe) on your PATH.
From crates.io (Rust toolchain required):
From source:
Version compatibility
After installing, check the version against any existing project file:
If you're joining a project that already has a project.req, your installed
req must be at least the version that last wrote the file. Older binaries
refuse to read newer formats and tell you to upgrade rather than silently
mis-reading; the symptom is an unsupported _format error pointing you at
this section. Pre-commit hooks and Claude Code Stop hooks invoke req
conform, so a stale binary will fail every commit until upgraded.
Quick start
# one-shot bootstrap: init + git hooks (pre + post commit) + AGENTS.md
# session-start brief — where is the project right now?
# add a requirement (non-interactive form, agent-friendly)
# see what you have
# change something — always with a reason
# conform before you commit (the pre-commit hook does this for you)
For everything else: req help lists the section index, req help <section> drills in. The agent guide is req help agents.
The workflow
1. Reference requirements from code
Drop markers where you implement them:
// REQ-0003: integrity hash verification
Then:
shows you:
- Orphans — requirements at
Implementedwith no code reference. - Ghosts — markers in code that point at non-existent or obsolete requirements.
Spec and code stay in sync, or you find out fast.
2. Link for hierarchy and trace
3. Retire, don't delete
Soft delete by default — links and history are preserved. --hard is gated on having no inbound links.
4. Ship
If you changed behaviour that has a requirement, the diff of project.req and the diff of your source should tell the same story.
Git integration
installs:
.git/hooks/pre-commit— runsreq conformon staged.reqfiles and rejects the commit on errors..gitattributesline —*.req merge=req-mergeso merges runreq renumber --base %Oand auto-fix ID collisions. The command prints the twogit configlines needed to activate the driver in your clone.
If you ever merge by hand and IDs collide:
If someone hand-edits the file and breaks the integrity hash:
Provenance & audit
req does not invent its own signature scheme. Authenticity comes from signed git commits:
req help audit documents the signature-status codes (good / bad / expired / no-signature).
Working with agents
req was designed with LLM agents as first-class users. Drop this into your AGENTS.md (or equivalent) and your agents will know how to drive the tool:
That command writes a managed block, between sentinel markers, into AGENTS.md. Re-run any time to refresh; edit outside the markers freely. The block tells agents:
- Never read or write
project.reqdirectly. - Every mutation goes through
req <subcommand>with a--reason. - Use
// REQ-NNNNmarkers in source;req coverageties spec to code. - Don't argue with the conformance checker — rewrite.
Command surface
Project lifecycle
req init -n <name> [--layout directory] Create project.req (file or dir layout)
req setup [--strict] [--no-hooks] One-shot bootstrap: init + hooks + AGENTS.md
req tui Interactive menu (mirrors CLI surface)
req conform Run all rules; 0 errors to ship
req status [--tag ...] Per-status counts + delivery_progress_pct
req brief [--full] Session-start "where are we now?" summary
req purpose ["..."] --reason "..." Set/print the one-paragraph project purpose
req version Print binary version (--json for tooling)
req export -f markdown -o reqs.md Publish (markdown / json / csv / html)
req serve [--read-only] Local web UI (HTML + /api/* JSON)
req mcp JSON-RPC stdio server for agents
req mcp --init-config Write .mcp.json for MCP-capable clients
req schema [add|batch|import|test-map] JSON Schema for structured CLI inputs
Day-to-day
req add ... Add a requirement (also: --from-json)
req list [--status ...] [--tag ...] Filter (Obsolete hidden by default)
req show REQ-0007 Full detail + history + test records
req update REQ-0007 --status approved --reason "..."
[--add-acceptance "..." | --remove-acceptance N]
req link <from> <to> -k <kind> parent | depends-on | verifies | …
req delete REQ-0007 --reason "..." Soft by default; --hard if no inbound links
req next [--status ... --tag ...] Suggest one requirement to work on
req split REQ-0007 --into "..." --into "..." Break a compound req into atomic parts
req batch path/to/changes.json Transactional multi-mutation
req import -f markdown spec.md Bulk ingest through the conformance checker
req adopt --all-drafts --to verified Retroactive backfill of existing work
req lint [--path src] Quality audit beyond the conformance checker
Evidence & verification
req test record REQ-0007 --result pass --notes "..."
req test run [--from-file <log>] [--map <file>] [--promote]
Drive cargo test, attach records,
optionally flip Implemented -> Verified
req test list REQ-0007 Test-record history for one requirement
req verify REQ-0007 --by composition --cites REQ-0003 --notes "..." [--promote]
req verify REQ-0007 --by inspection --notes "reviewed src/..." [--promote]
req stale [--only-stale] Records vs HEAD; three-state staleness
Integration & review
req hooks install [--strict] [--claude-code]
Pre-commit (conform + marker gate) +
post-commit summary + merge driver
(+ .claude/settings.json allowlist)
req doctor Per-clone setup audit (gates 5 checks)
req precheck [--skip STEP] Run the CI gate suite locally
req renumber --base origin/main Post-merge ID collisions
req coverage [--path src] Orphans / ghosts / test-only / obsolete-in-code
req coverage --by-file Per-file -> REQ IDs
req coverage --by-req Per-REQ -> files
req coverage --unlinked-files Code files with zero markers
req coverage --remap REQ-OLD=REQ-NEW --apply
req coverage --strict --allow REQ-NNNN... CI gate; non-zero on findings
req review [--gate] [--staged] [--new] One-shot PR-style spec review report
req diff origin/main..HEAD Per-requirement changes between revs
req check origin/main Incremental conform + scoped coverage
req audit [--gate --require-good-signature --require-signer NAME]
Git signature trail / CI gate
req migrate Migrate project.req to the current _format
Functional safety (opt-in — see Functional safety section)
req safety accept-disclaimer --name "..." Human signs on; activates the safety surface
req safety status / calibrate Show state / edit the risk-graph SIL bands
req hazard add ... && req hazard assess HAZ-0001 -C ... -F ... -P ... -W ...
Log a hazard; derive its required SIL
req sf add ... --mitigates HAZ-0001 Safety function (inherits worst-hazard SIL)
req sreq add ... --realizes SF-0001 Safety requirement (inherits its SF's SIL)
req sreq verify SR-0001 --by automated [--promote] SIL-gated verification
req trace HAZ-0001 Whole hazard -> SF -> SR -> evidence case
Recovery
req repair --confirm-direct-edit After intentional hand edits
Docs
req help Section index
req help <section> overview | concepts | best-practice |
workflow | integration | version-control |
agents | mcp | audit | testing |
verification | format-policy | errors |
env | file-format | tui | web | export |
lint | safety
req help <section> --install Inject the section into AGENTS.md
req help <section> --json Structured form for tooling
req help all Everything
CI / build integration
Drop these three commands into your CI pipeline. The repo's own .github/workflows/ci.yml is the reference setup.
# Gating: any of these failing should fail the build.
- run: req conform
- run: |
req coverage --path . --strict \
--allow REQ-NNNN --allow REQ-MMMM # whitelist verification-only reqs
# Advisory: print but don't fail.
- run: req doctor || true
- run: req stale --path . || true
req conform checks every requirement against the rule set (0 errors required to ship).
req coverage --strict turns orphan / ghost / obsolete-in-code findings into a non-zero exit.
req doctor audits per-clone setup — useful as a warning when contributors skip req hooks install.
req stale is informational; staleness trips on every commit that touches a tested file, so blocking on it would block every PR.
For repos that require signed commits on the spec file, replace the req audit line with:
- run: req audit --gate --require-good-signature --require-signer "Alice <alice@example.com>"
File format
project.req is pretty-printed JSON with four reserved top-level fields:
{
"_warning": "DO NOT EDIT THIS FILE BY HAND. Managed by the `req` CLI.",
"_instructions": ["...directions for humans and agents..."],
"_format": "req-v3",
"_integrity": "sha256:<hex>",
"name": "...",
"requirements": { "REQ-0001": { ... }, ... }
}
The hash covers everything except those four reserved fields, in canonical form (sorted keys, no whitespace). Hand edits break the hash; the CLI refuses to load the file and points you at req repair --confirm-direct-edit.
The hash gives integrity ("the CLI wrote this last"). For authenticity ("a trusted human approved this"), use signed git commits and req audit.
Status
Single static binary, Rust, no runtime dependencies. req serve runs a local web view of the spec; req mcp exposes the same operations as MCP tools over JSON-RPC, and req mcp --init-config writes a .mcp.json so MCP-capable clients (Claude Code, etc.) can launch the server automatically.
Issues and contributions: https://github.com/Barks944/cli_req/issues
Functional safety (optional)
req has an opt-in mode for recording a functional-safety argument on the
IEC 61508 model. It is off by default and stays off until a human runs
req safety accept-disclaimer — an agent cannot (the command refuses REQ_ACTOR_KIND=agent,
and req safety is not on the MCP surface). Acceptance writes a committed
req-safety-acceptance.json beside project.req; its presence activates the
feature, deleting it switches the feature back off.
Four linked artifacts, each with its own ID space:
HAZ-NNNN Hazard a hazardous event, risk-assessed to a SIL
SF-NNNN Safety function the measure that reaches/keeps a safe state
SR-NNNN Safety requirement a normative `shall` realizing a function
REQ-NNNN Requirement ordinary requirements, unchanged
The defining rule: you never type a SIL — it is derived. A hazard's
risk-graph parameters (C/F/P/W) derive its required SIL; a safety function
inherits the worst of the hazards it mitigates; a safety requirement inherits
its function's SIL, which then governs how rigorously it must be verified — a
SIL 3/4 safety requirement cannot reach Verified on inspection alone. The
risk-graph table is the IEC 61508-5 Annex D worked example; the standard
requires you to calibrate it per project/sector via req safety calibrate.
The full guide is req help safety. Read the scope & disclaimer below before
using it for any safety-related work.
Functional safety — scope & disclaimer
req can manage hazards, safety functions, and safety requirements on the IEC 61508 model (req help safety). The features are off until a human signs on: req safety accept-disclaimer --name "..." writes a committed req-safety-acceptance.json whose presence activates them — an agent cannot accept on your behalf (req safety is not on the MCP surface and refuses REQ_ACTOR_KIND=agent). Read this before using it for safety-related work:
reqis NOT a qualified safety tool. Under IEC 61508-3 §7.4.4 (and ISO 26262-8), a tool whose output you rely on without independent verification needs a tool-confidence/qualification argument.reqprovides none. If you work to a functional-safety standard, qualifying it — or independently verifying every classification it computes — is your responsibility.- The SIL is a candidate. It is derived from the qualitative risk parameters you enter. The "derive, never type" design prevents casual fudging; it does not make the result objective or remove the need for competent review. The risk-graph table is the worked example from IEC 61508-5 Annex D — the standard requires a risk graph to be calibrated per project/sector, so confirm or recalibrate the SIL-band boundaries against your own scheme before relying on the result.
reqtracks the required integrity target, not achieved integrity. It does not model PFD/PFH, diagnostic coverage, safe-failure-fraction, systematic capability, hardware fault tolerance, or SIL decomposition/independence. A "complete" trace means the chain is linked and verified, not that the residual risk is acceptable.- It is a place to record and trace a safety analysis, not to perform one. Do your HARA/HAZOP, FMEA, FTA, and quantification with the proper methods and tools; use
reqto keep the results reviewable, versioned, and linked to code.
The software is provided "as is" without warranty of any kind (see LICENSE); nothing here constitutes safety assurance or fitness for any safety-related purpose. The safety determination remains the responsibility of a competent assessor.
License
MIT.