migrate-to-codex

<!-- Generated by the ccode-to-codex mirror sync on 2026-04-14 from input revision 9a2403fb. -->

Migrate to Codex

Preserve the source workflow first. The goal is not to transliterate Claude primitives. The goal is to produce the Codex skill artifact that best preserves the source skill's behavior.

Conversation-First Entry

Bare or vague requests should not dump raw script flags immediately. Resolve the request through the shared contract in references/conversational-migration-contract.md.

Default menu for underspecified requests:

1. Assess one skill
2. Preview one skill
3. Migrate one skill live
4. Batch assess pending skills
5. Review one migrated skill for nativeness
6. Explain blockers and statuses

Routing rules:

• If the user already says assess <skill>, preview <skill>, or migrate <skill>, or review <skill>, route directly.
• In Plan mode, use request_user_input for the action choice only.
• Outside Plan mode, render the same choices as a numbered text menu.
• If the action needs a skill name and the user did not provide one, ask for it in plain text.
• Require explicit confirmation before any live write into .codex/skills/.

Advanced CLI

• Preferred wrappers:
  • python3 .codex/skills/migrate-to-codex/scripts/migration_doctor.py --skill example-skill --json
  • python3 .codex/skills/migrate-to-codex/scripts/run_migration_workflow.py --preview --skill example-url-validator --json
  • python3 .codex/skills/migrate-to-codex/scripts/run_migration_workflow.py --skill example-url-validator --json
• Power-user engine:
  • python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --analysis-only --json --skill example-skill
  • python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --skill example-url-validator
  • python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --all
  • python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --all --dry-run --json
  • python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --analysis-only --json

Explicit Non-Goals

• Do not attempt to preserve inline Claude Agent() / Task() semantics mechanically in this skill.
• Do not migrate agents here. Route agent dependencies to migrate-agents-to-codex at .codex/skills/migrate-agents-to-codex/SKILL.md.
• Do not treat legacy .codex/agents/*.md imports as resolved runtime dependencies. Only .codex/agents/*.toml counts.
• Do not treat command-derived skills or generated hook config as native/trusted output. They are compatibility artifacts that require manual review.

Sandbox Policy

Recommended mode: workspace-write

Rationale: this workflow creates skill files, updates repo-local documentation, and runs validation scripts. Infrastructure or deployment access is not needed.

Runtime Contract

1. Codex callable MCP namespaces use underscore-normalized server names.
2. Hard MUST / NEVER / ONLY constraints survive verbatim.
3. Preserve the source workflow's control shape unless Codex lacks a required primitive.
4. Preserve direct execution when Codex supports it. Only redesign into manager-to-subagent when the source truly depends on task/team semantics.
5. Do not invent spawn_agent, wait_agent, update_plan, or approval requirements unless the source workflow genuinely needs them.
6. User interaction is mode-dependent: request_user_input exists only in Plan mode; outside Plan mode rely on normal user messages or approval workflow.
7. File edits use apply_patch when the workflow actually edits files.
8. Explicitly named Claude agents that exist under .claude/agents/*.md are hard runtime dependencies. Never substitute, downgrade, drop, or neutralize them during skill migration. If .codex/agents/<name>.toml is missing, stop and route to migrate-agents-to-codex.
9. Claude skill references are context-sensitive. Only operational uses are hard migration dependencies. Related-skills tables, troubleshooting notes, provenance/history, and redirected-skill markers are not blockers by themselves.
10. For ambiguous skill mentions, the Python migrator extracts structured candidates and returns MANUAL_REVIEW_REQUIRED. The interactive Codex skill then owns the read-only mini-auditor pass. If the auditor still cannot classify a mention confidently, keep the skill in manual-review state rather than auto-blocking or auto-migrating.

Reference Map

Reference	Load when
references/primitive-mapping.md	You need authoritative primitive translation rules or sandbox inference
references/embedded-agent-taxonomy.md	The source skill embeds Claude Agent(...) or Task(...) sub-agent sites and you must distinguish inline slices from named agent dependencies
references/complexity-classifier.md	You need to decide Tier 1 vs Tier 2 vs Tier 3
references/codex-skill-template.md	You are hand-authoring a Tier 3 native skill
references/architectural-patterns.md	You need preservation-first rules or runtime-coupling checks
references/conversational-migration-contract.md	You need the shared menu/direct-routing/confirmation rules for the migrate-* family
../migrate-agents-to-codex/SKILL.md	You need the agent-only migration workflow or its direct script entrypoint
docs/how-to/claude-to-codex-agentic-migration.md	You need the repo-level migration contract and CLI examples

Scripts

Script	Purpose
.codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py	Deterministic migration engine with preflight classification, --analysis-only, and additive --json structured output
.codex/skills/migrate-to-codex/scripts/migration_doctor.py	Read-only readiness layer for the migration family: blocker counts, existing validator failures, drift, pending nativeness review, and oversized packages
.codex/skills/migrate-to-codex/scripts/run_migration_workflow.py	Script-driven orchestration: doctor -> migrate -> validate -> tracker refresh -> dashboard summary, with optional materialized preview and markdown evidence report
tools/migration_support/	Shared migration-family support package for tracker CLI, tracker state, nativeness handoff, and repo-root path helpers
tools/migration_support/validate_names.py	Thin wrapper around the shared Codex migration validator

Discovery Summary

• Agent targets are out of scope and must be routed to migrate-agents-to-codex.
• Project-local Claude command markdown files are converted only in batch/all mode into single-file skills named command-* under .codex/skills/.
• Project-local Claude settings command hooks are converted only in batch/all mode into the Codex hooks config file. Generated hooks are always reported as "Check before using."
• Embedded agent sites are a dependency-classification problem first: separate inline delegated slices from file-backed named agent dependencies before any primitive rewrite.
• The migrator now classifies first: MECHANICAL_SAFE, MANUAL_REVIEW_REQUIRED, REFACTOR_REQUIRED, or BLOCKED.
• Root CLI compatibility matters: zero-argument execution must remain valid even if the implementation moves under .codex/skills/.
• Provenance markers are not automatically runtime coupling; treat active docs, active scripts, and live references as the real completion gate.
• Tier 3 migrations usually fail when they are treated as textual conversion instead of behavior-preserving rewrite.

Known Corrections

• Banner insertion must happen after YAML frontmatter, never before it.
• Primitive mapping is semantic, not textual. A source primitive name appearing in documentation does not mean the workflow should be auto-rewritten around the nearest Codex tool.
• Legacy Claude skill-call syntax is context-sensitive during source analysis. Cross-references in prose, tables, and examples are dependency metadata, not orchestration. Operational workflow steps that invoke sibling skills still require rewrite.
• Embedded Agent(...) syntax alone is not enough to choose a migration strategy. What matters is whether the spawned thing is an inline behavior slice or a referenced runtime artifact under .claude/agents/.
• Inline Claude orchestration forms are refusal triggers here, not transformation targets.
• Plan-mode-only user-input primitives are not universal replacement targets. Outside Plan mode, normal user interaction or approval flow is the correct fallback.
• Runtime-coupling checks must distinguish active dependencies from provenance-only strings.
• Only .codex/agents/<name>.toml satisfies a named agent dependency. .md files are legacy imports and ignored.
• If a named Claude agent exists in .claude/agents/, it is a hard dependency edge. Missing Codex parity is a stop condition, not a substitution opportunity.
• If a referenced skill exists only in the Claude tree, it is a hard dependency edge only when the mention is operational. Support or provenance mentions are evidence to classify, not blockers by themselves.

Migration State

• Default status is CODEX_COMPATIBLE_BUT_NOT_NATIVE until Step 5 passes.
• Any mechanically generated artifact enters pending_native_review after write. File existence may unblock downstream migrations, but native status still requires a recorded manual nativeness review.
• Command-generated command-* skills enter the same pending_native_review state. Hook config is operational-review-required and is not native-tracked in v1.
• No migration may be marked NATIVE if any active consumer-side script or active doc still points to the old source asset path for that workflow.
• Preserve the source tree. Do not delete or rewrite the source skill unless the user explicitly asks for cutover work.
• Agent migration is OUT OF SCOPE. If the target is a Claude agent, stop and route

---

Content truncated.