# 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: resolve the latest release, `gh release download` the matching platform asset (`linux-x86_64`, `macos-arm64`, or `windows-x86_64.exe`), drop it in `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\Programs\traceable-reqs` (Windows), `chmod +x` if Unix, verify with `--version`, and surface the PATH line if needed.

Requires `gh` ([install](https://cli.github.com/)) authenticated via `gh auth login`. The skill stays in `~/.claude/skills/traceable-reqs` — re-invoke any time with "install traceable-reqs" to update. Without Claude: follow [`SKILL.md`](SKILL.md) by hand, or build 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.

---

## 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: required **`traceable-reqs.toml` manifest** with authoritative IDs; comment scanning for Rust, Python, C/C++, JavaScript/TypeScript, Markdown, CMake, YAML, shell, and PowerShell; stages `doc`, `impl`, `unit`, `int`; manifest-driven required stages; pyramid reporting; CLI commands `list`, `trace`, **`check`**, with `--json` for structured output.

Additional capabilities such as include/exclude globs, priority gates, custom stage definitions, 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.