divide-and-conquer

---
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:

1. Carry the user's bare prompt verbatim plus the node-kind contract from `${CLAUDE_PLUGIN_ROOT}/schemas/node-types.json`.
2. 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.
3. 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:

1. Write it to a temporary file.
2. Validate it against `${CLAUDE_PLUGIN_ROOT}/schemas/task-graph.schema.json`.
3. 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

```bash
# 1. Load + validate + initialize (modules resolve relative to <skill>/graph.json's dir).
node "${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs" init --graph <skill-dir>/graph.json
# -> prints the GRAPH_ID. A validation error here means the shipped graph is invalid; fix the skill, do not patch around it.

# 2. Drive it with the execute-plan scheduling loop, exactly as for any graph:
#    ready --window N -> dispatch agent (background) / exec-node fn / expand / switch -> complete -> repeat
```

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.

• SKILL.md 8 KB
• examples/wide-research/graph.json 1 KB
• examples/wide-research/fns/gather.mjs 1 KB
• examples/wide-research/fns/seed.mjs 1 KB