migrate-agents-to-codex

name

migrate-agents-to-codex

description

Migrate Claude agent definitions (.claude/agents/*.md) to Codex-compatible markdown or TOML outputs under `.codex/agents/`. Strips frontmatter, maps fields to native Codex contracts, normalizes MCP namespaces, and classifies agents into 3 tiers. Includes adversarial cross-model review (GPT-5.4 inline native sub-agent) with auto-fix loop before completion. Use when asked to "migrate agents to codex", "convert agents", or "port agent definitions". Pipeline stage: CODE → VERIFY.

Migrate Agents to Codex

Purpose

Migrates Claude agent definitions from .claude/agents/*.md (YAML frontmatter

• markdown body) to Codex-compatible outputs under .codex/agents/.

Preferred output: standalone TOML custom-agent files. Backward-compatible output only: pure-markdown behavioral specifications.

The migration strips frontmatter, maps fields to native Codex contracts, preserves runtime hints such as model, effort, reasoning_effort, and model_reasoning_effort, normalizes MCP namespaces, and extracts large domain content into companion reference files.

After migration, a native Codex compliance audit (GPT-5.4 inline sub-agent) validates every migrated file passes as a native Codex sub-agent — not a ported Claude artifact. Mechanical output is never final on write alone: every mechanically generated agent requires a recorded manual nativeness review before it may be treated as native. Findings are auto-addressed and a convergence check confirms no regressions were introduced by the fixes.

Pipeline position: CODE → VERIFY (runs during implementation phase). Covers 2 stages: CODE (migration) + VERIFY (adversarial review loop).

Canonical conversation wrapper: .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py Deterministic engine: .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py

Conversation-First Entry

Bare requests should start with a user-facing action menu, not a wall of CLI flags. Follow the shared contract in ../migrate-to-codex/references/conversational-migration-contract.md.

Default menu for underspecified requests:

1. Assess one agent
2. Preview one agent as TOML
3. Migrate one agent live
4. Batch preflight all agents
5. Review one migrated agent for nativeness
6. Explain MCP or skill blockers

Routing rules:

• If the user already says preview example-agent-e, migrate example-agent-c, or review example-agent-e, route directly.
• In Plan mode, use request_user_input only for the action choice.
• Outside Plan mode, render the same action set as a numbered text menu.
• If the action still needs an agent name, ask for it in plain text.
• Require explicit confirmation before any live write into .codex/agents/ or any --force overwrite.

Advanced CLI

• Preferred wrappers:
  • python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json
  • python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json
  • python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --agent example-agent-a --json
• Power-user engine:
  • python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --format toml

Prerequisites

• Python 3.11+ available
• Sibling skill exists: .codex/skills/migrate-to-codex/ (provides shared functions)
• .codex/agents/ directory will be created by the script if missing
• .codex/config.toml exists with MCP server definitions
• Gold standard reference if present: a previously migrated agent artifact under .codex/agents/
• Shared conversation contract available at ../migrate-to-codex/references/conversational-migration-contract.md

Format: Markdown vs TOML

Official Codex custom-agent format is TOML under .codex/agents/*.toml.

Use:

• --format toml for new migrations
• --format md only for backward-compatible markdown outputs

Rules:

• If both .md and .toml exist for the same agent, treat .toml as the runtime-preferred artifact.
• Markdown remains useful as documentation and as a bridge for older migration runs, but new custom agents should default to TOML.
• Validation must branch by format. A TOML migration is not complete if the workflow still validates only markdown headings.

Step 1: Assess Complexity & Resolve Dependencies

Context: User provides an agent name, a list, --all, or a bare request that still needs the menu/front-door routing.

Before running the backend:

• bare request -> show the family menu from the shared conversational contract
• explicit action + explicit target -> route directly
• explicit action + missing target -> ask for the target name
• explicit review <agent> on an already migrated agent -> skip migration write logic and jump to Step 5 as a read-only nativeness audit
• live migration -> require confirmation before the write step

1a. Classify

Classify each target agent using the decision tree in agent-complexity-classifier.md.

Run the assessment path through the backend wrapper or execute directly:

python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json
python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --dry-run --json

The script parses each .claude/agents/*.md, extracts frontmatter, counts MCP tools, detects hooks/orchestration patterns, and outputs a classification table with tier, readiness score, sandbox recommendation, dependency blockers, and next actions.

Skip rules:

• Agents with existing native .codex/agents/{name}.toml or legacy .codex/agents/{name}.md → SKIP (validate only)
• Use --force to overwrite existing agents

Classification output:

Use generated classification output from the current input batch. Do not hard-code source-agent rosters in this skill.

1b. MCP Dependency Preflight

Before resolving skill dependencies or writing any migrated agent, run an MCP dependency preflight against the project-level .codex/config.toml.

Rules:

• Source of truth is the Claude agent frontmatter tools: list only.
• Extract required MCP servers only from tools matching mcp__<server>__<tool>.
• Treat ide as a Claude-only built-in integration, not a project MCP dependency. Record it as unsupported source tooling and drop it from migrated agent dependency requirements.
• Normalize server ids to project config-key form before comparison (example_server_g → example-server-g, chrome_devtools → chrome-devtools).
• Read only top-level [mcp_servers.<id>] entries from .codex/config.toml. Nested tables such as [mcp_servers.<id>.tools.*] do not count as separate servers.
• Agent-local output must not synthesize [mcp_servers.*] stanzas. Missing server config is resolved only by editing project .codex/config.toml.

Blocker behavior:

• --agent <name> --dry-run: always print required/configured/missing MCP servers and preview the generated output.
• --agent <name> in write mode: if missing_mcp_servers is non-empty, print a blocker report, write nothing, and exit non-zero.
• --all --dry-run: report MCP status for every agent, including all blocked agents and their missing servers.
• --all in write mode: preflight the full batch first. If any target agent is blocked, write nothing for the whole batch and exit non-zero.

Source-specific dependency notes:

• Treat unsupported source tooling such as ide as input data, not as an MCP blocker.
• Do not hard-code the current repository's agent roster or dependency state into public guidance.

1c. Resolve Skill Dependencies

For each agent being migrated, cross-reference its skills: frontmatter against what exists in .codex/skills/:

# Extract skills from Claude agent
grep '^  - ' .claude/agents/{name}.md | sed 's/^  - //'

# Check which exist in Codex
ls .codex/skills/

Produce a dependency table:

Agent: <example role> (Tier 3)
Skills: 5 declared, 3 available, 2 MISSING
  ✅ api-proxy-pattern-example              → .codex/skills/api-proxy-pattern-example/SKILL.md
  ✅ frontend-interaction-example  → .codex/skills/frontend-interaction-example/SKILL.md
  ✅ api-contracts-example          → .codex/skills/api-contracts-example/SKILL.md
  ❌ example-url-validator             → NOT IN .codex/skills/
  ❌ example-feature-implementation → NOT IN .codex/skills/

If all skills are available → READY. Proceed to Step 2.

If any skills are missing → BLOCKED. For each missing skill, choose a resolution:

Resolution	When to Use	Action
MIGRATE	Skill is essential to the agent's core workflow	Invoke $migrate-to-codex for this skill BEFORE continuing agent migration
SUBSTITUTE	A similar Codex skill covers the same domain	Map to the substitute in References, document the rationale
DROP	Skill is deprecated, merged, or redundant with agent body content	Omit from References, document the rationale

Present the dependency table to the user with recommended resolutions. Only proceed to Step 2 after all missing skills are resolved (migrated, substituted, or explicitly dropped).

Example resolution table:

Missing Skill	Recommendation	Rationale
example-url-validator	SUBSTITUTE → developing-website-features	URL validation rules are covered in agent body Constraints section
example-feature-implementation	SUBSTITUTE → integration-testing	Testing patterns overlap; fullstack patterns are in companion ref

Batch migration note: When migrating --all, run Step 1c across ALL agents first to collect the full set of missing skills. Migrate missing skills in one batch before starting any agent migrations. This prevents redundant skill migrations when multiple agents share the same dependency.

Step 2: Map Fields

Apply the field mapping from agent-field-mapping.md.

Key transformations:

Claude Field	Codex Section
name	# Agent: {Title}
description	## Purpose
tools + disallowedTools	## Recommended Sandbox + ## Constraints
model + effort / reasoning_effort / model_reasoning_effort	## Runtime Configuration
skills	## References (.codex/skills/ paths)
hooks.Stop	## Runtime Configuration → completion gate
color, permissionMode	Dropped (documented loss)

MCP namespace normalization (automated by script):

• example-server-g config server id → mcp__example_server_g__*
• chrome-devtools config server id → mcp__chrome_devtools__*

Skills → References mapping: All skill dependencies were resolved in Step 1b. Map each resolved skill 1:1 to .codex/skills/{name}/SKILL.md. Substituted or dropped skills use the resolution documented in Step 1b.

Runtime hint preservation: If the Claude source already carries concrete Codex runtime hints such as model = "gpt-5.4-mini" and model_reasoning_effort = "medium", preserve them in TOML output instead of down-mapping them to legacy advisory prose.

Body preservation: Preserve as much Claude agent content as possible. Agent spec hard limit: ≤1000 lines. Extract to .codex/agents/references/{name}-domain.md only if exceeding the limit.

Step 2.6: Convert Embedded Delegation Sites

If the source agent or its companion references contain embedded delegation sites, apply the decision process in subagent-migration-guide.md.

Decision rules:

• Reusable named role → create .codex/agents/<name>.toml
• One-off workflow-local prompt slice → keep inline via spawn_agent(...)
• Thin proxy around one MCP call → usually keep inline
• Routing table with several named roles → every reachable role must have a real Codex agent file before the migration is considered complete

Model guidance:

• Use the intent-based mapping in subagent-migration-guide.md Section 2.
• Treat that table as this migration package's policy informed by Codex runtime guidance, not as an official OpenAI Claude-to-Codex table.

Format note:

• File-backed custom agents should use --format toml.
• Markdown output remains valid for compatibility, but it is not the preferred target for new reusable sub-agent roles.

Step 2.5: Verify Domain Content (Tier 2-3 only)

WHY THIS STEP EXISTS: Claude agent bodies drift from the codebase. Route constants get renamed, helper functions get deleted, test infrastructure gets replaced. If you copy stale domain examples into the companion reference, the Codex audit will catch them — but at the cost of an extra audit cycle (~500K-1.5M tokens). Verify first, write once.

For every code example, symbol, path, or config pattern in the Claude agent body, verify against the live codebase before including in the Codex output:

Content Type	Verification Method
Configuration constants (EXAMPLE_CONSTANTS.*)	grep -n "EXAMPLE_" example-project/src/config/settings.config.ts
Helper function names	grep -rn "functionName(" path/to/module/
Directory paths (locales/, i18n/)	ls path/to/directory/
Locale directory aliases	Check actual directory names
Router meta patterns (meta.role vs meta.roles)	grep -n "meta.*role" example-project/src/router/
Test infrastructure (stub dependency vs real dependency)	Read test setup files: example-project/tests/fixtures/
MCP tools referenced	Check config.toml entries

Decision rule: If a code example can't be verified in <30 seconds, replace it with a neutral description (e.g., "use the module's existing pattern") rather than copying potentially stale specifics. The companion reference should be accurate over detailed.

Skip for Tier 1: Mechanical agents have no domain examples to verify.

Step 3: Execute Migration

Tier 1 (Mechanical)

python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent <agent_name>

Output is structurally complete, but it is not final on write alone. Record a manual nativeness review before treating the generated agent as native.

Tier 2 (Assisted)

python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent <agent_name> --format toml

Script output contains [REVIEW: ...] annotations. Review:

• MCP preflight status: confirm project .codex/config.toml satisfied all required top-level MCP servers before write mode
• Sandbox recommendation: confirm matches agent's access pattern
• Knowledge Priority ordering: adjust for agent's actual tool preference
• initialPrompt → Initial Action conversion: verify prose is accurate

Tier 3 (Hand-Authored)

python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent <agent_name> --format toml

Script generates a skeleton with [TODO: hand-author] placeholders.

1. Read a representative migrated agent artifact under .codex/agents/
2. Read template: codex-agent-template.md
3. Fill domain sections manually (keep ≤40 lines each)
4. Extract verbose content to .codex/agents/references/{name}-domain.md
5. For orchestrator roles: restructure Supervisor Pattern per architectural-patterns.md Pattern 4 + 6

Batch Mode

python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --format toml

Processes all agents. Preflight MCP dependencies → assess → migrate by tier → report.

Step 4: Validate

Automated Checks

Native Codex output is TOML. Use markdown-only checks only when you explicitly request --format md.

# Markdown compatibility output only:
# 1. No frontmatter delimiters (line 1 must NOT be --- or +++)
head -1 .codex/agents/{name}.md | grep -Ev '^(---|\+\+\+)$'

# 2. No Claude primitives or hyphenated MCP namespaces
python3 tools/migration_support/validate_names.py --scan-dir .codex/agents/

# 3. Required sections present
grep -c '## Purpose\|## Constraints\|## Output Contract' .codex/agents/{name}.md

# 4. Under 1000 lines (hard limit)
wc -l .codex/agents/{name}.md

# 5. Starts with # Agent:
head -1 .codex/agents/{name}.md | grep '^# Agent:'

# Native TOML output:
# 1. Valid TOML syntax
python3 - <<'PY'
from pathlib import Path
import tomllib
tomllib.loads(Path(".codex/agents/{name}.toml").read_text(encoding="utf-8"))
print("OK")
PY

# 2. Required keys present
python3 - <<'PY'
from pathlib import Path
import tomllib
data = tomllib.loads(Path(".codex/agents/{name}.toml").read_text(encoding="utf-8"))
required = ["name", "description", "developer_instructions"]
missing = [key for key in required if not data.get(key)]
assert not missing, f"Missing keys: {missing}"
print("OK")
PY

# 3. No Claude primitives or hyphenated MCP namespaces in developer instructions
python3 tools/migration_support/validate_names.py --scan-dir .codex/agents/

Tier 2 Manual Checklist

• MCP preflight passed against project .codex/config.toml
• Sandbox recommendation matches agent's access pattern
• Knowledge Priority reflects actual tool preference
• Skills referenced exist in .codex/skills/
• No [REVIEW: ...] annotations remain

Tier 3 Manual Checklist (adds)

• Companion reference file created and referenced
• Hooks mapped to completion gate in Runtime Configuration
• Orchestration patterns (example-agent-m) restructured
• No absolute file paths leaked through
• No [TODO: ...] placeholders remain
• Domain sections ≤40 lines each

Step 5: Native Codex Compliance Audit (inline native sub-agent)

When: After Step 4 validation passes — before reporting to the user.

Review-only entry: If an agent already exists under .codex/agents/ and the tracker says it is pending_native_review, this step may be invoked directly as a read-only single-agent review flow. In that entry path, audit first, present findings plus next actions, and auto-record native by default when the final audit result is NO_FINDINGS unless the user explicitly asked for audit-only behavior.

Dashboard routing note:

• migration-dashboard may use this review-only entry as a bounded Verify phase after review next, review <number>, or review <name>.
• In that entry path, the parent dashboard remains a thin router. This skill owns the reviewer prompt, delegated lifecycle, review-report guidance, and tracker close-out instructions.
• Shared nativeness handoff helpers live in tools/migration_support/; workflow scripts bootstrap that package before importing shared migration-family helpers.

Tracker close-out: For a clean review, record the outcome automatically with:

• python3 tools/migration_support/tracker.py --write --record-review agent:<name>=native
• python3 tools/migration_support/tracker.py --write --record-review agent:<name>=codex_compatible_but_not_native

Use the native path by default when the final audit or convergence result is NO_FINDINGS, attaching summary No findings after convergence. Keep manual close-out only when MEDIUM findings remain, when the user requested audit-only behavior, or when the tracker write fails. Do not leave the tracker at pending_native_review after a clean nativeness audit.

Purpose: The migrated agent must pass as a native Codex sub-agent — not a ported Claude artifact. A format-correct file that still thinks in Claude primitives, references .claude/ paths, or assumes Claude-only tools is a failed migration regardless of validation results. GPT-5.4 running as an inline native sub-agent audits from inside the Codex ecosystem, judging whether it would accept these agents as its own peers.

MANDATORY: Step 5 MUST use inline spawn_agent(...) — NEVER external Codex review proxy or external large-context reviewer. Only the Codex ecosystem model (GPT-5.4) can judge whether an agent reads as a native Codex sub-agent. Gemini cannot assess Codex nativeness.

5a. Compliance Audit

Spawn one inline nativeness-audit sub-agent with model: "gpt-5.4" and reasoning_effort: "high". Keep this agent alive for the entire Step 5 loop. The parent workflow remains the only writer; the auditor stays read-only.

Workflow contract for this skill:

1. Spawn the auditor once with the full first-pass audit prompt
2. wait_agent({"targets": [agent.id]}) for findings
3. Parent applies fixes locally
4. Reuse the same live auditor via send_input(...) for convergence
5. wait_agent({"targets": [agent.id]}) again
6. close_agent(...) once Step 5 completes or escalates

Rationale for the legacy feature choices in this workflow:

• Adopt: send_input(...), close_agent(...)
• Keep as-is: model, reasoning_effort
• Defer: fork_context, structured items, resume_agent(...)
• Avoid here: send_input(interrupt=true)

See legacy-subagent-roi.md for the feature-by-feature ROI table.

Example shape:

agent = spawn_agent({
  agent_type: "default",
  model: "gpt-5.4",
  reasoning_effort: "high",
  message: `You are a Codex ecosystem compliance auditor.

  This is a READ-ONLY audit.
  - Do not edit files
  - Do not call apply_patch
  - Do not rerun migration scripts
  - Verify paths and symbols through read-only inspection when the runtime permits

  ${dynamicAuditPrompt}`
})
result = wait_agent({"targets": [agent.id]})

Prompt (substitute {MIGRATED}, {SOURCES} with actual absolute paths):

You are a Codex ecosystem compliance auditor. Your job: determine whether
each migrated agent file would pass as a NATIVE Codex sub-agent — as if it
was designed for Codex from day one, not ported from another system.

This is a READ-ONLY audit.
- Do not edit files
- Do not call apply_patch
- Do not rerun migration scripts
- Verify paths and symbols through read-only inspection when the runtime permits

READ FIRST (gold standard): {reference migrated agent artifact under .codex/agents/}
READ NEXT (Codex MCP config): .codex/config.toml
THEN READ each migrated file and its Claude source side by side:

MIGRATED: {MIGRATED}
SOURCES:  {SOURCES}

AUDIT DIMENSIONS (ordered by severity):

CRITICAL — Ecosystem incompatibility:
- Frontmatter delimiters present (Codex markdown agents are pure markdown)
- References old tool or primitive spellings that don't exist in Codex
- MCP config server ids are used directly as callable namespaces instead of underscore-normalized names (`example-server-g` config id → `mcp__example_server_g__`)
- References .claude/ paths instead of .codex/ paths
- Absolute /Users/... paths leaked through

HIGH — Semantic fidelity:
- Purpose section lost the agent's core responsibility vs Claude source
- The agent's execution contract was not re-expressed in Codex sub-agent terms and instead was flattened into a generic helper, losing operational role, decision boundaries, or constraint model
- Safety-critical constraints dropped or weakened during migration (especially test guardrails, zero-mocking stances, cleanup lifecycle rules)
- Hard constraints softened during compression: MUST/NEVER/ONLY language becomes suggestions. Compare constraint strength between source and target — hard rules must survive verbatim
- MCP servers referenced but missing from .codex/config.toml
- Skill paths referenced but don't exist under .codex/skills/
- Companion reference files referenced but missing on disk

HIGH — Domain accuracy (VERIFY AGAINST LIVE CODEBASE):
Claude agent bodies drift from the codebase. Every code example, route
constant, helper function name, directory path, router meta pattern, and
test infrastructure detail in the migrated files is an implicit assertion.
Verify these against the actual repo with read-only inspection when the runtime permits:
- Configuration constants: grep the routes config file for the exact symbol name
- Directory paths: inspect the actual directory (e.g., locales/ vs i18n/, source-locale vs target-locale)
- Helper functions: grep for the function name in the relevant module
- Router meta patterns: read the actual router file (singular role vs roles array)
- Test infrastructure: check actual test setup files (stub dependency vs real dependency)
- API service names: grep for the class name to confirm it exists
If an example references something that doesn't exist in the live codebase,
that is a HIGH finding — a sub-agent copying it will produce broken code.

MEDIUM — Nativeness quality:
- Agent reads as a translation rather than a native spec (Claude jargon, hedging language about "in Codex this would be...")
- Knowledge Priority doesn't reflect actual Codex tool availability
- Sandbox recommendation mismatches agent's access pattern
- Leftover [REVIEW:] or [TODO:] annotations
- Sections exceed 40 lines (should extract to companion ref)

OUTPUT (per finding):
  SEVERITY: {CRITICAL|HIGH|MEDIUM}
  FILE: {path}
  ISSUE: {one-line}
  FIX: {concrete instruction}

If clean: "NO_FINDINGS"
End with: "AUDIT_COMPLETE"

5b. Auto-Address Findings

Parse audit output. For each finding:

• CRITICAL/HIGH — Fix immediately via Edit tool. Surgical edits only — do NOT re-run the migration script.
• MEDIUM — Fix if mechanical. Flag to user only if the fix requires judgment.

Do not spawn a second auditor for fixes. The parent applies fixes, then reuses the same auditor thread for convergence.

For dashboard-driven review-only entry, keep the parent-thread return compact:

• verdict
• top findings or NO_FINDINGS
• next action
• review-report path when available

Do not paste the full audit transcript into the main thread unless the user explicitly asks for it.

5c. Convergence Check

Reuse the same live nativeness-audit sub-agent via send_input(...) for a focused re-audit. Do not respawn the auditor unless the original agent died.

send_input({
  target: agent.id,
  message: `CONVERGENCE CHECK: Previous audit found {N} issues, all addressed.

  This is a READ-ONLY audit.
  - Do not edit files
  - Do not call apply_patch
  - Do not rerun migration scripts
  - Verify paths and symbols through read-only inspection when the runtime permits

  Re-read these files and verify:
  1. Previous findings resolved
  2. No new CRITICAL/HIGH issues introduced by fixes
  3. Each agent still reads as a native Codex sub-agent

  FILES: {paths that had findings}
  GOLD STANDARD: {reference migrated agent artifact under .codex/agents/}

  Same output format. "NO_FINDINGS" if clean. End with "AUDIT_COMPLETE".`
})
result = wait_agent({"targets": [agent.id]})

If the initial audit already returned NO_FINDINGS, skip convergence, record native by default, and close the auditor immediately unless the user asked for audit-only behavior.

5d. Convergence Decision

Native completion rule:

• The agent's execution contract must be re-expressed in Codex sub-agent terms without flattening its original operational role, decision boundaries, or constraint model. If the file is format-correct but semantically flattened, do not declare it native.

Result	Action
NO_FINDINGS	Auto-record native, then proceed to Step 6
Only MEDIUM	Proceed to Step 6, note as "Acknowledged minor items"
Any CRITICAL/HIGH	STOP — escalate to user. Do not declare complete.

Hard cap: 2 cycles (audit + convergence). Persistent critical issues = systemic problem requiring human judgment.

Lifecycle rule:

• Always close_agent({ target: agent.id }) before leaving Step 5, whether the result is success, acknowledged-medium, or escalation.
• Save the full nativeness review to a markdown report when the review is meant to be recorded later. Reuse the existing agent-migration report directories or an explicit /tmp review path, then attach that path through --review-evidence at tracker close-out.

Step 6: Report

Single Agent

Migration Report: {name}
  Tier: {1|2|3}
  Source: .claude/agents/{name}.md ({N} lines)
  Target: .codex/agents/{name}.toml ({M} lines)
  Companion: .codex/agents/references/{name}-domain.md (if extracted)
  Status: {COMPLETE|REVIEW_NEEDED|SKELETON_GENERATED|ALREADY_MIGRATED}
  Sandbox: {read-only|workspace-write}
  Validation: {PASS|FAIL (details)}
  Codex Compliance: {NATIVE (0 findings)|NATIVE ({N} fixed)|ESCALATED (details)}
  Fields mapped: {list}
  Fields dropped: {list with reason}
  Remaining gaps: {items needing attention}

Batch Summary

Table of migrated agents with tier, status, and validation result.

Migration Order

When migrating all agents, process in this order:

1. example-agent-a (Tier 1) — simplest, validates the pipeline
2. example-agent-i, example-agent-l, example-agent-j, example-agent-k (Tier 2)
3. example-agent-h, example-agent-g (Tier 2, borderline complexity)
4. example-agent-c, example-agent-f (Tier 3, companion ref extraction)
5. example-agent-d, example-agent-e (Tier 3, MCP gap resolution needed)
6. example-agent-m (Tier 3, LAST — depends on all leaf agents being stable)

Anti-Patterns

Don't	Do Instead
Preserve frontmatter delimiters	Strip frontmatter, map to markdown sections
Exceed 1000 lines	Extract verbose domain content to companion refs
Convert hooks to comments	Map to completion gate in Runtime Configuration
Map tools to a "Tools" section	Use Constraints + Recommended Sandbox sections
Keep absolute /Users/... paths	Strip to repo-relative paths
Mechanical conversion on Tier 3	Generate skeleton, hand-author domain sections
Use fabricated Codex primitives	Verify against official Codex docs
Skip compliance audit for "simple" agents	Always run — even T1 agents can have namespace drift
Let the nativeness auditor edit files directly	Keep the auditor read-only by prompt contract — parent workflow applies fixes
Loop audit >2 cycles	Escalate to user after convergence if CRITICAL remains
Report completion before audit passes	Step 5 must gate Step 6
Treat format-correct as native-compliant	A file can pass validation but still read as a port
Trust Claude agent body as accurate	Agent bodies drift — verify domain examples against live codebase (Step 2.5)
Substitute or drop missing skills silently	Treat missing skills as a blocker — resolve via MIGRATE/SUBSTITUTE/DROP in Step 1b
Copy code examples verbatim from Claude source	Every route constant, helper name, meta pattern is an assertion — grep to confirm
Weaken safety constraints during compression	Preserve hard rules verbatim: "preserve setup boundaries", "preserve integration constraints", "preserve test-scope constraints"
Use port-artifact language in companion files	"Extracted during Codex migration" → "Reference for X agent. Use when Y."

Migration Review Guidance

Rationale: Migration audits often find format issues and stale source knowledge carried over from the Claude agent body.

Key patterns:

1. Claude agent bodies are NOT authoritative — they're cached snapshots of codebase knowledge. Configuration constants get renamed, test infrastructure gets replaced, helpers get deleted. Step 2.5 exists to catch this BEFORE writing.
2. Companion references are assertion-dense — every code example is a claim about codebase state. More specific = more fragile. When in doubt, use neutral descriptions ("use the module's existing pattern") over stale specifics.
3. The initial audit catches ecosystem issues; convergence catches domain drift — this asymmetry is by design now. The initial audit prompt includes "Domain accuracy: VERIFY AGAINST LIVE CODEBASE" to push more domain checks into the first cycle, reducing convergence-cycle findings and token cost.
4. Unmigrated skill references are invisible until audit — ls .codex/skills/ takes 1 second but saves an entire audit finding + fix cycle.
5. Specific constraints need review — "real dependencies over simplified fixtures" is not the same rigor as "specific external dependency requirements — no lightweight stand-ins, no simplified fixtures." Keep the actionable requirement clear.

Shared References

These references are symlinked from the sibling migrate-to-codex skill:

• primitive-mapping.md — Claude→Codex tool mapping
• architectural-patterns.md — 6 migration patterns

Agent-specific references:

• agent-complexity-classifier.md — Tier decision tree
• agent-field-mapping.md — Frontmatter→section mapping
• codex-agent-template.md — Gold standard template
• legacy-subagent-roi.md — Which legacy sub-agent features are worth using in this migration workflow