Subagent Orchestration

Unified skill for orchestrating subagent sessions — parallel, sequential, or mixed — with task packaging, failure recovery, and disciplined integration.

Indexed Reference Map

• @[SKILL.md#L1-L142] Frontmatter, scope, trigger rules, SOP, error handling, output contract.
• @[references/INDEX.md#L1-L23] Reading order and reference inventory.
• @[references/task-packaging.md#L1-L55] How to build a subagent task package (handoff contract).
• @[references/parallel-dispatch.md#L1-L65] Parallel fan-out: suitability, partitioning, fan-out limits.
• @[references/sequential-delegation.md#L1-L40] Sequential delegation: plan-first, handoff, control loop.
• @[references/failure-recovery.md#L1-L55] Timeout handling, re-dispatch, partial completion detection.
• @[references/merge-and-verify.md#L1-L45] Result collection, merge checkpoints, post-integration verification.
• @[references/worked-examples.md#L1-L120] Real-world orchestration patterns with concrete code/tool flows.

Scope

• In-scope:
  • Splitting work into bounded subagent tasks (parallel or sequential).
  • Packaging task contracts with clear scope, constraints, and deliverables.
  • Spawning via sessions_spawn with appropriate timeout/mode settings.
  • Tracking completion events (push-based, no polling).
  • Handling timeout/failure: detecting partial completion, re-dispatching remainder.
  • Merging multi-branch outputs with verification before reporting done.
• Out-of-scope:
  • Spawning subagents for trivial single-agent work.
  • Vague delegation without a task contract.
  • Autonomous long-running agent swarms without integration checkpoints.
  • Polling sessions_list in loops (violates push-based model).

KB Mode Notes

• Reading order:
  1. references/INDEX.md
  2. references/task-packaging.md
  3. references/parallel-dispatch.md
  4. references/sequential-delegation.md
  5. references/failure-recovery.md
  6. references/merge-and-verify.md
  7. references/worked-examples.md
• Coverage Matrix:
  • Task contract design -> task-packaging.md
  • Parallel fan-out patterns -> parallel-dispatch.md
  • Sequential plan-first delegation -> sequential-delegation.md
  • Timeout/failure/re-dispatch -> failure-recovery.md
  • Result merge + verification -> merge-and-verify.md
  • Concrete worked examples -> worked-examples.md
• Portability note:
  • "Subagent" means OpenClaw sessions_spawn with bounded tasks and push-based completion.
  • Patterns transfer to any runtime supporting session orchestration with auto-announce.

Trigger Rules

• Positive:
  • Task has 2+ independent workstreams that benefit from parallel execution.
  • Implementation is large enough that one agent should orchestrate others.
  • User says: parallelize, split into subagents, fan out, delegate, dispatch workers.
  • Need to coordinate investigation + implementation + verification in separate sessions.
  • Batch processing where items are independent (e.g., translate N files, audit N skills).
• Negative:
  • Task is small enough for one agent in one session.
  • Subtasks are tightly coupled with heavy shared-state mutation.
  • No clear task contract or partition exists.
  • User only wants brainstorming/planning, not execution.
• Escalation:
  • If shared-state collision risk is high, redesign split or fall back to sequential.
  • If task contract is weak, strengthen it before spawning.
  • If fan-out exceeds 8 branches, justify or reduce.

SOP

Phase 1: Assess & Plan

1. Determine orchestration mode: parallel, sequential, or mixed.
2. Assess suitability: Are branches genuinely independent? Is fan-out justified?
3. Create backup if the work mutates shared state (files, configs).
4. Define task packages: Each subagent gets a bounded contract (see task-packaging.md).

Phase 2: Dispatch

5. Set appropriate timeouts: runTimeoutSeconds based on expected workload per batch.
6. Spawn subagents: Use sessions_spawn with mode="run", unique labels, clear task instructions.
7. Track expected completions: Record child session keys and labels; do NOT poll.

Phase 3: Monitor & Recover

8. Wait for push-based completion events: Each subagent auto-announces when done.
9. On timeout/failure: Check which items were actually completed vs. remaining.
10. Re-dispatch remainder: Split failed batches into smaller sub-batches with tighter scope.

Phase 4: Merge & Verify

11. Collect results: Track completed vs. pending across all branches.
12. Run final verification: Automated scan/check that all intended changes were applied.
13. Report completion: With verification evidence, backup/rollback path, and any remaining risks.

Error Handling

• Subagent timeout:
  • Do not assume all work was lost; check which items were actually completed.
  • Re-dispatch only the remaining items in smaller batches.
  • Consider increasing runTimeoutSeconds if the original was too tight.
• Subagent task too vague:
  • Stop and rewrite the task package with tighter constraints.
• Returned output lacks evidence:
  • Request artifacts or re-run with stricter deliverable requirements.
• Shared-state collision:
  • Pause, reconcile, then continue with stricter isolation.
• Too many branches (fan-out explosion):
  • Cap at 6-8 parallel branches; batch remaining into subsequent waves.
• Completion event arrives after final report:
  • Respond with NO_REPLY (late arrivals after synthesis).
• Push-based model violation:
  • Never call sessions_list or exec sleep to poll for results.
  • Wait for completion events to arrive as user messages.

Output Contract

• Deliverable:
  • Orchestration Mode: parallel | sequential | mixed.
  • Task Packages: branch/batch -> objective, scope, file list, deliverable.
  • Dispatch Summary: subagent labels, session keys, timeouts.
  • Completion Tracking: N/M batches done, any failures/timeouts.
  • Recovery Actions: re-dispatched batches (if any).
  • Verification Evidence: automated check confirming all changes applied.
  • Backup/Rollback Path: where backups live, how to restore.
  • Remaining Risks: anything unverified.
• Validation:
  • Must show bounded task contracts + post-completion verification.
  • Must not claim done without automated verification scan.
• Compliance Verdict:
  • PASS when all branches completed, verified, and integrated safely.
  • PARTIAL when some branches succeeded but gaps remain documented.
  • FAIL when orchestration violated safety boundaries or lost work.

Relationship to Superseded Skills

• dispatching-parallel-agents: Parallel dispatch patterns are now in references/parallel-dispatch.md.
• subagent-driven-development: Sequential delegation patterns are now in references/sequential-delegation.md.
• Both skills' reference content has been consolidated and enriched with real-world failure recovery patterns.