Codex-Claude Handoff Skill
Purpose
Use this skill to coordinate AI tools in the same software project using a shared handoff file (AI_HANDOFF.md) as the execution state.
Recommended Workspace
The recommended user-facing workspace is VS Code with the same project folder open for
Codex and Claude Code. The tools coordinate through the project's local handoff files,
not through a hidden chat bridge. VS Code is a convenient shared workspace; this protocol
does not install a VS Code extension or provide unrestricted background automation.
When a window turn is manual, NEXT_TURN.md contains the short prompt for the next tool.
Bounded CLI automation is available only for the states and adapters documented in
ADAPTERS.md, and sensitive actions still require the user.
Role Model
The protocol is organized around three roles, plus the User. Roles are bound to concrete tools in .ai/roles/ROLE_ASSIGNMENT.md, so they can be reassigned (with user approval) without rewriting the protocol.
- Master - decision router, architect, task writer, and coordinator.
- Implementer - implementation agent; during investigation and planning turns also a read-only repository-local feasibility and capability partner.
- Reviewer - independent review of implementation against approved scope, plus the Verification Gate.
- The User - the approval point. Never one of the three roles.
Default binding: Master = Codex, Reviewer = Codex, Implementer = Claude Code. This is behaviorally identical to earlier versions of the protocol.
Invariant: the Reviewer must never be the same tool as the Implementer (an implementer cannot be the sole reviewer of its own work). Switching roles requires explicit user approval. See .ai/roles/ROLE_ASSIGNMENT.md.
Multi-task coordination (the "Sequence Owner") is a duty of the Master role, not a fourth role. For the operating method, its layers, and the lifecycle vocabulary, read PROTOCOL_METHOD.md in this folder (since v0.18.0).
The Master role is read-only with respect to source during consultation: the Implementer does not modify source files during investigation or planning turns, and control returns to the Master before any implementation task is finalized.
Canonical Shared Folder
This file is in .ai/skills/codex-claude-handoff/. The following files contain the full protocol:
| File | Contents |
|---|---|
SKILL.md | This file - shared protocol index and role model |
MASTER.md | Master + Reviewer role protocol: decision router, gates, states, review, verification |
IMPLEMENTER.md | Implementer role protocol: investigation mode, planning mode, implementation rules, states |
PROTOCOL_METHOD.md | Protocol method specification: method layers, lifecycle mapping, vocabulary, precedence (since v0.18.0) |
ADAPTERS.md | Adapter registry and automation capability contract (since v0.19.0) |
CODEX.md | Codex entry pointer - resolves Codex's current role(s) and points to the role file |
CLAUDE.md | Claude Code entry pointer - resolves Claude Code's current role(s) and points to the role file |
CAPABILITIES.md | Agent capability profile: what each tool is good at and the default role binding |
CLAUDE_EXECUTION_POLICY.md | Claude execution profiles, command transparency, model/subagent evidence rules, and continuity artifacts |
README.md | Human-facing overview of this folder |
VERSION | Installed protocol version |
The role-to-tool binding lives one level up, in .ai/roles/ROLE_ASSIGNMENT.md.
It is the single source of truth for role binding. AI_HANDOFF.md Task Actors are
derived display data only. Every turn begins by rereading the binding and checking
for drift or Reviewer==Implementer; failures stop the protocol closed.
How to Resolve Your Behavior
- Read
.ai/roles/ROLE_ASSIGNMENT.mdto find which role(s) your tool currently holds. - If you hold Master and/or Reviewer: follow
MASTER.md. - If you hold Implementer: follow
IMPLEMENTER.md. - The tool-named entry pointers (
CODEX.md,CLAUDE.md) exist only to send each tool to the right role file; they do not define behavior themselves.
Required Project Files
When this protocol is active, expect these files in the project root:
AGENTS.md- project context plus the Master + Reviewer protocol (read by the tool that follows the AGENTS.md convention)CLAUDE.md- the operational entry file for Claude Code (resolves its role)AI_HANDOFF.md- current state, which role acts next, changed files, verification, risks, and next stepAI_SEQUENCE.md- local multi-task ordering artifact (since v0.18.1): ordered task list, per-task status, release checkpoints. Local, gitignored, never committed; seePROTOCOL_METHOD.md.ai/skills/codex-claude-handoff/ADAPTERS.md- adapter registry for callable/manual automation status (since v0.19.0).ai/skills/codex-claude-handoff/CLAUDE_EXECUTION_POLICY.md- Claude execution policy and continuity evidence (since v2.3.0)
Encoding-Safe Handoff Rule
When a task involves non-English UI text (Hebrew, Arabic, RTL, CJK, or any language with encoding-sensitive characters), every role must follow these rules:
- Never copy UI text from handoff files.
AI_HANDOFF.mdandNEXT_TURN.mdmay contain garbled or corrupted characters if the author's terminal encoding was unstable. Do not use that text as a search string, a match pattern, or text to insert. - Write semantic English descriptions in handoff files. Describe what the text means rather than copying the literal characters.
- Always inspect the source file directly. Before editing, searching for, or reviewing any UI string, open the actual source file and read the text from there.
- Point to the exact location. Reference the file path, component name, line number, or a nearby code comment - not the raw text itself.
- If exact text is needed for a search or match, derive it from the source file, not from terminal output or handoff notes.
- The source of truth for UI text is the source file, not the handoff.