siglernir-ai Codex-Claude Handoff Skill
One drives. One challenges. Neither ships alone.
Purpose
Use this skill to make Codex and Claude Code an accountable engineering pair in
the same software project, using AI_HANDOFF.md as durable execution state. The
handoff is only the transport: unlike a session-summary handoff, this protocol
assigns concrete roles, tracks one live task and its exact scope, lets a different
agent challenge and review the implementation, and stops before sensitive actions
for user approval.
This is bounded collaboration rather than parallel answer generation or an unrestricted private chat. Reviewer-blocked work can return to the Implementer for correction inside an opt-in loop with turn, time, and budget limits. The two-directional question states remain explicit-turn workflows until a verified dialogue adapter is available.
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.
The default binding is Codex as Master + Reviewer and Claude Code as Implementer. With explicit user approval, the tools can exchange Master and Implementer responsibilities. Reviewer and Implementer must always remain different, and automation availability depends on the verified adapter for the selected role and tool.
- 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 |
MODEL_ROUTING.json |
Project-local, replaceable mapping from stable capability profiles to current Claude Code model identifiers |
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 stepDECISIONS.md- durable record of decisions the user confirmed (since v3.7.0). Accumulates across tasks, never reset bystart, and tracked by Git.AI_HANDOFF.mdis the source of truth for the live task; this file is the source of truth for what the product is.AI_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.