# AGENTS.md — `req`
Hey. If you're an LLM agent picking up this project, read this once — it's
how the project stays coherent across the conversational sessions where you
and the user actually do the work.
This project is `req`, a CLI that gives agents (and humans) a way to keep
software requirements in sync with the code that implements them. The
requirements live in a git-tracked file (`project.req`) that's managed
through the CLI. Hooks remind you about them at commit time. A short
session-start command tells you where things stand. None of this gets in
your way — it's the spec-memory that survives between conversations so the
next session doesn't start blind.
This project also **dogfoods** its own tool: the requirements in
`project.req` describe the binary you're working on. Treat that file as the
source of truth for behaviour, and this document as the workflow guide.
Start with: `req brief` — it'll tell you where the project is right now.
---
## 1. Project shape
```
cli_req/
├── Cargo.toml
├── AGENTS.md ← this file
├── project.req ← managed requirements (dogfooded)
└── src/
├── main.rs dispatch only
├── cli.rs clap surface — one source of truth
├── model.rs Project / Requirement / Kind / Priority / Status / Link
├── storage.rs JSON I/O + SHA-256 integrity hash
├── validate.rs best-practice rules
├── help_text.rs `req help <section>` content
├── tui.rs dialoguer-based interactive browser
├── web.rs STUB — local web server
├── mcp.rs STUB — MCP JSON-RPC server
└── commands/ one file per subcommand
```
If you add a subcommand: add the `clap` variant in `src/cli.rs`, a module
under `src/commands/`, dispatch in `src/main.rs`, and **at least one** help
section in `src/help_text.rs`.
## 2. The handful of things that matter
The discipline is small. Treating it as muscle memory is what makes the
sessions stack up into real progress instead of drifting apart.
1. **Route mutations through the CLI, not the file.** `project.req`
is JSON — nothing at the OS level stops you from editing it, but
every read is checked against an integrity hash. Agents that
bypass the CLI don't break anything silently; the next `req`
call refuses to load and points at `req repair
--confirm-direct-edit`. The contract is honest: tamper and you'll
know. Use `req add` / `req update` / `req delete` / etc. — there's
a CLI verb for every mutation you'd want.
2. **The validator is the product.** Statements need a normative modal
verb (`shall` / `must` / `should` / `will`) and one obligation each.
If the validator rejects something, rewrite the requirement, don't
try to relax the rule.
3. **Mutations go through `commands::*`, not direct `Project` access.**
That's how history attribution and hash recomputation stay correct.
4. **History is append-only.** Use `commands::history(action, reason)`
when you mutate. Never edit or drop existing history entries.
5. **`req <subcommand>` is the agent surface — no fast-paths that skip
validation.** Whatever a human can do with the tool, an agent can do
too — through the same commands or via `req mcp`.
6. **New reserved top-level fields need a `_format` bump.** The reserved
keys are `_warning`, `_instructions`, `_format`, `_integrity`.
7. **New behaviour gets a REQ first, then the code, then a marker.**
If you're about to add a new command, a new validator rule, or a
non-trivial behaviour change: write the requirement first with
`req add`, implement, then drop a `// REQ-NNNN:` comment near the
code that lives the requirement. The pre-commit gate catches you
if you skip this; the post-commit summary tells you when you did
it right. (Pure bug fixes that don't change the contract don't
need a new REQ — the existing one is the right home.)
## 3. The integrity model (read this once, refer to it later)
`storage::save` writes pretty-printed JSON with four reserved fields:
```jsonc
{
"_warning": "DO NOT EDIT THIS FILE BY HAND. Managed by the `req` CLI.",
"_instructions": [ "...multi-line directions..." ],
"_format": "req-v1",
"_integrity": "sha256:<hex>",
"name": "...",
"requirements": { ... }
}
```
The hash covers everything *except* the four reserved fields, in canonical
form (sorted keys, no whitespace). Any direct edit breaks the hash; the
CLI refuses to read the file and tells the user to run
`req repair --confirm-direct-edit`.
The hash gives **integrity** (the CLI wrote this last). It does not give
**authenticity** (a trusted human approved it). For authenticity, use
signed git commits and inspect with `req audit`. See `req help audit`.
## 4. Demonstrated workflow — read this end-to-end at least once
This is how you, the agent, should work on this codebase. The same flow
applies to any project using `req`.
### 4.1 Get a green baseline
```sh
cargo build --release
./target/release/req validate # 0 errors required to ship
./target/release/req coverage --path src
```
If both are clean, you can start. If not, address findings before adding
new behaviour.
### 4.2 Read before you write
```sh
./target/release/req help # section index
./target/release/req help best-practice # the validator's contract
./target/release/req help version-control
./target/release/req help integration
./target/release/req list --tag <topic> # narrow to the area you're touching
./target/release/req show REQ-0007 # full detail with history
```
Pulling the slice you need beats reading the whole file in one go. Use
`req help all` only when you genuinely need everything.
### 4.3 Make changes managed
Adding a new requirement (non-interactive, the agent-friendly form):
```sh
./target/release/req add \
--title "Short imperative title" \
--statement "The system shall ..." \
--rationale "Why this exists" \
--kind functional \
--priority should \
--accept "Concrete, testable criterion" \
--accept "Second criterion" \
--tag <topic>
```
Updating a requirement — always include `--reason`:
```sh
./target/release/req update REQ-0015 \
--status approved \
--reason "Reviewed in 2026-05-17 sync"
```
Linking — parent for hierarchy, depends-on / verifies for trace:
```sh
./target/release/req link REQ-0026 REQ-0019 -k depends-on
```
Soft-delete (default) preserves links and history:
```sh
./target/release/req delete REQ-XXXX --reason "Superseded by REQ-YYYY"
```
### 4.4 Reference requirements from code
Drop `REQ-NNNN` markers in source comments where you implement them:
```rust
// REQ-0003: integrity hash verification
fn load(...) { ... }
```
Then `req coverage --path src` tells you which requirements have no code
references (orphans) and which markers point at non-existent or obsolete
requirements (ghosts). Aim for: every functional requirement at
`Implemented` status has at least one code reference.
### 4.5 Before you finish
```sh
cargo build --release
./target/release/req validate # must be 0 errors
./target/release/req coverage --path src
git diff project.req # human-readable, by design
```
If you touched behaviour that has a requirement, you should see a
matching `req update` in the same change. Diffs to `project.req` and
diffs to `src/` should tell the same story.
## 5. Version-control workflow
The .req file is git-tracked normal JSON. Three things change the
default workflow:
- **Pre-commit hook.** Run `req hooks install` once per clone. It writes
`.git/hooks/pre-commit` that runs `req validate` on staged .req files.
- **Merge driver.** `req hooks install` also adds
`*.req merge=req-merge` to `.gitattributes`. Activate it in your
clone with the two `git config` lines that the command prints. The
driver runs `req renumber --base %O` so merges auto-fix ID collisions.
- **Renumber after merge.** If you skipped the driver and merged by
hand, run `req renumber --base origin/main` and then
`req repair --confirm-direct-edit` if the integrity hash needs
refreshing. `req help version-control` has the full details.
## 6. Provenance / signing
We do **not** ship our own signature scheme. Authenticity comes from
signed git commits. `req audit` walks `git log --follow` on the .req
file and prints signature status (good / bad / expired / no-signature)
and signer per commit. If your project has compliance requirements:
```sh
git config commit.gpgsign true # or use SSH-signed commits
./target/release/req audit # see the trail
./target/release/req audit --json -n 500 # for tooling
```
`req help audit` documents the signature-status codes.
## 7. Conventions
- **Errors:** `anyhow::Result` at command boundaries. Print user-friendly
messages that name the next command to run, like the integrity-check
failure does.
- **Time:** `chrono::Utc::now()` everywhere; never `Local`.
- **IDs:** Allocated by `Project::allocate_id()` only. Never reuse, never
let an agent pick its own.
- **Statuses:** Draft → Proposed → Approved → Implemented → Verified.
Obsolete is the terminal sink for retired requirements.
- **clap help strings stay tight and accurate** — they're the primary UX
for humans and agents alike, and they ship with the binary.
- **`req help <section>` stays in sync** with the validator and the
command surface. Adding a rule? Document it. Adding a command? Add a
section (or extend one).
## 8. Status as of v0.1.0
- **120 tests passing** across 12 integration test files; `cargo test
--release -- --test-threads=1` is the canonical invocation. CI runs
each test binary serially to keep the concurrency suite within the
30s file-lock timeout.
- **`cargo-llvm-cov` line coverage ~58%**; validate.rs / storage.rs are
> 85%, mcp.rs and web.rs ~50%, tui.rs is intentionally 0% (dialoguer
interactive code is hard to fixture).
- **All three surfaces are at parity** (REQ-0083): CLI, MCP, TUI offer
the same agent-relevant operations. Two automated tests fail the
build if a new CLI command lands without a matching MCP tool *and*
TUI menu entry, modulo a documented humans-only exclusion list.
- **CI gates on:** `cargo fmt --check`, `cargo clippy -D warnings`,
`cargo build -D warnings`, `cargo test`, `req validate`,
`req coverage --strict --allow REQ-0051 REQ-0052 REQ-0061 REQ-0082`.
- **CI advisory:** `req doctor`, `req stale --path .`.
- **No auth/multi-user model.** `REQ_ACTOR` / `USER` / `USERNAME`
attribute history; `REQ_ACTOR_KIND` (human/agent) is the provenance
signal. Treat attribution as advisory until signed-commit policy is
added (see §6 — `req audit --gate`).
## 9. Quick reference
```sh
# project lifecycle
req init -n <name> # create project.req
req tui # interactive menu (16 actions)
req validate # rules across the project
req status # delivery_progress_pct
req export -f markdown -o reqs.md # publish
# day-to-day
req add ... # see §4.3 (also: --from-json)
req list --status draft --tag foo # Obsolete hidden by default
req show REQ-0007 # detail + history + test records
req update REQ-0007 --status approved --reason "..."
req link REQ-0008 REQ-0007 -k parent
req delete REQ-0007 --reason "..." # soft; --hard if no inbound links
req next # dependency-aware next pick
req batch path/to/changes.json # transactional multi-mutation
req import -f markdown spec.md # bulk ingest through the validator
# evidence
req test record REQ-0007 --result pass --notes "..."
req test run --promote # cargo test + record + auto-Verify
req verify REQ-0007 --by composition --cites REQ-0003 --notes "..." --promote
req verify REQ-0007 --by inspection --notes "..." --promote
req stale --only-stale # records whose linked files changed
# integration
req hooks install [--claude-code] # pre-commit + merge driver
req doctor # per-clone setup audit
req renumber --base origin/main # post-merge ID collisions
req coverage [--by-file | --unlinked-files | --remap OLD=NEW]
req coverage --strict --allow REQ-NNNN # CI gate
req diff origin/main..HEAD # per-requirement transitions
req check origin/main # incremental validate + coverage
req audit # git signature trail
req audit --gate --require-good-signature
req mcp # JSON-RPC stdio server
req mcp --init-config # write .mcp.json bootstrap
req schema [add|batch|import] # JSON Schemas for structured input
req migrate # schema migration (no-op on req-v1)
# recovery
req repair --confirm-direct-edit # after intentional hand edits
# documentation
req help # section index
req help <section> # drill in
req help <section> --install # write into AGENTS.md (this file)
req help <section> --json # structured form for tooling
req help all # everything
```
## 10. Green baseline ritual
```sh
cargo fmt --check
cargo clippy --release --locked -D warnings
cargo build --release
cargo test --release -- --test-threads=1
req validate
req coverage --path . --strict --allow REQ-0051 --allow REQ-0052 \
--allow REQ-0061 --allow REQ-0082
```
If all six commands exit 0, you have a green baseline. Make your
change, run them again, you're done. CI runs exactly these (plus
`req doctor` and `req stale` as advisory).
## req — agents
_What req does for you as an agent, and how to use it._
```
Hey. If you're an LLM agent picking up this project — this is for you.
WHY THIS EXISTS (the short version)
Vibecoding sessions are conversational. The user describes what they
want, you build it, the conversation ends. Without something carrying
the spec between sessions, the next conversation starts blind: you
re-discover the project from source files, you re-derive the intent,
and small things drift.
`req` is the spec-memory that survives between conversations. The
project's requirements live in a git-tracked JSON file managed by
this CLI. The tool tells you what's there, what's queued, and what's
loose. Hooks remind you at commit time. It's there so you can pick
up where the last session left off, instead of guessing.
START HERE
req brief one-line summary of where the project is
right now. Run this first in any session.
Now leads with the project's `_purpose`
(REQ-NNNN) plus its top three Must/Verified
requirements — the spine — so you learn
what the project is FOR before what's queued.
req list full list of requirements with status
req show REQ-NNNN details + history for one requirement
req next suggests what to work on, dependency-aware
WHEN THE USER ASKS FOR SOMETHING NEW
req add --title "..." \ record the requirement BEFORE you write
--statement "..." \ the code. The statement should have a
--rationale "..." \ modal verb (shall / must / should / will)
--kind functional \ and describe one obligation. The validator
--priority must \ tells you if it doesn't.
--accept "..."
Then drop a `// REQ-NNNN:` comment in the file that implements it.
When you commit, the pre-commit hook checks that source files cite
the REQs they implement. The post-commit hook prints a one-line
summary so you see what landed.
WHILE YOU WORK
req coverage --path src where are the markers? what's orphaned?
req validate are the requirements well-formed?
req lint softer audit (rationale length, etc.)
req precheck run the local CI gate suite (REQ-NNNN) —
fmt + clippy + test + validate + coverage
+ review, in CI's order. Catches the
environment-skew failures (rustfmt drift,
fixture-config flakiness) that otherwise
only show up after push.
WORKING WITH AN EXISTING PROJECT (RETROFIT)
req adopt REQ-NNNN REQ-NNNN walk a list of requirements through the
lifecycle to Verified in one invocation
(REQ-NNNN). One history entry per hop,
auto-placeholder acceptance for functional
reqs that lack one, inspection evidence
recorded when the target is Verified.
req adopt --all-drafts same, scoped to every requirement at Draft.
req adopt --to implemented stop short of Verified.
req adopt --dry-run show the plan without writing.
The retrofit path matters because the lifecycle state machine exists
to make ongoing work disciplined — not to make loading existing state
painful. `req adopt` is the explicit acknowledgement that those are
two different modes.
WHEN YOU FINISH SOMETHING
req update <id> --status implemented --reason "..."
req verify <id> --by inspection --notes "..." --promote
These advance the requirement up the lifecycle. The post-commit
hook nudges you about this — if you cited a REQ but didn't advance
its status, the hook prints a suggestion.
HOW THE FILE IS PROTECTED
`project.req` is just JSON — there's nothing at the filesystem
level stopping you from opening it in an editor. The contract is
*post-hoc*: every change passes through an integrity hash, and
any edit that didn't go via the CLI will fail your next `req`
call until `req repair --confirm-direct-edit` re-signs it.
Agents that bypass the CLI don't break anything silently — they
just trigger a visible repair audit on the next operation.
This isn't about gatekeeping you. It's so the diff in any PR
reflects something the CLI was willing to record — the
guarantee humans rely on when reviewing.
RULES THAT MATTER (the short list)
* One obligation per requirement (the validator catches compounds).
* A normative modal verb in every statement.
* Pass `--reason` on every update so history attributes the why.
* `// REQ-NNNN:` markers in source link spec to code.
* Status only goes forward one step at a time; backwards needs
`--force --reason`. Same for skips.
NEW SESSION? RUN THIS FIRST.
req brief
That tells you where the project is. From there, `req next` to
pick something up or just start fixing what the user described.
INSTALL THIS GUIDANCE
req help agents --install writes a managed block into AGENTS.md
(between sentinel markers — idempotent,
re-run any time to refresh).
MCP (Model Context Protocol)
An MCP server is built in. Run `req mcp` and connect from an
MCP-capable client (Claude Code, etc.). Or `req mcp --init-config`
to write `.mcp.json` for auto-launch. The full surface (25 tools)
is documented at `req help mcp`.
ONE-LINE BOOTSTRAP FOR A NEW PROJECT
req setup # init + hooks + AGENTS.md, all in one.
```