orchestrator-workflow 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-09-05
+
+### Added
+
+- Native Codex custom agents under `.codex/agents/`, including profile-scoped
+  roles and optional effort-tier variants with explicit model and effort.
+  The initial routing uses Astra for review/advice and implementation
+  escalation, Sol for discovery/slicing, Terra for regular implementation,
+  and Luna for narrowly scoped low-tier work.
+- Harness-specific role/tier routing overrides through `--routing <file>`
+  on `init`, `setup`, and `apply`, persisted alongside the legacy `models`
+  configuration. Optional `--codex-catalog <file>` checks selected Codex
+  model/effort pairs against a supplied catalog before installation writes.
+
+### Changed
+
+- Agent-led installation and deliberate model refresh are the recommended
+  entry point. The agent inspects capabilities and existing preferences,
+  applies authorized scoped changes through the CLI, and reports verification
+  gaps. The CLI remains available as the reproducible installation backend.
+- Codex workflow guidance uses native role delegation when supported, with an
+  explicit inline fallback for environments without native subagents. Normal
+  reinstallation preserves recorded routing; model changes use explicit
+  overrides or documented operator synchronization.
+
+
+## [0.28.0] - 2026-09-04
+
+### Added
+
+- The explorer, reviewer, and implementer prompts, and `SKILL.md`'s
+  Discover step, each gained one tool-agnostic sentence pointing the role
+  at a connected structural code-search, verify, or mutation-probe runner
+  when one is available in the session, in place of raw grep, hand-editing
+  probe files, or reading full logs. Anchored by a pandora-workspace
+  measurement of subagent tool-call patterns (see run
+  `.ai/runs/2026-09-03-agent-tools-kit`).
+
+### Changed
+
+- `init`'s interactive harnesses prompt on a target whose own manifest
+  recorded a real `harnesses: []` (a deliberate `--harness none`
+  templates-only install) now starts with nothing pre-checked, matching
+  `apply`'s existing semantics, instead of pre-checking whatever
+  `detectHarnesses(targetDir)` found on disk. Decision D-002 (agent-dx
+  7669907c): the weak-signal argument that motivated `apply`'s own fix
+  (agent-tasks fe834823, a stray harness config left on disk, e.g. a
+  `.claude/` directory, is not the recorded intent, the manifest is)
+  applies to `init` identically, and the earlier fix's concern (ask
+  instead of silently falling back to templates-only) is preserved
+  because the prompt still appears and still annotates detection with a
+  " (detected)" label; only the pre-check now follows recorded intent
+  instead of on-disk detection. `init` and `apply` now share one
+  resolution inside `resolveInitInputs` (`stickyPreChecked ?? []`,
+  `stickyAnnotateDetected ?? detected`) instead of `init`'s own call site
+  relying on a different default.
+
 ## [0.27.0] - 2026-09-01
 
 ### Added

package/INSTALL-AGENT.md

@@ -17,21 +17,23 @@ which is mutable. For a stable audit, pin the URL to a commit SHA instead
 
 ## What the linked instructions do
 
-1. **Locate existing harness configs** in the repo root and report them to
-   you (Claude Code, opencode, Codex marker files; full list in step 1
-   below).
-2. **Ask you, not guess**: which harnesses should get adapters, which role
-   profile to install (`full` — every role, or `minimal` — implementer and
-   reviewer only; the reviewer is never optional), which model each
-   installed subagent role should use, and whether to also render effort-tier
-   subagent variants (`--tiers`; off by default, no per-tier model prompt
-   since tier models are chosen automatically). Suggested defaults: profile
-   `full`; explorer `sonnet`, task-slicer `sonnet`, implementer `sonnet`,
-   reviewer `opus`, advisor `opus`; tiers off.
-3. **Run the non-interactive installer** with your answers:
-   `npx orchestrator-workflow init --yes --harness ... --profile ... --models ... [--tiers]`.
-   If the installer reports conflicts with locally edited files, the agent
-   shows them to you and asks before any `--force` re-run. **The operator
+1. **Inspect the repository and installed state**: detect harness configs,
+   read an existing workflow manifest, and inspect native model capabilities
+   where the harness provides them. Existing choices and authorization are
+   evidence; the agent does not make you answer them again.
+2. **Prepare a concrete configuration diff**: selected harnesses, profile,
+   tier variants, and the complete per-harness role/tier routing that will be
+   persisted. Existing routing leaves remain exact unless you asked to change
+   them. The agent records the prior routing in its handoff as the rollback
+   input and never treats "latest" or "newer" as a reason to change models.
+3. **Ask only when needed**, for a material preference, missing authority, or
+   a conflict that changes the result. Then run the non-interactive CLI with
+   `--routing <json-file>` for the reviewed deep patch and, when available,
+   `--codex-catalog <json-file>` for deterministic Codex capability checking.
+   If the installer reports conflicts with locally edited files, inspect the
+   concrete files and reuse any overwrite authority already granted for that
+   scope. Ask before a `--force` re-run only when authority or conflict scope
+   remains unresolved. **The operator
    path**: when an operator has already run `orchestrator-workflow setup`
    on this machine (an operator manifest exists at
    `<operator home>/manifest.json`, where the operator home is
@@ -48,9 +50,12 @@ which is mutable. For a stable audit, pin the URL to a commit SHA instead
    following the byte-precise rules in step 4 below. This manual path
    covers `init` only; there is no manual equivalent for `apply` or
    `adopt`, both of which require the installed CLI.
-5. **Report back**: which harnesses were installed, which profile and model
-   each role uses, whether effort-tier variants were rendered, and any
-   conflicts left in place.
+5. **Verify and report back**: describe the applied routing, prior routing
+   rollback input, installed profile and variants, and the supported dispatch
+   path (named selection, explicit model/effort spawn from the installed TOML,
+   or inline/sequential fallback). Include checks run, unknown capability or
+   entitlement gaps, and conflicts left in place. The workflow never opens a
+   GUI or changes fleet or global harness configuration.
 
 ### Write surface
 
@@ -77,24 +82,26 @@ The install creates or touches only these paths:
   is created with a short heading when absent (Claude Code harness only)
 - `.claude/skills/orchestrator-workflow/SKILL.md` and
   `.claude/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md` (Claude Code)
-- `.agents/skills/orchestrator-workflow/SKILL.md` (Codex)
+- `.agents/skills/orchestrator-workflow/SKILL.md` and
+  `.codex/agents/{explorer,task-slicer,implementer,reviewer,advisor}.toml` (Codex)
 - `.opencode/skills/orchestrator-workflow/SKILL.md` and
   `.opencode/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md` (opencode)
 
 The per-role agent files above are the `full` profile (the default); the
-`minimal` profile writes only the `implementer` and `reviewer` files for
-Claude Code and opencode and skips `task-slicer`, `explorer`, and `advisor`
-entirely. Codex has no per-role files, so the profile choice does not change
-what it gets. When `--tiers` is on, each installed Claude Code and opencode role
+`minimal` profile writes only the `implementer` and `reviewer` files for all
+three harnesses and skips `task-slicer`, `explorer`, and `advisor` entirely.
+When `--tiers` is on, each installed role
 additionally gets one subagent file per non-default effort tier, named
-`<role>-<tier>.md` (never a file for the role's own default tier, which
-would collide with the plain `<role>.md` file); see the package README's
+`<role>-<tier>.md` for Claude Code/opencode or `<role>-<tier>.toml` for Codex
+(never a file for the role's own default tier, which would collide with the
+plain role file); see the package README's
 "Effort tiers" section for the full role/tier table and the per-harness
 frontmatter shape. `--tiers` is off by default and has no interactive
 prompt equivalent in the manual fallback below (nor does its negation,
 `--no-tiers`): the automated installer is the only path that renders
 tier-variant files; a manual scaffold (step 4) does not cover them.
-Nothing else in the repository is modified. Locally edited files are
+The manifest records the complete effective routing map, including exact
+Codex model and effort selections. Nothing else in the repository is modified. Locally edited files are
 reported as conflicts and left alone, never overwritten silently; the
 exceptions are the kit-owned surfaces: `.ai/workflow/manifest.json` (the
 kit's state file, rewritten whenever the applied state changes) and the
@@ -103,52 +110,64 @@ is fully reversible: `npx orchestrator-workflow uninstall` removes exactly
 this write surface again, keeping run history under `.ai/runs/` and any
 locally edited files. Network access is limited to the npm registry (for
 `npx`) and, in the manual fallback, this repository on github.com /
-raw.githubusercontent.com.
+raw.githubusercontent.com. Native harness capability inspection is read-only;
+the workflow does not open a GUI or mutate global or fleet configuration.
 
 ## Instructions for the agent
 
 You are a coding agent that was pointed at this file. Execute the following
 steps in the repository you were asked to install into.
 
-1. Detect existing harness configs in the repo root: `.claude/` or
-   `CLAUDE.md` (Claude Code), `.opencode/`, `opencode.json` or
-   `opencode.jsonc` (opencode), `.agents/` or `.codex/` (Codex). Tell the
-   operator what you found.
+1. Inspect the target before proposing changes:
+   - Detect `.claude/` or `CLAUDE.md` (Claude Code), `.opencode/`,
+     `opencode.json` or `opencode.jsonc` (opencode), and `.agents/` or
+     `.codex/` (Codex).
+   - Read `.ai/workflow/manifest.json` when present. Treat its harnesses,
+     profile, tiers, legacy models, and exact routing as the reinstall
+     baseline. Preserve them unless the operator already requested a change.
+   - Inspect native model capabilities when the installed harness exposes a
+     read-only command. For Codex, a refreshed `codex debug models` catalog
+     can be supplied to the installer with `--codex-catalog`; a bundled-only
+     view does not prove account entitlement. Do not invent a minimum harness
+     version. If the catalog or entitlement is unavailable offline, report
+     that gap instead of claiming validation.
+   - Check for an operator manifest as described under "Operator path" below.
+     Existing authorization and preferences remain valid. Do not open a GUI
+     or change global or fleet configuration.
 
-2. Ask the operator, do not guess:
-   - Which harnesses should get adapters: claude, codex, opencode?
-     Suggest the detected ones.
-   - Which role profile: `full` (explorer, task-slicer, implementer,
-     reviewer, advisor — the default) or `minimal` (implementer and reviewer
-     only; the reviewer is never optional under either profile)?
-   - Which model for each role the chosen profile installs? Suggest the
-     defaults: explorer `sonnet`, task-slicer `sonnet`, implementer
-     `sonnet`, reviewer `opus`, advisor `opus`. Accept the aliases `sonnet`,
-     `opus`, `haiku` or a full model id. Skip asking about a role's model
-     when the chosen profile does not install that role.
-   - Whether to also render effort-tier subagent variants (`--tiers`)?
-     Default: off. There is no per-tier model question: tier models are
-     chosen automatically from the tier (see the package README's "Effort
-     tiers" section for the role/tier table and the model-class mapping).
+2. Prepare a concrete, reviewable configuration diff. Infer the harness set
+   from installed state and detected configs; infer the existing profile,
+   tiers, and routing from the manifests. Use `full` for a fresh install
+   unless the repository clearly calls for `minimal`. Build a routing JSON
+   deep patch only for leaves that need to change. Its shape is
+   `harness -> role -> tier -> {model, effort}`; the role's default-tier key
+   configures the unsuffixed file. Preserve every omitted leaf. Keep the prior
+   routing in the handoff as the rollback input. Never upgrade a model merely
+   because a newer one exists, and ask the operator only when a material
+   preference, authority boundary, or conflict remains unresolved.
 
-3. Run the non-interactive installer with the operator's answers:
+3. Run the non-interactive installer with the reviewed configuration:
 
    ```bash
    npx orchestrator-workflow init --yes \
      --harness <claude,codex,opencode> \
      --profile <minimal|full> \
-     --models "explorer=<model>,task-slicer=<model>,implementer=<model>,reviewer=<model>,advisor=<model>" \
+     [--models "explorer=<model>,task-slicer=<model>,implementer=<model>,reviewer=<model>,advisor=<model>"] \
+     [--routing <routing.json>] \
+     [--codex-catalog <codex-catalog.json>] \
      [--tiers | --no-tiers]
    ```
 
    Omit `--profile` to keep `full` (or, on a re-run, whatever profile was
-   installed previously); omit the models for roles the chosen profile does
-   not install. Add `--tiers` only when the operator asked for tier
+   installed previously). `--models` is a backward-compatible input for
+   Claude Code and opencode only; never use it to configure Codex. `--routing`
+   is the highest-precedence deep patch. Add `--tiers` only when the operator asked for tier
    variants; add `--no-tiers` only when the operator explicitly wants them
    turned off on a re-run that previously had them on; omit both to keep
    tiers off on a fresh install, or whatever value was previously installed
-   on a re-run. If the command reports conflicts, show them to the operator
-   and ask before re-running with --force.
+   on a re-run. If the command reports conflicts, inspect the concrete files,
+   reuse prior overwrite authority for the same scope, and ask before
+   `--force` only when authority or scope remains unresolved.
 
    **Operator path**: before running `init`, check whether an operator
    manifest already exists on this machine, at
@@ -166,9 +185,13 @@ steps in the repository you were asked to install into.
 4. Only if npx or the registry is unavailable, scaffold manually from
    https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow/assets.
    This manual path does not cover `--tiers`: it never renders
-   `<role>-<tier>.md` variant files, regardless of what the operator asked
+   tier variant files, regardless of what the operator asked
    for in step 2; tell the operator tier variants require the automated
-   installer (step 3).
+   installer (step 3). It also cannot safely reproduce native Codex TOML from
+   the Markdown assets without duplicating the installer's serializer. For a
+   Codex manual fallback, install the shared skill only and state that roles
+   must run inline and sequentially until the automated CLI can generate
+   `.codex/agents/*.toml`.
 
    - `.ai/workflow/templates/00-goal.md` through `06-handoff.md` from
      `assets/templates/`, unchanged.
@@ -197,6 +220,8 @@ steps in the repository you were asked to install into.
      directly after the `effort:` line. Ensure `CLAUDE.md` exists and
      contains a line `@AGENTS.md`.
    - Codex: `.agents/skills/orchestrator-workflow/SKILL.md`, same skill file.
+     Do not hand-author `.codex/agents/*.toml`; report the native-agent
+     limitation above and use the inline/sequential role fallback.
    - opencode: `.opencode/skills/orchestrator-workflow/SKILL.md` from
      `assets/skill/SKILL.md`, unchanged.
      For each role in the chosen profile (same set as Claude Code above),
@@ -237,7 +262,7 @@ steps in the repository you were asked to install into.
      ---
      ```
    - `.ai/workflow/manifest.json`, exactly this shape (harnesses MUST be an
-     array, `profile` is `"minimal"` or `"full"`, models keyed by role,
+     array, `profile` is `"minimal"` or `"full"`, legacy models keyed by role,
      version = the kit version you installed, read from this kit's own
      `packages/orchestrator-workflow/package.json` `version` field):
 
@@ -270,6 +295,8 @@ steps in the repository you were asked to install into.
      run then treats existing kit files conservatively and reports conflicts
      rather than overwriting them.
 
-5. Report back to the operator: which harnesses were installed, which model
-   each role uses, whether effort-tier variants were rendered, and any
-   conflicts that were left in place.
+5. Verify the expected files and manifest entries, then report back: which
+   harnesses and roles were installed; the exact model and effort per routed
+   role/tier; whether variants were rendered; the prior routing to use for a
+   rollback; the commands actually run; any offline capability or entitlement
+   gap; and conflicts left in place.

package/README.md

@@ -52,6 +52,25 @@ Two effects fall out of this shape:
 
 ## Install
 
+### Recommended: agent-led installation
+
+Give a coding agent this line:
+
+```text
+Follow the install instructions at https://raw.githubusercontent.com/LanNguyenSi/agent-dx/master/packages/orchestrator-workflow/INSTALL-AGENT.md
+```
+
+The agent inspects installed harnesses, reusable preferences, authorization,
+and available model capabilities. It presents the exact CLI invocation and
+routing diff, asks only about unresolved material decisions, applies the
+authorized change, and verifies the supported dispatch path. Existing routing
+is preserved unless you explicitly change it, and a newer model is never an
+automatic upgrade. [INSTALL-AGENT.md](INSTALL-AGENT.md) makes the write surface
+and fallback behavior auditable. The link tracks `master`; pin it to a commit
+SHA for a stable audit.
+
+### Manual and advanced CLI installation
+
 ```bash
 npx orchestrator-workflow init
 ```
@@ -62,14 +81,17 @@ resolved target (`Installing into ...`) before it writes anything and warns
 when the target is not a git repository root; pass `init <dir>` to install
 into a different directory. The installer is interactive by default: it
 locates existing harness configs (`.claude/`, `CLAUDE.md`, `.opencode/`,
-`opencode.json`, `.agents/`, `.codex/`), preselects what it found, and asks
-which model each subagent role should use.
+`opencode.json`, `.agents/`, `.codex/`) and preselects what it found. For a
+guided install, use the agent-led path above: the agent inspects the repository
+and available harness capabilities, prepares the exact CLI invocation and
+routing diff, and asks only about choices or authority it cannot infer safely.
 
 Non-interactive:
 
 ```bash
 npx orchestrator-workflow init --yes
 npx orchestrator-workflow init --harness claude,codex,opencode --models "implementer=sonnet,reviewer=opus" --yes
+npx orchestrator-workflow init --harness codex --routing ./routing.json --codex-catalog ./codex-models.json --tiers --yes
 npx orchestrator-workflow init --profile minimal --yes
 ```
 
@@ -89,34 +111,22 @@ files on disk from something else; add a harness back with an explicit
 `--profile`/`--models`/`--tiers` use, applied to the no-harness case. An
 **interactive** re-run is different: it still prompts, with nothing forced
 pre-selected, instead of silently skipping straight back to templates-only
-without asking; deselect every checkbox to stay templates-only. `init`
-pre-checks whatever it detects on disk; `apply` pre-checks nothing at all
-(both still annotate what is detected with a " (detected)" label).
+without asking; deselect every checkbox to stay templates-only. `init` and
+`apply` both pre-check nothing at all on this prompt, and both still
+annotate what is detected on disk with a " (detected)" label; select a
+harness to install it.
 
 ```bash
 npx orchestrator-workflow init --harness none --yes
 ```
 
-To let a coding agent do the install, give it this single line:
-
-```text
-Follow the install instructions at https://raw.githubusercontent.com/LanNguyenSi/agent-dx/master/packages/orchestrator-workflow/INSTALL-AGENT.md
-```
-
-The agent then asks you the harness and model questions in chat and runs the
-non-interactive CLI (manual scaffolding where npx is unavailable).
-[INSTALL-AGENT.md](INSTALL-AGENT.md) documents, step by step, what the
-linked instructions make the agent do and which files it may touch, so the
-prompt can be audited before delegating. The link tracks `master`; pin it
-to a commit SHA for a stable audit.
-
 ## What gets installed
 
 ```text
 .ai/
   workflow/
     templates/        00-goal.md ... 06-handoff.md (canonical run templates)
-    manifest.json     kit version, chosen harnesses, role profile, per-role models
+    manifest.json     kit version, harnesses, profile, legacy models, exact routing
   runs/               one directory per unit of work, newest = active
 AGENTS.md             marker-fenced "Agentic Coding Workflow" policy section
 ```
@@ -130,17 +140,19 @@ Per selected harness:
 | Harness | Files | Notes |
 |---|---|---|
 | Claude Code | `.claude/skills/orchestrator-workflow/SKILL.md`, `.claude/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter; the read-only explorer, reviewer, and advisor also get `disallowedTools: Edit, Write, NotebookEdit`. |
-| OpenAI Codex | `.agents/skills/orchestrator-workflow/SKILL.md` | Codex reads `AGENTS.md` natively. There is no standardized project-level subagent definition; the skill instructs running the roles inline with the same contracts. |
+| OpenAI Codex | `.agents/skills/orchestrator-workflow/SKILL.md`, `.codex/agents/{explorer,task-slicer,implementer,reviewer,advisor}.toml` | Codex reads `AGENTS.md` natively. Native custom-agent files carry the canonical role instructions plus `model` and `model_reasoning_effort`. Explorer and advisor request a read-only sandbox; reviewer inherits the caller's sandbox so it can run temporary/build checks, while its prompt prohibits source edits. |
 | opencode | `.opencode/skills/orchestrator-workflow/SKILL.md`, `.opencode/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md` | opencode reads `AGENTS.md` natively. Subagents get `mode: subagent`; the read-only explorer, reviewer, and advisor also get `permission: edit: deny`. Model resolution is described below. |
 
-**Read-only posture, honestly stated.** For the explorer, reviewer, and
-advisor the read-only posture is enforced at the tool level only for the
-file-mutation tools (`disallowedTools: Edit, Write, NotebookEdit` on Claude
-Code, `permission: edit: deny` on opencode). Bash stays available because
-these roles must run tests and linters, so shell-level mutation (`git checkout`,
+**Read-only posture, honestly stated.** Claude Code disables file-mutation
+tools for explorer, reviewer, and advisor; opencode denies edits for those
+roles. Codex requests a read-only sandbox for explorer and advisor. Its
+reviewer inherits the caller's sandbox so temporary/build checks remain
+possible, while its prompt prohibits source edits. In inherited or otherwise
+write-enabled sandboxes, shell-level mutation (`git checkout`,
 `git restore`, `git clean`, `git stash`, `git reset`, `sed -i`, redirecting
 output into a file) is guarded by instruction only: the agent prompts forbid
-it explicitly, but nothing technically prevents it. This residual has bitten in practice (a
+it explicitly, but the role definition itself does not prevent it. A native
+read-only sandbox can block those writes. This residual has bitten in practice (a
 reviewer ran `git checkout` and discarded uncommitted work), which is why the
 prompts now name the forbidden commands instead of just saying "read-only".
 Marker- or verdict-style enforcement of the Bash residual (sandboxing,
@@ -148,8 +160,8 @@ PreToolUse hooks) is harness territory and out of this kit's scope.
 
 ## Role profile
 
-`--profile` selects which subagent roles get installed (Claude Code and
-opencode only; Codex has no per-role files to select from):
+`--profile` selects which subagent roles get installed for Claude Code, Codex,
+and opencode:
 
 | Profile | Roles installed | When to use it |
 |---|---|---|
@@ -205,7 +217,33 @@ without reporting them at all.
 
 ## Model preselection
 
-Each subagent role gets a model, chosen interactively or via `--models`:
+Routing is a harness-specific map from role and tier to a complete
+`{model, effort}` selection. Pass a JSON file with `--routing`; the CLI deep
+merges only the leaves you provide and records the resulting effective map in
+`.ai/workflow/manifest.json`. The role's default-tier key configures its
+unsuffixed file; another allowed key configures the corresponding
+`<role>-<tier>` variant when `--tiers` is enabled. For example:
+
+```json
+{
+  "codex": {
+    "implementer": {
+      "medium": { "model": "gpt-5.6-terra", "effort": "medium" },
+      "xhigh": { "model": "gpt-6-astra", "effort": "xhigh" }
+    }
+  }
+}
+```
+
+An omitted `--routing` preserves the exact persisted map on a re-install.
+Changing one leaf leaves the others intact, which makes a previous manifest a
+usable rollback record. Model updates are deliberate per role and tier: the
+installer never interprets a newer model as automatically better and never
+rewrites a preserved choice merely because another model exists.
+
+`--models` remains as the backward-compatible, per-role input for Claude Code
+and opencode. It does not configure Codex. Existing manifests that contain
+only `models` continue to produce the same Claude Code and opencode defaults:
 
 | Role | Default | Why |
 |---|---|---|
@@ -215,9 +253,41 @@ Each subagent role gets a model, chosen interactively or via `--models`:
 | reviewer | `opus` | skeptical review benefits from the strongest model |
 | advisor | `opus` | escalations happen precisely when the situation is hard, so it shares the reviewer's strongest-model default |
 
-The orchestrator itself runs on the session's main model; use the strongest
-reasoning model available. The chosen mapping is recorded in
-`.ai/workflow/manifest.json` and reused as the default on later re-runs.
+The orchestrator itself runs on the session's main model. For Codex, start the
+orchestrator on `gpt-6-astra` at `high` effort; use `xhigh` for demanding work.
+The installer does not mutate global or fleet Codex configuration to enforce
+that recommendation.
+
+**Codex defaults.** Codex uses native `.codex/agents/*.toml` custom agents.
+The file shape follows the
+[official Codex subagent configuration](https://learn.chatgpt.com/docs/agent-configuration/subagents).
+The shipped routing is:
+
+| Role | Tier | Model | Effort |
+|---|---|---|---|
+| explorer | low | `gpt-5.6-luna` | low |
+| explorer | medium (default) | `gpt-5.6-sol` | medium |
+| explorer | high | `gpt-5.6-sol` | high |
+| task-slicer | low | `gpt-5.6-luna` | low |
+| task-slicer | medium (default) | `gpt-5.6-sol` | medium |
+| task-slicer | high | `gpt-5.6-sol` | high |
+| implementer | low | `gpt-5.6-luna` | low |
+| implementer | medium (default) | `gpt-5.6-terra` | medium |
+| implementer | high | `gpt-5.6-terra` | high |
+| implementer | xhigh | `gpt-6-astra` | xhigh |
+| reviewer | medium | `gpt-5.6-terra` | medium |
+| reviewer | high (default) | `gpt-6-astra` | high |
+| reviewer | xhigh | `gpt-6-astra` | xhigh |
+| advisor | high (default) | `gpt-6-astra` | high |
+| advisor | xhigh | `gpt-6-astra` | xhigh |
+
+When you have a deterministic Codex model catalog, pass it with
+`--codex-catalog <json-file>`. The CLI validates the selected Codex model and
+effort pairs before writing. Without a supplied catalog it performs no online
+entitlement check; offline or account-specific availability remains unknown.
+Use the harness's native capability commands, such as `codex debug models`, to
+refresh a catalog before installation when appropriate. A bundled-capability
+view describes what the binary knows and does not prove account entitlement.
 
 **opencode model resolution.** opencode requires fully-qualified `provider/model-id`
 strings (e.g. `github-copilot/claude-sonnet-4.6`). At install time the CLI
@@ -241,14 +311,14 @@ be supplied as a fully-qualified `--models` entry, e.g.
 `--tiers` renders an additional per-role subagent definition for each
 non-default effort tier, alongside the one default (unsuffixed) agent file
 `--profile` already installs. Each tier variant is a standalone subagent
-definition, not a modification of the default file: the default file
-(`<role>.md`) stays byte-identical to what a tiers-off install already
-produces, and each variant lives next to it as `<role>-<tier>.md`.
+definition, not a modification of the default file. Claude Code and opencode
+use `<role>.md` / `<role>-<tier>.md`; Codex uses `<role>.toml` /
+`<role>-<tier>.toml`.
 
 **Every default file carries its own pinned effort, independent of
-`--tiers`.** Since 0.22.0, `composeClaudeAgent`/`composeOpencodeAgent` add
-the role's own `TIER_DEFS[DEFAULT_TIER[role]].effort` to the default
-(unsuffixed) file unconditionally: `effort: medium` for explorer,
+`--tiers`.** The harness composers add the role's own default routing
+selection to the unsuffixed file. In the legacy Claude/opencode path this is
+`TIER_DEFS[DEFAULT_TIER[role]].effort`: `effort: medium` for explorer,
 task-slicer, and implementer; `effort: high` for reviewer and advisor
 (opencode: a `variant: high` line when the resolved model is Claude-family,
 following the same dispatch rule tier variants use, `reasoningEffort:
@@ -270,7 +340,8 @@ no variant files unless asked. `--tiers` turns the feature on for that run,
 `--no-tiers` turns it off; a plain re-run with neither flag keeps whatever
 the previous install had, the same override-vs-persist rule already used
 for `--profile` and `--models`. There is no interactive prompt for it:
-`tiers` is opt-in/off via the flags only.
+`tiers` is opt-in/off via the flags only. Neither Codex nor the other harnesses
+get `max` or `ultra` variants from this kit.
 
 ```bash
 npx orchestrator-workflow init --tiers --yes
@@ -345,6 +416,19 @@ warning are opencode-scoped only; Claude Code variants resolve `model:` from
 a plain alias (`haiku`/`sonnet`/`opus`) and need no live catalog lookup, so
 they are unaffected.
 
+Codex variants carry `model` and `model_reasoning_effort` from their exact
+routing leaf. The canonical role prompt becomes `developer_instructions`.
+Runtime dispatch follows the client's actual capabilities: select the named
+installed agent when supported; otherwise, if spawning supports explicit model
+and effort, read the installed TOML and pass its selection, developer
+instructions, and narrow task contract into a fresh task-local spawn. A
+full-history spawn may not permit a model override. If that explicit spawn
+cannot accept a sandbox override, explorer and advisor inherit the caller's
+sandbox and their prompt is the edit guard. When native spawning is
+unavailable, run the same contract inline and sequentially. The orchestrator
+alone spawns agents. In particular, it must not choose `implementer-low` when
+the task requires a test, typecheck, lint, build, or named mutation probe.
+
 **Warning: `CLAUDE_CODE_EFFORT_LEVEL` overrides every agent's frontmatter
 `effort:`, tier variants included.** Claude Code's `effort:` frontmatter
 field does work: it reaches the model request as `output_config.effort`.
@@ -378,12 +462,13 @@ orchestrator-workflow apply --target /path/to/repo
 ```
 
 **`setup`** writes or updates this operator's default install options
-(harnesses, profile, models, tiers) as the baseline for future installs; it
+(harnesses, profile, legacy models, routing, tiers) as the baseline for future installs; it
 touches no repository. A flag always wins; a flag-less re-run keeps the
 previously stored values; a first-ever `setup` falls back to `claude` /
-`full` / the kit's default models / tiers off. `setup` takes the same
-option flags as `init` (`--harness`, `--profile`, `--models`, `--tiers` /
-`--no-tiers`, `--opencode-provider`, `--yes`). The defaults live in
+`full` / the kit's default routing / tiers off. `setup` takes the same
+option flags as `init` (`--harness`, `--profile`, `--models`, `--routing`,
+`--codex-catalog`, `--tiers` / `--no-tiers`, `--opencode-provider`, `--yes`).
+The defaults live in
 `<operator home>/manifest.json`, where the operator home is
 `~/.orchestrator-workflow/` unless the `ORCHESTRATOR_WORKFLOW_HOME`
 environment variable names a different directory.
@@ -399,22 +484,21 @@ what `init` would have auto-detected) -- except a target whose own
 manifest recorded a real `harnesses: []` (a deliberate templates-only
 install, see "Templates-only mode" above), which stays templates-only on
 a flagless run regardless of the operator's defaults or what is on disk;
-an **interactive** re-run on such a target still prompts, but with
-nothing pre-checked at all -- neither whatever `apply`'s harness fallback
-(recorded harnesses, else operator defaults, else detection) would
-otherwise have picked, nor a harness config left on disk from something
-else, which is a weak signal next to the target's own recorded
-`harnesses: []`.
+an **interactive** re-run on such a target still prompts, with the same
+nothing-pre-checked behaviour described in "Templates-only mode" above
+(it applies identically to `apply`).
 Pass `--sync` to invert that for
-profile, tiers, and models: the operator's defaults then win over whatever
+profile, tiers, legacy models, and routing: the operator's defaults then win over whatever
 the target already had recorded. A target pinned to a kit version other
 than the one being applied is skipped rather than touched (see the pin
 rule below). `apply` also takes the same install options as `init` (`--harness`,
-`--profile`, `--models`, `--tiers` / `--no-tiers`, `--opencode-provider`,
-`--force`, `--yes`), which feed the precedence rule above.
+`--profile`, `--models`, `--routing`, `--codex-catalog`, `--tiers` /
+`--no-tiers`, `--opencode-provider`, `--force`, `--yes`), which feed the
+precedence rule above. An explicit routing file is the highest-precedence
+deep patch; leaves it omits retain their resolved baseline values.
 
 **`doctor [--json] [--prune]`** reports every operator-registered target's
-status: `clean`, `divergent` (from the operator defaults), `version-lag`,
+status: `clean`, `divergent` (from the operator defaults, including routing), `version-lag`,
 `drift` (installed files edited, deleted, or unreadable since install),
 `missing`, `no-manifest`, or `unverifiable`. It exits `2` when the operator
 manifest is missing or unreadable, or, with `--prune`, when the operator
@@ -426,6 +510,10 @@ version. `--prune` removes `missing` and `no-manifest` targets from the
 registry before reporting (never an `unverifiable` one, since that status
 means the check itself was inconclusive, not that the target is confirmed
 gone) and rewrites the manifest file in its normalized form.
+For a legacy opencode leaf without a recorded provider-qualified model id,
+doctor reports `Routing comparison incomplete` and includes
+`routingComparisonGaps` in JSON instead of declaring a false routing
+divergence. The gap alone does not change the target status.
 
 **`adopt [dir] [--json]`** brings a repository that already has the kit installed,
 by hand or by an earlier `init`, under the operator's management without
@@ -504,3 +592,11 @@ organizational guidance (when to use agents at all, review depth, risk tiers)
 live in the sibling package
 [agentic-coding-playbook](../agentic-coding-playbook), which the skill
 references.
+
+## okf-kit version pin
+
+`test/docs-consistency.test.ts` pins the `okf-kit@<version>` this repo's own
+`.github/workflows/` install against the sibling `packages/okf-kit`
+package's version, so a release of `okf-kit` must bump those pins in the
+same commit as the version cut; see `CONTRIBUTING.md`'s "Releasing okf-kit"
+section (repo root) for the order.