orchestrate

orchestrate — autonomous phase runner

WHEN THIS SKILL FIRES

Trigger phrases (case-insensitive, anywhere in user message):

• "orchestrate"
• "orchestrate <path>"
• "orchestrate <path> waits on <ids>" / "orchestrate <path> depends on <ids>"
• "orchestrate <path> --autonomous" (explicit autonomous mode, default ON anyway)
• "orchestrate resume <session-id>" (resume from a prior orchestrate run's SESSION_HANDOFF)

Does NOT fire on:

• "explain orchestrate" / "what does orchestrate do" — read-only, answer directly
• "show orchestrate status" — read state files directly without invoking the protocol

INVOCATION CONTRACT

User input shapes that resolve correctly:

• "orchestrate F:.ELAI_workflow\docs\thefinalglance\B-plan\B-30_multilang_dkg_hardening.md, depends on B-29 and B-29.5"
• "orchestrate the B-30 plan, B-29 + B-29.5 running, dont bother me, test with sonnet 4.6 cloud"
• bare "orchestrate" with no path > ask user for plan path (this is the ONE pre-flight question allowed)

HARD RULE (BLOCKING — see .Codex/rules/orchestrate-protocol.md for H-1..H-10): When this skill fires, agent dispatch is NON-OPTIONAL. The main LLM is the controller and dispatches the canonical ELAI agents (context-compiler, integration-explorer-elai, auditor, memory-writer, fixer, wiring-contract-validator) per protocol.md step 8. It does NOT run those steps in-band by itself. NO Edit/Write on plan-scope files BEFORE the parallel batch returns. NO test/build runs by the main LLM (auditor only). NO memory-bank writes by the main LLM (memory-writer only). "Save tokens across N queued plans" / "small plan" / "I already read it" / "this is just UI" are NOT valid skip reasons — sub-agents have their own GC'd context, so dispatching them SAVES the main LLM's context. The only legal skips: (a) explicit USER_OVERRIDE in the current message, (b) patch-N single-file isolated fixes, (c) prose-only documentation sub-phases. ELAI agents are NOT in the Agent tool's subagent_type list; dispatch via subagent_type=general-purpose with the prompt: "Read F:.ELAI_workflow.Codex\agents<name>.md and follow it strictly. <task args>". This block exists because the main LLM has repeatedly skipped agent dispatch under bogus optimizations.

WHAT THIS SKILL ACTUALLY DOES

1. Parses user input to extract: plan_path (required), depends_on (list of B-N ids or session ids, default empty), parallel_cap (default 3), model_executor (default sonnet-4.6), autonomous (default true).
2. Resolves target project from plan_path (walks up looking for .Codex/ folder).
3. Loads compat/<target_project>.md if present (e.g. compat/ELAI.md for F:.ELAI_workflow...). Compat file declares native orchestration skill + stack + integration gates + dashboard wiring path.
4. Detects stack via tools/detect-stack.ps1 (Cargo.toml > rust, package.json > typescript, .xcodeproj > swift, multi > cross-stack).
5. Loads matching stack-adapter file from stack-adapters/.
6. Registers THIS session via mcp_session_register (apps_workflow side, even though work runs in target project).
7. For each dep in depends_on: tools/dep-wait.ps1 polls mcp_session_list every 60s until released. Never calls mcp_fsm_* against another session.
8. Generates boot prompt by filling overrides-template.md with: plan_path, depends_on (now empty), parallel_cap, sub-phase-grain instruction, skip-prompt-engineer flag, 1-audit-cycle flag, commit-at-end-only flag, autonomous flag, stack adapter content inlined, compat content inlined.
9. Launches Codex -p --output-format stream-json --resume <sid> via tools/orchestrate-launcher.ps1 with CWD = target project root. The bootstrapped session sees target's native .Codex/ (b-plan-runner skill for ELAI, planning-workflow for apps_workflow).
10. The bootstrapped session runs target's native orchestration skill BUT with the per-sub-phase loop inserted between PROMPT_TRANSFORM and EXECUTING, AND with the override policies enforced.
11. Tails stream-json, parses system/init (verify hooks loaded), system/api_retry (rate-limit observability), tool_use (progress), result (per-sub-phase completion). Surfaces tripwires.
12. Phase-end sweep (tools/phase-end-sweep.ps1) runs the 6 generic + stack-specific gates after each sub-phase. BLOCK any sub-phase that fails the sweep; bubble-up policy decides next action.
13. After all sub-phases complete + final sweep passes: bootstrapped session does ONE commit per commit-cadence.md. Reports final result.
14. FEATURE-MAP UPSERT: if the run shipped/activated/changed ELAI features and docs/thefinalglance/ELAI-FEATURE-MAP.md exists (the source of truth for features + their composition), upsert the touched entries (status flag flip, cross-links, new entries) and bump its header date. One flag per feature, never narrative.

AGENT RULE INJECTION + HANDOFF MEDIATION (binding)

Sub-agents do NOT reliably load AGENTS.md or .Codex/rules/ - their rule context is whatever the dispatch prompt carries. Therefore EVERY agent prompt this skill (or its bootstrapped executor) sends MUST begin with the pointer line from .Codex/rules/agent-dispatch-preamble.md: "Read F:.ELAI_workflow.Codex\rules\agent-dispatch-preamble.md FIRST and obey it as binding. handoff_file=<path>; task_id=<id>; scope=<paths>." The preamble bans worker git mutation + destructive ops, locks scope, defines the BLOCKED protocol, AND (R-8, D-030) binds the production-caller contract: an EXECUTOR shipping new pub Rust symbols must wire each into the PRODUCTION_HOOK seam in the same changeset and self-run .Codex/tools/production_caller_check.py before DONE; an EXPLORER scoping a sub-phase that adds a new pub fn must return the exact PRODUCTION_HOOK seam (file+fn); the AUDITOR re-runs the checker off-agent and BLOCKs any DARK fn. This structurally kills the wire-dark-machinery pattern (executor builds + unit-tests machinery but never wires production; 6 occurrences in the s-107b022a stretch). See .Codex/rules/production-caller-gate.md. A dispatch without the preamble pointer line is a protocol violation (same severity as skipping the parallel batch).

HANDOFF MEDIATION LOOP: at run start the controller resolves ONE topic-keyed handoff file per .Codex/rules/handoff-protocol.md (workflow/handoff/{run-topic-slug}.md) and passes its path to every agent. When an agent returns BLOCKED: (1) read its handoff entry (the entry, not the whole file), (2) decide - ground the decision, search if needed, surface to user ONLY if it is tripwire-grade, (3) APPEND a DECISION block under the agent's entry (what was chosen + why + what the next agent must do), (4) the next agent's prompt includes the handoff path + "read entry <N> and its DECISION before starting". The orchestrator decides; workers never resolve material forks themselves. This loop is also the recovery path for context-exhausted agents (their HOW TO PICK UP section is the resume spec).

MODEL LADDER + COST DISCIPLINE (binding)

Every agent dispatch picks the cheapest tier that fits the job - capability and cost are balanced per dispatch, never "session model for everything":

• haiku: any ad-hoc bulk read/summarize helper (file sweeps, log digests, doc reads that return a focused summary). Never the session model for bulk reads.
• sonnet: ALL canonical ELAI agents (context-compiler, integration-explorer-elai, auditor, memory-writer, fixer, wiring-contract-validator, paper-ingestor, spec-grounder...) per the AGENTS.md model=sonnet rule, plus the executor (model_executor, default sonnet-4.6).
• opus/fable: the controller session only. NEVER spawned as an agent by orchestrate without the user explicitly asking for it in the current message. parallel_cap=3 is a HARD CAP (provider rate limit), not a tunable default: the user may lower it, orchestrate may never raise it. Dispatches beyond 3 queue and run as slots free. The user's "orchestrate <plan>" invocation is standing authorization for the CANONICAL fleet only (the per-sub-phase pattern above at cap 3). Any fleet beyond that pattern - more than 3 agents in one batch, any non-sonnet/haiku agent, any agent type outside the canonical list - requires announcing count + model + rough token cost and getting a yes first (global agent-spawning rule).

THE 4 TRIPWIRE CONDITIONS (only times orchestrate breaks autonomous mode)

T1 IRREVERSIBLE OP detected in proposed Bash command (git push --force, git reset --hard/--mixed, git checkout -- <paths> / git restore, git clean, git stash drop, any git history rewrite, rm -rf, db drop, prod deploy, npm publish, cargo publish): surface to user with the exact command and a Y/N. Default no. Destructive git is in this list because of the 2026-06-11 incident: an executing agent ran git reset --hard 8x to "self-repair" a confusing tree and wiped the whole integration diff. A wrong-looking working tree is a TRIPWIRE, never something a session repairs with resets. Also: mcp__pod-lifecycle__pod_stop or mcp__pod-lifecycle__pod_terminate when pod_cost_status shows nonzero cost-so-far: surface the cost figure in the Y/N confirm (H-38 compose, not a restatement of the tripwire). T2 50-EVENT BUBBLE-UP CAP reached (per .Codex/rules/bubble-up.md SAFETY rule): force ABORT and SESSION_HANDOFF. T3 DEP-WAIT EXCEEDS 4h on any single dependency: surface to user with options [keep waiting / abort / proceed-without-dep]. T4 SWEEP FAILS after 3 consecutive sub-phase retries OR after fixer agent has been spawned 3 times with no progress (Magentic stall counter): surface to user with the failing gate + recommended actions.

In all other cases: orchestrate runs through. No "should i proceed" prompts. No "i found a question" deferrals. Choose the best non-lazy grounded option and continue.

OUTPUTS THIS SKILL PRODUCES

• workflow/sessions/<sid>/orchestrate-run.md — full run log, every sub-phase decision, every agent dispatch, every gate result
• workflow/sessions/<sid>/orchestrate-state.json — FSM + cursor state (sub-phase index, batch index, retry counts)
• workflow/sessions/<sid>/phase-reports/<sub-phase-id>.md — per-sub-phase end report (one per Phase 1, Phase 2, ...)
• workflow/sessions/<sid>/SESSION_HANDOFF.md — only on abort / tripwire / PreCompact
• one git commit at end of run (in target project, not apps_workflow)

DEEP PROTOCOL

See protocol.md for the full step-by-step. This file is the trigger contract; protocol.md is the body. The launched session reads overrides-template.md (filled) as its boot prompt. Per-stack gates live in stack-adapters/. Per-target compat lives in compat/.

ESCAPE HATCHES

• user types "abort orchestrate" at any time > tools/orchestrate-launcher.ps1 sends SIGINT to the bootstrapped session, runs session-handoff, returns control
• user types "pause orchestrate" > save state, kill launched session, mark resumable. Resume via "orchestrate resume <sid>".
• PreCompact hook fires in launched session > session-handoff.ps1 auto-writes SESSION_HANDOFF.md
• launched session crashes / hits rate limit > stream-json result event with error_status reports back, orchestrate-launcher.ps1 emits a clear failure summary

CROSS-REFERENCES

• protocol.md — deep step-by-step
• overrides-template.md — boot prompt template (filled per-run)
• stack-adapters/ — per-stack gate definitions
• compat/ — per-target-project overrides + delegate map
• tools/ — PS1 wrappers (launcher, detect-stack, dep-wait, phase-end-sweep)
• .Codex/rules/orchestrate-protocol.md — hard-rule summary
• .Codex/rules/bubble-up.md — retry budgets + 50-event cap
• .Codex/rules/agent-spawning.md — canonical agent list (target project's agents take precedence at execution time)

END SKILL.md