Copilot packaging

GitHub Copilot packaging for the agentic traceability tool. Reuses ../common/ verbatim (deterministic tools, methodology, config); only the orchestration wrapper differs. Status: implemented.

⚠️ REQUIRED: use the Claude Haiku model (or stronger)

Before running, switch the Copilot model to Claude Haiku (in the CLI: /model → pick a Claude Haiku model; in the IDE: the model picker).

The traceability run is a multi-step reasoning task (read each requirement, reason about which specific files implement it). On weaker/default models (e.g. gpt-5-mini) the agent over-links — it keyword-matches and maps almost every requirement to almost every file, producing a "100% coverage" matrix that is actually noise (one observed run: 133 edges where ~23 are correct). On Haiku the same agent, tools, and methodology produce a tight, correct matrix (each requirement → the 1–2 files that implement it).

The deterministic tools and structural guards are model-independent and always run; only the relationship-bridging quality depends on the model. For high-fidelity traces use Haiku or a stronger Claude model.

Install

From the repository root:

./install.sh --ide copilot

This writes the install target under .github/ and a repo-root AGENTS.md (both gitignored, regenerated). Re-run after editing anything in ../common/ or copilot/.

install.sh --ide copilot produces:

• ../common/tools/* → .github/traceability/tools/
• ../common/methodology/* → .github/traceability/methodology/
• common/trace-config.yaml → .github/traceability/trace-config.yaml
• copilot/agents/traceability.agent.md → .github/agents/traceability.agent.md
• copilot/prompts/traceability.prompt.md → .github/prompts/traceability.prompt.md
• copilot/copilot-instructions.md → .github/copilot-instructions.md
• copilot/AGENTS.md → AGENTS.md (repo root, non-clobbering)

Run

1. Switch the model to Claude Haiku (see the warning above) — this is not optional for usable output.

2. Select the agent and give it a project path:

Surface	How
Copilot CLI	copilot --agent="AIDLC Traceability" --prompt "build the trace matrix for <project-path>" — or start copilot, run /agent and pick AIDLC Traceability, then ask in natural language.
VS Code Copilot Chat (agent mode)	pick AIDLC Traceability from the agent picker, or run the /traceability prompt (requires the prompt-files feature enabled).

Point it at a project root containing aidlc-docs/ (the source may be nested under a workspace/ wrapper — discovery finds it). Approve the terminal (runCommands) prompts so the two Python tools can run; they are stdlib-only and need no pip and no AWS.

Reports are written to <project>/aidlc-docs/traceability/traceability-matrix-<stamp>.{md,html}.

Verifying a good run

A correct run shows these tells; anything else means it went wrong:

• The report is stamped v1.0 (Copilot) (any other tool_version ⇒ the agent hand-built the matrix instead of running build_matrix.py — a failed run).
• It ran .github/traceability/tools/discover_artifacts.py then build_matrix.py — and never python -m traceability.cli, pip install, or aws.
• Each requirement traces to a small set of files (the ones that implement it), not to nearly all of them. Broad fan-out = over-linking ⇒ you're on a weak model; switch to Haiku and re-run.

If build_matrix.py exits with code 3 ("0 relationships across a multi-layer chain"), the agent skipped bridging — re-run; the guard is forcing it to do the work rather than emit an empty matrix.

How it works

GitHub Copilot has no dedicated config dir — it reads .github/ (and a repo-root AGENTS.md). The tool is packaged as a first-class custom agent plus pointers:

• .github/agents/traceability.agent.md — the AIDLC Traceability custom agent. Its body is the full self-contained orchestration (discovery → active chain → sequential bridges via the methodology files → validate/merge → build_matrix.py). It is always-AI: it always bridges and never hand-builds the matrix. Primary artifact for both CLI and IDE.
• .github/prompts/traceability.prompt.md — the /traceability reusable prompt for VS Code Copilot Chat.
• AGENTS.md (repo root) + .github/copilot-instructions.md — always-on pointers that route "traceability" requests to the agent and forbid the retired coded traceability.cli, which CLI agents might otherwise discover (e.g. in git history) and run.

Key difference from Claude: single agent loop, no subagent fan-out — the bridges run sequentially in chain order, the agent applying each methodology itself and accumulating relationships into one payload for build_matrix.py. The deterministic tools and methodology are identical to every other IDE.

Source vs. install target

This copilot/ folder is source (tracked). The installer writes the targets under .github/ and the root AGENTS.md (gitignored, regenerated). Any pre-existing unrelated .github/ content (workflows, etc.) is left untouched, and a pre-existing root AGENTS.md that isn't ours is not clobbered (a sidecar AGENTS.traceability.md is written instead, to merge).