Codex SDD
codex-sdd is the Codex adapter for the Software Development Department.
It does not replace Claude Code behavior. It helps Codex follow the existing SDD contract without changing the Claude-native runtime.
Core Rule
Treat these files as the SDD source of truth:
CLAUDE.md.claude/skills/using-sdd/SKILL.mddocs/technical/SDD_LIFECYCLE_MAP.md.claude/settings.jsonfor Claude-only runtime behavior
Use using-sdd for routing. Use this skill only for Codex-specific adaptation.
Non-Impact Boundary
Do not change these for Codex-only reasons:
.claude/settings.json.claude/hooks/- existing skill names or directories
- existing agent names or files
- Claude workflow semantics for
/plan,/spec,/tdd,/context, or other
SDD commands
Codex compatibility must be additive unless the user explicitly approves a broader Claude regression-tested change.
Codex Session Start
At the start of a Codex session in SDD:
- Read
AGENTS.md. - Read
.claude/skills/using-sdd/SKILL.md. - Use
docs/technical/SDD_LIFECYCLE_MAP.mdfor phase orientation. - Select the governing SDD skill for the user request.
- Remember that Claude hooks do not auto-run in Codex.
Tool Mapping
| Claude-style tool | Codex equivalent | | --- | --- | | Read | shell read commands or direct file inspection | | Glob | rg --files or shell listing | | Grep | rg | | Write | apply_patch | | Edit | apply_patch | | Bash | shell_command | | RunCommand | shell_command | | Task | spawn_agent only when explicitly authorized | | TodoWrite | update_plan | | AskUserQuestion | concise direct user question | | WebSearch | web search only when required or explicitly requested |
Manual Hook Equivalents
Claude Code hooks in .claude/settings.json do not run automatically in Codex. Use manual equivalents:
| Claude behavior | Codex behavior | | --- | --- | | Session bootstrap | Read AGENTS.md, using-sdd, lifecycle map, and relevant memory. | | Pre-code gate | State the SDD pre-code gate before edits. | | Bash safety | Follow Codex sandbox and escalation rules. | | File history | Use git log -- <file> when needed. | | Write logging | Use git diff/status and final changed-file summary. | | Circuit guard | Inspect .claude/memory/circuit-state.json before subagent workflows. | | Completion gate | Use verification-before-completion before success claims. |
Pre-Code Gate
Before implementation edits, state:
Pre-code gate: <Fast|Spec|Plan|Interview|Override> satisfied by <evidence>; next edit: <file>; verification: <command/check>.
If the gate is not satisfied, stop and ask for the missing approval or clarification.
Verification
For SDD repo changes, run:
powershell -ExecutionPolicy Bypass -File scripts\codex-preflight.ps1
If verification cannot be run, say exactly what was skipped and why.
For narrower checks, use:
powershell -ExecutionPolicy Bypass -File scripts\validate-skills.ps1
node scripts\harness-audit.js --compact
References
AGENTS.md.codex/INSTALL.mddocs/codex-compatibility.md.claude/skills/using-sdd/SKILL.mddocs/technical/SDD_LIFECYCLE_MAP.md