feat: Codex CLI plugin support (manifest, agent generation, skills)

[lukeinglis]

Summary

Closes #392

• Add .codex-plugin/plugin.json manifest with MCP server reference
• Extend factory/agents/plugin.py with TOML agent generation (generate_codex_agent_toml())
• Add --runner codex flag to factory install (writes to ~/.codex/agents/)
• Create .agents/skills/ directory with 5 Codex skill definitions
• Create AGENTS.md (cross-tool instruction file)
• Create docs/codex-mcp.md (MCP setup documentation for Codex users)
• Update scripts/sync_agents.py to generate both Markdown + TOML formats
• Add 22 new tests (46 total in test_plugin_agents.py)

Review notes

• TOML generation uses literal strings (''') to avoid escape injection
• Sandbox mode mapping is fail-closed (ValueError on unknown roles)
• Description escaping handles backslashes and control characters
• Skills path in plugin.json points to ../.agents/skills/

Test plan

• uv run pytest tests/test_plugin_agents.py -v passes (46 tests)
• factory install --runner codex writes TOML files to ~/.codex/agents/
• factory install --runner claude still works (backwards compatible)
• Generated TOML files parse correctly

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.38%. Comparing base (8097461) to head (d82c6b2).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #395      +/-   ##
==========================================
+ Coverage   87.31%   87.38%   +0.07%     
==========================================
  Files          61       61              
  Lines        9339     9396      +57     
==========================================
+ Hits         8154     8211      +57     
  Misses       1185     1185              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[xukai92]

Review: Align with the Claude Code plugin pipeline

The core code (TOML generation, sandbox mapping, install command, tests) is well-executed — nice work. But the PR diverges from how the Claude Code plugin pipeline works in several structural ways. The goal should be: same pattern, different format.

1. Generated TOML files should NOT be on main — use the plugin branch

The Claude pipeline generates agents/*.md via CI and pushes them to the plugin branch. They never land on main. This PR checks 9 generated TOML files (~4800 lines) directly into main under codex-agents/.

Fix: Remove codex-agents/ from this PR. Update .github/workflows/plugin.yml to also git add -f codex-agents/ alongside agents/ when pushing to the plugin branch. The sync script already generates both formats — CI just needs to include both in the push.

# In the "Push to plugin branch" step:
git add -f agents/ codex-agents/

2. Skills duplication — .agents/skills/ is a full copy of skills/

The 5 skill files under .agents/skills/ are copies of the existing skills/ directory. There's no mechanism to keep them in sync — they'll drift.

Fix: Either:

• (Preferred) Symlink .agents/skills → skills so Codex discovers them at its conventional path, or
• Have CI copy skills/ → .agents/skills/ on the plugin branch, same as agent files

Don't maintain two copies of the same files on main.

3. AGENTS.md has a factual error and will drift from CLAUDE.md

Line 54 lists "Refiner" as an agent role — there is no Refiner in agents.yml. The 9 roles are: researcher, strategist, builder, reviewer, evaluator, archivist, distiller, failure_analyst, ceo.

More broadly, AGENTS.md is a hand-written subset of CLAUDE.md with no generation mechanism. It will go stale.

Fix: Either:

• Generate AGENTS.md from CLAUDE.md in CI (strip architecture details, keep build/test/lint/style), or
• Symlink AGENTS.md → CLAUDE.md (both tools read the same format), or
• At minimum, fix the "Refiner" typo and add a comment noting it should be kept in sync with CLAUDE.md

4. .codex-plugin/plugin.json — skills path points to .agents/skills/ which depends on #2

The manifest has "skills": "../.agents/skills/". This only works if .agents/skills/ exists and is kept in sync. If you go with the symlink approach for #2 this resolves itself; if you go with CI-only, then .codex-plugin/ also belongs on the plugin branch.

For reference, the Claude plugin manifest (.claude-plugin/plugin.json) has no "skills" key — Claude Code discovers skills from the skills/ directory by convention.

5. check_codex_agents_in_sync(None) silently returns []

The Markdown version check_agents_in_sync(None) falls back to a default _PLUGIN_AGENTS_DIR. The Codex version returns [] (always passes) when agents_dir is None. This is fine at the script level since sync_agents.py always passes an explicit dir, but the function API is asymmetric. Consider giving it a default _CODEX_AGENTS_DIR too, or documenting why it differs.

---

Summary

The Python code (plugin.py, cli.py, tests) is solid. The structural issues are about aligning with the existing pipeline:

1. Generated files → plugin branch, not main
2. Skills → single source of truth (symlink or CI copy)
3. AGENTS.md → fix "Refiner", add sync mechanism
4. Update CI workflow to include Codex artifacts in the plugin branch push

After these changes, sync_agents.py generates both formats, CI publishes both to plugin, and factory install --runner codex pulls from the same source — clean parity.

[lukeinglis]

@xukai92 Thanks for the thorough review — all 5 items addressed in d92f458:

1. Generated TOML files removed from main — codex-agents/ deleted, added to .gitignore. CI workflow updated to git add -f codex-agents/ alongside agents/ on the plugin branch only.

2. Skills duplication resolved — .agents/skills/ copies removed. CI now copies skills/ → .agents/skills/ during plugin branch generation. Single source of truth on main.

3. AGENTS.md fixed — "Refiner" replaced with "Failure Analyst". Added <!-- Keep in sync with CLAUDE.md --> comment at top.

4. plugin.json skills path — Changed from ../.agents/skills/ to ../skills/.

5. check_codex_agents_in_sync default dir — Added _CODEX_PLUGIN_AGENTS_DIR with same fallback pattern as the Claude version.

[xukai92]

All 5 items from the previous review are addressed. The pipeline is now aligned:

• Generated files (codex-agents/, .agents/skills/) stay off main, published to plugin branch via CI
• Skills path in .codex-plugin/plugin.json corrected to ../skills/
• AGENTS.md fixed ("Refiner" → "Failure Analyst") with sync reminder comment
• check_codex_agents_in_sync now has a default dir fallback matching the Claude version
• CI workflow updated to copy skills and push both formats

One nit (non-blocking): _WORKSPACE_WRITE_ROLES in plugin.py still contains "refiner" which isn't a real role in agents.yml. It's harmless (never matched by load_agent_config()), but worth removing to avoid confusion — the same Refiner ghost that was in AGENTS.md.

LGTM otherwise.

[lukeinglis]

@xukai92 Good catch. Removed "refiner" from _WORKSPACE_WRITE_ROLES in the latest push.

Thanks for the review!