codex-thread-orchestration

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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

From Arch1eSUN/Arcgentic, MIT.

More from Arch1eSUN/Arcgentic