# Traceable Reqs **NLSpec** (natural-language specification) for a requirements-tracing CLI—organized like [strongdm/attractor](https://github.com/strongdm/attractor): point an agent at the spec to implement the tool or verify behavior. The tool follows the spirit of [OpenFastTrace](https://github.com/itsallcode/openfasttrace): tag-based traces across languages, with a focus on **coding agents** and **CI**. > **Status:** the spec is the primary artifact at the repo root. A reference Rust implementation lives in [`rust/`](rust/) — `cd rust && cargo build` produces `rust/target/debug/traceable-reqs`. Run the binary from a directory that holds `traceable-reqs.toml` (e.g. `cd example && ../rust/target/debug/traceable-reqs check --json`). Issues and PRs welcome. ## Install ### If you are human Tell your coding agent (Claude Code, etc.): ``` Read README.md from BigscreenVR/traceable-reqs and follow the install instructions there. ``` ### If you've been sent here by your human Clone this repo into the user's Claude skills directory, then follow [`SKILL.md`](SKILL.md): - **Claude Code:** `gh repo clone BigscreenVR/traceable-reqs ~/.claude/skills/traceable-reqs` Then read `~/.claude/skills/traceable-reqs/SKILL.md` and execute the install procedure: install the matching release binary, copy the bundled `.claude/skills/req-confusion-audit` directory to the sibling `~/.claude/skills/req-confusion-audit` directory, copy `.claude/workflows/req-confusion-score.js` to `~/.claude/workflows`, verify all three installations, and surface the PATH line if needed. The audit skill and the scoring workflow install together on purpose — the skill dispatches to `req-confusion-score` by name, so the skill alone would fail at the point where it fans out. Requires `gh` ([install](https://cli.github.com/)) authenticated via `gh auth login`. The installer source stays in `~/.claude/skills/traceable-reqs`; re-invoke “install traceable-reqs” to update the CLI, the bundled audit skill, and its workflow. Without Claude, follow [`SKILL.md`](SKILL.md) by hand or build the CLI from source with `cd rust && cargo build --release`. ## What the tool does The specified CLI is **written in Rust**. It reads the required **`traceable-reqs.toml`** manifest as the authoritative list of requirement IDs, scans configured files for **`[stage->requirement-id]`** tags, reports missing required documentation, implementation, unit-test, and integration-test evidence, and exposes the same trace facts through pyramid-friendly human and agent output plus structured JSON. `check` also verifies **where** each tag sits: a tag must be attached to an item that can carry its stage, so a tag that drifts off the test or function it names is a `misplaced_tag` finding rather than silent green. See [Tag placement enforcement](SPEC.md#tag-placement-enforcement). --- ## Spec Read [**SPEC.md**](SPEC.md). It is the source of truth for the core behavior and optional capabilities: manifest shape, tag grammar, trace completeness, commands, findings, examples, and extension details. --- ## Terminology - **NLSpec:** a human-readable specification meant for coding agents (and humans) to implement or check behavior—following the usage in [Attractor](https://github.com/strongdm/attractor). --- ## Non-goals - Replacing GitHub Issues (or your planner). - Full ReqIF or OpenFastTrace interchange. - Shipping a deep IDE plugin for every editor on day one—**CLI first**. --- ## Prior art - [OpenFastTrace](https://github.com/itsallcode/openfasttrace) — tag-based tracing across languages. - [Sphinx-Needs](https://www.sphinx-needs.com/), [Doorstop](https://github.com/doorstop-dev/doorstop), [ReqIF](https://www.omg.org/spec/ReqIF/) — other requirement workflows. --- ## Implementing Example prompt for a coding agent: ``` Implement the traceable-reqs tool from SPEC.md in this repository. ``` Point the agent at the **root of this repo** (or a published URL). Implement against [**SPEC.md**](SPEC.md). --- ## Scope The core behavior is intentionally small but extensible: required **`traceable-reqs.toml` manifest** with authoritative IDs; comment scanning for Rust, Python, C/C++, JavaScript/TypeScript, Markdown, CMake, YAML, shell, PowerShell, and TLA+; built-in stages `doc`, `impl`, `unit`, `int`; manifest-declared custom stages; external signoff URL evidence; manifest-driven required stages; pyramid reporting; CLI commands `list`, `trace`, **`check`**, with `--json` for structured output. Inside a git work tree the scanner takes its candidate files from git — everything tracked, plus everything untracked that is not ignored — so `build/`, `.venv/`, and other gitignored trees stay out without any configuration. `scan.roots` narrows that set; `scan.exclude` globs remove vendored trees that are tracked on purpose. See [Scan enumeration](SPEC.md#scan-enumeration). Additional capabilities such as include/exclude globs, priority gates, requirement groups, and stability promises are defined in [**SPEC.md**](SPEC.md). Implementation order is up to the implementor. Optional later: a small Rust **library** for deeper integration—not required to use the CLI. --- ## License Default intent: **Apache-2.0 OR MIT** dual license once `LICENSE` files are added. Submitting PRs implies you are ok with that choice unless you state otherwise.