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/<run-id>/
  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/<id>/spec.json - note the intended output in nodes/<id>/notes.md - append an event to events.jsonl

After executing a node: - save the result in nodes/<id>/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