--- description: Decompose a task into subtasks, execute up to 10 parallel background agents, refill as workers complete. category: general --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] %% Phase 1: Decompose subgraph Decompose["Phase 1: Decompose"] TASK[Receive Task] --> ANALYZE[Analyze Task] ANALYZE --> SPLIT[Split into Subtasks] SPLIT --> QUEUE[Write Todo Queue
all pending] end %% Phase 2: Spawn Workers subgraph Spawn["Phase 2: Spawn Workers"] QUEUE --> READ[Read Pending Items] READ --> CAP{Items <= 10?} CAP -->|Yes| LAUNCH_ALL[Launch All as Agents] CAP -->|No| LAUNCH_10[Launch First 10] LAUNCH_ALL --> MARK[Mark In-Progress] LAUNCH_10 --> MARK end %% Phase 3: Track + Refill subgraph Track["Phase 3: Track + Refill"] MARK --> WAIT[Wait for Agent
Completion] WAIT --> RESULT{Succeeded?} RESULT -->|Yes| COMPLETE[Mark Completed] RESULT -->|No| FAIL[Mark Failed
with Reason] COMPLETE --> PENDING{Pending Items
Remain?} FAIL --> PENDING PENDING -->|Yes| REFILL[Spawn 1 New Agent
for Next Item] REFILL --> MARK PENDING -->|No| ALLDONE{All Workers
Finished?} ALLDONE -->|No| WAIT ALLDONE -->|Yes| SUMMARY[Summarize Results] end click TASK "#" "**Receive Task**\nThe top-level task to be parallelized.\nPassed as `$ARGUMENTS` to the `/divide-and-conquer` command.\n\nExamples:\n- 'Run tests across 8 modules'\n- 'Audit 15 config files'\n- 'Add docs for 12 endpoints'" click ANALYZE "#" "**Analyze Task**\nDetermine how to break the task into independent pieces.\n\nKey question: can each subtask run without depending on another's output?\nIf subtasks have dependencies, they must be sequenced within a single agent -- not split across agents." click SPLIT "#" "**Split into Subtasks**\nDecompose into discrete, independently-executable units.\n\nRules:\n- Each subtask must be self-contained\n- No subtask should depend on another's result\n- Subtasks should be roughly equal in effort\n- Prefer more granular splits (10 small > 3 large)" click QUEUE "#" "**Write Todo Queue**\nUse `TodoWrite` to create a todo list with one item per subtask.\nAll items start as `pending`.\n\nThe todo list is the single source of truth for work state -- all status transitions go through `TodoWrite`." click READ "#" "**Read Pending Items**\nUse `TodoRead` to get the current list of pending items.\nThis is checked both at initial launch and after each refill cycle." click CAP "#" "**Items <= 10?**\nHard cap: never exceed 10 concurrent background agents.\n\nIf 10 or fewer pending items, launch all.\nIf more than 10, launch the first 10 and queue the rest for refill." click LAUNCH_ALL "#" "**Launch All as Agents**\nSpawn one `Agent` per subtask with `run_in_background: true`.\n\nCritical rule: **one item per agent, no batching.**\nEach agent receives exactly one todo item and works only on that." click LAUNCH_10 "#" "**Launch First 10**\nSpawn 10 background agents for the first 10 pending items.\nRemaining items stay in the queue for refill." click MARK "#" "**Mark In-Progress**\nUse `TodoWrite` to update each launched item to `in_progress`.\nDo this *before* handing off to the agent -- the todo list must reflect that work has been claimed." click WAIT "#" "**Wait for Agent Completion**\nBackground agents notify on completion automatically.\nNo polling needed -- the orchestrator is notified when each agent finishes." click RESULT "#" "**Succeeded?**\nCheck the agent's return status.\n\nSuccess: the agent completed its subtask without errors.\nFailure: the agent encountered an error or could not complete." click COMPLETE "#" "**Mark Completed**\nUse `TodoWrite` to update the item to `completed`.\nRecord a brief summary of what the agent accomplished." click FAIL "#" "**Mark Failed**\nUse `TodoWrite` to update the item to `failed`.\nInclude a brief reason so the orchestrator can report it.\n\nFailed items are not retried automatically -- they appear in the final summary for human review." click PENDING "#" "**Pending Items Remain?**\nCheck if any items in the todo list are still `pending`.\nIf yes, there is capacity to refill (one worker just finished)." click REFILL "#" "**Spawn 1 New Agent**\nLaunch exactly one new background agent for the next pending item.\nThis maintains the worker pool without exceeding the cap of 10.\n\nNever assign two items to one agent.\nNever exceed 10 concurrent agents." click ALLDONE "#" "**All Workers Finished?**\nCheck if any items are still `in_progress`.\nIf yes, keep waiting for those agents to complete.\nIf all items are `completed` or `failed`, proceed to summary." click SUMMARY "#" "**Summarize Results**\nReport:\n- Total subtasks\n- Completed count\n- Failed count (with reasons)\n- Notable outputs from each agent\n\nThe orchestrator stops when all todo items have a terminal status (`completed` or `failed`)." classDef decompose fill:#d1ecf1,stroke:#7ec8d8 classDef spawn fill:#dfe6ff,stroke:#5b7bce classDef track fill:#fff3cd,stroke:#f0c040 classDef success fill:#d4edda,stroke:#5cb85c classDef failure fill:#f8d7da,stroke:#e06070 class TASK,ANALYZE,SPLIT,QUEUE decompose class READ,CAP,LAUNCH_ALL,LAUNCH_10,MARK spawn class WAIT,RESULT,PENDING,REFILL,ALLDONE track class COMPLETE,SUMMARY success class FAIL failure end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_