Dual-Assistant Maintenance Model

Last updated: April 16, 2026

Purpose

This document defines how WDG should maintain Claude and Codex support without creating two separate AI configuration systems.

The goal is to keep one platform workflow with assistant-specific render targets only where the formats or discovery paths actually differ.

Core Rule

Do not hand-maintain duplicate Claude and Codex content unless the file formats are genuinely different.

Prefer this order:

1. one canonical authored source
2. one or more generated assistant-specific outputs
3. one generic CLI command that keeps those outputs in sync

Source Of Truth Model

Shared guidance

Use AGENTS.md and AGENTS.md.template as the canonical cross-assistant instruction layer.

Why:

• the guidance is conceptually shared
• Codex reads AGENTS.md directly
• duplicating repository norms into assistant-specific files creates drift immediately

Shared skills

Use cli/templates/project-skills/ as the canonical authored skill source.

Render targets:

• Claude: .claude/skills/
• Codex: .agents/skills/

Why:

• the SKILL.md model is reusable
• the discovery path differs
• the copy step can handle small path or metadata rewrites

Assistant-specific agents

Treat project agents as assistant-specific output formats.

Canonical sources:

• Claude agents: cli/templates/project-agents/
• Codex agents: cli/templates/project-codex-agents/

Why:

• Claude agent files and Codex subagent files are different formats
• trying to force one source file to render cleanly into both formats is brittle

Assistant-specific config

Treat assistant config files as generated outputs owned by the CLI.

Examples:

• Claude: .claude/settings.json
• Codex: .codex/config.toml
• Cursor: .cursor/cursorrules

Why:

• these are format-specific
• they should be regenerated from templates, not hand-edited across repositories

Command Model

The CLI should remain assistant-agnostic in naming and assistant-aware in behavior.

That means:

• wdg create should generate all supported assistant outputs for a new project
• wdg <project> ai-config sync should refresh all generated assistant config outputs
• wdg <project> skills sync should deploy skills to all supported discovery paths

Avoid creating separate commands such as codex-sync or claude-skills-sync unless there is a real operational need that cannot be expressed through flags.

Maintenance Matrix

Concern	Canonical source	Claude output	Codex output	Primary sync path
Repo instructions	AGENTS.md.template	AGENTS.md	AGENTS.md	wdg create, wdg <project> ai-config sync
Project config	assistant templates in repo root	.claude/settings.json	.codex/config.toml	wdg create, wdg <project> ai-config sync
Skills	cli/templates/project-skills/	.claude/skills/	.agents/skills/	wdg create, wdg <project> skills sync
Project agents	assistant-specific template dirs	.claude/agents/	.codex/agents/	wdg create, wdg <project> ai-config sync
MCP baseline	MCP templates and config templates	tool-specific config output	tool-specific config output	wdg create, wdg <project> ai-config sync, wdg <project> mcp sync
Docs	docs/	shared docs	shared docs	normal docs updates

When Divergence Is Allowed

Differences between Claude and Codex are acceptable only when at least one of these is true:

• the file format is different
• the discovery path is different
• the tool surface is intentionally different and documented
• the assistant runtime model is different, such as Claude Markdown agents versus Codex TOML subagents

Differences are not acceptable when they are only the result of maintenance neglect.

Change Workflow

For any AI platform change:

1. Classify the change as shared or assistant-specific.
2. Update the canonical source first.
3. Update the Claude and Codex render paths if both are in scope.
4. Update the generic sync command rather than inventing a one-off manual step.
5. Update help text and docs so command behavior matches reality.
6. Add or update tests for both assistant outputs.
7. Run a manual smoke test when the change affects generated files or sync flows.

Anti-Patterns

Avoid these patterns:

• hand-editing generated .claude/ or .codex/ files across project repositories
• keeping the same workflow text in multiple assistant-specific source files
• shipping a new shared feature to Claude only and planning Codex later
• adding assistant-specific command names when one generic command can own the behavior
• silently narrowing Codex or Claude tool access without documenting the intentional difference

Review Standard

Any AI-related pull request should answer these questions clearly:

1. What is the canonical source of truth for this change?
2. Does it affect shared guidance, skills, agents, config, MCPs, or docs?
3. What are the Claude and Codex render targets?
4. Which command generates or syncs the outputs?
5. What tests prove the two assistants stay aligned?

Related Documents

• Overview
• Current State Audit
• Migration Plan
• AI Feature Checklist