Task Orchestrator

English | 简体中文

A general-purpose Codex Skill for coordinating complex work with a user-selected controller, Luna Max execution, optional Terra read-only evidence scouting, risk-gated Sol decisions and acceptance, bounded parallelism, optional TaskGraph escalation, and independent review.

Task Orchestrator is still a single, self-contained Skill. It does not require a graph database, message queue, or resident orchestration service. Most work uses a compact controller ledger; a lightweight local Python kernel provides deterministic TaskGraph scheduling only for hard coordination, recovery, audit, or consequential external-state triggers.

Why

The cost of complex work is not limited to implementation. It also comes from dependency mistakes, duplicate dispatch, concurrent write conflicts, incorrect baselines, repeated reviews, and missing acceptance evidence.

Task Orchestrator keeps one controller accountable for the final outcome while making the execution chain explicit and verifiable:

• decide whether delegation is useful before decomposing the task;
• use Direct or Strong Lite orchestration for normal work and promote only hard-risk coordination to TaskGraph;
• use a five-field child handoff while keeping routing, permissions, ownership, and runtime identity in the controller ledger;
• choose Outcome, Skeleton, or Directed plan depth without taking implementation freedom away from Luna;
• settle high-risk architecture, security, permission, database, and public-interface decisions before Luna executes;
• use Terra only for read-only evidence and fall back to Luna Max when Terra is unavailable;
• use Sol rescue only for an evidenced unresolved Luna scope;
• route bounded work, complex implementation, and independent review by role;
• dispatch only nodes that are Ready under dependency, slot, and write-set rules;
• run one independent full review of the integrated baseline;
• normalize actionable findings into a stable Finding Manifest;
• remediate only approved findings and recheck them individually;
• avoid another full review unless an explicit escalation trigger applies.

What's New in v0.1.7

• keeps Luna Max as the default delegated executor instead of lowering its reasoning effort for cost alone;
• limits Terra to same-route, read-only evidence nodes with no write set, using Luna Max as the honest fallback when Terra cannot be verified or called;
• requires the controller or Sol to settle high-risk architecture, security, permission, database, and public-interface decisions before implementation;
• replaces unconditional post-write Sol acceptance with a risk gate, so bounded deterministic Luna work can be accepted directly by the controller;
• compresses normal child handoffs to five fields while retaining identity, permissions, ownership, dependencies, and evidence in the controller ledger;
• enforces model, effort, permission, and role restrictions in both TaskGraph schema validation and runtime dispatch checks.

Workflow

flowchart TD
    A["Read request and current state"] --> B{"Complexity"}
    B -->|Trivial| C["Controller completes and verifies"]
    B -->|Bounded / Complex / Critical| D["Controller or Sol fixes only required decisions"]
    D --> E{"Explicit TaskGraph needed?"}
    E -->|No| F["Luna plans locally and executes"]
    E -->|Yes| G["Validate graph and compute Ready nodes"]
    G --> H["Dispatch by dependencies, slots, and write sets"]
    F --> I{"Sol acceptance risk gate?"}
    H --> I
    I -->|No| S["Controller accepts and integrates"]
    I -->|Yes| T["Focused Sol acceptance"]
    T --> S
    S --> J{"Independent review required?"}
    J -->|No| K["Report traceable outcome"]
    J -->|Yes| L["One independent full review"]
    L --> M{"Blocking findings?"}
    M -->|No| K
    M -->|Yes| N["Stable Finding Manifest"]
    N --> O["Targeted remediation and focused tests"]
    O --> P["Original reviewer performs targeted recheck"]
    P --> Q{"All blockers cleared?"}
    Q -->|Yes| K
    Q -->|No| R["Stop and reassess; do not loop full reviews"]

Loading

Capabilities

Capability	Behavior
Complexity classification	Classifies work as Trivial, Bounded, Complex, or Critical
Plan-depth gate	Uses Outcome, Skeleton, or Directed planning according to ambiguity and risk
Model routing	Uses Luna Max for execution, Terra only for read-only evidence, and Sol for decisions, risk-gated acceptance, review, and evidenced rescue
Sol rescue	Allows Sol implementation only for an evidence-backed unresolved Luna scope
Deterministic scheduling	Uses the TaskGraph kernel only after a hard coordination, recovery, audit, or external-state trigger
Bounded parallelism	Defaults to 3 active execution units, with a conditional soft maximum of 5
Write-set isolation	Prevents concurrent nodes from owning conflicting path prefixes
Authorization boundaries	Keeps delegated permissions equal to or stricter than the parent
Event replay and recovery	Uses immutable graph revisions and append-only events
Acceptance gates	Verifies actual diffs, tests, integration state, evidence, and residual risk
Independent review	Prefers a user-visible Codex task when explicitly requested and available
Targeted remediation	Rechecks stable Finding IDs instead of repeating the entire review
Token discipline	Bounds context packets, reports, retries, polling, and duplicate investigation

Model and Reasoning Routing

Model identity and reasoning effort are separate routing dimensions. The runtime remains the authority on what is actually callable, but the routing decision is strict once that evidence is available.

Role	Preferred model	Preferred reasoning effort	Typical work
Controller	User-selected main model	User-selected	scope, arbitration, integration, final verification
Strong Lite planner	gpt-5.6-sol	Max (max)	choose plan depth and define outcomes, invariants, boundaries, and acceptance
Evidence scout	gpt-5.6-terra	High (high)	optional read-only evidence and source-location work
Default delegated implementer	gpt-5.6-luna	Max (max)	local planning, implementation, tests, debugging probes, packaging, docs, evidence fallback, and verification
Focused acceptor	gpt-5.6-sol	Max (max)	risk-gated check of the exact contract, diff, and test evidence
Rescue implementer	gpt-5.6-sol	Max (max)	implement only an evidenced unresolved Luna nucleus
Independent reviewer	gpt-5.6-sol	Max (max)	read-only review of raw diffs, artifacts, and test logs

Reasoning effort for Luna and Sol falls back in this order; Terra evidence uses High and falls back to Luna Max if that route is unavailable:

max → xhigh (Extra High) → high (High)

The Skill:

• requires Luna Max for ordinary delegated execution whenever a compatible same-Provider, same-route Luna candidate is callable, while keeping explicit Terra evidence and Sol planning, acceptance, review, and rescue roles separate;
• preserves the user-selected controller model;
• uses Outcome, Skeleton, or Directed planning and gives Luna explicit implementation freedom;
• requires a Contract Delta before a material deviation from a fixed boundary;
• treats Bounded, Complex, and Critical as risk classifications rather than automatic model selections;
• permits Terra only for compatible same-route, read-only evidence support with an empty write set, then falls back to Luna Max;
• permits Sol rescue only with a Luna exemption, structured event evidence, a shared contract, an incoming Luna fallback, and an exact unresolved write scope;
• keeps work in the controller or on an allowed exact parent model when no valid rescue can be bound, and refuses parent inheritance when the runtime identifies it as Terra;
• routes Luna-capable research, analysis, implementation, tests, documentation, packaging, and verification to Luna across Bounded, Complex, and Critical work;
• reports the actual model and reasoning effort instead of claiming the preference was used;
• records runtime-selected; identity unavailable when trustworthy identity metadata is absent;
• does not substitute an exact user-required model or effort without approval;
• cannot change the controller model after the current task has already started;
• preserves task scope and acceptance criteria when a model, effort, or execution surface falls back.

Role-Affine Relay Compatibility

Task Orchestrator does not hard-code any relay or vendor name. Provider, route, and model IDs are treated as opaque runtime values. One Provider may front multiple relays, so Provider equality alone is insufficient. Resolution prefers an explicitly same-Provider, same-route Luna candidate, then an advertised Provider-default exact gpt-5.6-luna with route-preservation proof, then an exact adapter- or user-supplied route mapping.

Multi-Agent compatibility is execution-surface relative: V1 Luna is valid on a V1 surface and V2 Luna is valid on a V2 surface. A cross-version candidate is rejected. The Skill records both versions and never rewrites V1 as V2 merely to pass validation.

Immediately before every subagent or visible-task dispatch, the controller refreshes the current callable catalog and runtime-confirmed Provider and route, then re-resolves the exact model ID and effort. A successful earlier dispatch does not pin the next one. If a relay or model selection changes, cached dispatch identity is stale.

The same rule applies to visible independent review: when the active route and its Sol mapping are exposed, task creation must receive that route's exact Sol model ID. Generic gpt-5.6-sol plus a shared Provider ID is not proof that the selected relay was used. Persisted task metadata is the acceptance evidence.

Codex may snapshot the subagent model allowlist when a process or task starts. Switching a relay inside an already-running task therefore cannot be made reliable by Skill instructions alone. Treat a relay switch as a task boundary:

1. inspect the active catalog;
2. repair metadata only when runtime evidence proves it is wrong for the active execution surface and explicit authority permits it;
3. fully reload Codex and start a new task;
4. confirm Luna appears in that task's callable model list; and
5. run one bounded Luna probe and verify persisted runtime metadata.

The bundled helper reads the active catalog path from config.toml:

python scripts/luna_v2_catalog.py inspect-config "$env:USERPROFILE\.codex\config.toml"
python scripts/luna_v2_catalog.py repair-config "$env:USERPROFILE\.codex\config.toml" `
  --model-id "<exact-route-scoped-luna-id>" --confirm

The bundled helper is V2-specific: use it only when the active execution surface is confirmed V2 and a selected Luna entry is incorrectly marked V1. Never use it to rewrite a valid V1 catalog. repair-config creates and verifies a timestamped backup before an in-place change. Mutation requires exact --model-id values by default; repeat the flag for every intended entry. Name-based mutation additionally requires --allow-name-match. At the JSON data level it changes only matching Luna entries' multi_agent_version; serialization formatting may be normalized. It aborts if the source catalog changes before atomic replace, but it does not provide a cross-process file lock. It is a no-op when the entries are already V2.

TaskGraph Kernel

Direct or Lite orchestration is the default. Multiple independent nodes, one linear implementation-review chain, long duration, or one awaited review do not by themselves require TaskGraph. The explicit kernel is activated only for branching or converging dependencies, overlapping mutable resources, executable fallback or retry, interruption recovery, exact audit provenance, consequential release/security/permission/device gates, or an explicit user request.

The kernel:

• validates the graph structure and acyclic contract;
• replays append-only lifecycle events;
• computes a deterministic Ready set;
• enforces controller-wide logical slots;
• rejects conflicting write-set prefixes;
• evaluates depends_on and fallback_to edges;
• generates stable dispatch keys for idempotent dispatch;
• records runtime phase and activity through node_progress;
• persists bound runtime checks through node_snapshot;
• rejects stale stalled-cancellation evidence after newer activity;
• detects deadlocks and unsatisfied awaited nodes;
• preserves revision and artifact provenance.

The kernel does not create Codex tasks, change permissions, invoke external services, execute nodes, or run as a daemon. Those actions remain under controller ownership and host authorization.

Commands

Run from the installed Skill directory with Python 3:

python scripts/task_graph.py validate <task-graph.json>
python scripts/task_graph.py ready <task-graph.json> --events <events.jsonl>
python scripts/task_graph.py reduce <task-graph.json> <events.jsonl>
python scripts/task_graph.py append-event <task-graph.json> <events.jsonl> --event-json '<json>'

append-event is the only event-log writer. TaskGraph v1 does not implement cross-process file locking, so a single controller must own event writes.

Adaptive Liveness

The controller monitors runtime state and recent activity rather than treating artifact count as a heartbeat. Reading, analysis, patch composition, builds, and tests may all remain at zero output files while making useful progress.

Each delegated node records an output mode, a phase-specific stall timeout, and a minimum of two unchanged snapshots. New tool activity or a phase transition is written as node_progress, resets the stall window, and may update the timeout for the new phase. Runtime checks are persisted as distinct node_snapshot events. Progress, snapshots, and stalled cancellation bind to the current attempt, dispatch key, and delegated task ID. Before cancellation, the kernel requires the latest fresh snapshot IDs, unchanged activity fingerprints, fresh runtime observations, no recent activity, and the current node-specific timeout. append-event supplies authoritative append time; caller-provided timestamps, elapsed counters, and bare snapshot counts cannot prove a stall.

Independent Review and Targeted Remediation

The default review loop is deliberately bounded:

1. Run one independent full review of the integrated baseline.
2. Normalize actionable findings into stable Finding IDs.
3. Assign one implementation owner to the approved remediation scope.
4. Run focused tests for affected behavior.
5. Continue the original independent reviewer for a targeted recheck.
6. Return CLEARED, PARTIALLY_CLEARED, NOT_CLEARED, or NEW_BLOCKER_INTRODUCED_BY_FIX for every Finding ID.
7. Allow one remediation pass and one targeted recheck by default.

A new full review is allowed only when a recorded escalation trigger applies, such as a remediation that changes architecture, public interfaces, persisted formats, shared compatibility contracts, security boundaries, or work outside the approved Finding Manifest.

When the user explicitly asks for independent, separate, or visible review:

• prefer a user-visible Codex task when the runtime supports it and authorization allows it;
• use a fresh read-only subagent if the user rejects a separate task;
• fall back to a fresh read-only subagent if visible task creation is unavailable or fails;
• disclose the failed surface, fallback type, actual model, and actual effort;
• do not duplicate a successful visible review with a hidden review over the same diff.

When review was not requested, the controller decides whether review is warranted and whether it should use a visible task or a subagent based on risk, complexity, user value, and quality gates.

Token and Efficiency Boundaries

Task Orchestrator is designed to reduce duplicate investigation, unbounded concurrency, context replication, and repeated full reviews. It does not guarantee lower Token use for every task.

The current development source retains the two-stage Lite/Core loading path:

• a compact description conservatively prefilters multi-step work with dependencies, independently verifiable units, useful parallelism, shared-write or permission risk, release, recovery, or independent-review needs;
• short answers, one safe command, and tiny obvious edits are excluded from implicit selection;
• after selection, the Core classifies the task again before delegation, reference loading, TaskGraph use, or review;
• the conservatively counted SKILL.md plus agents/openai.yaml path is 1,171 Tokens with o200k_base;
• detailed references are not loaded during the normal path;
• TaskGraph commands run the deterministic kernel without requiring the model to read the schema or full kernel guide;
• child prompts receive a compact node contract and do not invoke this Skill again.

Provider ambiguity, routing failures, recovery, privileged actions, releases, security work, and review findings still load the relevant detailed reference when needed. Those exceptional Full-mode paths may exceed 2,000 Tokens.

Default controls include:

• no duplicate work merely to fill concurrency slots;
• no subdelegation unless explicitly bounded;
• context packets limited to about 2,000 words plus 10 focused files or artifacts;
• narrative reports limited to about 800 words;
• one retry before the controller reassesses the premise;
• status checks at milestones, blockers, completion, or a node-specific liveness deadline, with the deadline reset after fresh activity;
• reuse of manifests, test logs, graph state, and existing evidence;
• a review, remediation, and recheck budget normally within 15% of delegated-task usage when telemetry exists.

Parallelism primarily improves latency and responsibility isolation. On a small task that the controller could finish directly, delegation and review may consume more Tokens, so triage happens first.

Installation

Requirements

• a Codex runtime with Skill support;
• Python 3.11 or newer for deterministic TaskGraph scheduling and catalog repair;
• optional runtime support for subagents and user-visible tasks.

No graph database, MCP server, queue, or daemon is required.

Install from source

$source = ".\task-orchestrator"
$destination = Join-Path $env:USERPROFILE ".codex\skills\task-orchestrator"
Copy-Item -Recurse -LiteralPath $source -Destination $destination

Back up and resolve an existing installation explicitly. Do not silently force-overwrite local changes.

Install from a release

The v0.1.7 release assets are:

• task-orchestrator-v0.1.7.zip
• task-orchestrator-v0.1.7.sha256
• task-orchestrator-v0.1.7-files.sha256
• task-orchestrator-v0.1.7.provenance.txt

Download the assets from the GitHub Release, then verify and extract:

$package = ".\task-orchestrator-v0.1.7.zip"
Get-FileHash -Algorithm SHA256 -LiteralPath $package
Expand-Archive -LiteralPath $package -DestinationPath (Join-Path $env:USERPROFILE ".codex\skills")

Compare the result with task-orchestrator-v0.1.7.sha256.

Fully reload Codex and begin a new task after installation. A new task is also required after changing relays because an existing task may retain a stale subagent model allowlist.

Usage

Use automatic selection or explicitly name the Skill:

v0.1.7 enables conservative implicit selection for likely orchestration work. Selection is only the first gate: the Core classifies the task again, and Trivial work stays in the controller without subagents, TaskGraph, or independent review. Explicit invocation remains available:

Use $task-orchestrator as the controller for this request.
Keep the user-selected controller model. Let Sol choose the minimum useful plan
depth, give Luna implementation freedom, and require a Contract Delta for
material boundary conflicts. Use evidence-gated Sol rescue only for unresolved work.
Use Terra only for read-only evidence, with Luna Max fallback. Use risk-gated
Sol acceptance and independent review when justified. Bound concurrency and Token use,
and report the actual model and reasoning effort for every delegated unit.

Request a visible review:

Use $task-orchestrator to implement this change and create a user-visible independent review task.
If the review reports findings, remediate only the Finding Manifest and recheck each item.
Do not automatically repeat the full review.

Constrain authorization:

Use $task-orchestrator to coordinate this work.
Delegated permissions must not exceed the current task.
Keep review read-only and allow inspection, but no mutation, of external systems.

Suitable Work

Good fits:

• multi-module or multi-repository changes;
• implementation with explicit dependencies and useful parallelism;
• architecture, algorithms, concurrency, protocols, security, or difficult debugging;
• releases that require independent review and traceable remediation;
• long-running work that needs bounded writes, permissions, retries, and Tokens;
• work that may need recovery from explicit state after interruption.

Poor fits:

• a short answer;
• one safe read-only command;
• a very small local edit with an obvious acceptance check;
• work split only to create the appearance of multi-agent execution.

Authorization and Honest Fallback

• Subagents inherit a dispatch-time permission snapshot, not guaranteed continuous synchronization.
• Permission parity for a visible task is claimed only when the runtime exposes and confirms it.
• Delegated permissions must remain equal to or stricter than the parent.
• Plugins, connectors, websites, secrets, and external services require separate authorization checks.
• If hard read-only enforcement is unavailable, the contract still prohibits writes, commits, messages, deployments, and device mutation, and discloses the limitation.
• Terra is allowed only for read-only evidence with no writes and verified route identity; otherwise use Luna Max or keep the work controller-owned.
• If the TaskGraph kernel cannot run, the Skill reports TaskGraph kernel unavailable, lowers concurrency, and strengthens manual verification without claiming deterministic scheduling or recovery.

Repository Layout

task-orchestrator/
├── SKILL.md
├── LICENSE
├── agents/
│   └── openai.yaml
├── references/
│   ├── model-affinity.md
│   ├── quality-gates.md
│   ├── review-remediation.md
│   ├── routing.md
│   ├── subtask-contract.md
│   ├── task-graph.md
│   └── task-graph.schema.json
└── scripts/
    ├── luna_v2_catalog.py
    ├── requirements-test.txt
    ├── task_graph.py
    ├── test_luna_v2_catalog.py
    ├── test_task_graph.py
    └── test_skill_policy.py

Key documents:

• SKILL.md: controller workflow and trigger definition;
• model-affinity.md: Provider-affine Luna resolution, relay-switch barrier, and compatibility repair;
• routing.md: model, complexity, parallelism, and Token policy;
• task-graph.md: graph contract and scheduling semantics;
• subtask-contract.md: delegation contract;
• quality-gates.md: integration and review gates;
• review-remediation.md: Finding Manifest and targeted recheck.

Validation

Push-Location task-orchestrator
python -m pip install -r scripts/requirements-test.txt
python -m unittest discover -s scripts -t . -p "test_*.py" -v
python -m py_compile `
  scripts/luna_v2_catalog.py `
  scripts/task_graph.py `
  scripts/test_luna_v2_catalog.py `
  scripts/test_task_graph.py `
  scripts/test_skill_policy.py
Pop-Location

The v0.1.7 distribution passed:

• 172 automated tests;
• pinned tiktoken==0.13.0 and jsonschema==4.26.0 test dependencies;
• an o200k_base measured total of 1,199 Tokens over SKILL.md and agents/openai.yaml;
• Python compilation;
• Skill structural validation;
• Markdown link validation;
• source/package file-hash comparison;
• independent validation after ZIP extraction.

Known Limitations

• TaskGraph v1 does not provide cross-process event-log locking.
• Rescue graphs created before v0.1.6 with free-form string evidence are audit artifacts; preserve their original kernel for replay or start a successor revision with structured event evidence before new dispatch.
• Legacy no-Terra graphs remain valid audit artifacts; do not rewrite them to relabel prior nodes as evidence. Start a new revision for new dispatch.
• Sol rescue evidence proves the recorded routing decision, not that every provider exposes a route-scoped Sol or Luna candidate.
• Write-set checks do not resolve symlinks or Windows Junctions.
• The kernel schedules local state but does not execute Codex tasks.
• A running task cannot hot-refresh a changed relay's subagent model allowlist; fully reload Codex and start a new task.
• On a confirmed V2 execution surface, a relay manager may regenerate its catalog and overwrite repaired Luna V2 metadata; rerun inspect-config after switching relays.
• A provider that exposes no structured affinity, Provider-default identity, canonical Luna text, or exact mapping cannot be matched safely without user or adapter metadata.
• A shared Provider ID does not identify one relay; exact-route claims require runtime route metadata or a confirmed route-preserving canonical ID.
• Visible tasks, model selection, effort selection, and permission metadata depend on the host runtime.
• Hardware, production, and external-state claims still require validation in the relevant environment.
• Higher concurrency may reduce latency while increasing Token, quota, and integration costs.

Design Principles

1. The controller owns decomposition, integration, quality, and the final conclusion.
2. Do not parallelize merely to fill slots, and do not duplicate reviews by default.
3. Make dependencies, write sets, permissions, baselines, and acceptance criteria explicit.
4. Report models, efforts, permissions, and verification according to runtime facts.
5. Convert review findings into problems that can be located, remediated, and cleared individually.
6. A fallback route must not bypass quality gates.
7. Treat Tokens as a bounded resource without trading away verification or honest reporting.

License

Licensed under the Apache License 2.0.