Recursive Swarm

---

name: recursive-swarm description: "Bounded recursive orchestration for complex tasks that are too large for one agent turn but cleanly decompose into a few independent subproblems. Use for multi-angle research, audits, mixed research+synthesis, or coding projects that benefit from explicit planning, task-tree state, artifact folders, and controlled parallel execution. Keep recursion tight: default max depth 2, hard cap 3, preferred fan-out 2-4, and modest concurrency. Use git worktrees only for coding leaves inside git repos. Do not use for simple one-shot tasks, destructive workflows, or open-ended exploration."

---

Recursive Swarm

Use this skill to turn one large task into a small, bounded task tree with explicit node state, artifacts, merge points, and audit events.

Use this workflow

Use recursive-swarm only when all of these are true:

1. The task is too large or messy for one agent turn. 2. The task has at least 2 meaningful subproblems. 3. The outputs can be merged back into one answer, report, or code result.

Do not recurse for simple reads, one-shot edits, destructive workflows, or open-ended exploration with no clear output contract.

Defaults

Default max depth: 2

Hard cap: 3

Preferred fan-out per node: 2-4 children

Hard cap per node: 5 children

Default concurrency: 2-3 active leaves

Hard cap concurrency: 5

Default max nodes per run: 9

Hard cap nodes per run: 15

Default workspace mode: artifact folders, not git worktrees

Append-only audit log: events.jsonl

Use git worktrees only for coding leaves inside a git repo when sibling edits benefit from isolation

Node types

Assign each node one primary type:

research — extraction, investigation, analysis

coding — implementation, refactor, test work

ops — shell, system, or environment workflows

browser — web/UI automation

synthesis — combine child outputs into one merged result

review — challenge weak claims, reconcile conflicts, prune bad findings

Execution routing

Route nodes like this:

research, synthesis, review → subagents

coding → ACP sessions by default; use worktrees only when useful

ops, browser → direct tools or a narrowly scoped subagent if needed

destructive, external, or approval-sensitive nodes → pause and ask before execution

Quiet child execution (default)

For routine child runs, prefer silent child completion + parent-owned final delivery.

That means:

child sessions do the work

child results are harvested from session history and/or artifact files

routine child announce steps should reply exactly ANNOUNCE_SKIP

the parent/orchestrator sends the one final merged answer to the user

Only allow a child announce message to reach the user when:

the child is blocked

the child needs approval to continue

the child hit a major error the parent must surface immediately

the child itself is the intended final user-facing delivery step

Do not let every child produce routine completion chatter in the user channel.

Atomic vs composite rule

Treat a node as atomic when one agent run can finish it without meaningful internal planning.

Examples of atomic nodes:

extract top travel dates from the indexed threads

summarize one PDF

implement one endpoint

validate one config file

Treat a node as composite when it clearly breaks into independent workstreams.

Examples of composite nodes:

reconstruct a work year from exported messages

build a feature spanning backend, frontend, and tests

audit a system and produce remediation steps

If a child split feels artificial or the merge plan is vague, stop decomposing.

Workflow

1) Initialize the run

Create a run folder with scripts/init_run.py.

Recommended output layout:

runs//
  tree.json
  events.jsonl
  summary.md
  nodes/
    1/
      spec.json
      notes.md
      result.md

2) Create the root node

Use scripts/upsert_node.py to record the root task and defaults.

Record at minimum:

id

parentId

goal

type

depth

executor

status

workspaceMode

approvalRequired

3) Decompose only when worth it

For each composite node:

split into 2-5 children

assign node type and executor

keep child goals concrete

define how the parent will merge the results

stop at depth 2 unless there is a strong reason to go to 3

Never recurse just to make the tree look smart.

4) Persist state and audit events

Before executing a node:

mark it running

create or update nodes//spec.json

note the intended output in nodes//notes.md

append an event to events.jsonl

After executing a node:

save the result in nodes//result.md

mark it completed, failed, or waiting_for_approval

record artifacts and confidence

append an event to events.jsonl

Use these scripts:

scripts/upsert_node.py

scripts/mark_node.py

scripts/list_ready_nodes.py

scripts/list_events.py

scripts/merge_results.py

scripts/render_tree.py

5) Execute leaves

Use scripts/list_ready_nodes.py to identify executable leaves.

Execution guidance:

prefer subagents for analysis/synthesis leaves

prefer ACP for coding leaves

prefer direct tools for small ops/browser leaves

keep concurrency modest; avoid flooding the system with low-value leaves

when spawning routine child runs, instruct them to keep their work in session/artifacts and reply ANNOUNCE_SKIP during the announce step unless they are blocked or explicitly responsible for final delivery

do not clean up or delete child sessions until the parent has harvested the needed results

6) Merge upward

When all child nodes under a parent are complete:

harvest child outputs from child result.md, session history, or other saved artifacts

use scripts/merge_results.py to bundle child file results when applicable

create a parent synthesis or review node if needed

write the merged result to the parent result.md

If a child was run in quiet mode with ANNOUNCE_SKIP, treat that as normal. Silence is not failure; it just means the parent owns user-facing delivery.

Use type-aware merge behavior:

research → combine evidence, themes, and caveats

coding → combine patches, test notes, and integration risks

ops → combine findings, risks, and recommended actions

review → identify weak claims, contradictions, and missing coverage

Do not silently average conflicting child outputs. Bubble disagreements up.

7) Finish with a skeptical pass

For important runs, add one final review node that:

challenges overconfident claims

checks whether decomposition went too far or not far enough

identifies ambiguous results

tightens the final summary

Approval gates

Pause and ask before executing any node that would:

write, edit, move, or delete important files

install or update software

restart services

change config

send external messages

perform destructive system actions

Mark these nodes waiting_for_approval instead of forcing them through.

Worktrees

Do not use git worktrees by default.

Use a worktree only when all of these are true:

the node type is coding

the target is a git repo

sibling coding tasks benefit from isolation

there is a plausible merge path afterward

Otherwise keep the node in normal artifact-folder mode.

Stop conditions

Stop decomposing when any of these is true:

the node is already atomic

the merge plan is unclear

decomposition is becoming repetitive

depth 2 already produced workable leaves

time/cost budget would be wasted by further splitting

adding another node would exceed the run budget

References

Read these only if needed:

references/tree-schema.json — canonical run and node schema

references/example-run.md — example run layout and sample tree

references/quiet-mode.md — quiet child execution pattern using ANNOUNCE_SKIP