# AIDLC Traceability Tool — Agentic Solution An agent-native re-implementation of the AIDLC Traceability Tool: it generates a five-layer traceability matrix (Requirements → Stories → Units → Components → Code) over a project's `aidlc-docs` and source tree, with coverage metrics and gap analysis, and writes Markdown + HTML reports — entirely inside an AI coding assistant, **with no Bedrock/AWS dependency**. It implements the **Claude Code**, **Kiro**, **GitHub Copilot**, and **Codex** packagings plus the shared common components. The original Python/Bedrock CLI has been retired; it remains available in the project's git history (it previously lived under `legacy/`). The founding product specs are retained under [`docs/product/`](docs/product/). ## Quick start Install the tool into the assistant's config for the project you want to analyze, then launch that assistant from the project folder and ask for the matrix. Below, `` is this repository and `` is the target project (the folder containing its `aidlc-docs/`; source may be nested under a `workspace/` wrapper — discovery finds it). Reports are written to `/aidlc-docs/traceability/traceability-matrix-.{md,html}`. The install is self-contained: each assistant runs the tools/methodology copied into `` — no dependency on `` at run time, and no `pip`/AWS. **Claude Code** ```bash cd && /install.sh --ide claude claude # restart/new session so the skill + agents register # then, in the session: /traceability ``` **Kiro** ```bash cd && /install.sh --ide kiro kiro-cli chat --agent traceability # then ask: generate a traceability matrix for ``` **GitHub Copilot** (run on a Claude-class model — the bridging is multi-step reasoning) ```bash cd && /install.sh --ide copilot copilot --agent="AIDLC Traceability" --prompt "generate a traceability matrix for " # or in VS Code Copilot Chat (agent mode): run /traceability ``` **Codex** ```bash cd && /install.sh --ide codex codex # then ask: generate a traceability matrix for # (the root AGENTS.md routes the request to the orchestrator) ``` A correct run traces `Requirements → Stories → Units → Components → Code` (skipping any absent layers) and reports coverage per layer plus any gaps. See [Install](#install) for flags (`--dry-run`, `--dest`) and per-IDE details. ## Layout This solution lives at the repository root. ```text . ├── common/ # IDE-agnostic resources (single source of truth) │ ├── methodology/ # the 5 bridge bodies (canonical prompts) │ │ ├── req-story.md story-unit.md unit-component.md │ │ ├── component-code.md │ │ └── bridge.md # generic bridge (any pair; discovers a missing layer) │ ├── tools/ # deterministic Python tools (stdlib only) │ │ ├── discover_artifacts.py # discovery + parsing + heuristic linking → JSON │ │ └── build_matrix.py # graph + coverage analysis + MD/HTML rendering │ ├── trace-config.yaml # shared settings (AI toggle, max files, format) │ └── AGENTS.md # shared repo-root pointer for CLI agents (Copilot CLI, Codex) ├── claude/ # Claude Code packaging │ ├── agents/*.head.md # thin frontmatter heads (composed with methodology) │ └── skills/traceability/SKILL.md # the /traceability orchestrator (parallel subagents) ├── kiro/ # Kiro packaging │ ├── steering/traceability.md # the orchestrator steering doc (sequential) │ └── agents/traceability.json # agent manifest (tool trust + resources) ├── copilot/ # GitHub Copilot packaging │ ├── agents/traceability.agent.md # first-class custom agent (self-contained) │ ├── prompts/traceability.prompt.md # reusable /traceability prompt (mode: agent) │ └── copilot-instructions.md # minimal always-on pointer ├── codex/ # Codex packaging │ └── traceability.md # the orchestrator (read on demand via AGENTS.md) ├── docs/ # supporting docs │ ├── product/ # founding product specs (vision.md, PR-FAQ.md) │ └── dev/ # lint/type-check configs for common/tools (ruff, mypy) ├── install.sh # composes the right pieces into an IDE's config dir ├── smoke_test.sh # deterministic contract check └── README.md ``` > `common/AGENTS.md` is the shared repo-root pointer the Copilot CLI and Codex > auto-load; both installers write it to the root `AGENTS.md` (idempotently). ## How the conversion maps to the coded tool | Coded component (`src/traceability/`) | Agentic replacement | | --- | --- | | `discovery.py` + `parsers/*` + `parsers/linker.py` | `common/tools/discover_artifacts.py` (deterministic) | | `agent.py` — 4 Bedrock Strands agents | 4 Claude subagents driven by `common/methodology/*.md` | | `pipeline.py` `run_pipeline()` | the `/traceability` skill orchestrator | | `graph.py` + `analysis.py` + `generators/{markdown,html}.py` | `common/tools/build_matrix.py` (deterministic) | | `cli.py` (Click) | IDE invocation + `install.sh` | | `models.py` (pydantic), networkx, jinja2, rich, boto3 | replaced by stdlib (dataclasses-free dicts, hand-rolled graph + HTML) | The subagents do the relationship reasoning that used to run on Bedrock; the two Python tools do the parsing, graph math, and formatting so coverage numbers and report layout stay exact and reproducible. **Single source of truth.** The `common/` tools, methodology, and config are reused **verbatim** by every IDE packaging; only the orchestration wrapper differs. For Claude the installer composes a thin frontmatter head + methodology into each subagent; Kiro reads the same methodology files directly from its single agent loop. So the methodology never drifts between IDEs. ## Install From the repository root, pick your assistant: ```bash # Claude Code → ./.claude (skill + subagents, parallel bridges) ./install.sh --ide claude # Kiro → ./.kiro (steering doc + agent, sequential bridges) ./install.sh --ide kiro # GitHub Copilot → ./.github (custom agent + prompt, sequential bridges) ./install.sh --ide copilot # Codex → ./.codex + root AGENTS.md (orchestrator, sequential bridges) ./install.sh --ide codex # common flags ./install.sh --ide --dry-run # preview file operations, write nothing ./install.sh --ide --dest # install to a custom location ``` Then: - **Claude Code** — run `/traceability ` (restart the session to pick up the new skill/agents). - **Kiro** — ask "generate a traceability matrix", or `kiro-cli chat --agent traceability`. See [`kiro/README.md`](kiro/README.md). - **GitHub Copilot** — in Copilot Chat (agent mode) run `/traceability`, or in the Copilot CLI use the `AIDLC Traceability` agent. See [`copilot/README.md`](copilot/README.md). - **Codex** — ask "generate a traceability matrix" (the root `AGENTS.md` routes to the orchestrator). See [`codex/README.md`](codex/README.md). Point any of them at a project containing `aidlc-docs/` (source may be nested under a `workspace/` wrapper — discovery finds it). ## Supported assistants - **Claude Code** — implemented. `/traceability` skill + 5 subagents; spec-layer bridges dispatched sequentially (rate-limit safe), `* → code` last. - **Kiro** — implemented. Steering doc + agent manifest; the single agent loop applies each bridge methodology itself, in chain order (no subagent fan-out). - **GitHub Copilot** — implemented. Reusable `/traceability` prompt (`mode: agent`) + a minimal always-on instructions pointer; single agent loop, bridges run sequentially. - **Codex** — implemented. Minimal root `AGENTS.md` pointer + an on-demand orchestrator (`.codex/traceability/traceability.md`); single agent loop, bridges run sequentially. Shares `AGENTS.md` with the Copilot CLI. ## Run without AI (rule-based only) Set `enable_ai_analysis: false` in `.claude/traceability/trace-config.yaml`, or tell the skill `--no-ai`. The matrix is then built from the explicit unit→story links and the heuristic requirement→story links that `discover_artifacts.py` finds, skipping the four subagents — the analogue of the original CLI's `--no-ai` flag. ## Operational notes - **Fresh session per batch.** Each bridge reads many files; a large session context plus parallel fan-out can trip account-level rate limits (HTTP 429). Bridges are dispatched sequentially, but still run only a few projects per session and start a new session between batches to keep context small. - **Temp-file hygiene.** Intermediate JSON (discovery corpus, per-bridge output, report payload) is written to `/tmp` with **run-unique names keyed to the run timestamp** (`/tmp/trace--*.json`). A fixed name could be re-read from a previous run and corrupt the corpus. If you ever drive the tools by hand, use a unique name (or `mktemp`). The `/tmp` files are scratch; the reports under `aidlc-docs/traceability/` are the deliverable. - **Model matters for Copilot.** The bridging is multi-step reasoning; on weak models it over-links. Use Claude Haiku or stronger — see [`copilot/README.md`](copilot/README.md). ## Smoke test `smoke_test.sh` runs both stdlib tools against the bundled full-chain fixture (`test_data/proj`) and asserts the expected active chain and coverage. No AI, no network — a pure determinism check. Run it after editing either tool: ```bash ./smoke_test.sh # exits non-zero on any mismatch ``` ## Reproducibility `build_matrix.py` is the source of truth for the five coverage layers, gap detection, and report layout — the model never computes coverage by hand. Given the same artifacts + relationships JSON, it always produces byte-identical reports. Both tools are standard-library-only and run under any Python 3.10+. ## Security See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for how to report a potential security issue. ## License This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.