tranhieutt --- name: codex-sdd type: workflow description: "Adapts SDD for Codex while preserving Claude Code behavior. Use when working in Codex, setting up Codex compatibility, mapping Claude tools to Codex tools, or explaining how SDD should run outside Claude Code." argument-hint: "[codex-task-or-compatibility-question]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash context: main effort: 2 agent: technical-director when_to_use: "Use at the start of Codex sessions in this repo, before Codex implementation work governed by SDD, and whenever the task mentions Codex compatibility, AGENTS.md, .codex, or Claude-to-Codex workflow mapping."
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