ZCL Orchestrator (Codex Skill)

This skill is for the orchestrator (you), not the spawned mission agent.

Native Runtime Boundary (Current)

ZCL has first-class native runtime execution in

zcl suite run

and campaign flows via

runner.type=codex_app_server

.

Runtime selection is strategy-based and deterministic via ordered fallback chains (

--runtime-strategies

,

ZCL_RUNTIME_STRATEGIES

).

Process runner mode remains supported as explicit fallback (

--session-isolation process

).

Native runtime strategy health/failure classes are typed and surfaced in artifacts/JSON outputs.

Capability Matrix

Capability

Implemented

Enforced

Notes

Native suite execution (

--session-isolation native

)

yes

yes

suite run

forbids process runner command in native mode.

Runtime strategy fallback chain

yes

yes

Ordered strategy IDs, capability checks, typed per-strategy failures.

Native campaign runner (

runner.type=codex_app_server

)

yes

yes

No per-flow

runner.command

required.

Native event trace mapping (

tool=native

)

yes

yes

Redaction + bounds + integrity flags preserved.

Mission-only result-channel finalization

yes

yes

3-turn workflows via

minResultTurn

.

Provider onboarding structure

yes

partial

provider_stub

demonstrates unsupported-capability behavior.

Runtime failure taxonomy (auth/rate-limit/stream/crash/listener/stall)

yes

yes

Typed

ZCL_E_RUNTIME_*

codes in summaries + feedback failure payloads.

Primary evidence:

.zcl/.../tool.calls.jsonl

.zcl/.../feedback.json

Operator Invocation Story

When asked to "run this through ZCL", use this order:

zcl init

Optional preflight:

zcl update status --json

zcl doctor --json

Optional single-attempt allocation path:

zcl attempt start --suite --mission --prompt --isolation-model native_spawn --json

Preferred native suite path:

zcl suite run --file --session-isolation native --runtime-strategies codex_app_server --feedback-policy auto_fail --finalization-mode auto_from_result_json --result-channel file_json --result-min-turn 3 --campaign-id --progress-jsonl --json

Process fallback path:

zcl suite run --file --session-isolation process --feedback-policy auto_fail --finalization-mode auto_from_result_json --result-channel file_json --result-min-turn 3 --campaign-id --progress-jsonl --shim tool-cli --json -- [args...]

First-class campaign path:

zcl campaign lint --spec --json

zcl campaign canary --spec --missions 3 --json

zcl campaign run --spec --json

zcl campaign resume --campaign-id --json

zcl campaign status --campaign-id --json

zcl campaign report --campaign-id --allow-invalid --json

zcl campaign publish-check --campaign-id --json

Validate/report from artifacts:

zcl report --strict

zcl validate --strict

zcl attempt explain --json

Explicit finalization path for harness-aware prompts:

zcl feedback --ok --result

or

zcl feedback --fail --result-json

Operator Guardrails

Native suite attempts now anchor timeout windows before native turn execution; stalled native attempts classify as

ZCL_E_RUNTIME_STALL

.

Native suite orchestration now guarantees terminal artifacts on failure paths (

feedback.json

+ best-effort

attempt.report.json

) for post-mortem continuity.

Campaign read/report/resume commands fail fast with

ZCL_E_CAMPAIGN_STATE_DRIFT

when persisted

campaign.run.state.json

disagrees with current spec mission selection (for example

totalMissions=0

on a non-empty selection).

For CI/automation, prefer

zcl campaign report --allow-invalid --json

to collect report payloads without branching on process exit codes; keep

zcl campaign publish-check

as the strict publish gate.

Campaign Guidance

Recommended native Codex flow:

flows

:

-

flowId

:

codex

-

native

runner

:

type

:

codex_app_server

sessionIsolation

:

native

runtimeStrategies

:

[

"codex_app_server"

]

feedbackPolicy

:

auto_fail

freshAgentPerAttempt

:

true

Mission-only recommended variant:

promptMode

:

mission_only

flows

:

-

flowId

:

codex

-

native

runner

:

type

:

codex_app_server

sessionIsolation

:

native

runtimeStrategies

:

[

"codex_app_server"

]

finalization

:

mode

:

auto_from_result_json

minResultTurn

:

3

resultChannel

:

kind

:

file_json

path

:

mission.result.json

Prompt Policy

Use exactly one mode per campaign:

promptMode: mission_only

(preferred): mission intent + output contract only; no harness terms.

promptMode: default

harness-aware prompts permitted. Native Recommendation Criteria (Measured) Codex native runtime is recommended when both hold in CI/nightly checks: Reliability: native 20-attempt parallel smoke run success rate >= 95%. Throughput: same run completes in <= 30 seconds on CI worker baseline. Guard test path: internal/interfaces/cli/suite_run_integration_test.go ( TestSuiteRun_NativeParallelUniqueSessions , TestSuiteRun_NativeSchedulerRateLimitIsDeterministic ). Templates examples/campaign.canonical.yaml examples/campaign.no-context.comparison.yaml examples/campaign.no-context.codex-exec.yaml examples/campaign.no-context.codex-subagent.yaml examples/campaign.no-context.claude-subagent.yaml examples/campaign.native.codex.minimal.yaml examples/campaign.native.codex.advanced.yaml docs/migration/shell-adapter-to-native-codex.md