WDG AI Dev Environment

Appearance

Codex Migration Plan ​

Last updated: April 15, 2026

Goal ​

Bring Codex to first-class platform support without breaking the existing Claude and Cursor workflows.

The migration should make Codex a normal, generated, documented, and tested part of project setup rather than a manual afterthought.

Guiding Principles ​

  1. Keep one shared project instruction source where possible.
  2. Add Codex support to the current generic commands instead of creating a parallel setup system.
  3. Prefer canonical source templates plus tool-specific render targets over hand-maintaining duplicate generated content.
  4. Preserve backward compatibility for existing Claude users while Codex support is added.
  5. Treat docs and tests as part of the feature, not as cleanup work.

Shared project guidance ​

Keep AGENTS.md as the canonical cross-assistant instruction file.

Reason:

  • Codex reads it directly.
  • Claude and other agents can already use it.
  • duplicating the same repository norms into a new Codex-only file would create drift immediately

Project-scoped Codex config ​

Generate .codex/config.toml into project repositories.

Reason:

  • Codex supports project-level config directly.
  • WDG needs project-local MCP server definitions and possibly project-local agent settings.

Skills ​

Keep cli/templates/project-skills/ as the canonical authored skill source, but deploy a Codex-facing copy to .agents/skills/.

Reason:

  • Codex still uses SKILL.md.
  • the skill directory shape is mostly reusable
  • the discovery path is different

Required caveat:

  • Claude-specific frontmatter and tool assumptions must be audited and either preserved only where supported or translated into Codex-compatible metadata such as agents/openai.yaml

Subagents ​

Treat Codex subagents as a separate output format.

Recommended structure:

  • keep the existing Claude templates where they are
  • add Codex-specific agent templates under a new template path such as cli/templates/project-codex-agents/

Reason:

  • Claude agent files and Codex subagent files are not the same format
  • forcing both assistants to share one source file would likely make authoring brittle

Rules ​

Do not attempt to migrate repository coding standards into Codex rules/.

Use rules/ only if the platform later wants to distribute command approval policy. That is a separate concern from project guidance and can be deferred.

Workstreams ​

1. Config Generation And Sync ​

Objective ​

Extend project creation and sync commands so Codex files are generated and refreshed automatically.

Local files in scope ​

  • cli/commands/create.sh
  • cli/commands/ai-config.sh
  • cli/commands/repo.sh
  • .codex/config.toml
  • new .codex/config.template.toml or equivalent

Tasks ​

  • add a Codex config template in the platform repo
  • generate .codex/config.toml during wdg create
  • include Codex outputs in wdg <project> ai-config sync
  • ensure repo clone/setup paths also install Codex assets
  • decide whether project-level agent limits such as [agents] max_threads and max_depth are generated by default or omitted until agents exist

Acceptance criteria ​

  • a new project repository contains .codex/config.toml
  • an existing project gains or refreshes .codex/config.toml via wdg <project> ai-config sync
  • docs no longer describe Codex as manual-only setup

2. MCP Parity ​

Objective ​

Make Codex receive the required WDG MCP servers by default.

Local files in scope ​

  • .mcp.json.template
  • .codex/config.toml
  • new Codex config template
  • cli/verify-mcp-config.sh

Tasks ​

  • define the required Codex MCP baseline
  • include wdg-local
  • decide whether chrome-devtools should be included by default or only on selected agents
  • decide whether mcp-auth-proxy belongs in the default Codex project config
  • document any intentional differences from .mcp.json

Open design question ​

Should project .codex/config.toml mirror .mcp.json one-to-one, or should Codex intentionally get a narrower default tool surface with extra MCP servers attached only to specific custom agents?

Recommended answer:

  • mirror the required baseline first for parity
  • optimize later only if a real usability or safety issue appears

Acceptance criteria ​

  • Codex project config includes the required WDG MCP servers
  • the documented Codex tool surface matches the generated config
  • a manual smoke test confirms Codex can see the expected servers in a generated project

3. Skills Migration ​

Objective ​

Make project skills discoverable by Codex without discarding the existing skill investment.

Local files in scope ​

  • cli/templates/project-skills/
  • cli/commands/create.sh
  • cli/commands/skills.sh
  • .claude/skills/
  • new .agents/skills/ output paths

Tasks ​

  • audit the 25 existing project skill templates for Codex compatibility
  • classify each skill as:
    • reusable as-is
    • reusable with metadata cleanup
    • needing a Codex-specific rewrite
  • deploy Codex copies to .agents/skills/
  • update wdg <project> skills sync so it is no longer Claude-only in behavior or wording
  • decide whether the command keeps the same name but syncs both tool outputs, or adds explicit target flags

Keep the command name skills sync, but make it assistant-agnostic in behavior.

Reason:

  • the command already represents project workflow support, not a Claude-only concept
  • adding --target=claude|codex|all can remain optional if needed later

Compatibility checks for each skill ​

  • Does the frontmatter rely on unsupported keys
  • Does the skill mention .claude/skills/ paths directly
  • Does the skill mention Claude-only tools or slash command semantics
  • Does the skill assume Claude-specific agent behavior
  • Does the skill need agents/openai.yaml metadata for better Codex behavior

Acceptance criteria ​

  • generated project repositories include .agents/skills/
  • Codex can discover at least a validated starter subset of project skills
  • CLI sync tests cover Codex skill deployment

4. Subagent Migration ​

Objective ​

Provide supported Codex subagents for project and platform workflows.

Local files in scope ​

  • .claude/agents/
  • cli/templates/project-agents/
  • new cli/templates/project-codex-agents/
  • project .codex/agents/

Tasks ​

  • inventory the existing 8 platform agents and 3 project agent templates
  • identify which ones deserve Codex equivalents
  • rewrite them as TOML subagents with narrow scopes
  • decide which agents should be project-generated by default and which should stay platform-only
  • attach specialized MCP servers only where they add clear value

Start with a small, high-value set:

  • onboarding or code-mapper agent
  • reviewer agent
  • docs-researcher agent

Reason:

  • these are narrow
  • they align well with Codex's explicit subagent model
  • they reduce the risk of over-porting low-value Claude-specific agents

Acceptance criteria ​

  • project repositories can include .codex/agents/*.toml
  • at least one generated project can successfully spawn a local Codex subagent using the documented configuration
  • agent docs describe what each Codex subagent is for and what it must not do

5. Documentation Refresh ​

Objective ​

Make the docs truthful before and after rollout.

Local files in scope ​

  • README.md
  • QUICKSTART.md
  • docs/index.md
  • docs/claude-config.md
  • docs/MCP_GUIDE.md
  • docs/codex-update/
  • docs/.vitepress/config.js

Tasks ​

  • add Codex rollout docs before implementation begins
  • update setup docs once generation exists
  • clarify the difference between:
    • AGENTS.md
    • .codex/config.toml
    • .agents/skills/
    • .codex/agents/
    • .mcp.json
  • remove language that implies Codex parity before it exists
  • add a dedicated Codex setup section once the implementation lands

Acceptance criteria ​

  • public docs accurately describe Codex behavior
  • there is no claim of automatic Codex setup unless the generator actually performs it
  • the docs site sidebar exposes the Codex migration pages

6. Test Coverage ​

Objective ​

Add test coverage for generated Codex files and sync behavior.

Local files in scope ​

  • cli/tests/commands/create.bats
  • cli/tests/commands/ai-config.bats
  • cli/tests/commands/skills.bats
  • new tests as needed

Tasks ​

  • add assertions for .codex/config.toml generation
  • add assertions for .agents/skills/ generation and sync
  • add assertions for .codex/agents/ generation if that path is added
  • update help-text assertions where commands stop being Claude-only
  • update the testing checklist

Acceptance criteria ​

  • BATS coverage exists for every new generated Codex path
  • existing Claude coverage still passes
  • test naming and help text reflect assistant-agnostic behavior where appropriate

Delivery Phases ​

Phase 0: Audit And Spike ​

Deliverables:

  • this documentation set
  • one manual reference implementation
  • decisions on canonical template locations

Exit criteria:

  • no unresolved confusion about skills path, subagent format, or shared instruction strategy

Phase 1: Config And MCP Parity ​

Deliverables:

  • project .codex/config.toml
  • ai-config sync support
  • documented MCP baseline

Exit criteria:

  • a fresh project opens in Codex with expected instructions and MCP servers

Phase 2: Skill Parity ​

Deliverables:

  • .agents/skills/ deployment
  • migrated starter skills
  • updated skills sync behavior and help text

Exit criteria:

  • Codex can discover and use a validated subset of project skills

Phase 3: Subagent Parity ​

Deliverables:

  • initial .codex/agents/ templates
  • generated Codex subagents in projects that opt in or receive defaults

Exit criteria:

  • at least one project can use documented Codex subagents end-to-end

Phase 4: Docs And General Rollout ​

Deliverables:

  • updated README and setup docs
  • updated site navigation
  • removal of stale Claude-only wording where the workflow is now shared

Exit criteria:

  • users can follow docs and get working Codex setup without tribal knowledge

Risks And Mitigations ​

Risk 1: Skill metadata incompatibility ​

Problem:

Current skills contain Claude-oriented frontmatter such as allowed-tools, argument-hint, and user-invocable. Codex docs explicitly require only name and description, with optional richer metadata living in agents/openai.yaml.

Mitigation:

  • audit every skill
  • strip or translate unsupported metadata rather than assuming silent compatibility

Risk 2: Template drift between assistants ​

Problem:

Maintaining separate Claude and Codex outputs can drift quickly.

Mitigation:

  • keep shared guidance in AGENTS.md
  • keep skills canonically authored once where feasible
  • keep assistant-specific render steps explicit and tested

Risk 3: Over-porting low-value agents ​

Problem:

Not every Claude agent deserves a Codex equivalent.

Mitigation:

  • start with a small, valuable Codex subagent set
  • add more only after real usage feedback

Risk 4: User confusion about file roles ​

Problem:

The platform already has many AI-related files.

Mitigation:

  • document the responsibility of each file type clearly
  • avoid introducing new overlapping project-guidance files

Open Questions ​

  1. Should Codex project config mirror .mcp.json exactly, or should it intentionally narrow the default MCP surface
  2. Should skills sync deploy both Claude and Codex outputs by default, or expose target flags
  3. Which existing Claude agents actually justify Codex translations in the first rollout
  4. Should Codex subagents be generated into every project by default, or only into projects that opt in
  5. Do we want a dedicated docs/codex-setup.md after implementation, or should Codex live inside a more general AI config guide

Definition Of Done ​

The Codex update is done when:

  • project creation produces Codex-ready files
  • sync commands maintain those files
  • Codex can discover project skills
  • Codex can use supported custom subagents
  • docs accurately describe the behavior
  • CLI tests enforce the new contract

References ​

Released under the MIT License.

Copyright © 2024 WDG