Codex
Install ADLC as a native Codex plugin with skills, lifecycle hooks, MCP gate tools, and project-scoped agents.
ADLC in Codex
The Codex integration is a native plugin, not a Claude compatibility shim. It
ships six progressive-disclosure skills, hooks across eight Codex lifecycle
events, an allowlisted MCP gate server, and nine project-agent templates. ADLC
evidence under .adlc/ remains the source of truth.
Install
ADLC releases the CLI and Codex plugin package in lockstep. Use @adlc/cli
1.4.2 or newer so the adlc mcp-server entrypoint is available. Codex installs
the native plugin through its Git marketplace; installing @adlc/codex with npm
alone does not register the plugin with Codex.
npm install -g @adlc/cli@latest
codex plugin marketplace add voodootikigod/adlc --ref main
codex plugin add adlc-codex@adlc
adlc init --root /absolute/path/to/projectThe initializer is idempotent. It creates the committable .adlc/ runtime and
current .codex/agents/*.toml project roles without modifying ~/.codex or
overwriting project-owned files. Start a new Codex thread after installation and
review the bundled hooks when Codex prompts you.
If an older compatibility install is producing a translated
PostToolUse hook exited with code 1 error, remove it and install the native
plugin:
codex plugin remove adlc@plugins-cli
codex plugin add adlc-codex@adlcNative surfaces
| Surface | What ships |
|---|---|
| Skills | $adlc, $adlc-init, $adlc-spec, $adlc-rail-build, $adlc-prosecute, $adlc-distill |
| Hooks | Session start, pre/post tool use, pre/post compact, subagent start/stop, and stop |
| MCP | adlc_gate for an allowlisted, non-shell gate invocation and adlc_prosecute for explicit prosecution |
| Agents | Project-scoped explorer, reviewer, and verifier roles, plus the five-lens P5 prosecution fan-out (correctness, security, contract, diff, tests) and its independent verifier — all created by $adlc-init |
The MCP gate tool exposes a deliberately small read-only allowlist, requires
--prompt-only for generative gates, and rejects path escapes, control
characters, mutating flags, and nested-command/provider arguments. Commands are
executed without a shell. The MCP transport launches the stable CLI entrypoint
adlc mcp-server and preserves the active project directory; it does not depend
on plugin-root placeholder expansion. Lifecycle hooks separately use Codex's
PLUGIN_ROOT and PLUGIN_DATA contracts.
Rail enforcement
The PreToolUse hook automatically arms when .adlc/current-ticket.json
selects an incomplete ticket with frozen rails. ADLC_TICKET can select a
ticket explicitly. ADLC_P4_ENFORCEMENT=1 forces enforcement and
ADLC_P4_ENFORCEMENT=0 deliberately opts out locally.
Once active, conflicting or stale ticket state and writes to frozen rails fail
closed. The hook gives immediate feedback, but Codex hooks are guardrails, not a
complete security boundary. Keep the repository rails-guard CI job required;
it is the authoritative proof over the committed diff.
PostToolUse only tracks repeated failures. Its implementation catches internal
errors and exits successfully, so telemetry cannot break a Codex tool call.
Update, inspect, and remove
npm install -g @adlc/cli@latest
codex plugin marketplace upgrade adlc
codex plugin add adlc-codex@adlc
codex plugin list --json --available
codex plugin remove adlc-codex@adlcUpgrade the CLI and marketplace plugin together, then start a new Codex thread so the refreshed MCP transport is loaded.
Maintainers can run the offline contract and the isolated live install proof:
node scripts/codex-install-smoke.mjs .
ADLC_CODEX_LIVE_INSTALL=1 node scripts/codex-install-smoke.mjs .The live proof uses throwaway home/config/cache directories, installs through the real Codex marketplace commands, starts the MCP server declared by the installed plugin, makes a successful tool call, exercises the installed hook, and verifies that the user's real home is unchanged.
Phase routing
| ADLC phase | Codex entry point | Deterministic evidence |
|---|---|---|
| P0 | $adlc | adlc preflight --json |
| P1–P2 | $adlc-spec | spec-lint, premortem, coldstart, router/forecast results |
| P3–P4 | $adlc-rail-build | hollow-test, rails-guard, phase manifest |
| P5–P6 | $adlc-prosecute | prosecution, behavior diff, and acceptance evidence |
| P7 | $adlc-distill | foundry, rejection-mining, rot, and ratchet results |
Source: plugins/adlc-codex/
· design rationale: ADR 0001.
Claude Code
Adopt the ADLC inside Claude Code with a phase-routing skill, gate commands, a prosecutor subagent, and hooks that fire the gates automatically.
Cursor
Native ADLC integration for Cursor: marketplace plugin with sessionStart context, preToolUse rails, packaged prosecutor agents + MCP wrapper (channel unverified), /adlc-* commands, and CI as the backstop.