Orchestration

Use this skill when a task benefits from deeper reasoning or delegated work than the primary model should provide.

Modes

The saved Orchestration preferences contain a policy and two model choices:

• manual: escalate only when the user explicitly asks.
• recommend: suggest escalation for substantial work and wait for confirmation.
• automatic: escalate complex tasks without asking each time, while still respecting approval boundaries.

The escalationModel is the stronger isolated model that plans, delegates, and reviews. The workerModel is used by that orchestrator for implementation and research workers. If either model is unset or unavailable, ask the user to choose a configured model; do not silently substitute the primary model.

• Explicit: use when the user asks to think deeply, delegate, use a stronger model, or orchestrate the work.
• Recommended: suggest escalation when a task is multi-step, spans files or tools, needs architecture/research, or is costly to get wrong.
• Automatic: only use if the saved policy is automatic. Do not silently spend on a stronger model when the policy is manual or recommendation-only.

Handoff

Do not forward the complete conversation by default. Give the orchestrator a compact, structured brief containing:

{
  "objective": "What must be achieved",
  "user_intent": "What a successful outcome means to the user",
  "background": ["Relevant facts only"],
  "constraints": ["Permissions, safety, budget, or approval limits"],
  "relevant_files": ["Paths or URLs worth inspecting"],
  "known_decisions": ["Decisions that must not be revisited"],
  "success_criteria": ["Concrete acceptance checks"],
  "risk_level": "low|medium|high",
  "requested_mode": "investigate|plan|prepare_changes|execute_with_approval"
}

Include only context needed to solve the task. Escalation does not grant permission to publish, send external messages, commit, push, delete, merge, or make other irreversible changes.

Orchestrator procedure

The primary agent must _not_ implement the task or spawn the implementers itself. It should:

1. Confirm the objective and identify missing information before escalating.
2. Resolve the configured orchestration-orchestrator agent profile, its allowlist, and escalationModel before escalating.
3. Create a compact handoff and spawn exactly one isolated session with explicit agentId: orchestration-orchestrator and model: escalationModel. Never target orchestration-worker directly from the primary agent.
4. If the target profile, model, or allowlist cannot be resolved, stop and report the escalation failure; do not silently fall back to the primary model or agent.
5. Wait for that orchestrator's completion result and present it to the user. If escalation fails, report the failure rather than taking over silently.

The stronger isolated orchestrator must then:

1. Plan first. Resolve the configured orchestration-worker agent profile, its allowlist, and workerModel before spawning.
2. Spawn narrowly scoped specialist subagents targeting only the configured orchestration-worker agent, with explicit agentId: orchestration-worker and model: workerModel, for research, inspection, implementation, or testing when useful. Never omit either field or silently substitute the orchestrator/primary model.
3. Give each worker a bounded objective, write scope, and verification requirement. Avoid duplicate overlapping edits.
4. Respect the worker profile's allowAgents policy. A direct primary-to-worker spawn must be rejected; if it is accepted, treat the routing test as failed and report it.
5. Review worker results, reconcile contradictions, and run the smallest meaningful checks.
6. Return a structured result to the primary agent:

{
  "status": "completed|blocked|needs_approval|failed",
  "summary": "Short result",
  "findings": ["Important discoveries"],
  "work_performed": ["Changes or actions taken"],
  "files_changed": ["Paths"],
  "checks": ["Tests, lint, or verification"],
  "open_questions": ["Remaining decisions"],
  "approval_needed": false
}

1. The primary agent remains responsible for the user-facing explanation and any approval request.

Routing validation

Do not call an orchestration run fully validated merely because child sessions exist. Verify from live session/cockpit evidence that:

• the orchestrator session is assigned to orchestration-orchestrator and runs escalationModel;
• worker sessions are assigned to orchestration-worker and run workerModel;
• the primary cannot directly target orchestration-worker because the allowlist rejects it;
• no child silently inherited the primary model.

If task metadata omits model information, use live session/cockpit status as the source of truth and report any mismatch explicitly.

Setup and explicit triggers

When preferences are missing, ask the user conversationally which configured model should be the escalation/orchestrator model and which should be the worker/implementation model. Inspect available models with the normal OpenClaw model/session tools, explain the tradeoff, confirm the choices, and save them in the Orchestration preferences. Reuse them in future sessions.

Recognize /deep, /delegate, and /plan as requests to use this workflow. Natural-language equivalents include “think deeply about this”, “use the stronger model”, and “delegate this”. If the command layer does not expose these commands, follow the same workflow from the user request.

Budget and safety defaults

• Prefer one orchestrator and a small number of specialists over an unbounded tree.
• Respect configured model, token, parallelism, and depth limits.
• Escalate only the sensitive context necessary for the task.
• Never claim a worker or stronger model ran unless the runtime confirms it.
• Stop and return needs_approval before external, destructive, or permanent actions.