codex-handoff

Codex Handoff

Codex-handoff orchestrates read-only investigation or implementation within the current session after explicit plan approval. Task-handoff instead writes a decision-complete file for a fresh, separate session; use it when work continues later or elsewhere, and use an in-session handoff skill to implement an approved plan now.

If these instructions are already present in the conversation from a slash or dollar invocation, follow them directly; do not invoke this skill again through a skill tool.

Follow the shared contract below, select exactly one host adapter, and use it for every host-specific action.

Host Selection

Inspect the callable orchestration tools, not environment variables, process ancestry, or a user-supplied host name:

• spawn_agent, wait_agent, send_message, followup_task available: read references/codex-cli-host.md completely.
• Otherwise, Claude Code's Agent and Bash tools available: read references/claude-code-host.md completely.
• Neither: stop with a compatibility error. Native Codex multi-agent support is mandatory on the Codex host; never fall back to a nested Codex CLI process.

Use exactly one adapter for every host-specific action; never load both or combine their launch, progress, retry, permission, or result-transport mechanics. The adapter may specialize host mechanics and manifest configuration but cannot weaken this shared contract.

Contract

• Run only after explicit invocation. Research-only = requested outcome is findings/evidence/assessment only, no repo changes or plan requested. All handoffs may run in any host mode; implementation handoffs must pass through the Plan Phase and receive explicit user approval before launch.
• The parent owns decisions, the final plan, and orchestration. Delegate investigation to read-only research agents only when task and repository evidence make it useful before planning.
• Research agents gather evidence and report findings only — never edit files, make design decisions, or return plans.
• Implementation agents implement their assigned part of the approved plan: inspect, edit, validate, never redesign or return another plan.
• Use the smallest effective implementation team (one agent is valid); add agents only when decomposition materially improves latency, correctness, or verification. Never exceed eight implementation agents total.
• Size every brief before finalizing the team: estimate its wall-clock time and split any brief likely to exceed roughly 25-30 minutes into parallel disjoint scopes or dependency waves — add an integration agent if needed — instead of one monolithic agent.
• Use at most three research agents, stable IDs R1-R3, counted separately from the eight implementation agents.
• Keep the parent's own implementation work to orchestration, integrity checks, failure handling, and conditional polish passes.
• Treat an explicit user model preference (e.g. GPT-5.6 Luna) as an orchestration constraint on every research and implementation agent unless scoped narrower; don't substitute the adapter's usual Luna/Terra/Sol/Astra selection. If the host can't launch that model, report the incompatibility and ask before falling back.
• Treat the approved outcome — not the initial manifest or its write scopes — as the authorization boundary: when implementation reveals a related in-repository fix or evidence change required for that outcome, the parent may extend the handoff and launch follow-on agents for the newly discovered scope without asking again. The worker that discovered the need still stops at its assigned scope and returns evidence; the parent owns scope expansion, repository coordination, and delegation.