---
name: codex-orchestrator
description: >
  Codex-only orchestration workflow (replaces codex-forkestrator): keeps a
  single voice-friendly main thread on Astra Low as the human communications
  channel, delegates to normal in-thread subagents via preset Codex agent
  profiles (architect/builder/scout) instead of sidebar thread forks, enforces
  artifact-first file handoffs so full contexts are never copied back into the
  main thread, and caps concurrent workers to preserve quota. Triggers:
  codex-orchestrator, codex orchestrate, orchestrate with codex, sub-orchestrate.
---

# Codex Orchestrator (`codex-orchestrator`)

Codex-only orchestration workflow replacing `codex-forkestrator`. Keeps you in
**one voice-friendly thread** watching clean subagents—eliminating sidebar
fork sprawl, `read_thread` context bloat, and always-on `XHigh` relay burn.

Loading or installing this skill does not by itself spawn subagents. Ordinary
small work stays inline (Tier 0).

---

## 1. Roles, Preset Profiles & Reasoning Effort

Raw `spawn_agent` inherits the parent's model and reasoning effort by default.
To avoid inheriting an expensive parent (or starving a hard task from a light
voice parent), define named agent profiles in `~/.codex/config.toml` (or
`~/.codex/agents/`) and invoke them by role name:

| Role | Profile Name | Model / Effort | Responsibility |
| :--- | :--- | :--- | :--- |
| **Communications Driver** *(Main / Voice Thread)* | *(main thread)* | `gpt-6-astra` (`low`) | Talk with the human (voice or text), clarify intent, run pre-flight checks, dispatch bounded subagents, present concise outcomes. |
| **Architect / Deep Research** | `architect` | `gpt-6-astra` (`xhigh`) | One-shot deep research, trade-off & threat modeling, system design. Writes full plan to disk; returns ≤ 10-line summary + file path, then ends. |
| **Builder / Implementation** | `builder` | `gpt-6-astra` (`medium`, bump to `high` for intertwined changes) | Reads the plan file + scoped paths, implements, runs targeted verification, writes report to disk, returns short summary. |
| **Scout / Fast Worker** | `scout` | `gpt-6-astra` (`low`) | Read-only codebase scans, log triage, test runs, mechanical single-scope edits. |

### Recommended `~/.codex/config.toml` Agent Profiles
```toml
[agents.architect]
description = "One-shot deep research, architecture, and threat modeling; writes plan to disk."
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

[agents.builder]
description = "Scoped implementation and verification reading from an artifact/plan file."
model = "gpt-6-astra"
model_reasoning_effort = "medium"

[agents.scout]
description = "Fast read-only research, log scanning, test execution, and mechanical edits."
model = "gpt-6-astra"
model_reasoning_effort = "low"
```

---

## 2. Quota & Efficiency Guardrails (Hard Rules)

* **No sidebar `fork_thread` sprawl:** Use normal in-thread `spawn_agent` subagents by default—do not clone parent conversation history with `fork_thread` or pull multi-turn transcripts back via `read_thread`.
* **Never keep an `XHigh` middleman alive:** `architect` is strictly **one-shot** (produce plan file → return summary → done). Never wake an `XHigh` agent just to relay status or update a map.
* **Concurrency cap:** Cap parallel subagents at **≤ 3 concurrent workers** unless the user explicitly asks for wider fan-out.
* **Voice-thread hygiene & Clean Switch Rule:** Speech drives many short turns. Never paste raw logs, diffs, or full plans into the main thread, and never advise switching models mid-thread on a large history (which triggers a hard KV-cache miss). When moving from a heavy planning phase to execution—or when a voice session grows long—save the plan/state to a file on disk and give the user a **ready-to-paste starter prompt for a brand-new thread** pointing at that file (or dispatch fresh `builder` subagents against it).

---

## 3. User-Only Pre-Flight Check (Main Thread Only)

Run only on the human-facing main thread—never inside subagents:

1. **Model & Effort Fit Check:** If the current model/effort is mismatched to the task (e.g., `XHigh` on a quick voice Q&A, or `Low` on a complex design that won't be delegated), concisely offer either the one picker change needed or to delegate the heavy phase to the `architect` subagent. Never edit global model settings silently.
2. **Voice-to-Text Sanity Guard:** Before dispatching `architect` or parallel `builder` workers, scan dictated input for likely transcription slips (domain names, repo names, identifiers) and confirm in 1–2 lines if anything looks ambiguous.

---

## 4. Complexity Router (3 Tiers)

| Tier | Task Shape | Action |
| :--- | :--- | :--- |
| **Tier 0 — Inline** | Quick Q&A, single-file edit, short command | Execute directly in the main thread. Zero subagent overhead. |
| **Tier 1 — Single Subagent** | Self-contained research, test sweep, single-module change | Spawn one named subagent (`scout` for fast read/test, `builder` for scoped code, `architect` for design). |
| **Tier 2 — Multi-Phase Epic** | Research → plan → multi-file/multi-module build | Run the 3-phase flow below (≤ 3 concurrent subagents). |

### Tier 2 Flow
1. **Plan (`architect`):** Spawn `architect` to analyze and write the complete plan to a file on disk (e.g., `.codex-artifacts/<slug>-plan.md` or `/tmp/codex-<slug>.md`, never committed to product repos). It returns only a 5–10 line summary, file path, and open decisions.
2. **Human Checkpoint (Main Thread):** Present the concise summary + decisions to the user for steering/approval.
3. **Execute & Verify (`builder` / `scout`):** Spawn up to 3 `builder` or `scout` subagents, passing **only the plan file path + bounded target scope**—never the main thread's chat history. Verify outcomes and give one compact final report.

---

## 5. Artifact-First Handoff Contract

Every subagent prompt **must** require:
* Write full plans, research tables, or lengthy diagnostics to a scratch/artifact file on disk.
* Return **only**: (1) 5–10 line outcome summary, (2) file path, (3) decisions or blockers needing the user's call.
* Never echo full diffs, raw command logs, or multi-page reports back into the main thread.
