Claude ↔ Codex Bridge Skill

Bidirectional alignment of a project's Claude Code and Codex CLI configuration. Detects what runtime artifacts exist, produces the missing side, surfaces drift, reports plugin availability across runtimes. Pure file-level operation; never edits skill content.

Auth Approach

No authentication required. Operates on the local filesystem only. Never makes network calls.

Tool Preference

1. Subagent dispatch (when available and permitted) for the reviewer phase only. You run scout and apply yourself: they run in order, each feeds the next, and the files they read are small, so a subagent would only add a handoff. The reviewer stays a fresh subagent so it checks work it did not do.
2. File read tools for loading prompt templates and reading project files.
3. Shell for filesystem operations (ln -s, mkdir -p, find, stat).
4. User confirmation tool for the manifest approval gate and policy decisions.

Platform Adaptation

Cursor: dispatch the reviewer with the Task tool and the same prompt.

When subagent dispatch is unavailable (no Agent, spawn_agent or Task tool) for the current request, run the reviewer inline too, and say in the final report that the review was not independent of the apply.

Workflow

Prompt file location (MUST check before every phase):

Before reading any phase prompt file, run:

echo "${RUNTIME_BRIDGE_SKILL_OVERRIDE:-}"

If the output is a non-empty path, read ALL prompt files (scout-prompt.md, apply-prompt.md, reviewer-prompt.md) from that directory instead of the bundled skill directory. This is the fault-injection override used by integration tests.

Step 1: Confirm scope and mode

If the user hasn't specified, ask one consolidated question: target directory (default: cwd) and dry-run vs full execution. Skip if both are obvious from context.

Step 2: Run SCOUT

Read scout-prompt.md and follow it yourself, read-only, with these inputs:

• repo_root: absolute path to the project root.
• recipes_path: absolute path to port-recipes.md.
• schema_path: absolute path to manifest-schema.md.

Scout produces a JSON manifest matching manifest-schema.md. Validate it parses (use jq empty or equivalent). If invalid, fix it once; if it still fails, surface the error to the user and do not continue.

Step 3: Present manifest, get approval

Render the manifest for the user:

• Direction (claude_to_codex / codex_to_claude / bidirectional_drift).
• Op count by kind.
• Each op with the source path, target path, and (for translates and drifts) the diff preview.
• Skip list with reasons.
• Plugin report bucketed (dual / Claude-only / Codex-only).
• Notes (free-form).
• If trust_warning is present: include the line "After apply, run codex once in this dir and accept the trust prompt; .codex/ artifacts no-op on untrusted projects."

For drift ops, ask the user to confirm the suggested canonical or pick the other side. If the user's original prompt already specifies a canonical-selection rule (for example "use the newer file as canonical"), apply that rule to all drift ops without re-asking per pair.

If dry-run: stop here. Print the manifest summary as the final report.

Otherwise: ask the user to approve the full op set. If approved, continue. If declined, stop.

Step 4: Run APPLY

Read apply-prompt.md and follow it yourself with these inputs:

• manifest: the approved manifest (with any user drift selections applied).
• recipes_path: absolute path to port-recipes.md.
• repo_root: absolute path.

Apply produces a JSON apply-log matching manifest-schema.md. Validate it parses.

Step 5: Dispatch REVIEWER

Read reviewer-prompt.md. Dispatch it as a fresh subagent, with no conversation history, and these arguments:

• manifest: the same manifest apply consumed.
• apply_log: what apply returned.
• recipes_path: absolute path to port-recipes.md.
• repo_root: absolute path.

Reviewer returns a verdict matching manifest-schema.md.

Step 6: Decide loop

If verdict is pass: go to Step 7.

If verdict has issues, classify:

• Any unauthorized_change issue: STOP. Print final report including the unauthorized change. Do not loop.
• Same issue (same kind + same op_index) appears two rounds in a row: STOP. Stalling.
• Issue requires user decision (drift the user already chose canonical for; translation key with no defensible default): STOP. Surface to user.
• Issue requires action apply cannot perform (mark project trusted in Codex; install a missing plugin): STOP. Surface to user.
• Otherwise (mechanical, in-scope): construct a focused manifest containing only the affected ops + the reviewer's suggested_fix text. Run APPLY again yourself on this focused manifest. Then dispatch a fresh REVIEWER again. Track issues across rounds for the stalling check.

No fixed iteration cap. Loop until pass or break condition.

Step 7: Final report

Print to user:

• Direction.
• Ops applied (success count, error count).
• Skips with reasons and suggested followups.
• Plugin report.
• Notes.
• Reviewer verdict.
• Outstanding issues (if any) with detail and suggested_fix verbatim.
• Trust gate reminder if .codex/ was written.

Invocation forms

• "Make this project work with codex too" triggers a Claude → Codex full run.
• "I want this codex project to also work in claude code" triggers a Codex → Claude full run.
• "My CLAUDE.md and AGENTS.md are out of sync" triggers bidirectional drift mode.
• "Is this project set up for both runtimes" implies dry-run.
• Add "dry run" or "preview only" to any of the above for dry-run mode.

Self-Healing

• Manifest fails to parse twice: surface the raw scout output to the user; suggest re-running.
• Apply errors on a specific op (e.g. EACCES): logged in apply-log, reviewer surfaces as missing, orchestrator stops with outstanding issue.
• Reviewer disagrees with apply but issue kind is unclear: surface verbatim; user decides.
• Subagent dispatch unavailable: run the reviewer inline. Manifest, apply, and review are still produced; the user still sees the two checkpoints, and the report says the review was not independent.

Behavioral Guidelines

• Never modify skill content.
• Never run network requests.
• Never apply ops the user did not approve.
• Never touch paths outside the manifest.
• When in doubt about canonical (drift), suggest newer-mtime side and ask the user.
• For Codex writes, always include the trust gate reminder.

See manifest-schema.md and port-recipes.md for the data contract and translation rules.

Smoke testing on real projects

Before merging meaningful changes to this skill, run dry-run mode on at least one real project of each shape:

• A Claude-only project with hierarchical CLAUDE.md files (e.g. ~/Code/Klassenzeit).
• A drift project with CLAUDE.md and AGENTS.md already present and out of sync (e.g. ~/Zettelkasten).

Invocation:

cd <project>
claude  # or codex
> Use the claude-codex-bridge skill on this project. Dry run only. Show me the manifest, do not apply anything.

Inspect the manifest. Sanity checks:

• All hierarchical memory files are mapped.
• No commands or rules appear in ops (they should be in skip).
• Plugin report buckets are populated.
• For Codex writes: trust_warning: true is set.