Use for coordinating multi-step workflows across several tools or skills, managing shared state, and ensuring coherent sequential or parallel execution.
The orchestrator manages execution order, shared state, and error recovery across multiple skills. It does not do any coding itself — it sequences and monitors.
Use when a task requires three or more distinct skill invocations where:
The most common pattern:
Phase 1 (parallel): Read all inputs
├── rg_search (find usages)
├── get_file_outline (understand structure)
└── fetch_url (get external reference)
Phase 2 (sequential): Consolidate findings → form action plan
Phase 3 (sequential): Write / mutate (one file at a time)
├── edit_block file_A
├── edit_block file_B
└── edit_block file_C
Phase 4 (parallel): Verify
├── run_ruff
├── run_mypy
└── run_pytest (targeted)
Rule: reads can parallelize; writes must serialize.
Parallelize when:
Do NOT parallelize when:
Write the execution DAG before starting:
scratch_write("
Orchestration plan:
Phase 1 [parallel]:
- explore: find all usages of foo()
- explore: get outline of config.py
Phase 2 [sequential — depends on phase 1]:
- think: decide which files need editing
Phase 3 [sequential]:
- edit_block: update foo() in utils.py
- edit_block: update call sites in core.py
- edit_block: update tests in test_utils.py
Phase 4 [parallel]:
- quality: ruff check
- quality: pytest test/test_utils.py
Phase 5 [sequential — if phase 4 green]:
- git: checkpoint commit
")
Use todo_write for longer orchestrations:
todo_write([
{"task": "Find all usages (rg_search)", "status": "pending"},
{"task": "Get config.py outline", "status": "pending"},
{"task": "Edit utils.py", "status": "pending"},
{"task": "Edit core.py", "status": "pending"},
{"task": "ruff + pytest verify", "status": "pending"},
{"task": "Git checkpoint", "status": "pending"},
])
Mark items in-progress and done as you go.
If a step fails:
shell, file_ops)After orchestration completes:
git step was reached: confirm checkpoint created| Anti-pattern | Correct behavior |
|---|---|
| Writing to file B before confirming file A edit succeeded | Always verify each write before proceeding |
| Running all reads AND writes in one parallel batch | Reads parallel, writes sequential |
| Continuing after a write failure | STOP and report |
| Committing without a quality pass | Quality gate is mandatory before git |
| Losing track of which steps completed | Use scratch or todo to track state |