Simple specification-driven development workflow for Codex CLI
npm install spec-driven-codex-for-claudecodeA lightweight, specification-driven development workflow that combines Codex CLI for requirements definition and prompt creation with Claude Code for actual code implementation. This is a fork of Spec Driven Codex, optimized for Claude Code workflows.
This tool enables a hybrid workflow:
1. Codex CLI - Define requirements, create structured prompts, and review specifications
2. Claude Code - Implement the actual code based on the prompts generated by Codex
Run npx spec-driven-codex-for-claudecode init to scaffold the .sdd workspace and install Codex prompts that guide you from discovery to delivery. Use npx spec-driven-codex-for-claudecode upgrade any time you need to refresh the prompts with the latest templates.
``bashGlobal installation (recommended)
npm install -g spec-driven-codex-for-claudecode
Features
- Single command setup –
bootstraps everything you need
- Safe re-runs – existing Codex prompts are kept as-is while .sdd/README.md is refreshed every run
- One-step upgrades – upgrade force-installs the latest prompt copies and refreshes .sdd/README.md
- Codex-ready prompts – English by default, Japanese with
- Always in sync – Spec artifacts live under for the entire flowQuick Start
`bash
Inside your project root
npx spec-driven-codex-for-claudecode initLaunch Codex CLI for requirements and prompt creation
codex
> /sdd-steering
> /sdd-requirements
> /sdd-design
> /sdd-tasks
> /sdd-task-prompt 1 # Generate implementation prompt for task 1Implement with Claude Code
Open .sdd/specs/[spec-name]/tasks/1/prompt.md
Let Claude Code implement the task
Review implementation with Codex CLI
codex
> /sdd-task-review # Review the implemented code
> /sdd-task-fix # Generate fix instructions (if FAIL)Fix with Claude Code (if needed)
Open .sdd/specs/[spec-name]/tasks/1/fix-v1.md
Let Claude Code fix the issues
Repeat review until PASS (max 5 iterations)
`Pass
to init if you prefer Japanese templates and prompts:`bash
npx spec-driven-codex-for-claudecode init --locale ja
`To refresh the prompt templates later on, run:
bash
npx spec-driven-codex-for-claudecode upgrade
`CLI Command
| Command | Description |
| --- | --- |
|
| Creates .sdd/ scaffolding, localized templates, installs Codex prompts (existing prompt files are left untouched) and always refreshes .sdd/README.md. |
| npx spec-driven-codex-for-claudecode upgrade [--locale ja] | Force-installs the latest Codex prompt templates into ~/.codex/prompts (overwrites without confirmation) and refreshes .sdd/README.md. |Codex CLI Prompts
$3
Once the workspace is initialized, run the Codex CLI prompts in sequence to progress through the specification-driven flow:
-
/sdd-steering — Capture product context, stakeholders, and risks.
- /sdd-requirements — Define requirements and acceptance criteria. Update .sdd/description.md with the problem and feature summary before running this prompt so the requirements stay grounded in the latest context.
- /sdd-highway — Optional fast lane that triggers /sdd-design, /sdd-tasks, and /sdd-implement back-to-back.
- /sdd-design — Document architecture and implementation strategy.
- /sdd-tasks — Break the design into actionable tasks.
- /sdd-implement — Implement every task with tests and refactors.
- /sdd-archive — Summarize outcomes, lessons learned, and next steps.$3
Use these commands to create task-specific prompts and review Claude Code's implementation:
-
/sdd-task-prompt [number] — Generate a structured implementation prompt for a specific task. Outputs to .sdd/specs/[spec-name]/tasks/[number]/prompt.md.
- /sdd-task-review — Review the code implemented by Claude Code against requirements and design. Creates .sdd/specs/[spec-name]/tasks/[number]/review-v[N].md with PASS/FAIL judgment.
- /sdd-task-fix — Generate fix instructions for issues detected in review. Outputs .sdd/specs/[spec-name]/tasks/[number]/fix-v[N].md with prioritized code fixes.Workflow:
1. Use Codex CLI to break down requirements into tasks
2. Generate implementation prompt:
/sdd-task-prompt 1
3. Let Claude Code implement the code based on the prompt
4. Review implementation: (Codex reviews the code)
5. If FAIL: /sdd-task-fix → Claude Code fixes → /sdd-task-review (repeat until PASS, max 5 times)
6. If PASS: Move to next task with /sdd-task-prompt 2This separates specification and review (Codex CLI) from implementation (Claude Code), allowing each tool to focus on its strengths.
$3
Codex CLI occasionally prints a high-level plan to the console before it actually runs the command. When that happens—or when the CLI explicitly asks for approval—simply type
(or another affirmative response) and press Enter to let the flow continue.Generated Structure
`
project/
├── .sdd/
│ ├── README.md # Locale-aware command overview
│ ├── description.md # Feature description template
│ ├── target-spec.txt # Active specification name
│ ├── target-task.txt # Current task number
│ ├── steering/ # Discovery notes (/sdd-steering)
│ └── specs/ # Specs, tasks, archives, and artifacts
│ └── [spec-name]/
│ ├── requirements.md
│ ├── design.md
│ └── tasks/ # Task-specific prompts and reviews
│ └── 1/
│ ├── prompt.md # Implementation instructions
│ ├── review-v1.md # Code review results
│ ├── fix-v1.md # Fix instructions
│ ├── review-v2.md # Re-review after fixes
│ └── ... # Up to 5 review-fix iterations
└── ~/.codex/prompts/
├── sdd-steering.md
├── sdd-requirements.md
├── sdd-design.md
├── sdd-tasks.md
├── sdd-task-prompt.md # New: task-specific prompt generation
├── sdd-task-review.md # New: code implementation review
├── sdd-task-fix.md # New: code fix instructions
└── sdd-archive.md
Need the Japanese documentation? Check README.ja.md.
Looking for updates in another language? Contributions that keep both documents aligned are welcome.
This project is a fork of Spec Driven Codex by Tomada, which itself draws inspiration from gotalab/cc-sdd. Many thanks to all maintainers and contributors for sharing their approach to specification-driven development.