Add Codex compatibility layer for stepwise skills and agents - #12
Merged
Conversation
OpenAI Codex reads AGENTS.md and Claude Code reads CLAUDE.md; keeping them as a single source of truth (AGENTS.md) with a one-line pointer from CLAUDE.md avoids the drift that comes from maintaining two copies.
The four plugins already work under Claude Code. This commit lets the
same skill and agent sources run under OpenAI Codex without duplicating
content or maintaining a separate tree.
- codex/install.sh symlinks core/git/research skills into ~/.agents/skills
and copies the transpiled agents into ~/.codex/agents; the symlinks
keep repo edits visible to Codex immediately without reinstalling.
- codex/uninstall.sh removes only what install.sh created, so a
hand-installed skill or third-party agent survives.
- codex/transpile-agents.sh rewrites each agent .md as a Codex TOML;
the generated files under codex/agents/ are committed so users who
install from the marketplace don't need a working transpiler.
- Makefile gets install-codex, uninstall-codex, transpile-codex and
check-codex; check-codex is wired into ci so a stale TOML or a bare
${CLAUDE_PLUGIN_ROOT} in a SKILL.md fails the build.
- test/codex-test.sh covers the transpilation contract (name, tools,
developer instructions, model mapping, sandbox policy). Helpers gain
assert_equals and assert_fails for it.
- test/plugin-structure-test.sh gets the coverage that was missing for
the practice skills, review-pr-comments, and the whole research plugin.
- README.md and AGENTS.md document the Codex path and its limitations
(Codex doesn't expand $ARGUMENTS, and only delegates on explicit
instruction).
Every user-invoked skill (create-plan, iterate-plan, implement-plan, validate-plan, research-codebase, commit, review-pr-comments, deep-research) ships an agents/openai.yaml with allow_implicit_invocation: false. This mirrors the disable-model-invocation flag those skills already carry for Claude Code, so under Codex they only trigger when the user asks for them by name.
…Codex
Claude Code injects CLAUDE_PLUGIN_ROOT for every skill; Codex does not,
so shell lines like `bash ${CLAUDE_PLUGIN_ROOT}/skills/.../scripts/foo`
expanded to `bash /skills/.../scripts/foo` and blew up. Adding the
`:-$HOME/.agents` default resolves against the Codex install location
that install.sh always uses, and stays a no-op under Claude Code because
the variable is already set.
Users who install via `claude plugin marketplace add` never clone the repo themselves; the full tree (Makefile, codex/) lands in ~/.claude/plugins/marketplaces/stepwise-dev/ instead. Document both paths and call out that ~/.claude/plugins/cache/ is not usable for this since it only carries what each plugin.json declares.
main migrated every agent to `model: inherit` for Bedrock, which the transpiler rejected as an unknown model — merging the two branches left `make ci` failing on all nine agents. `inherit` is now just another entry in the model case, mapping to "pin nothing": a Codex agent with no `model` key runs on the session's configured model, which is what inherit means. The haiku/sonnet/opus mappings stay for an agent that deliberately pins one. Also: - derive the list of skills needing an `agents/openai.yaml` from their `disable-model-invocation` frontmatter, so a new opt-out skill that forgets the file fails instead of passing a hardcoded loop - `grep -qxE 'Write|Edit'`, since BRE alternation is a GNU/BSD extension - document uninstall.sh and the inherit mapping in AGENTS.md - minor bump on core, git and research for the openai.yaml files, with marketplace mirrored and patch-bumped Claude-Session: https://claude.ai/code/session_014PJwGSZGFY3JiP1cSetPER
Verified against codex-cli 0.148.0: an agent role TOML without a `model` key loads fine (the loader only requires name, description and developer_instructions), while `model: inherit` in a SKILL.md frontmatter makes the skill parser drop the annotation — not the skill. Claude-Session: https://claude.ai/code/session_014PJwGSZGFY3JiP1cSetPER
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an OpenAI Codex compatibility layer so the same skills and agents that already run under Claude Code also run under Codex, without duplicating content or forking the tree.
codex/directory withinstall.sh,uninstall.sh,transpile-agents.sh, and the nine generatedcodex/agents/*.toml(committed so marketplace installs don't need a working transpiler)~/.agents/skills/; agents copied into~/.codex/agents/\${CLAUDE_PLUGIN_ROOT}to\$HOME/.agentsso it resolves under both harnessesagents/openai.yaml(mirrors thedisable-model-invocationflag they already carry for Claude Code)make install-codex,uninstall-codex,transpile-codex,check-codextargets —check-codexis wired intociso a stale TOML or a bare\${CLAUDE_PLUGIN_ROOT}fails the buildtest/codex-test.shcovers the transpilation contract;test/plugin-structure-test.shpicks up the coverage that was missing for the practice skills,review-pr-comments, and the whole research pluginCLAUDE.mdbecomes a one-line pointer to a newAGENTS.md(single source of truth read by both Claude Code and Codex)Test plan
make cipasses (41 tests, shellcheck, TOML syntax,\${CLAUDE_PLUGIN_ROOT}fallback, manifest validation)codex/install.shinstalls 16 skills + 9 agents;codex/uninstall.shremoves only what was installed (idempotent)/stepwise-core:research-codebase,/stepwise-git:commit,/stepwise-research:deep-researchunder Codex and verify sub-agents are spawned via forked sessionsKnown limitations under Codex
research-codebase,create-plan,iterate-planuse\$ARGUMENTS, which Codex does not expand — pass the input in the message itselfallow_implicit_invocation: falseis unverified (it is documented for the ChatGPT desktop app)