# rqtk **Requirements that live in your repository, proven by tests.** rqtk keeps requirements, stakeholder needs and verification evidence as TOML files next to your code. A requirement change is a commit, a baseline is a git tag, and history is `git log`. There is no separate tool or database, and no export step between your requirements and your version control. ``` .rqtk/ config.toml ← project policy: categories, states, lint rules requirements/SYS/SYS-0001.toml needs/NEED-0001.toml stakeholders/STK-0001.toml evidence.toml ← which tests passed, against which version of each requirement ``` ## Why Most requirements tools are separate systems: documents, spreadsheets or SaaS platforms, disconnected from source control. Engineers end up maintaining two ledgers, and the two drift apart. rqtk treats requirements as source code, and it holds them to the same standard as code: - **Checked like code.** `rqtk lint` rejects typos, unknown references, cycles and vague statements, with the file and line of every finding. - **Proven, not claimed.** A requirement counts as *verified* only when the tests linked to it passed against its current wording. Reword the requirement and it becomes *Suspect* until those tests pass again. Nobody can mark a requirement done by editing a file. - **Operable by agents.** Every command prints JSON with `--json`, exits with documented codes, and never prompts. Agent skills plug rqtk into a coding agent's normal workflow. ## Where to go next - [Install rqtk](getting-started/installation.md), then follow the [quick start](getting-started/quick-start.md). - Read how [verification from test evidence](guides/verification.md) works: it is the core idea. - Using Claude Code, Codex, Cursor or another coding agent? See [Coding agents](guides/agents.md). --- # Installation ## Prebuilt binaries On macOS and Linux: ```bash curl -LsSf https://rqtk.dev/install.sh | sh ``` On Windows (PowerShell): ```powershell powershell -ExecutionPolicy Bypass -c "irm https://rqtk.dev/install.ps1 | iex" ``` Both scripts download the right binary for your platform from the [latest GitHub release](https://github.com/wdoppenberg/rqtk/releases/latest) and verify its checksum. You can also download an archive from the release page yourself. ## With pip or uv ```bash pip install rqtk # or: uv tool install rqtk ``` The Python package contains the full command line and the `@rqtk.verifies` decorator for linking pytest tests. Wheels are available for Linux, macOS and Windows on Python 3.9 and later. ## With Cargo ```bash cargo install rqtk --locked ``` This needs Rust 1.88 or later. ## Linking tests Linking tests to requirements needs nothing extra for most languages: a `// rqtk: verifies VA-…` comment above a test is enough. Two languages have a checked annotation: - **Rust:** add `rqtk = { version = "1", default-features = false, features = ["macros"] }` to `[dev-dependencies]` and annotate tests with `#[rqtk::verifies("VA-…")]`. An unknown activity ID is a compile error. (The standalone `rqtk-macros` crate works too.) - **Python:** `pip install rqtk` and decorate tests with `@rqtk.verifies("VA-…")`. An unknown activity ID fails test collection. See [Verifying with tests](../guides/verification.md). ## Check the installation ```bash rqtk --version ``` --- # Quick start This walks through the whole loop: set up a repository, write a requirement, prove it with a test, and watch it go Suspect when it changes. ## 1. Initialise In a git repository: ```bash rqtk init ``` This creates `.rqtk/config.toml` with a starter policy, named after your project. Add `--agents` to also install the [agent skills](../guides/agents.md), `--hook` for a pre-commit hook that lints before every commit, and `--example` for an example stakeholder and need. Everything except history (`impact`, `diff`, `log`, `baseline`) works outside a git repository too. ## 2. Add a requirement ```bash rqtk add --category SYS --type Functional \ --title "Fast boot" \ --statement "The system shall boot in under 5 seconds." \ --rationale "Operators restart the unit during a pass." \ --criteria "Boot completes in under 5 s on reference hardware." \ --activity "Boot time test" ``` rqtk assigns the next free ID (here `REQ-SYS-0001`) and writes `.rqtk/requirements/SYS/REQ-SYS-0001.toml`, with a verification activity `VA-SYS-0001-01`: ```toml [verification] method = "Test" level = "Unit" phase = "Development" success_criteria = "Boot completes in under 5 s on reference hardware." [[verification.activities]] id = "VA-SYS-0001-01" name = "Boot time test" ``` `--parent` and `--satisfies` link it to the requirement it derives from and the need it serves; `rqtk add-activity` adds more activities later. Then check it: ```bash rqtk lint ``` ## 3. Link a test Put the activity ID above the test that proves it: ```rust // rqtk: verifies VA-SYS-0001-01 #[test] fn boots_in_under_five_seconds() { // … } ``` `rqtk scan` lists every link it finds, and the test each one is attached to. ## 4. Record the results Run your tests with JUnit output, then hand the report to rqtk: ```bash cargo nextest run # writes target/nextest/default/junit.xml rqtk verify --results target/nextest/default/junit.xml rqtk coverage ``` The requirement is now **Verified**, and `.rqtk/evidence.toml` records which test passed, at which commit, against which version of the requirement. Commit it with the code. ## 5. Change the requirement Tighten the statement to "under 3 seconds" and run `rqtk coverage` again. The requirement is now **Suspect**: its tests passed for the old wording, and nothing has proven the new one. Rerunning the same test doesn't settle it: it passed for 5 seconds and says nothing about 3. Update the test for the new limit, run it, and `rqtk verify` again. (If a test already checks the new wording, record that with `rqtk review REQ-SYS-0001 --note "…"`.) `rqtk coverage --strict` exits 1 until every requirement is Verified, so it works as a CI gate. --- # Writing requirements rqtk tracks three kinds of item, each a TOML file named after its ID: | Item | Lives in | Says | |---|---|---| | **Stakeholder** | `.rqtk/stakeholders/` | who cares about the system | | **Need** | `.rqtk/needs/` | what a stakeholder needs, and why | | **Requirement** | `.rqtk/requirements//` | what the system shall do, and how that is verified | Requirements *satisfy* needs, *decompose* into child requirements through `trace.parents`, and are proven by *verification activities*. Every link is by ID, and `rqtk lint` checks that every link resolves. ## Creating items ```bash rqtk add-stakeholder --name "Operator" --role "Runs the ground station" rqtk add-need --title "Fast recovery" \ --statement "Operators need the unit back within seconds after a restart." \ --stakeholders STK-0001 rqtk add --category SYS --type Functional --title "Fast boot" \ --statement "The system shall boot in under 5 seconds." \ --rationale "Operators restart the unit during a pass." \ --satisfies NEED-0001 \ --criteria "Boot completes in under 5 s on reference hardware." \ --activity "Boot time test" ``` rqtk assigns the next free ID in each case. Pass `--dry-run` to see the file without writing it, and `--json` to get the assigned ID in machine-readable form. `rqtk add` also takes `--parent` (repeatable) for the requirement it decomposes, `--priority`, and `--method`, `--level` and `--phase` for how it is verified. A category listed in `validation.require_parent_for_categories` needs `--parent`. Each `--activity` gets an ID derived from the requirement's: `REQ-SYS-0001` gets `VA-SYS-0001-01`, `VA-SYS-0001-02`, and so on. Tests cite these IDs. Add an activity to an existing requirement with: ```bash rqtk add-activity REQ-SYS-0001 --name "Cold boot test" ``` ## Anatomy of a requirement ```toml id = "REQ-SYS-0001" title = "Fast boot" category = "SYS" type = "Functional" state = "Approved" priority = "High" statement = "The system shall boot in under 5 seconds." rationale = "Operators restart the unit during a pass." [trace] satisfies = ["NEED-0001"] # parents, derived_from, refines, depends_on, conflicts_with, related: all by ID [verification] method = "Test" level = "System" phase = "Development" success_criteria = "Boot completes in under 5 s on reference hardware." [[verification.activities]] id = "VA-SYS-0001-01" name = "Boot time test" ``` The full list of fields is on the [File formats](../reference/file-formats.md) page, and `rqtk schema requirement` prints the JSON Schema. Unknown fields are errors, so a typo is reported instead of silently ignored. ## Good statements `rqtk lint` enforces the basics, and the project configuration can tighten them: - **One sentence, with the shall keyword** (RQ010). Split compound requirements. - **Measurable.** A test must be able to decide pass or fail. Forbid vague words such as "fast" or "user-friendly" with `validation.forbidden_keywords` (RQ011). - **Justified.** A `rationale` says why the requirement exists (RQ007). - **Traced.** Set `trace.parents` to the requirement it decomposes, and `trace.satisfies` to the need it serves. With `forbid_orphans`, every requirement must trace back to a root category (RQ018). ## Finding your way around ```bash rqtk search boot -i # substring search across requirements, needs and stakeholders rqtk trace REQ-SYS-0001 # parents and children rqtk context REQ-SYS-0001 # everything about one item: links, tests, status, findings rqtk graph > trace.dot # the whole graph, for Graphviz ``` ## Configuration `.rqtk/config.toml` decides the vocabulary: categories and their hierarchy, requirement types, lifecycle states, priorities, verification methods, and which lint rules apply. See [Configuration](../reference/configuration.md). To add a category, add a table for it: ```toml [categories.SW] name = "Software" level = 2 ``` Requirement IDs are checked against `--` for the configured categories (RQ001). Set `identification.id_pattern` only if your IDs follow another scheme; then new categories must be added to it too. --- # Verifying with tests A requirement is **verified** only by recorded test results, never by editing a file. rqtk records which tests passed against which version of each requirement. When the requirement changes afterwards, that evidence turns **Suspect** until the tests run again. ## The loop 1. **Link a test** to a verification activity. 2. **Run the tests** with JUnit XML output. 3. **Record the results** with `rqtk verify`. 4. **Check** with `rqtk coverage --strict`, and commit `.rqtk/evidence.toml` with the code. ## Linking tests Put the activity ID directly above the test. Only blank lines, comments, other tags and attributes (`#[test]`, `@Test`, `@pytest.mark.parametrize(…)`, `[Fact]`) may sit in between; the first other line must be the test. | Language | Annotation | Checked when | |---|---|---| | Rust | `#[rqtk::verifies("VA-…")]` (the `rqtk` crate with `default-features = false, features = ["macros"]`) | compile time | | Python | `@rqtk.verifies("VA-…")` | test collection | | Anything | `// rqtk: verifies VA-…` (or `#`, `--`, `/* */`) | `rqtk lint` | rqtk recognises these test declarations: | Language | Tests | |---|---| | Rust | `fn name` | | Python | `def test_x`, `async def test_x`, methods of test classes | | Go | `func TestX`, including methods `func (s *S) TestX` | | JavaScript, TypeScript | `it`, `test` and `describe` (a whole group), with `.only`, `.skip`, `.concurrent`, `.each(…)`; `function name` | | Java, C#, C, C++ | methods and functions (`void name()`, `public async Task Name()`), GoogleTest `TEST`, `TEST_F`, `TEST_P`, Catch2 and doctest `TEST_CASE` | | Kotlin, Swift, Ruby, Zig, Elixir | `fun`, `func`, `def`, `test "name"`, RSpec `it "…" do` | `rqtk scan` shows what each link is attached to. A tag with no test declaration below it can never match a result; `rqtk lint` reports it as an error (RQ030). A test can verify several activities, and an activity can have several tests; it passes only when all of them pass. `rqtk lint` also reports links to unknown activities (RQ028). ### One case of a table-driven test Tag the case's row, and name the case: ```go func TestIntact(t *testing.T) { cases := []struct{ name string; flip bool }{ // rqtk: verifies VA-SYS-0003-01 case "flipped byte is corrupt" {"flipped byte is corrupt", true}, // rqtk: verifies VA-SYS-0003-02 case "intact file passes" {"intact file passes", false}, } // … } ``` The link belongs to the enclosing test and matches the runner's result for that case: Go's `TestIntact/flipped_byte_is_corrupt`, or pytest's `test_x[case]`. In Python and Rust, pass `case` to the annotation instead: `@rqtk.verifies("VA-…", case="neg")`. The same works for rows of a JS/TS `it.each([...])` table, where the case is any part of the rendered title (`case "1+1"` for `"adds 1+1"`), and for GoogleTest value-parameterised tests, where the case is the parameter's value: tag the `TEST_P` with `// rqtk: verifies VA-… case "7"`. ### Display names JUnit's `@DisplayName("…")` and `@ParameterizedTest(name = "…")`, and xUnit's `DisplayName = "…"`, change the name some runners report (Gradle does; Maven Surefire reports the method name). rqtk reads them from the annotations above the test and matches either name. A parameterised JUnit test without a `name` is reported by Gradle as `[1] …` with no trace of the method, so give it a `name`. ### Choosing what is scanned In `.rqtk/config.toml`: ```toml [scan] paths = ["."] # default; .gitignore is honoured exclude = ["tests/fixtures/**"] # gitignore-style globs ``` ## Running tests with JUnit output rqtk reads [JUnit XML](../reference/json-and-exit-codes.md#why-junit-xml), which nearly every test runner can write: | Ecosystem | Command | |---|---| | Rust (nextest) | `cargo nextest run`, with `[profile.default.junit] path = "junit.xml"` in `.config/nextest.toml`; the report lands in `target/nextest/default/` | | Rust (stable libtest) | `RUSTC_BOOTSTRAP=1 cargo test --tests -- -Z unstable-options --format junit > junit.xml` | | Python | `pytest --junitxml=junit.xml` | | Go | `go test -v ./... 2>&1 \| go-junit-report > junit.xml` (`go install github.com/jstemmer/go-junit-report/v2@latest`), or `gotestsum --junitfile junit.xml` | | JS/TS | `vitest run --reporter=junit --outputFile=junit.xml`, `bun test --reporter=junit --reporter-outfile=junit.xml`, or jest with `jest-junit` | | JVM | Maven Surefire and Gradle write JUnit XML by default (`target/surefire-reports/*.xml`, `build/test-results/test/*.xml`) | | C/C++ | `ctest --output-junit junit.xml` (CMake 3.21+), or GoogleTest's `--gtest_output=xml:junit.xml` | `--results` takes several files, so one per package or module works too. ### How results are matched A result matches a link by test name (or display name), together with the suite for GoogleTest and the case for a case link. When several tests share a name, rqtk narrows by the source file the runner reports (Bun, vitest, GoogleTest) or by what the link's path says about the result's class or module. If a linked test still matches several distinct tests, `rqtk verify` records nothing for it and says which tests it matched; rename one. Disabled and skipped tests leave an activity incomplete. ## Recording results ```bash rqtk verify --results junit.xml ``` rqtk matches each test case to the functions linked to each activity and records one entry per activity in `.rqtk/evidence.toml`: the outcome, the tests, the commit, and the **content hash of the requirement at that moment**. - An activity passes only when every linked test ran and passed; a skipped test leaves it incomplete. - A run that covers only some tests, such as the Python suite without the Rust one, leaves other activities' evidence untouched. `verify` counts the linked tests it found no result for, so a runner naming tests differently doesn't go unnoticed. - Evidence names each test as `::`, so the same test gets the same entry whichever runner reported it. - `verify` exits 1 if a linked test failed, if a linked test matched several tests, or if the results matched no linked test at all (usually the wrong file, or tags rqtk can't attach). - `verify --check` writes nothing and exits 1 if the committed evidence doesn't match this run. Use it in CI. ## Coverage states `rqtk coverage` puts every requirement in one state: | State | Meaning | What to do | |---|---|---| | **Verified** | Every activity passed: linked tests against the current wording, or a manual status of Passed/Waived | nothing | | **Suspect** | Evidence no longer settles it; see [Suspect](#suspect) | depends on the reason | | **Failed** | A linked test failed, or a manual status is Failed | fix the code, or with the stakeholder, the requirement | | **In Progress** | Some activities passed or started | finish the rest | | **Planned** | Activities defined, nothing run yet | link and run tests | | **Gap** | No activities, or no success criteria | define them | `rqtk coverage --strict` exits 1 unless every requirement is Verified and every need is satisfied. For requirements written ahead of their implementation, `--allow planned` (and `--allow in-progress`) accepts those states too. ## Suspect A requirement becomes Suspect when evidence recorded for it no longer settles it. `rqtk coverage` and `rqtk context` say why: | Reason | What happened | What settles it | |---|---|---| | changed since its tests passed | its content hash changed after its tests passed | run the tests, `rqtk verify` | | passed again with unchanged tests | it changed, and the same tests that passed for the old wording passed again | change the tests for the new wording and run them, or `rqtk review` | | upstream changed | a parent requirement, or a need it or its ancestors satisfy, changed after it was verified | check it still fits, then `rqtk review` | The **content hash** covers what the requirement demands and how it is verified: the statement, its structural links (parents, depends_on, derived_from, refines, satisfies), its parameters, and the verification method, level and phase. Editing the title, keywords, priority or notes changes nothing. This is deliberate. A reworded requirement may no longer be what the tests check, so rqtk refuses to carry the old verdict over, and rerunning a test that was never updated proves nothing new. `rqtk impact ` lists every activity to re-run after a change. [Change control](change-control.md#review-debt) covers `rqtk review`. ## Activities no test can check Inspections, analyses and demonstrations keep a hand-written status: ```toml [[verification.activities]] id = "VA-SYS-002-01" name = "Thermal analysis" status = "Passed" executed_at = 2026-03-14 evidence = ["reports/thermal-2026-03.pdf"] ``` As soon as a test is linked to an activity, its `status` is ignored, and `rqtk lint` warns until you remove it (RQ029). --- # Baselines and change control Requirement changes that slip through without review are harder to catch than code changes: there is no compiler to notice a modified shall statement. rqtk leans on git for the record and adds what git can't tell you. ## Baselines A baseline is an annotated git tag, `rqtk/`: ```bash rqtk baseline 1.0.0 --dry-run # show what would be stamped and tagged rqtk baseline 1.0.0 ``` It writes `approval.baselined_at` and `approval.baselined_by` into every requirement (leaving the rest of each file untouched), commits that, and tags the commit. ## What changed ```bash rqtk diff 0.9.0 1.0.0 # between baselines, branches, tags or SHAs rqtk impact main # between a revision and your working tree rqtk log SYS-0001 # git history of one requirement ``` `diff` classifies each modified requirement as **semantic** (its content hash changed: statement, links, parameters or verification) or **cosmetic** (anything else). `impact` goes further. For a branch or pull request it lists: - requirements and needs added, removed or changed; - requirements **downstream** of a semantic change, which may need their own review; - every verification activity to **re-run**, because its requirement changed or a file containing one of its tests changed, with the tests to run. Activities whose evidence already covers the change are listed separately. ## Review debt Two kinds of change leave a requirement **Suspect** until someone deals with them, however often the tests run: - **Its tests didn't change with it.** The requirement was reworded and the same tests that passed for the old wording passed again. They may still prove it, or they may test the old behaviour; rqtk can't tell which. - **Something upstream changed.** A parent requirement, or a need it or its ancestors satisfy, changed after it was verified. The child may no longer fit. Each is settled one way: - update the tests for the new wording and run them, then `rqtk verify`; - or confirm the requirement still holds, and record that: ```bash rqtk review REQ-SW-0004 --note "Threshold follows the parent; tests check the configured value." ``` The review lands in `.rqtk/evidence.toml` with the date, the commit and the note, and shows in `rqtk report`. It lasts until the requirement or anything upstream changes again. A review doesn't stand in for running a changed requirement's tests: that Suspect reason stays until they pass. ## Review and sign-off Two platform features make the git log an auditable change record: **CODEOWNERS** routes changes to the right reviewer: ``` .rqtk/requirements/SYS/ @systems-lead .rqtk/requirements/SW/ @software-lead ``` **Signed commits**, enforced by branch protection, tie every change to a verified identity. The `[approval]` table in each requirement is a readable summary for anyone looking at the TOML. The authoritative record is the git log: who signed the commit, and who approved the pull request. ```toml [approval] baselined_at = 2026-11-01 baselined_by = "systems-lead" approved_by = ["systems-lead", "chief-engineer"] ecr_ids = ["ECR-0042"] ``` ## Pre-commit hook ```bash rqtk install-hook # or, in a new repository: rqtk init --hook ``` This adds a managed block to `.git/hooks/pre-commit` that runs `rqtk rehash` (refresh any stored content hashes) and `rqtk lint` before each commit. Existing hook content is kept. New files carry no `content_hash`; rqtk computes it when it needs it. Stamp every file with `rqtk rehash --all` if you want the hash visible in the TOML; lint rule RQ021 then reports when it goes stale. --- # Coding agents rqtk is built to be driven by coding agents as well as people: nothing prompts, every command prints JSON with `--json`, and exit codes are fixed. Four agent skills bring it into an agent's normal workflow. ## Skills ```bash rqtk skills install # or, in a new repository: rqtk init --agents ``` | Skill | Invoked by | What it does | |---|---|---| | `rqtk-requirements` | agent or you | Reading and writing `.rqtk/`: find the governing requirement, read its briefing, author items that lint clean. | | `rqtk-verification` | agent or you | The proof loop: link a test, run it, `rqtk verify`; done when `rqtk lint` and `rqtk coverage --strict` exit 0. | | `/to-requirements` | you | Turn a spec or discussion into needs and requirements with verification activities; you approve the draft before anything is written. | | `/requirements-review` | you | Review a diff against the requirements it touches: facts from `rqtk impact`, then a verdict per requirement, and the `rqtk review` commands that would settle what is still Suspect. | The skills follow the open [Agent Skills](https://agentskills.io) format, so they work with any agent that supports it: | Agents | Read skills from | What rqtk installs | |---|---|---| | Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Amp, Cline, Zed, Warp, … | `.agents/skills/` | the skill files | | Claude Code | `.claude/skills/` | a link per skill into `.agents/skills/` | `rqtk skills install --for claude` or `--for universal` installs for one family only; `--copy` writes copies instead of links; `--dir` installs anywhere else. The skills are compiled into the binary, so they always describe the rqtk you have. Reinstall after upgrading: untouched skills are updated, and skills you edited are kept. rqtk also adds a short block to `AGENTS.md` (and to `CLAUDE.md`, unless it already imports `@AGENTS.md`) telling agents where requirements live and when work is done. It never creates those files unless you name one with `--instructions`. ## Where the skills fit The skills are small and slot into an existing flow rather than imposing one. They were designed alongside [mattpocock/skills](https://github.com/mattpocock/skills): ``` grill → /to-spec → /to-requirements → /to-tickets → /implement → /code-review + /requirements-review ``` - `/to-requirements` turns the spec into requirements with activity IDs. - Tickets cite those IDs in their acceptance criteria. - The implementer's tests cite the activity IDs, and `rqtk verify` records them. - `/requirements-review` checks the result on the requirements axis, next to the usual code review. ## Commands agents use most ```bash rqtk context REQ-SYS-0001 --json # the briefing: statement, links, tests, status, findings rqtk impact main --json # what a change touches, what to re-verify, and with which tests rqtk lint --json # findings with code, severity and file:line rqtk explain RQ010 # what a rule checks and how to fix it rqtk schema requirement # the JSON Schema of a file kind rqtk add … --parent … --criteria … --activity … # a complete requirement in one command ``` Exit codes and the JSON contract are described under [JSON output and exit codes](../reference/json-and-exit-codes.md). ## Machine-readable docs These docs are also available in plain Markdown for agents: [`/llms.txt`](/llms.txt) indexes every page, and [`/llms-full.txt`](/llms-full.txt) contains them all in one file. --- # Continuous integration Three commands make a complete requirements gate: ```bash rqtk lint # every file valid, every link resolves rqtk verify --check --results junit.xml # committed evidence matches this test run rqtk coverage --strict # every requirement Verified ``` Each exits 1 when it finds a problem, so any CI system can use them directly. If you write requirements ahead of their implementation, `rqtk coverage --strict --allow planned` lets those through while still failing on anything Suspect, Failed or half-done. ## GitHub Actions ```yaml name: Requirements on: [push, pull_request] jobs: requirements: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable - uses: taiki-e/install-action@v2 with: tool: cargo-nextest - name: Install rqtk run: curl -LsSf https://rqtk.dev/install.sh | sh - name: Test run: cargo nextest run --profile ci # writes target/nextest/ci/junit.xml - run: rqtk lint - run: rqtk verify --check --results target/nextest/ci/junit.xml - run: rqtk coverage --strict ``` Configure the `ci` nextest profile to write JUnit in `.config/nextest.toml`: ```toml [profile.ci.junit] path = "junit.xml" ``` ## Why `verify --check` Evidence is committed, so it is reviewed like code. `verify --check` makes sure it is honest: it fails when the committed `.rqtk/evidence.toml` doesn't match what this CI run observed. For example, someone may have changed a requirement without re-running its tests, or a test may now fail. To fix it, run the tests and `rqtk verify` locally, then commit the updated evidence. Editing a test that still passes doesn't count as a mismatch. Reviews recorded with `rqtk review` live in the same file, so they reach the main branch through the same pull request review as the change they settle. ## Pull request review `rqtk impact origin/main --json` lists the requirements a pull request changes, the requirements downstream of them, and the activities to re-verify. It is a good input for a review bot, or for the `/requirements-review` [agent skill](agents.md). --- # Commands Every command accepts `--json` (one JSON document on stdout) and `--repo-root `. The same text is available from `rqtk --help`. ```text Requirements Toolkit Usage: rqtk [OPTIONS] Commands: init Scaffold a new requirement set in the current repo add Add a new requirement with the next free ID in its category add-activity Add a verification activity to an existing requirement add-stakeholder Add a new stakeholder definition add-need Add a new stakeholder need lint Check every file against the schema, the config and the `verifies` links in source context Everything relevant to one requirement, need or stakeholder: links, tests, status, evidence and lint findings. Designed as the briefing for working on an item impact What changed since a git revision, and which requirements and activities it affects trace Show the parent/child traceability chain of a requirement coverage Report need satisfaction and verification status (verified / suspect / failed / …) graph Print the traceability graph of stakeholders, needs and requirements baseline Stamp all requirements and create a git tag baseline for HEAD export Export requirements to a file in the given format diff Show requirements that changed between two git revisions or baselines scan List `verifies` links between source code and verification activities verify Record test results as verification evidence in `.rqtk/evidence.toml` review Confirm a requirement still holds after something it depends on changed search Search requirements, needs and stakeholders by substring open Open a requirement file in $EDITOR log Show the git commit history for a single requirement install-hook Install a git pre-commit hook that runs `rqtk rehash` and `rqtk lint` rehash Refresh stored content hashes that no longer match their requirement or need report Generate a Markdown requirements report schema Print the JSON Schema of a file kind, or list the kinds explain Explain a lint rule and how to fix it, or list all rules skills Agent skills for working with rqtk in coding agents (Claude Code, Codex, …) help Print this message or the help of the given subcommand(s) Options: --repo-root Repository root (the directory containing `.rqtk/`) [default: .] --json Print one JSON document to stdout instead of text. Errors go to stderr as JSON -h, --help Print help -V, --version Print version Exit codes: 0 success, nothing to report 1 findings: lint errors, failed or suspect verification, stale evidence 2 usage error: bad arguments or unsupported option 3 error: configuration, I/O or git failure ``` ## `rqtk init` ```text Scaffold a new requirement set in the current repo Usage: rqtk init [OPTIONS] Options: --repo-root Repository root (the directory containing `.rqtk/`) [default: .] --requirements-dir --force Overwrite an existing `.rqtk/config.toml` --json Print one JSON document to stdout instead of text. Errors go to stderr as JSON --agents Also install the agent skills (see `rqtk skills install`) --example Also create an example stakeholder and need --hook Also install the git pre-commit hook (see `rqtk install-hook`) --dry-run Report the files that would be created without writing them -h, --help Print help ``` ## `rqtk add` ```text Add a new requirement with the next free ID in its category Usage: rqtk add [OPTIONS] --category --type --title