CodexModule

Create or review Forge modules so they work reliably in Codex.

Reference: Core/docs/CodexModuleCompatibility.md

Workflow Routing

Instructions

Step 1: Select workflow and scope

Identify:

1. •target module path
2. •workflow (scaffold or audit)
3. •whether to include tests/docs updates in the same change

Scaffold Workflow

Use this when Codex compatibility artifacts are missing or incomplete.

Step S1: Scaffold module essentials

Ensure module has:

• •module.yaml with accurate events
• •skills/<SkillName>/SKILL.md with valid frontmatter
• •optional runtime scripts/binaries only when behavior requires them

Step S2: Scaffold Codex-facing compatibility

Create or update:

• •skill descriptions with explicit USE WHEN triggers
• •fallback behavior for Claude-specific primitives (for example AskUserQuestion)
• •tool-agnostic shell env resolution (FORGE_MODULE_ROOT, fallback CLAUDE_PLUGIN_ROOT)

Step S3: Scaffold verification coverage

Create or update module verification checks for:

• •skill discovery via bash Core/bin/list-skills.sh
• •Codex adapter sync via bash Core/bin/forge-update.sh --platform codex
• •dangling symlink check:

find "$CODEX_HOME/skills" -type l ! -exec test -e {} \; -print

Step S4: Scaffold-safe adapter rules

If touching Adapters/codex/install.sh, enforce:

1. •preserve unmanaged directories
2. •manage only .forge-source directories
3. •remove managed symlinks before relinking companions
4. •keep updates idempotent
5. •never write undocumented Codex config.toml keys

Audit Workflow

Use this for compatibility reviews without broad feature work.

Step A1: Check structural compatibility

Verify module contains:

• •module.yaml with accurate events
• •skills/<SkillName>/SKILL.md files with valid frontmatter
• •hooks and binaries only where required

Step A2: Check skill runtime portability

For each skill:

1. •Ensure description includes USE WHEN triggers.
2. •Check for Claude-only hard dependencies.
3. •Keep strict requirements (for example MUST use AskUserQuestion) and add equivalent fallback for runtimes where the primitive is unavailable.
4. •Prefer FORGE_MODULE_ROOT with CLAUDE_PLUGIN_ROOT fallback in shell snippets.

Step A3: Check Codex adapter impact

If work touches Adapters/codex/install.sh:

1. •Preserve unmanaged directories.
2. •Manage only .forge-source directories.
3. •Remove managed symlinks before relinking companions.
4. •Keep updates idempotent.
5. •Do not write undocumented Codex config.toml keys.

Step 2: Verify end-to-end

Run:

make check
bash Core/bin/forge-update.sh --platform codex
bash Core/bin/list-skills.sh

If module has Rust:

cargo test --manifest-path Modules/<module>/Cargo.toml

Then check Codex skill links:

find "$CODEX_HOME/skills" -type l ! -exec test -e {} \; -print

No output means no dangling symlinks.

Step 3: Report findings

Provide:

1. •workflow used (scaffold or audit)
2. •compatibility verdict (compatible, compatible with caveats, not compatible)
3. •files created/updated (scaffold) or issues found (audit)
4. •commands run and key outcomes
5. •any follow-up tasks

Constraints

• •Do not assume Codex supports Claude hook schema/config keys.
• •Treat Codex compatibility as skill-first unless documented runtime hooks exist.
• •Keep changes narrow: fix compatibility defects without unrelated refactors.