agent-orchestrator

The strength of this skill is that it treats orchestration as a file-system protocol rather than a prompt trick: each sub-agent gets its own workspace with inbox/, outbox/ and a status.json, so the parent can poll state instead of parsing free-text replies. The Phase 1 checklist (end goal, deliverables, dependency graph, then group into parallelizable chunks) is the part that actually prevents the classic failure where three sub-agents edit the same artifact. Trade-off worth naming: the inbox/outbox pattern adds two extra write-read hops per subtask, so for short tasks it costs more tokens than it saves. I use it when a task has 3+ genuinely independent deliverables and I want recoverability mid-run; for anything smaller, a single agent with a todo list is cheaper. Also note the generated SKILL.md files must be dissolved or they accumulate and silently pollute later agent discovery.

Use case: Coordinating a multi-part deliverable (research + draft + verification) where each part can run in parallel and I need to resume after a failure without redoing finished work.

# Orchestrating sub-agents without losing the plot The failure mode of multi-agent work is rarely a bad sub-agent. It is a parent agent that cannot tell which sub-agents are done, which are wedged, and which results were already consumed. The orchestrator skill's file-based layout fixes this, but only if you treat the files as the source of truth and the chat replies as hints. ## Write the decomposition down before you spawn anything The Phase 1 checklist only pays off if it produces an artifact. Before spawning, record the end goal, the deliverables, and the dependency edges. Anything with no incoming dependency can run in parallel; anything with an incoming edge must wait, no matter how tempting it is to spawn it now. ```python import json, os, time AGENTS = { "collect": {"out": "out/collect.json", "deps": []}, "analyze": {"out": "out/analyze.json", "deps": ["collect"]}, "verify": {"out": "out/verify.json", "deps": ["analyze"]}, } def pending(done): ready, blocked = [], [] for name, spec in AGENTS.items(): if name in done: continue (ready if all(d in done for d in spec["deps"]) else blocked).append(name) return ready, blocked def collect(done, timeout_s=900): deadline = time.time() + timeout_s while time.time() < deadline: for name in list(AGENTS): path = AGENTS[name]["out"] if name not in done and os.path.exists(path): done[name] = json.load(open(path)) ready, blocked = pending(done) if not blocked: break time.sleep(5) return done, sorted(set(AGENTS) - set(done)) ``` ## Treat the outbox file, not the reply, as completion A sub-agent can finish its work and still return a vague summary; it can also return an enthusiastic summary with an empty output directory. Gate every stage on the artifact existing and parsing. If a stage is still missing after its timeout, re-spawn it once with the same brief, then escalate to the user rather than looping. ## Dissolve agents when the run ends Generated agents persist and get rediscovered by later runs, so leftovers behave like stale configuration. After consolidation, delete the workspaces or move them under an archive path, and keep only the consolidated result. ## Tips - Keep each subtask self-contained: give it its input paths and its output path, never an instruction to "look around the repo". - Parallelise only work with no shared mutable output. Two agents writing one file is a corruption, not a merge conflict you can resolve. - Log the spawn and the completion of each stage with a timestamp so a wedged run is diagnosable after the fact. - Gotcha: a sub-agent that exits cleanly is not evidence of success. Verify the artifact and its shape before marking the stage done. - Gotcha: the orchestrator's own context is the scarcest resource. Read status files and summaries, never full sub-agent transcripts.