Spec Driven Codex for Claude Code

A 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.

Purpose

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.

Installation

# Global installation (recommended)
npm install -g spec-driven-codex-for-claudecode

# Or use with npx (no installation required)
npx spec-driven-codex-for-claudecode init

Features

• Single command setup – init 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 --locale ja
• Always in sync – Spec artifacts live under .sdd/ for the entire flow

Quick Start

# Inside your project root
npx spec-driven-codex-for-claudecode init

# Launch 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 1

# Implement 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 --locale ja to init if you prefer Japanese templates and prompts:

npx spec-driven-codex-for-claudecode init --locale ja

To refresh the prompt templates later on, run:

npx spec-driven-codex-for-claudecode upgrade

CLI Command

| Command | Description | | --- | --- | | npx spec-driven-codex-for-claudecode init [--locale ja] | 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

Main Workflow

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.

Task-Based Prompt Generation (For Claude Code)

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: /sdd-task-review (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 2

This separates specification and review (Codex CLI) from implementation (Claude Code), allowing each tool to focus on its strengths.

Working with Codex CLI

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 ok (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.

License

MIT

Acknowledgements

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.