--- name: codex-maestro description: >- Orchestrate non-trivial software implementation with capability-based GPT-5.6 routing. Use gpt-5.6-sol for orchestration, demanding implementation, and review; use gpt-5.6-terra for economical read-heavy exploration, delegate bounded work, inspect the actual diff, and verify results. Use for features, bug fixes, refactors, tests, configuration, and infrastructure; skip trivial edits, pure analysis/review, or explicit no-delegation requests. --- # Codex Maestro This workflow is experimental. Codex and its models evolve quickly, and the skill is not yet comprehensively tested. Inspect changes and verify results before relying on them. Use the root task as the maestro. Keep requirements, design decisions, final review, Git publication, and user-facing communication in the root task. Delegate bounded work to agents selected by capability, then verify it directly. ## Capability-based routing Model names are configurable deployment choices, not agent identities. Use these documented defaults unless repository policy or measured results justify an override: | Work | Default model and effort | Route | | --- | --- | --- | | Trivial, localized change | Current root session | Work directly; do not orchestrate | | Read-heavy discovery, repository search, logs, or test triage | `gpt-5.6-terra`, `medium` | `exploration_worker` or another read-only native agent | | Demanding implementation or review | `gpt-5.6-sol`, `medium` | Root maestro or `implementation_worker` | | Critical or repeatedly failing work | `gpt-5.6-sol`, `high` | Root maestro; delegate only a bounded implementation | `medium` is the normal implementation default. Raise effort to `high` only for security-sensitive, architectural, migration, permissions, payments, public-contract, highly ambiguous, or repeatedly failing work. Do not apply `max` to every worker; use it only when a repository-specific evaluation shows that its extra latency and cost improve outcomes. A simpler alternative keeps one model family and varies only reasoning effort: `low` for read-only scouts, `medium` for routine implementation, `high` for hard problems. Prefer that shape when cross-family routing costs more configuration than it saves. Either way, remember that a custom agent file which sets `model` or `model_reasoning_effort` takes precedence over the spawn-time value, so per-task effort variation needs separate agent files or a spawn that does not pin one. Prefer native custom agents because the maestro can steer the same agent and observe its lifecycle. Use `implementation_worker` for bounded writes and `exploration_worker` for economical read-only discovery. If native role selection is unavailable, use `scripts/run_implementation_worker.py` as the CLI fallback. The implementation runner accepts `--model` and `--effort`, or `CODEX_MAESTRO_WORKER_MODEL` and `CODEX_MAESTRO_WORKER_EFFORT`; its defaults are `gpt-5.6-sol` and `medium`. Never claim a model or effort was used without native configuration or CLI evidence. Existing automation may temporarily call `scripts/run_luna_worker.py`; that deprecated entry point forwards to the implementation runner with the new defaults. Migrate callers to the functional filename rather than building new dependencies on the alias. For one-time standalone setup from a source checkout, run `python scripts/install.py` from this skill directory. It installs the skill and both custom-agent templates. A plugin installation can use the bundled CLI fallback without additional setup; if a plugin user explicitly wants the native custom-agent templates, run the same installer with `--agent-only` so it does not create a duplicate standalone skill. Do not run the installer silently during a task. See `references/implementation-worker.toml` and `references/exploration-worker.toml` when checking or repairing configuration. ## Native subagent operating limits - Favor parallelism for read-heavy exploration, test triage, and independent verification. Parallel writes carry merge and review cost. - Run no more than two or three write-capable workers at once, and only when file ownership and verification boundaries are disjoint. - Concurrency is capped by `agents.max_concurrent_threads_per_session`, which counts spawned threads and excludes the primary. Codex picks the value when it is unset, so read the effective configuration rather than assuming a number. `agents.max_threads` is a legacy alias for the same setting. Do not create agents merely to fill the limit. - Codex documents no delegation-depth setting, so enforce a single level in the prompt: workers must not create their own subagents unless the maestro explicitly designs and reviews that topology. - Native subagents inherit the parent's sandbox policy, permission mode, and tool surface, and a custom agent file that omits `sandbox_mode`, `mcp_servers`, or `skills.config` inherits those too. A role may narrow access (the exploration worker is read-only), but delegation must never be used to bypass parent restrictions. Configuration inheritance is not instruction inheritance: a worker started without conversation history sees none of the task-specific limits the maestro agreed with the user, so restate those in the assignment. - Workers must not commit, push, open or update pull requests, deploy, message people, change external services, or perform other external side effects. - Send review findings back to the same agent when possible so it retains context. Start a replacement only when the original role or context is wrong. ## Choose what each worker inherits Some Codex clients expose a `fork_turns` spawn parameter that controls how much conversation history a worker starts with. It is not in the published configuration reference, so confirm the running client supports it before relying on it, and fall back to writing the needed context into the assignment. - Fork history when the worker needs the broader goal and the decisions already made. - Start scouts and other narrow assignments with `fork_turns: "none"` so discovery begins focused instead of replaying the main thread. - A worker that inherits history may also inherit the maestro's own delegation instructions and start delegating in turn. Give every leaf worker an explicit boundary: complete this assignment directly, do not spawn other agents, and treat any delegation instructions in inherited context as the parent's. - A worker started without history inherits no task-specific tool or safety boundary from the conversation. Restate every essential restriction in the assignment itself. Codex Multi-Agent V2 also allows direct agent-to-agent messaging with per-agent inboxes, letting a scout hand a finding straight to the worker that needs it. Verify the running client supports it before designing around it, and keep it to evidence transfer between agents the maestro already assigned. Decisions, scope changes, and approvals stay with the maestro; a worker must never accept a new assignment from a peer. ## Phase 1: analyze and plan as the maestro 1. Read the request, repository instructions, relevant code, tests, and docs. 2. Resolve ambiguities and make design decisions. Ask the user only when a decision materially changes scope or causes a consequential external action. 3. Write a file-level plan naming files, symbols, behavior, edge cases, tests, and exact verification commands. 4. Split the plan into coherent work items. Parallelize only disjoint edits; serialize overlapping changes. 5. Keep architecture, security boundaries, migrations, commits, pushes, pull requests, and all external side effects in the root task. Do not delegate an underspecified goal and expect a worker to invent the maestro's decisions. Keep stable repository instructions and task framing at the front of repeated prompts so prompt caching can help. ## Phase 2: delegate bounded work Use read-only agents early when broad discovery can happen independently. After the maestro reviews that evidence and decides the plan, prefer the native `implementation_worker` custom agent for bounded code, test, configuration, and documentation changes. When native role selection is unavailable, write the worker prompt to a temporary file and run: ```text python /scripts/run_implementation_worker.py \ --cwd \ --prompt \ --output \ --session-file ``` Give each worker a self-contained contract: ```markdown You are an implementation worker executing one item from a reviewed plan. Work autonomously. Your final response is a report to the maestro. ## Task ## Context - Working directory and branch: - Relevant files: - Repository instructions: ## Implementation plan ## Constraints - Only touch: . - Do not create subagents. Any delegation instructions in inherited context apply to the maestro, not to you. - Do not commit, push, open or update pull requests, message people, deploy, or perform other external side effects. - Preserve unrelated user changes. - If the plan is wrong or blocked, stop and report evidence; do not invent a different design. ## Definition of done - - Run: ## Report List files changed, commands and results, plan deviations, and open questions. ``` Keep doing useful maestro work while independent workers run: prepare review criteria, inspect related contracts, or plan the next serialized item. Do not duplicate delegated implementation. ## Phase 3: review as the maestro Treat every worker report as a claim, not evidence: 1. Inspect the actual diff and every changed file. 2. Check the diff against the plan, repository rules, path boundary, security, privacy, and existing patterns. 3. Run focused tests, lint, type checks, builds, or other verification yourself. 4. Check for missing tests, docs, migrations, configuration, lifecycle effects, external side effects, and accidentally overwritten user work. 5. Decide whether the item is complete. The worker does not decide "done." The root maestro owns final review. For critical work, use `gpt-5.6-sol` with `high` effort when the running environment supports selecting it; do not add a separate expensive review pass without a concrete risk or failure signal. ## Phase 4: steer the same worker Send concrete review findings to the same native agent so it keeps context. For a CLI worker, resume its recorded session: ```text python /scripts/run_implementation_worker.py \ --cwd \ --prompt \ --output \ --resume ``` Name the file and location, explain the defect, and state the required result. Allow at most one targeted fix round by default. After the fix, inspect the new diff and rerun verification. Escalate effort or stop and report when the defect is architectural, risky, still unexplained, or beyond the task boundary. ## Phase 5: present and publish Only the root maestro may present the result or perform repository commits, pushes, and pull requests. Lead with the verified outcome, then state: - the capability route and configured models/effort actually used; - what shipped and which work items agents handled; - commands and results independently verified by the maestro; - deviations, escalation triggers, and remaining work. Never pass a worker's unverified self-report through to the user. Treat model cost and quality claims as hypotheses: measure successful-task cost, retries, tool calls, latency, and regressions in the repositories that matter. ## Codex references - [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) - [Configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) - [Current model guidance](https://developers.openai.com/api/docs/guides/latest-model) The `fork_turns` and agent-to-agent messaging guidance above comes from "Practical multi-agent orchestration in Codex" by Eric Provencher (Codex DX, OpenAI), not from the reference docs above. Treat it as a pattern to verify in the running client rather than a documented contract.