/codex-thread-orchestration

name: codex-thread-orchestration
description: Use when running Arcgentic V2 in Codex and the current thread must orchestrate fixed Planner, Developer, Test, and Auditor role threads.

codex-thread-orchestration

Use this skill only in Codex host mode. The current thread is the `Orchestrator`.

Contract

V2 uses exactly five host-visible thread titles:

• `Orchestrator`
• `Planner`
• `Developer`
• `Test`
• `Auditor`

Never create `R1 Developer`, `R2 Test`, `R3 Auditor`, or other round-numbered thread names. Round identity lives in `.agentic-rounds/state.yaml` and in the role prompt.

Phase/project close is Orchestrator-owned after Planner declares that a phase or the full project is complete. It is not a per-round role and it must not run after every Auditor PASS.

V2 has two project-level modes:

• `single-session-subagent`: faster and usually completes sooner. The current

Orchestrator session runs named Planner / Developer / Test / Auditor subagents without creating role threads. Role names must still be inherited exactly. The first use of a role creates that named role identity; later rounds reuse the same role identity.

• `multi-session-subthread`: slower, with stronger role separation. The

Orchestrator creates or reuses fixed project threads titled Planner, Developer, Test, and Auditor.

If no mode is stored, judge the user's idea and recommend a mode before dispatching Planner:

arcgentic session-mode recommend-v2 --idea '<current user request>'

Show the recommendation, confidence, reasons, and tradeoff, then ask the user to confirm or override it. Do not default silently.

Procedure

1. Rename the current Codex thread to exactly `Orchestrator`, then ensure `.agentic-rounds/state.yaml` records the current thread as `Orchestrator` before dispatching any role:

   arcgentic v2-record-session \
     --state .agentic-rounds/state.yaml \
     --host codex \
     --role orchestrator \
     --thread-id <current-orchestrator-thread-id> \
     --title Orchestrator

If the host cannot provide the current Orchestrator thread id, stop. Without this id, Planner / Developer / Auditor cannot actively send completion back. If the host cannot rename the current thread, stop because the fixed-role thread set is not visible to the user. If this thread was created from a Codex delegation payload, the `source_thread_id` is not the current Orchestrator id. It is the upstream supervising thread id and must not be recorded as the push-return target. When correcting only this mistake, use:

   arcgentic v2-record-session \
     --state .agentic-rounds/state.yaml \
     --host codex \
     --role orchestrator \
     --thread-id <current-orchestrator-thread-id> \
     --title Orchestrator \
     --repair-current-orchestrator

2. If no project-level mode is stored, run the V2 mode recommendation command, ask the user to confirm or override it, then continue with the chosen mode.

3. Run:

   arcgentic v2-session-plan \
     --state .agentic-rounds/state.yaml \
     --host codex \
     --user-request '<current user request>' \
     --mode <single-session-subagent|multi-session-subthread>

This must happen before source inspection, test runs, git-log verification, or summaries of prior closed rounds.

4. If `orchestrator_status` is `sleeping`, stop immediately. The Orchestrator is waiting for `pending_role` to return a `RoleReturnSignal`; do not dispatch another role and do not do the pending role's work inline.

5. If `orchestrator_status` is `active` and `actions` is empty, branch by state:

• `passed`: stop and report that the round PASS cannot advance because the

state has no usable `project.arcgentic_v2.project_plan`. Do not close the round. A valid project plan lets `v2-session-plan` advance to the next round or Planner phase-boundary decision.

• `closed`: stop. The round is terminal and all role threads should be idle.

Only a new user request may wake Orchestrator and route to Planner.

• any other state: stop and report the stop state. Do not create a role

thread manually. This is how Arcgentic prevents loops such as a repeated `AUDIT_INCOMPLETE` for the same unresolved evidence gap.

6. If `orchestrator_status` is `active`, dispatch the single action in `actions`:

• `target=thread`, `kind=reuse`: send `prompt` to `thread_id`.
• `target=thread`, `kind=create`: create a Codex project thread using the

current workspace root path as the Codex `projectId`, set its title to `title`, send `prompt`, then record the returned id:

• `target=subagent`, `kind=create`: keep work inside the current

Orchestrator session and create the fixed named role agent, using `title` exactly (`Planner`, `Developer`, `Test`, or `Auditor`). Record the role with synthetic id `subagent:<role>` so later rounds reuse it.

• `target=subagent`, `kind=reuse`: keep work inside the current

Orchestrator session and reuse the fixed named role agent. Do not create a second Developer / Planner / Test / Auditor identity.

     arcgentic v2-record-session \
       --state .agentic-rounds/state.yaml \
       --host codex \
       --role <role> \
       --thread-id <created-thread-id>

For `target=subagent`, record the synthetic role id:

     arcgentic v2-record-session \
       --state .agentic-rounds/state.yaml \
       --host codex \
       --role <role> \
       --thread-id subagent:<role>

In Codex, the saved project id is the current workspace root path exposed by the thread `cwd`. Do not search thread lists to infer a separate project id. Do not use projectless threads for Arcgentic role sessions. If the created thread does not show the current project `cwd`, archive it and recreate it under the current project. Before creating a role thread, re-read `.a