Codex Thread Orchestration

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 .agentic-rounds/state.yaml and confirm that the same role is still unrecorded and that orchestrator_status is still active. If another turn has already recorded that fixed role, reuse the recorded thread. If the Orchestrator is now sleeping, stop; do not create a recovery duplicate.

   Supervising or recovery sessions must not create Planner / Developer / Test / Auditor threads on behalf of an in-progress Orchestrator turn. They may send one constraint-tightening message to the Orchestrator, then wait or report a timeout. Creating a role thread outside the Orchestrator creates duplicate role ownership and invalidates the workflow evidence.

   Use the strongest available Codex model for real Planner / Developer / Test / Auditor work. Do not default role threads to a lightweight or spark model unless the user explicitly asks for a low-cost smoke test. If the host tool supports a model override, choose the best available model. If unsure, omit the override so the current project/session default is preserved rather than downgraded.

7. In multi-session-subthread, after sending the role prompt, put the Orchestrator to sleep:

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

   End the Orchestrator turn here. Do not wait in the Orchestrator thread and do not dispatch another role. The next Orchestrator turn starts only after the role thread returns information.

   In single-session-subagent, do not call v2-dispatch-role and do not put the Orchestrator to sleep. The named subagent completes inside the current Orchestrator session, then the Orchestrator immediately consumes the returned RoleReturnSignal and routes the next action.

8. When a multi-session role thread completes, it must actively send its return message to the Orchestrator thread. The Orchestrator must not poll role threads to discover completion.

   If the role thread does not return promptly, send one status/constraint tightening message that repeats the required role boundary and RoleReturnSignal shape. If it still does not return a valid signal, stop with a role-timeout report. Do not perform that role's work in the Orchestrator.

9. Require the role thread to produce natural-language role output plus exactly one machine-readable footer:

Planner example. Planner must produce the complete project phase/round plan and a detailed Markdown handoff for the first/current round. Before writing the handoff, Planner must:

• search GitHub or equivalent public sources for reliable comparable projects or effective implementation references;
• scan locally available skills, plugins, MCP servers, connectors, and CLI tools that can help this project;
• choose which references/tools are used this round, which are considered but rejected, and why;
• write those decisions into the handoff so Developer, Test, and Auditor can read the artifact instead of relying only on the Orchestrator prompt.

The Orchestrator transfers prompt instructions between threads, but the role prompt must tell the receiving session to read the referenced handoff artifact before acting.

R1 plan is ready.

- Plan artifact: docs/plans/R1.md
- Scope: build the smallest working CLI and verify it through command-level tests.
- Next role: Developer should implement from the handoff and return a self-audit.

{
  "role": "planner",
  "status": "planned",
  "round_id": "R1",
  "state": "awaiting_dev_start",
  "artifacts": {
    "handoff": "docs/plans/R1.md",
    "project_plan": {
      "phases": [
        {
          "id": "P1",
          "rounds": [
            {
              "id": "R1",
              "handoff": "docs/plans/R1.md",
              "test_gate": {
                "required": false,
                "reason": "No separate reality QA gate is needed for this round."
              }
            }
          ]
        }
      ]
    }
  },
  "next_recommended_role": "developer"
}

Planner output should be a readable plan, not raw JSON. Developer output should be a readable self-audit summary, not raw JSON. Test output should be a readable simulated user-test report, not raw JSON. Auditor output should be a readable verdict, not raw JSON. The footer is the routing envelope.

Planner close/project-completion output must write a closeout artifact, create a local closeout commit, verify git rev-parse HEAD, and include both artifacts.closeout and artifacts.commit in the return footer. A closed project uses "next_recommended_role": null; it must not recommend Planner again unless there is a genuinely new user request.

Developer must not return from a purely working-tree state. After implementation and verification, Developer must stage the round-owned files, create a normal local Git commit, verify git rev-parse HEAD, write the self-audit, and include both artifacts in the return footer.

If project_plan.test_gate.required for the current round is true, Developer routes to Test:

{
  "role": "developer",
  "status": "completed",
  "round_id": "R1",
  "state": "awaiting_test",
  "artifacts": {
    "self_audit": "docs/audits/R1-self-audit.md",
    "commit": "<40-hex-local-dev-commit>"
  },
  "next_recommended_role": "test"
}

If the current round's Test gate is skipped, Developer routes directly to Auditor:

{
  "role": "developer",
  "status": "completed",
  "round_id": "R1",
  "state": "awaiting_audit",
  "artifacts": {
    "self_audit": "docs/audits/R1-self-audit.md",
    "commit": "<40-hex-local-dev-commit>"
  },
  "next_recommended_role": "auditor"
}

A GitHub remote is not required for local audit. It is stronger evidence for release or CI gates, but the minimum audit anchor is a local immutable commit.

Test is not the external auditor and is not a mandatory per-round step. Test owns realistic simulated user/session testing only when Planner's project plan requires it after Developer has produced code, self-audit, and a local commit anchor. Examples:

• CLI: run representative commands and stdin/argument flows like a user.
• Web/mobile app: launch the app or simulator and drive visible UI flows.
• Agent: run an end-to-end user conversation that exercises the promised task.

If the simulated user flow passes, Test writes a report and routes to Auditor:

{
  "role": "test",
  "status": "user_tested",
  "round_id": "R1",
  "state": "awaiting_audit",
  "artifacts": {
    "user_test": "docs/tests/R1-user-test.md",
    "commit": "<40-hex-local-dev-commit>"
  },
  "next_recommended_role": "auditor"
}

If the simulated user flow fails, Test writes the failed user-test report and routes to needs_fix / Developer.

9. Record the signal. This wakes the Orchestrator and clears the pending dispatch:

   arcgentic v2-return-signal \
     --state .agentic-rounds/state.yaml \
     --signal-text '<role return message including arcgentic-role-return block>'

   Treat rejection from this command as authoritative. Do not hand-extract or hand-repair JSON in the Orchestrator unless the same role thread explicitly returns a corrected message.

10. After an Auditor PASS return, do not close the round. Re-run v2-session-plan. If the stored project plan has another round in the current phase, v2-session-plan advances to that round and returns a Developer action. If the phase has no more rounds, it routes to Planner for phase-boundary close / next-phase / project-close decision.

11. Dispatch the next role only if the plan is active and contains exactly one action. If it is active with no actions, stop and report the stop state.