| name | divide-and-conquer |
| description | <EXTREMELY_IMPORTANT>You MUST use divide-and-conquer when the user wants to break a large job into a parallel, subagent-driven workflow — either decomposing a bare prompt into a reviewable graph (Mode A) or running a skill that ships its own workflow graph plus helper code (Mode B). Use it for wide fan-outs (e.g. "research all of these", "process each of these in its own context") where one long context would degrade.</EXTREMELY_IMPORTANT> |
Divide & Conquer
Announce at start: "I'm using the divide-and-conquer skill to decompose this into a parallel workflow."
Divide & conquer turns a job into a folded task graph of typed nodes and runs it on the generalized amplify engine (${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs), so independent work fans out across isolated subagent contexts and only handles — never payload bytes — cross the orchestrator. The graph is built from four node kinds (see ${CLAUDE_PLUGIN_ROOT}/schemas/node-types.json):
agent — a non-deterministic unit dispatched to a subagent; reads its inputs by reference, writes a typed output to the value store.fn — a deterministic pure module export (a transform or a gather/reduce step).expand — a fan-out combinator: one child per element of an upstream list, each bound to its element by reference, all wired into a gather.switch — a branch combinator over an enumerable selector.
There are two entry modes.
Mode A — Decompose a bare prompt (human-reviewed)
Use Mode A when the user hands you a bare prompt ("research X across these N angles", "do Y for each of these items") and there is no pre-built graph. The flow is decompose → validate → human review/edit → run.
A.1 Decompose with a sub-agent
You MUST spawn ONE decomposition sub-agent (subagent(general-purpose), in the background) whose job is to turn the bare prompt into a DRAFT folded-graph declaration — a JSON object shaped like the Mode B graph below (version, plan_file, variables, nodes), using only the agent/fn/expand/switch kinds, every node carrying an explicit output_schema. Its prompt MUST:
- Carry the user's bare prompt verbatim plus the node-kind contract from
${CLAUDE_PLUGIN_ROOT}/schemas/node-types.json.
- Require a real fan-out where the work is naturally parallel: an
expand over the list of units, one agent child per unit (each researching/processing exactly one unit in its own context), gathered by an fn reducer (require: "all-resolved") so partial results still gather.
- Return ONLY the draft graph JSON (no prose), so you can validate it directly.
You MUST NOT decompose by hand when the prompt is non-trivial; that is the sub-agent's job.
A.2 Validate the draft
You MUST validate the returned draft before showing it:
- Write it to a temporary file.
- Validate it against
${CLAUDE_PLUGIN_ROOT}/schemas/task-graph.schema.json.
- Dry-run
node "${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs" init --graph <tmp.json> — this runs the engine's validateGraph (unknown types, switch exhaustiveness, dangling deps, missing output_schema are all rejected here). If it fails, hand the errors back to the decomposition sub-agent and re-decompose; do not patch the graph silently.
A.3 Surface for human review/edit (plan mode)
The draft is a plan, not a fait accompli. You MUST present the validated draft graph to the human for review and editing in plan mode (e.g. via ExitPlanMode / the plan gate), showing the fan-out width, the per-unit work, and the gather step. You MUST NOT run it until the human approves; the human may edit nodes (prompts, the unit list, the schema) before approving. Re-validate (A.2) after any human edit.
A.4 Run
Once the human approves the (possibly edited) draft, run it through the engine. You MUST hand off to amplify:execute-plan's scheduling loop to drive it — init (capture the GRAPH_ID), then ready / dispatch agent in the background / exec-node for fn / expand / switch, honoring --window for wide fan-outs and the single-writer commit lock. Present the gathered result.
Mode B — Run a skill that ships a graph (no gate)
Use Mode B when a skill ships its own workflow: a JSON folded-graph declaration plus the fn module files it references, all in the skill's own folder. There is no decomposition and no review gate — the graph is authored, so the engine loads, validates, and runs it directly.
A Mode B skill folder ships:
graph.json — the folded-graph declaration (agent/fn/expand/switch nodes, each with an output_schema).- one or more
fn module files, referenced from graph.json by a path relative to the graph file (e.g. "module": "./fns/gather.mjs").
Module resolution. When the engine loads the graph, a node's relative module resolves against the directory of the graph JSON (the skill dir), not the cwd that ran init — init records that directory and exec-node resolves against it. An absolute module is used verbatim. So the skill's modules travel with the skill folder; no absolute paths are baked in.
B.1 Run a Mode B skill
node "${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs" init --graph <skill-dir>/graph.json
You MUST drive the run with amplify:execute-plan's scheduling loop (ready/complete/exec-node/expand/switch, the concurrency --window, the single-writer commit lock); divide-and-conquer authors/loads the graph, execute-plan runs it. Reductions use fn nodes with require: "all-resolved" (typically gatherSuccesses from ${CLAUDE_PLUGIN_ROOT}/scripts/lifecycle.mjs), so the run still gathers the successes when some children fail.
B.2 Reference example
A runnable Mode B example ships at ${CLAUDE_PLUGIN_ROOT}/skills/divide-and-conquer/examples/wide-research/:
graph.json — a wide fan-out: a seed fn emits the subtopic list, a research expand runs one agent per subtopic in its own context, and a gather fn (require: "all-resolved", re-exporting gatherSuccesses) reduces the per-subtopic findings.fns/seed.mjs, fns/gather.mjs — the deterministic helpers, referenced relative to the skill dir.
To run it: node "${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs" init --graph "${CLAUDE_PLUGIN_ROOT}/skills/divide-and-conquer/examples/wide-research/graph.json", then drive with execute-plan. Authoring your own Mode B skill means copying this shape into a new folder.
Principles
MUST:
- Quarantine non-determinism in
agent nodes; keep fn nodes pure, so the graph shape is a pure function of recorded values.
- Pass values by reference — the orchestrator handles only ids/handles; payload bytes never enter its context.
- Make every fan-out gather with an
fn reducer (require: "all-resolved") so partial results still gather and one failure never sinks the run.
- Grow the graph only through
expand/switch; never author the engine-internal raw mutation verbs.
MUST NOT:
- You MUST NOT run a Mode A draft before the human approves it.
- You MUST NOT hand-edit a Mode B skill's graph to work around a validation failure — fix the skill.
- You MUST NOT track the graph in memory; the engine state is the source of truth.
