<!-- REQ-0036: project README is the canonical landing page. -->
# 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:
```sh
req brief # what's the spec? what's queued? what's loose?
req next # what should I work on?
req add ... # record a new requirement (before you implement)
req conform # is everything well-formed?
```
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
```sh
cargo install req-cli
cd your-project
req setup # one-shot: init + git hooks + AGENTS.md
req add -t "..." -s "The system shall ..." -r "..." -k functional -p must
```
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 `--reason` on every change.
- **Integrity hash** so silent corruption shows up immediately, not three weeks later.
- **Code traceability** via `// REQ-NNNN` markers and `req 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](#functional-safety-optional)).
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](https://github.com/Barks944/cli_req/releases/latest), extract, and put `req` (or `req.exe`) on your `PATH`.
**From crates.io** (Rust toolchain required):
```sh
cargo install req-cli
```
**From source**:
```sh
git clone https://github.com/Barks944/cli_req
cd cli_req
cargo install --path .
```
### Version compatibility
After installing, check the version against any existing project file:
```sh
req --version
```
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
```sh
# one-shot bootstrap: init + git hooks (pre + post commit) + AGENTS.md
req setup
# session-start brief — where is the project right now?
req brief
# add a requirement (non-interactive form, agent-friendly)
req add \
--title "Persist user sessions" \
--statement "The system shall persist sessions across restarts." \
--rationale "Users lose work on deploys today." \
--kind functional \
--priority should \
--accept "Session survives process restart" \
--tag auth
# see what you have
req list
req show REQ-0001
# change something — always with a reason
req update REQ-0001 --status approved --reason "Reviewed in 2026-05-17 sync"
# conform before you commit (the pre-commit hook does this for you)
req conform
```
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:
```rust
// REQ-0003: integrity hash verification
fn load(path: &Path) -> Result<Project> { ... }
```
Then:
```sh
req coverage --path src
```
shows you:
- **Orphans** — requirements at `Implemented` with 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
```sh
req link REQ-0026 REQ-0022 -k parent
req link REQ-0026 REQ-0022 -k depends-on
req link REQ-0030 REQ-0026 -k verifies
```
### 3. Retire, don't delete
```sh
req delete REQ-0007 --reason "Superseded by REQ-0042"
```
Soft delete by default — links and history are preserved. `--hard` is gated on having no inbound links.
### 4. Ship
```sh
cargo build --release # or whatever your project uses
req conform # must be 0 errors
req coverage --path src # no new ghosts
git diff project.req # human-readable, by design
```
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
```sh
req hooks install
```
installs:
- `.git/hooks/pre-commit` — runs `req conform` on staged `.req` files and rejects the commit on errors.
- `.gitattributes` line — `*.req merge=req-merge` so merges run `req renumber --base %O` and auto-fix ID collisions. The command prints the two `git config` lines needed to activate the driver in your clone.
If you ever merge by hand and IDs collide:
```sh
req renumber --base origin/main
```
If someone hand-edits the file and breaks the integrity hash:
```sh
req repair --confirm-direct-edit
```
---
## Provenance & audit
`req` does not invent its own signature scheme. Authenticity comes from **signed git commits**:
```sh
git config commit.gpgsign true
req audit # walks git log on project.req, prints signer + signature status
req audit --json -n 500 # for tooling / compliance review
```
`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:
```sh
req help agents --install
```
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.req` directly.
- Every mutation goes through `req <subcommand>` with a `--reason`.
- Use `// REQ-NNNN` markers in source; `req coverage` ties 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](.github/workflows/ci.yml) is the reference setup.
```yaml
# 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:
```yaml
- 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:
```jsonc
{
"_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`.
```sh
req safety accept-disclaimer --name "Your Name <you@example.com>" # human signs on; commit the file
req hazard add --title "Blade restarts during cleaning" \
--harm "an operator's hand could be severed" --context "guard removed"
req hazard assess HAZ-0001 -C C_D -F F_B -P P_B -W W2 # derives the required SIL
req sf add --title "Guard interlock halts blade" --mitigates HAZ-0001
req sreq add --title "Interlock cuts power <=200ms" \
--statement "The interlock shall cut blade power within 200 ms of guard opening." \
--rationale "Bounds exposure to a moving blade." --realizes SF-0001
req trace HAZ-0001 # whole hazard -> SF -> SR -> evidence
```
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:
- **`req` is 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. `req` provides 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.
- **`req` tracks 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 `req` to keep the results reviewable, versioned, and linked to code.
The software is provided "as is" without warranty of any kind (see [LICENSE](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](LICENSE).