Codex packaging

July 7, 2026 · View on GitHub

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

Like every single-agent-loop packaging, bridge precision depends on the host model. Use a capable model (e.g. Claude Haiku or stronger); weak models over-link. The deterministic tools and structural guards are model-independent.

Install

From the repository root:

./install.sh --ide codex

install.sh --ide codex produces:

  • ../common/tools/* → .codex/traceability/tools/
  • ../common/methodology/* → .codex/traceability/methodology/
  • common/trace-config.yaml → .codex/traceability/trace-config.yaml
  • codex/traceability.md → .codex/traceability/traceability.md
  • common/AGENTS.md → AGENTS.md (repo root; sidecar if a non-ours one exists)

Run

In Codex, ask in natural language:

generate a traceability matrix for <project-path>

Codex loads the repo-root AGENTS.md every session; it routes the request to the orchestrator (.codex/traceability/traceability.md), which discovers and parses aidlc-docs/ + source, bridges the present layers (Requirements → Stories → Units → Components → Code, skipping absent layers), and writes Markdown + HTML reports to <project>/aidlc-docs/traceability/. Approve the shell commands so the two stdlib Python tools can run — they need no pip and no AWS.

How it works

Codex loads AGENTS.md from the repo root every session, so that file is kept minimal — a pointer. The actual orchestration is read on demand:

  • AGENTS.md (repo root) — minimal always-on instruction routing "traceability" requests to the orchestrator, and forbidding the retired coded traceability.cli. Shared with the Copilot packaging (the two installers write the same file, so co-installation is idempotent).
  • .codex/traceability/traceability.md — the sequential orchestrator (discover → active chain → bridges via methodology → validate/merge → build report).

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 codex/ folder is source (tracked). The installer writes the targets (.codex/ and the root AGENTS.md), which are gitignored and regenerated. A pre-existing root AGENTS.md that isn't ours is left untouched (a sidecar AGENTS.traceability.md is written to merge).

Verifying a good run

  • Report stamped v1.0 (Codex) (any other tool_version ⇒ the matrix was hand-built instead of via build_matrix.py — a failed run).
  • Ran .codex/traceability/tools/{discover_artifacts,build_matrix}.py — never python -m traceability.cli, pip install, or aws.
  • Each requirement traces to a small set of files; broad fan-out ⇒ over-linking (weak model). build_matrix.py exits 3 if bridging was skipped (0 edges across a multi-layer chain).