WDG AI Dev Environment

Appearance

Current State Audit ​

Audit date: April 16, 2026

Summary ​

The platform is no longer starting from zero. Codex now has real project-generation and sync support, but parity is still incomplete at the content and documentation layers.

The repo currently supports these layers of AI assistant setup:

  • shared repo guidance through AGENTS.md
  • Claude-specific config generation and sync
  • Cursor-specific config generation and sync
  • project-local Codex config, skills, and subagent generation with some remaining gaps

What Already Works For Codex ​

Shared instructions already exist ​

Codex reads AGENTS.md natively and supports layered instruction discovery from the repo root down to the current working directory. That makes the existing WDG AGENTS.md approach directly reusable.

Relevant local files:

  • AGENTS.md
  • AGENTS.md.template
  • project-generated AGENTS.md files described in docs/claude-config.md

A root Codex config already exists ​

The platform repo already contains .codex/config.toml.

Current behavior:

  • configures wdg-local
  • does not mirror all MCP servers found in .mcp.json
  • is not part of the project generation or sync flow

Relevant local file:

  • .codex/config.toml

Project creation now generates Codex files ​

The project generator now creates Codex-facing files alongside the existing Claude and Cursor outputs.

Current generated Codex outputs:

  • .codex/config.toml
  • .agents/skills/
  • .codex/agents/

Relevant local files:

  • cli/commands/create.sh
  • .codex/config.template.toml
  • cli/templates/project-codex-agents/

AI config sync now refreshes Codex outputs ​

wdg <project> ai-config sync now refreshes:

  • .codex/config.toml
  • .claude/agents/
  • .codex/agents/

Relevant local file:

  • cli/commands/ai-config.sh

Skills now deploy to both assistant discovery paths ​

Project skills are now deployed to:

  • .claude/skills/
  • .agents/skills/

The Codex copy also receives compatibility rewrites and generated agents/openai.yaml metadata.

Relevant local files:

  • cli/commands/create.sh
  • cli/commands/skills.sh
  • cli/lib/templates.sh

One project has a real Codex subagent example ​

There is at least one live example of a Codex subagent in the environment:

  • projects/ridhwan/repositories/ridhwan/.codex/agents/wdg-platform-onboarding.toml

This is useful as a migration reference because it already follows Codex's TOML-style custom agent format.

The docs already acknowledge Codex ​

Codex is mentioned in the documentation, but mostly as a placeholder rather than a fully supported workflow.

Relevant local docs:

  • docs/index.md
  • README.md

What Does Not Work Yet ​

MCP parity is incomplete ​

The generated .mcp.json template includes:

  • wdg-local
  • chrome-devtools
  • mcp-auth-proxy

The current root .codex/config.toml remains narrower, and the platform still needs a deliberate Codex MCP parity decision documented clearly.

Relevant local files:

  • .mcp.json.template
  • .mcp.json
  • .codex/config.toml

Skill content still contains assistant-specific assumptions ​

The deployment paths now work, but some skill bodies and references still assume older Claude-oriented wording or invocation semantics.

Relevant local files:

  • cli/templates/project-skills/
  • docs/claude-config.md
  • docs/MCP_GUIDE.md

Public docs still lag the implementation ​

Some docs still describe Codex as manual or partial setup even though the generator and sync layers are now live. Others still describe multi-assistant parity too broadly.

Relevant local docs:

  • docs/claude-config.md
  • docs/index.md
  • README.md
  • QUICKSTART.md

Compatibility Findings From Official Codex Docs ​

AGENTS.md is the right shared instruction layer ​

Codex reads AGENTS.md before work and supports layered project instructions. This means WDG should keep AGENTS.md as the cross-assistant project guidance file instead of inventing a Codex-specific replacement for the same purpose.

Codex project config belongs in .codex/config.toml ​

Codex supports both ~/.codex/config.toml and project-level .codex/config.toml files. Project config is loaded only for trusted projects and participates in precedence resolution.

Codex skills use SKILL.md, but not the Claude path ​

This is the most important compatibility nuance.

The skill content model is compatible enough to reuse:

  • SKILL.md
  • optional scripts/
  • optional references/
  • optional assets/

But the repository deployment location is different. Codex scans .agents/skills/, not .claude/skills/.

The current implementation now deploys both locations and rewrites the Codex copy as needed.

Codex subagents are not a drop-in copy of Claude agents ​

Codex subagents are standalone TOML files in .codex/agents/. Each file must define:

  • name
  • description
  • developer_instructions

Optional configuration keys such as model, sandbox_mode, mcp_servers, and skills.config can also be set per agent.

Codex rules are not a substitute for project norms ​

Codex rules/ files control approval and shell command decisions such as allow, prompt, and forbidden. They are not the right place for coding standards, workflow instructions, or project architecture guidance. Those should stay in AGENTS.md.

Local Inventory Of Impacted Files ​

Generator and sync layer ​

  • cli/commands/create.sh
  • cli/commands/ai-config.sh
  • cli/commands/skills.sh
  • cli/commands/repo.sh

Existing assistant templates and assets ​

  • .claude/settings.project.template
  • .claude/settings.wikit.template
  • .codex/config.template.toml
  • AGENTS.md.template
  • .mcp.json.template
  • cli/templates/project-skills/
  • cli/templates/project-agents/
  • cli/templates/project-codex-agents/

Existing tests that will need Codex coverage ​

  • cli/tests/commands/create.bats
  • cli/tests/commands/ai-config.bats
  • cli/tests/commands/skills.bats
  • cli/tests/TESTING_CHECKLIST.md

Docs that will need follow-up updates once implementation starts ​

  • README.md
  • QUICKSTART.md
  • docs/index.md
  • docs/claude-config.md
  • docs/MCP_GUIDE.md

Key Conclusion ​

The main migration challenge is not MCP or shared instructions. Those are already close.

The real remaining work is in three places:

  1. MCP baseline parity and tool-surface decisions
  2. skill content and metadata cleanup for Codex-friendly behavior
  3. public docs refresh to match the live generator and sync behavior

References ​

Released under the MIT License.

Copyright © 2024 WDG