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/.

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, <tool-repo> is this repository and <project> 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 <project>/aidlc-docs/traceability/traceability-matrix-<timestamp>.{md,html}.

The install is self-contained: each assistant runs the tools/methodology copied into <project> — no dependency on <tool-repo> at run time, and no pip/AWS.

Claude Code

cd <project> && <tool-repo>/install.sh --ide claude
claude          # restart/new session so the skill + agents register
# then, in the session:
/traceability <project>

Kiro

cd <project> && <tool-repo>/install.sh --ide kiro
kiro-cli chat --agent traceability
# then ask: generate a traceability matrix for <project>

GitHub Copilot (run on a Claude-class model — the bridging is multi-step reasoning)

cd <project> && <tool-repo>/install.sh --ide copilot
copilot --agent="AIDLC Traceability" --prompt "generate a traceability matrix for <project>"
# or in VS Code Copilot Chat (agent mode): run /traceability

Codex

cd <project> && <tool-repo>/install.sh --ide codex
codex
# then ask: generate a traceability matrix for <project>
# (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 for flags (--dry-run, --dest) and per-IDE details.

Layout

This solution lives at the repository root.

.
├── 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:

# 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 <name> --dry-run        # preview file operations, write nothing
./install.sh --ide <name> --dest <dir>     # install to a custom location

Then:

• Claude Code — run /traceability <project-path> (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.
• GitHub Copilot — in Copilot Chat (agent mode) run /traceability, or in the Copilot CLI use the AIDLC Traceability agent. See copilot/README.md.
• Codex — ask "generate a traceability matrix" (the root AGENTS.md routes to the orchestrator). See 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-<YYYYMMDD-HHMMSS>-*.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.

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:

./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 for how to report a potential security issue.

License

This library is licensed under the MIT-0 License. See the LICENSE file.