refactor(install): prefer native plugin install across targets (#609)

Co-authored-by: John Cavanaugh <cavanaug@users.noreply.github.com>

docs/specs/codex.md

@@ -1,6 +1,6 @@
-# Codex Spec (Config, Prompts, Skills, MCP)
+# Codex Spec (Config, Prompts, Skills, Subagents, MCP)
 
-Last verified: 2026-01-21
+Last verified: 2026-04-19
 
 ## Primary sources
 
@@ -10,6 +10,7 @@ https://developers.openai.com/codex/config-advanced
 https://developers.openai.com/codex/custom-prompts
 https://developers.openai.com/codex/skills
 https://developers.openai.com/codex/skills/create-skill
+https://developers.openai.com/codex/subagents
 https://developers.openai.com/codex/guides/agents-md
 https://developers.openai.com/codex/mcp
 ```
@@ -49,10 +50,28 @@ https://developers.openai.com/codex/mcp
 - Required fields are single-line with length limits (name ≤ 100 chars, description ≤ 500 chars). citeturn3view4
 - At startup, Codex loads only each skill’s name/description; full content is injected when invoked. citeturn3view3turn3view4
 - Skills can be repo-scoped in `.agents/skills/` and are discovered from the current working directory up to the repository root. User-scoped skills live in `~/.agents/skills/`. citeturn1view1turn1view4
-- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as legacy compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
+- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
+- Compound Engineering should avoid `~/.agents/skills` for managed installs because that shared root can shadow Copilot's native plugin skills. Use the Codex-specific compatibility root `~/.codex/skills/compound-engineering/<skill-name>/SKILL.md` for CE Codex skills, and track generated files with a CE manifest.
 - Codex also supports admin-scoped skills in `/etc/codex/skills` plus built-in system skills bundled with Codex. citeturn1view4
 - Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
 
+## Subagents and custom agents
+
+- Codex subagent workflows are enabled by default in current releases.
+- Codex only spawns subagents when explicitly asked.
+- Custom agent files are standalone TOML files under `~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped agents.
+- Each TOML file defines one custom agent. Required fields:
+  - `name`
+  - `description`
+  - `developer_instructions`
+- Optional fields can include `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.
+- The TOML `name` field is the source of truth; matching the filename to the agent name is only a convention.
+- CE converts Claude Markdown agents into Codex custom-agent TOML files under `~/.codex/agents/compound-engineering/`.
+- CE keeps generated agents under `~/.codex/agents`, not `~/.agents/skills`, because `~/.agents` is shared across harnesses and can shadow native plugin installs.
+- Generated TOML agent names preserve CE's hyphenated naming and include the source category, such as `review-ce-correctness-reviewer` and `research-ce-repo-research-analyst`.
+- Empirical test on 2026-04-19 confirmed Codex discovers nested custom-agent TOML files under `~/.codex/agents/compound-engineering/` and accepts hyphenated TOML `name` values.
+- Empirical plugin test on 2026-04-19 found Codex native plugins did not register custom agents bundled under plugin-local `agents/`, plugin-local `.codex/agents/`, or an undocumented plugin manifest `agents` field. Therefore CE still needs the custom Bun Codex installer for agent-heavy workflows.
+
 ## MCP (Model Context Protocol)
 
 - MCP configuration lives in `~/.codex/config.toml` and is shared by the CLI and IDE extension. citeturn3view2turn3view5