Skip to content
UXClaim
Design Ops

Claude Codex Handoff

Three-phase workflow (plan→implement→review) pairing Claude Code specs with Codex implementation and independent adversarial review for complex code changes.

View source More in Design Ops

What it does

Claude Codex Handoff orchestrates a structured three-phase workflow for code changes that deserve written specifications. Phase 1 has Claude Code explore code, ask clarifying questions, and write a detailed spec. Phase 2 delegates implementation to Codex CLI running in the background, isolated from planning assumptions. Phase 3 brings in a fresh Codex session to adversarially review the diff against the spec, flagging blockers and false positives separately.

How it works

The workflow automates protocol that otherwise requires reinvention: Claude plans and writes .agent/specs/ files for your approval. Once approved, you trigger /codex:rescue to run implementation in the background. When complete, /codex:adversarial-review runs in a fresh session with no memory of design rationale, treating the spec as ground truth and challenging implementation decisions independently. Claude then triages the review report and recommends fix-or-ship.

Use cases

Reach for this skill for changes touching multiple files, involving business logic, auth, data handling, or DB migrations. Skip it for typos, single-line tweaks, or exploration questions. For lighter in-between tasks (under 30 lines, single file), use /codex:review instead.

Who benefits

Product engineers managing code review quality and consistency. Teams working with Claude Code + Codex CLI stacks. Projects where written specs before coding prevent rework and miscommunication.

Frequently asked questions

What's the difference between this and asking Claude to code directly?
This skill separates planning from implementation: Claude writes a spec, then Codex implements independently without the planning bias, then a fresh Codex session reviews without memory of why things were designed that way. This catches oversights the original model rationalized away. Skip it for simple changes under 30 lines.
How do I install Claude Codex Handoff?
In Claude Code, run: `/plugin marketplace add ParaGenie/claude-codex-handoff` then `/plugin install codex-handoff@paragenie-skills`. Also install the Codex plugin: `/plugin marketplace add openai/codex-plugin-cc` and `/plugin install codex@openai-codex`. Then bootstrap each project with `cp CLAUDE.md.template CLAUDE.md` and `mkdir -p .agent/specs .agent/reviews`.
What does the adversarial review phase actually do?
Phase 3 starts a fresh Codex session with only the spec and diff, no context about design decisions. It re-reads the spec, challenges implementation choices, flags logical blockers, and separates valid concerns from false positives. Claude then triages the report and recommends fix-or-ship, returning decision authority to you.
When should I use this vs. just having Claude review its own code?
Use this for changes touching multiple files, involving business logic, auth, payments, data, or DB migrations — anything where a written spec and independent review prevent costly bugs. Skip it for typos, single-line tweaks, or exploration. For in-between tasks (< 30 lines, single file), use `/codex:review` instead.
How do I approve the spec and start implementation?
Once Claude writes `.agent/specs/<slug>.md` and asks for approval, review it and reply 'approved' in the chat. Claude will then issue `/codex:rescue --background` to start implementation. Codex works independently and commits to a feature branch when done.
What if Codex finds a bug during review?
Claude reads the review report, separates valid bugs from false positives, and recommends fix-or-ship. For valid blockers, you can run `/codex:rescue --resume` to fix them. For false positives, Claude explains why it's intentional. Final merge decision stays with you.
Can I customize the spec template for my project?
Yes. Edit `CLAUDE.md` per-project with your stack, key docs, and constraints. This file acts as the project's 'identity card' that Claude reads before writing specs. You can also create `.codex/config.toml` to pin model version and reasoning effort for consistent implementation.
What if I'm working in an air-gapped or offline environment?
Use Option B for manual install: `git clone https://github.com/ParaGenie/claude-codex-handoff.git ~/.claude/skills/codex-handoff`. Or use curl + tar if git isn't available. The skill directory name must be `codex-handoff` for Claude Code to locate it.

Glossary

Spec
A written specification (`.agent/specs/<slug>.md`) that Claude Code produces in Phase 1. It documents the change's intent, scope, edge cases, and acceptance criteria before any implementation begins.
Adversarial review
Phase 3 review by a fresh Codex session that reads only the spec and diff, with no memory of planning decisions. It challenges implementation choices and flags blockers independently.
Rescue
The `/codex:rescue` slash command that triggers Phase 2. Codex CLI implements the spec in a background process, creates a feature branch, commits changes, and runs acceptance tests.
Triage
Claude's act of reviewing the adversarial report: separating valid bugs from false positives, explaining the reasoning behind each flagged item, and recommending fix-or-ship.
CLAUDE.md
A per-project 'identity card' file that documents stack, key docs, hard constraints, and custom commands. Claude Code reads this before planning to understand project context.

More in Design Ops

All →
Design Ops

AI Code Refactoring

Disciplined 5-phase workflow for refactoring AI-generated code with safety nets, design systems, and tests.

chake111
Design Ops

Goal Workflow Designer

Interrogates you until your /goal prompt is precise enough to work, using a five-element framework and rubric SOP.

dragon375014
Design Ops

Backend Design

Auto-scaffold a matching backend from your frontend by analyzing screens, components, forms, and API calls.

jwolfsohn
Design Ops

Claude Code Design AI

AI-powered tool that converts design screenshots and wireframes into production-ready React components with Tailwind CSS styling.