Dynamic Workflows

Use workflow structure when it materially improves coverage, independence, verification, or resumability. Skip routine single-threaded tasks.

Choose The Surface

1. Native orchestration: coordinate Codex subagents in the current conversation. Use for one-off work, repo-native collaboration, and tasks that do not need persisted workflow state.
2. codex-dw runtime: validate or execute a workflow with persistent state. Saved workflows and TypeScript require a direct workflow/run request or manual CLI invocation. The main coordinator may automatically execute one generated declarative capability-fallback leaf under the exception below.

Do not imply that codex-dw is a native /workflows command or exact Claude Code parity.

Invocation And Authority

• Load implicitly for broad or risky workflow-shaped tasks, but do not execute arbitrary saved workflows or TypeScript from implicit activation alone. Automatic capability fallback is limited to a newly generated declarative leaf for a materially required model that the native spawn interface does not advertise.
• An explicit $dynamic-workflows, ultracode, workflow, or run request authorizes bounded orchestration within the actual requested mode; it does not broaden file scope, budgets, network, deployment, or other effects.
• Review, audit, explain, or report requests remain read-only.
• A clear implement/fix/edit request and current Codex permissions grant mutation only inside that task's scope. An automatic fallback may inherit this authority and pass --allow-mutation; implicit skill activation alone never grants mutation.
• Runtime mutation requires either a direct run request or the automatic capability-fallback exception, plus --allow-mutation, a clean Git base, declared ownership, independent verification, and no active native writers for the run's duration.
• Never run TypeScript merely because this skill loaded. TypeScript has no trust prompt by user choice, so explicit execution is a hard boundary.

Native Orchestration Loop

1. State the goal, mode, pattern, failure mode, coverage ledger, ownership, budget, stop gates, synthesis rule, and acceptance checks.
2. Prefer the smallest useful pattern: classify-and-act, fan-out-and-synthesize, adversarial verification, generate-and-filter, tournament, pipeline, or bounded loop.
3. Use bounded agents with non-overlapping responsibilities. Keep integration and final decisions in the main thread.
4. Default to four active agents unless the user or runtime grants a different bounded profile. Count delegated child work against the declared budget.
5. Preserve independence: a material producer result should be checked by a separate verifier or direct evidence review.
6. Track every item as covered, pending, skipped, or blocked. Never infer completeness from agent count.
7. Stop on unclear mutation authority, overlapping writes, secrets, destructive scope, production effects, budget exhaustion, or runtime permission limits.
8. Synthesize evidence, conflicts, skipped checks, and the actual terminal artifact. Close completed agents after integration.

Quality-First Model Routing

Generic native orchestration inherits the configured model and uses high reasoning. When the user requests quality-first routing, classify each semantic role before spawning and use the current family IDs advertised by the active interface:

Escalate effort when the role and intent are understood but more depth is needed. Escalate or reassign the model when ownership, architecture, or intent is misunderstood. Quality routing does not justify unnecessary agents, duplicate coverage, or overlapping writers.

Native model/effort overrides require a fresh context (fork_turns: "none"). Inspect the active spawn interface at call time; do not infer native availability from documentation or a model catalog. A route is required only when the user names the model/effort, a pinned artifact names it, or an explicit cost, evaluation, or acceptance constraint depends on it; a matrix selection by itself is preferred.

If a preferred Luna route is unavailable, announce the fallback and use native Terra xhigh; if Terra is also unavailable, announce the fallback and use inherited Sol xhigh. For each required route that is unavailable, the main coordinator automatically generates, validates, and executes one fresh declarative codex-dw leaf pinned to that route. Do not ask for separate runtime authorization. This exception is unavailable when CODEX_DW_ACTIVE=1, and a native child must return the requirement to the main coordinator rather than launching the runtime. If the backend rejects a required route, fail that role unless degradation was already allowed. Never label an inherited call as Luna or Terra.

Before dispatch, announce the route classification, requested and dispatched surface/model/effort, fallback reason, mode, and that an automatic runtime run will persist task content and usage. Report the same receipt with the native agent ID or runtime run/call ID in final synthesis.

codex-dw Runtime Policy

• Generate declarative YAML by default. Use TypeScript only when executable coordination logic is genuinely useful.
• Validate before execution. Require stable operation IDs and JSON Schema outputs.
• Default to the small profile: four concurrent calls and 25 total worker/verifier calls. Medium is 8/50; large is 16/100. Never exceed 16 concurrent or 100 total calls.
• An automatic capability fallback is one newly generated agent leaf per unavailable required route, each in a fresh small-profile run. It uses a self-contained prompt, a stable operation ID, a strict output schema, network disabled, and the original task's read-only or mutating mode. Never select an arbitrary saved workflow, resume an earlier run, or move the whole native workflow into codex-dw.
• Network defaults off. Generic user-authored workflows may omit model to inherit the configured default and use the runtime's high reasoning default. Quality-routed generated workflows pin both the current gpt-5.6-sol, gpt-5.6-terra, or gpt-5.6-luna family ID and the selected effort in each agent definition.
• Treat pinned routing as part of the deterministic workflow snapshot. The runner forwards it without model fallback; backend rejection fails the call. Report the requested route and whether the backend accepted it. The current SDK event surface does not attest the effective serving model, so do not claim that identity was independently observed.
• Treat every SDK worker and verifier as one bounded leaf call. It must not launch codex-dw, invoke another dynamic workflow, or delegate to unbudgeted subagents; express fan-out and retries in the parent workflow.
• Persist state under $CODEX_HOME/dynamic-workflows/runs/<run-id> and use call hashes to reuse only unchanged completed calls.
• On resume, restart interrupted/failed calls and invalidate downstream calls when rendered prompts or inputs change.
• Treat TypeScript subprocess controls as defense in depth, not a complete JavaScript sandbox. Do not execute untrusted TypeScript.
• For mutation, isolate each independent unit in a Git worktree; keep an item's pipeline stages in that worktree; reject ownership violations; verify read-only; integrate verified commits into the runner branch; preserve recovery branches on conflict.
• The integration branch is the output. Merging it into the active user branch remains a separate user-controlled action.
• In an interactive Codex session, a terminal mutating run with integrated changes publishes a codex-dw.review-artifact/v1 Git-range pointer in run state for an optional read-only final review. This does not merge or modify the integration branch.
• Cleanup is conservative. Do not force-remove unintegrated task branches or dirty runner worktrees without explicit --force authority.

Hard Stops

• Unclear authority for mutation or executable TypeScript.
• Destructive, irreversible, secret-bearing, production, or external side effects not directly requested.
• Overlapping mutation ownership, dirty Git base, detached HEAD, verifier rejection, integration conflict, or active-checkout drift.
• Automatic mutating fallback after a native writer has started, while any native writer is active, or without disjoint native/runtime ownership established before dispatch.
• Automatic fallback from a runtime worker (CODEX_DW_ACTIVE=1), automatic resume, arbitrary saved-workflow selection, or implicit TypeScript execution.
• Unbounded loops, delegation, agent counts, or retry behavior.
• Missing required evidence, structured-output contract, or acceptance check.
• Runtime sandbox, approval, connector, network, or tool limitations.

Reference Map

Read only what the task needs:

• references/runtime.md — codex-dw schema, operations, TypeScript API, CLI, resume, Git, and containment.
• references/workflow-patterns.md — native and persistent workflow recipes.
• references/agent-contracts.md — prompt, result, verifier, ownership, and synthesis contracts.