Shodh Memory

1---
2name: orchestrate
3description: This skill should be used when the user asks to 'orchestrate a task', 'break down work into parallel agents', 'coordinate subtasks', 'run agents in parallel', or mentions 'multi-agent'. Decomposes complex tasks into tracked subtasks, dispatches parallel subagents, and coordinates until completion.
4version: 1.0.0
5author: Shodh AI
6tags:
7  - orchestration
8  - multi-agent
9  - parallel
10  - task-decomposition
11  - coordination
12---
13
14# Agent Orchestration — Todo-Driven Parallel Execution
15
16You are orchestrating a complex task by decomposing it into tracked subtasks, dispatching parallel agents, and coordinating dependencies until completion. Shodh-memory todos are your task graph. Claude Code's Task tool is your agent spawner. Hooks handle the automation.
17
18## Phase 1: Decompose
19
20Break the user's request into 3-10 concrete, independently executable subtasks.
21
22### Create the project
23
24```
25add_project(name="orch-{kebab-case-summary}")
26```
27
28The project auto-generates a prefix (e.g., `ORCH`). All todos in this project use that prefix for short IDs like `ORCH-1`, `ORCH-2`.
29
30### Create todos with dependencies
31
32For each subtask, create a todo in the project:
33
34**Independent tasks** (can run immediately):
35```
36add_todo(
37  content="Clear, specific description of what this subtask produces",
38  project="orch-{name}",
39  priority="high",
40  tags=["orchestration", "batch:1"]
41)
42```
43
44**Dependent tasks** (must wait for others):
45```
46add_todo(
47  content="Description of dependent work",
48  project="orch-{name}",
49  status="blocked",
50  blocked_on="ORCH-1,ORCH-3",
51  tags=["orchestration", "batch:2"]
52)
53```
54
55The `blocked_on` field is comma-separated short IDs. The `batch:N` tag groups tasks by execution wave.
56
57### Dependency rules
58- A task blocked on `"ORCH-1,ORCH-3"` cannot start until BOTH are done
59- Keep dependency chains shallow (max 3-4 levels deep)
60- Maximize parallelism — identify tasks that are truly independent
61- Never create circular dependencies
62
63### Present the plan
64
65Show the user the task graph before executing:
66
67```
68Project: orch-refactor-auth (ORCH)
69
70Batch 1 (parallel):
71  ORCH-1: [todo] Extract JWT utilities into auth/tokens.ts
72  ORCH-2: [todo] Create password hashing module
73
74Batch 2 (after batch 1):
75  ORCH-3: [blocked on ORCH-1] Update login endpoint
76  ORCH-4: [blocked on ORCH-1] Update token refresh endpoint
77  ORCH-5: [blocked on ORCH-2] Update registration endpoint
78
79Batch 3 (after batch 2):
80  ORCH-6: [blocked on ORCH-3,ORCH-4,ORCH-5] Integration tests
81```
82
83Wait for user approval before dispatching.
84
85## Phase 2: Dispatch
86
87### Find unblocked work
88
89```
90list_todos(project="orch-{name}", status=["todo"])
91```
92
93### For each unblocked todo:
94
951. Mark it in-progress:
96```
97update_todo(todo_id="ORCH-N", status="in_progress")
98```
99
1002. Spawn a Task agent with the todo tag in the prompt:
101
102**CRITICAL:** Every Task prompt MUST start with `[ORCH-TODO:ORCH-N]` where N is the todo's sequence number. The PostToolUse hook extracts this tag to automatically complete the todo and unblock dependents.
103
104```
105Task(
106  description="ORCH-N: brief summary",
107  prompt="[ORCH-TODO:ORCH-N] Full detailed instructions for the agent...",
108  subagent_type="general-purpose"
109)
110```
111
1123. Spawn independent tasks in parallel — make multiple Task calls in a single response.
113
114### Choose the right agent type
115
116| Agent Type | Best For |
117|---|---|
118| `Explore` | Research, codebase exploration, finding patterns |
119| `Plan` | Architecture design, trade-off analysis |
120| `Bash` | Running commands, builds, deployments |
121| `general-purpose` | Code changes, implementation, multi-step work |
122
123### Include sufficient context in each prompt
124
125Each agent runs in isolation. Include in every Task prompt:
126- What files to look at or modify
127- What the expected output/deliverable is
128- Any constraints or patterns to follow
129- Context from previously completed tasks (copy relevant resolution comments)
130
131## Phase 3: Monitor & Continue
132
133After agents return, the PostToolUse hook automatically:
134- Adds the agent's result as a Resolution comment on the matching todo
135- Completes the todo
136- Unblocks dependent todos (removes from `blocked_on`, changes status to `todo`)
137
138### Check project state
139
140```
141list_todos(project="orch-{name}")
142```
143
144Review the status:
145- `done` — completed by agents
146- `todo` — newly unblocked, ready for next batch
147- `blocked` — still waiting on dependencies
148- `in_progress` — agents still running
149- `cancelled` — failed permanently
150
151### Dispatch next batch
152
153If there are `todo` status items, repeat Phase 2 for the next batch. Continue until all todos are `done` or `cancelled`.
154
155### Summarize results
156
157When all todos are complete:
1581. List all resolution comments to gather agent outputs
1592. Synthesize a summary for the user
1603. Note any cancelled tasks and why
161
162## Handling Failures
163
164When a Task agent returns an error or incomplete result:
165
1661. Add a Progress comment documenting the failure:
167```
168add_todo_comment(
169  todo_id="ORCH-N",
170  content="Agent failed: {error description}",
171  comment_type="progress"
172)
173```
174
1752. Retry (max 2 attempts) with additional context:
176```
177Task(
178  prompt="[ORCH-TODO:ORCH-N] RETRY: Previous attempt failed because {reason}. {updated instructions}...",
179  subagent_type="general-purpose"
180)
181```
182
1833. If retry fails, cancel the todo:
184```
185update_todo(todo_id="ORCH-N", status="cancelled", notes="Failed after 2 retries: {reason}")
186```
187
1884. Check if cancelled todo blocks other work — inform the user and ask how to proceed.
189
190## Cross-Session Continuity
191
192If a session ends mid-orchestration, the todo state persists. On the next session:
193
1941. Check for in-progress orchestration projects:
195```
196list_projects()
197list_todos(project="orch-{name}")
198```
199
2002. Resume from where you left off — dispatch any `todo` status items.
201
202## Example
203
204User: `/orchestrate Add comprehensive error handling to the API layer`
205
206**Planning:**
207```
208Project: orch-api-error-handling (ORCH)
209
210ORCH-1: [todo] Audit current error handling patterns across all handlers
211ORCH-2: [todo] Design error response format and error codes enum
212ORCH-3: [blocked on ORCH-1,ORCH-2] Implement centralized error middleware
213ORCH-4: [blocked on ORCH-3] Update all handler functions to use new error types
214ORCH-5: [blocked on ORCH-4] Add error handling integration tests
215```
216
217**Batch 1 dispatch (parallel):**
218```
219Task("[ORCH-TODO:ORCH-1] Explore the codebase and audit...", subagent_type="Explore")
220Task("[ORCH-TODO:ORCH-2] Design an error response format...", subagent_type="Plan")
221```
222
223**After batch 1 completes:**
224- Hook auto-completes ORCH-1 and ORCH-2
225- Hook unblocks ORCH-3 (both blockers resolved)
226- Claude dispatches ORCH-3
227
228**Continue until ORCH-5 is done.**
229