feat: Support Codex CLI as integration target

CHANGELOG.md

@@ -10,11 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Support Codex CLI as integration target with skills (`.agents/skills/`), agents (`.codex/agents/*.toml`), and hooks (`.codex/hooks.json`) (#504)
 - Marketplace integration for plugin discovery and governance: `apm marketplace add/list/browse/update/remove` commands, `apm search QUERY@MARKETPLACE` scoped search, `apm install NAME@MARKETPLACE` syntax for installing plugins from marketplace registries; lockfile provenance fields `discovered_via` and `marketplace_plugin_name` to track marketplace origin; support for Copilot CLI and Claude Code `marketplace.json` formats with 4 source types (github, url, git-subdir, relative path) (#503)
 
 ### Fixed
 
 - `apm install -g ./local-pkg` now rejects local path dependencies at user scope with a clear error instead of silently failing (relative paths resolve against `cwd` during validation but against `$HOME` during copy) (#452)
+
 ### Changed
 
 - `apm deps update` now skips download and integration for packages whose resolved SHA matches the lockfile SHA, making the common "nothing changed" case near-instant (#495)

README.md

@@ -4,7 +4,7 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode
+GitHub Copilot · Claude Code · Cursor · OpenCode · Codex
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)**
 

docs/src/content/docs/guides/compilation.md

@@ -4,7 +4,7 @@ sidebar:
   order: 1
 ---
 
-Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For OpenCode, `apm install` deploys agents, commands, skills, and MCP, but instructions require `apm compile` to generate the `AGENTS.md` that OpenCode reads. `apm compile` is also needed for Codex, Gemini, or other tools that read single-root-file formats.
+Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For OpenCode, `apm install` deploys agents, commands, skills, and MCP, but instructions require `apm compile` to generate the `AGENTS.md` that OpenCode reads. For Codex, `apm install` deploys skills, agents, and hooks natively, but instructions require `apm compile`. `apm compile` is also needed for Gemini or other tools that read single-root-file formats.
 
 **Solving the AI agent scalability problem through constraint satisfaction optimization**
 
@@ -22,34 +22,37 @@ When you run `apm compile` without specifying a target, APM automatically detect
 |-------------------|--------|---------------------|
 | `.github/` folder only | `copilot` | AGENTS.md (instructions only) |
 | `.claude/` folder only | `claude` | CLAUDE.md (instructions only) |
+| `.codex/` folder exists | `codex` | AGENTS.md (instructions only) |
 | Both folders exist | `all` | Both AGENTS.md and CLAUDE.md |
 | Neither folder exists | `minimal` | AGENTS.md only (universal format) |
 
 ```bash
 apm compile                    # Auto-detects target from project structure
-apm compile --target copilot   # Force GitHub Copilot, Cursor, Codex, Gemini
+apm compile --target copilot   # Force GitHub Copilot, Cursor, Gemini
+apm compile --target codex     # Force Codex CLI
 apm compile --target claude    # Force Claude Code, Claude Desktop
 ```
 
 You can set a persistent target in `apm.yml`:
 ```yaml
 name: my-project
 version: 1.0.0
-target: copilot  # or vscode, claude, or all
+target: copilot  # or vscode, claude, codex, or all
 ```
 
 ### Output Files
 
 | Target | Files Generated | Consumers |
 |--------|-----------------|-----------|
-| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode, Codex, Gemini |
+| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode, Gemini |
+| `codex` | `AGENTS.md` | Codex CLI |
 | `claude` | `CLAUDE.md` | Claude Code, Claude Desktop |
 | `all` | Both `AGENTS.md` and `CLAUDE.md` | Universal compatibility |
 | `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
 
 > **Aliases**: `vscode` and `agents` are accepted as aliases for `copilot`.
 
-> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, and `.opencode/commands/`.
+> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, `.opencode/commands/`, `.codex/agents/`, and `.agents/skills/`.
 
 ### How It Works
 
@@ -436,10 +439,10 @@ Different AI tools get different levels of support from `apm install` vs `apm co
 | Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
 | Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json` | `AGENTS.md` (optional) | **Full** |
 | OpenCode | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP) | Via `AGENTS.md` | **Full** |
-| Codex CLI | -- | `AGENTS.md` | Instructions via compile |
+| Codex CLI | `.agents/skills/`, `.codex/agents/`, `.codex/hooks.json` | `AGENTS.md` (instructions) | **Full** |
 | Gemini | -- | `GEMINI.md` | Instructions via compile |
 
-For Copilot, Claude, and Cursor users, `apm install` handles everything natively. OpenCode users should also run `apm compile` to generate `AGENTS.md` for instructions. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
+For Copilot, Claude, and Cursor users, `apm install` handles everything natively. OpenCode and Codex users should also run `apm compile` to generate `AGENTS.md` for instructions. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
 
 ## Theoretical Foundations
 

docs/src/content/docs/guides/skills.md

@@ -51,7 +51,8 @@ APM copies skills to every detected target directory:
 | **No SKILL.md and no primitives** | No skill folder created |
 
 **Target Detection:**
-- Recognized directories: `.github/`, `.claude/`, `.cursor/`, `.opencode/`
+- Recognized directories: `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`
+- Codex skills deploy to `.agents/skills/` (agent skills standard directory), not `.codex/skills/`
 - If none exist, `.github/` is created as the fallback
 - Override with `--target`
 
@@ -286,7 +287,7 @@ APM automatically detects package types:
 
 ## Target Detection
 
-APM deploys skills to every target directory that already exists: `.github/`, `.claude/`, `.cursor/`, `.opencode/`. If none exist, `.github/` is created as the fallback.
+APM deploys skills to every target directory that already exists: `.github/`, `.claude/`, `.cursor/`, `.opencode/`. For Codex (`.codex/`), skills deploy to `.agents/skills/` instead. If no target directories exist, `.github/` is created as the fallback.
 
 Override with:
 ```bash

docs/src/content/docs/index.mdx

@@ -26,7 +26,7 @@ APM fixes this. You declare your project's agent configuration once in `apm.yml`
 
 <CardGrid>
   <Card title="One Manifest, Every Agent" icon="document">
-    `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers — deployed to Copilot, Claude Code, Cursor, and OpenCode from a single source of truth.
+    `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers — deployed to Copilot, Claude Code, Cursor, OpenCode, and Codex from a single source of truth.
   </Card>
   <Card title="Dependencies That Resolve" icon="random">
     Packages depend on packages. APM resolves the full tree — transitive dependencies just work, like npm or pip.
@@ -92,7 +92,7 @@ New developer joins the team:
 git clone <org/repo> && cd <repo> && apm install
 ```
 
-**That's it.** Copilot, Claude, Cursor, OpenCode — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
+**That's it.** Copilot, Claude, Cursor, OpenCode, Codex — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
 
 ## Open Source & Community
 

docs/src/content/docs/integrations/ide-tool-integration.md

@@ -34,7 +34,7 @@ When using Spec-kit for Specification-Driven Development (SDD), APM automaticall
 # 1. Set up APM contextual foundation
 apm init my-project && apm install
 
-# 2. Optional: compile for tools without native integration (Codex, Gemini)
+# 2. Optional: compile for Codex/OpenCode instructions, Gemini, etc.
 # Spec-kit constitution is automatically included in compiled AGENTS.md
 apm compile
 
@@ -150,7 +150,7 @@ apm install microsoft/apm-sample-package
 
 ### Optional: Compiled Context with AGENTS.md
 
-For tools that do not support granular primitive discovery (such as Codex or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode also reads `AGENTS.md`, so run `apm compile` to deploy instructions there.
+For tools that do not support granular primitive discovery (such as Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode and Codex also read `AGENTS.md`, so run `apm compile` to deploy instructions there.
 
 ```bash
 # Compile all local and dependency instructions into AGENTS.md
@@ -213,6 +213,19 @@ APM natively integrates with OpenCode when a `.opencode/` directory exists in yo
 | `.cursor/hooks/{pkg}/` | Referenced hook scripts |
 | `.cursor/mcp.json` | MCP server configurations |
 
+#### Codex CLI (`.codex/`)
+
+| APM Primitive | Codex Destination | Format |
+|---|---|---|
+| Skills (`SKILL.md`) | `.agents/skills/{name}/SKILL.md` | Identical (agentskills.io standard) |
+| Agents (`.agent.md`) | `.codex/agents/*.toml` | Converted from Markdown to TOML |
+| Hooks (`.json`) | `.codex/hooks.json` + `.codex/hooks/{pkg}/` | Merged JSON config with `_apm_source` markers |
+| Instructions | Via `AGENTS.md` | Compile-only (`apm compile --target codex`) |
+
+**Setup**: Create a `.codex/` directory in your project root, then run `apm install`. APM detects the directory and deploys automatically.
+
+> **Note**: Skills deploy to `.agents/skills/` (the cross-tool agent skills standard directory), not `.codex/skills/`. Agents are transformed from `.agent.md` Markdown to `.toml` format.
+
 ### Automatic Agent Integration
 
 APM automatically deploys agent files from installed packages into `.claude/agents/`:
@@ -298,13 +311,14 @@ apm install anthropics/claude-plugins-official/plugins/hookify
 2. For VS Code: copies hook JSON to `.github/hooks/` and rewrites script paths
 3. For Claude: merges hook definitions into `.claude/settings.json` under the `hooks` key
 4. For Cursor: merges hook definitions into `.cursor/hooks.json` under the `hooks` key (only when `.cursor/` exists)
-5. Copies referenced scripts to the target location
-6. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
-7. `apm uninstall` removes hook files and cleans up merged settings
+5. For Codex: merges hook definitions into `.codex/hooks.json` under the `hooks` key (only when `.codex/` exists)
+6. Copies referenced scripts to the target location
+7. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
+8. `apm uninstall` removes hook files and cleans up merged settings
 
 ### Optional: Target-Specific Compilation
 
-Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode, run `apm compile` to generate `AGENTS.md` (OpenCode's instruction source). Also use it when targeting Codex or Gemini:
+Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode and Codex, run `apm compile` to generate `AGENTS.md` for instructions. Also use it when targeting Gemini:
 
 ```bash
 # Generate all formats (default)

docs/src/content/docs/introduction/why-apm.md

@@ -35,8 +35,8 @@ dependencies:
 Run `apm install` and APM:
 
 - **Resolves transitive dependencies** — if package A depends on package B, both are installed automatically.
-- **Integrates primitives** -- instructions, prompts, agents, and skills are deployed to `.github/`, `.claude/`, `.cursor/`, and `.opencode/` based on which directories exist. GitHub Copilot, Claude, Cursor, and OpenCode read these natively.
-- **Bridges other tools** — for Codex, Gemini, and other tools without native integration, `apm compile` generates compatible instruction files (`AGENTS.md`, `CLAUDE.md`).
+- **Integrates primitives** -- instructions, prompts, agents, and skills are deployed to `.github/`, `.claude/`, `.cursor/`, `.opencode/`, and `.codex/` based on which directories exist. GitHub Copilot, Claude, Cursor, OpenCode, and Codex read these natively.
+- **Bridges other tools** — for Gemini and other tools without native integration, `apm compile` generates compatible instruction files (`AGENTS.md`, `CLAUDE.md`).
 
 ## APM vs. Manual Setup
 

docs/src/content/docs/reference/cli-commands.md

@@ -87,7 +87,7 @@ apm install [PACKAGES...] [OPTIONS]
 - `--runtime TEXT` - Target specific runtime only (copilot, codex, vscode)
 - `--exclude TEXT` - Exclude specific runtime from installation
 - `--only [apm|mcp]` - Install only specific dependency type
-- `--target [copilot|claude|cursor|opencode|all]` - Force deployment to a specific target (overrides auto-detection)
+- `--target [copilot|claude|cursor|codex|opencode|all]` - Force deployment to a specific target (overrides auto-detection)
 - `--update` - Update dependencies to latest Git references  
 - `--force` - Overwrite locally-authored files on collision; bypass security scan blocks
 - `--dry-run` - Show what would be installed without installing
@@ -451,7 +451,7 @@ apm pack [OPTIONS]
 
 **Options:**
 - `-o, --output PATH` - Output directory (default: `./build`)
-- `-t, --target [copilot|vscode|claude|cursor|opencode|all]` - Filter files by target. Auto-detects from `apm.yml` if not specified. `vscode` is an alias for `copilot`
+- `-t, --target [copilot|vscode|claude|cursor|codex|opencode|all]` - Filter files by target. Auto-detects from `apm.yml` if not specified. `vscode` is an alias for `copilot`
 - `--archive` - Produce a `.tar.gz` archive instead of a directory
 - `--dry-run` - List files that would be packed without writing anything
 - `--format [apm|plugin]` - Bundle format (default: `apm`). `plugin` produces a standalone plugin directory with `plugin.json`
@@ -1084,7 +1084,7 @@ apm compile [OPTIONS]
 
 **Options:**
 - `-o, --output TEXT` - Output file path (for single-file mode)
-- `-t, --target [vscode|agents|claude|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
+- `-t, --target [vscode|agents|claude|codex|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
 - `--chatmode TEXT` - Chatmode to prepend to the AGENTS.md file
 - `--dry-run` - Preview compilation without writing files (shows placement decisions)
 - `--no-links` - Skip markdown link resolution
@@ -1104,22 +1104,24 @@ When `--target` is not specified, APM auto-detects based on existing project str
 |-----------|--------|--------|
 | `.github/` exists only | `vscode` | AGENTS.md + .github/ |
 | `.claude/` exists only | `claude` | CLAUDE.md + .claude/ |
+| `.codex/` exists | `codex` | AGENTS.md + .codex/ + .agents/ |
 | Both folders exist | `all` | All outputs |
 | Neither folder exists | `minimal` | AGENTS.md only |
 
 You can also set a persistent target in `apm.yml`:
 ```yaml
 name: my-project
 version: 1.0.0
-target: vscode  # or claude, opencode, or all
+target: vscode  # or claude, codex, opencode, or all
 ```
 
 **Target Formats (explicit):**
 
 | Target | Output Files | Best For |
 |--------|--------------|----------|
-| `vscode` | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor, Codex, Gemini |
+| `vscode` | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor, Gemini |
 | `claude` | CLAUDE.md, .claude/commands/, SKILL.md | Claude Code, Claude Desktop |
+| `codex` | AGENTS.md, .agents/skills/, .codex/agents/, .codex/hooks.json | Codex CLI |
 | `opencode` | AGENTS.md, .opencode/agents/, .opencode/commands/, .opencode/skills/ | OpenCode |
 | `all` | All of the above | Universal compatibility |
 

docs/src/content/docs/reference/manifest-schema.md

@@ -108,16 +108,17 @@ compilation:   <CompilationConfig>
 |---|---|
 | **Type** | `enum<string>` |
 | **Required** | OPTIONAL |
-| **Default** | Auto-detect: `vscode` if `.github/` exists, `claude` if `.claude/` exists, `all` if both, `minimal` if neither |
-| **Allowed values** | `vscode` · `agents` · `claude` · `all` |
+| **Default** | Auto-detect: `vscode` if `.github/` exists, `claude` if `.claude/` exists, `codex` if `.codex/` exists, `all` if both `.github/` and `.claude/`, `minimal` if neither |
+| **Allowed values** | `vscode` · `agents` · `claude` · `codex` · `all` |
 
-Controls which output targets are generated during compilation. When unset, a conforming resolver SHOULD auto-detect based on `.github/` and `.claude/` folder presence. Unknown values MUST be silently ignored (auto-detection takes over).
+Controls which output targets are generated during compilation. When unset, a conforming resolver SHOULD auto-detect based on `.github/`, `.claude/`, and `.codex/` folder presence. Unknown values MUST be silently ignored (auto-detection takes over).
 
 | Value | Effect |
 |---|---|
 | `vscode` | Emits `AGENTS.md` at the project root (and per-directory files in distributed mode) |
 | `agents` | Alias for `vscode` |
 | `claude` | Emits `CLAUDE.md` at the project root |
+| `codex` | Emits `AGENTS.md` and deploys skills to `.agents/skills/`, agents to `.codex/agents/` |
 | `all` | Both `vscode` and `claude` targets |
 | `minimal` | AGENTS.md only at project root. **Auto-detected only** — this value MUST NOT be set explicitly in manifests; it is an internal fallback when no `.github/` or `.claude/` folder is detected. |
 
@@ -378,7 +379,7 @@ The `compilation` key is OPTIONAL. It controls `apm compile` behaviour. All fiel
 
 | Field | Type | Default | Constraint | Description |
 |---|---|---|---|---|
-| `target` | `enum<string>` | `all` | `vscode` · `agents` · `claude` · `all` | Output target (same values as §3.6). Defaults to `all` when set explicitly in compilation config. |
+| `target` | `enum<string>` | `all` | `vscode` · `agents` · `claude` · `codex` · `all` | Output target (same values as §3.6). Defaults to `all` when set explicitly in compilation config. |
 | `strategy` | `enum<string>` | `distributed` | `distributed` · `single-file` | `distributed` generates per-directory AGENTS.md files. `single-file` generates one monolithic file. |
 | `single_file` | `bool` | `false` | | Legacy alias. When `true`, overrides `strategy` to `single-file`. |
 | `output` | `string` | `AGENTS.md` | File path | Custom output path for the compiled file. |