Smart Swarm

Smart Swarm — Intelligent Multi-Agent Orchestration

Automatically detects when a task is complex enough for multi-agent execution, selects the right agents, coordinates parallel work, and synthesizes results.

Task Complexity Scoring

Score each dimension 0-3, then sum for routing:

| Dimension | 0 | 1 | 2 | 3 | |-----------|---|---|---|---| | File Scope | 1-2 files | 3-5 files | 6-15 files | 16+ files | | Concern Count | 1 concern | 2 concerns | 3-4 concerns | 5+ concerns | | Risk Level | Low (cosmetic) | Medium (logic) | High (data/auth) | Critical (security/infra) | | Isolation | Fully dependent | Mostly dependent | Mostly independent | Fully independent | | Time Pressure | None | Implied | Explicit ("fast") | Blocking other work |

Total Score → Routing:

• 0-4 → SOLO: Just do it. No agents needed.
• 5-7 → DUO: 2 agents working in parallel (e.g., implementation + tests)
• 8-11 → TEAM: 3-4 agents with a lightweight coordinator
• 12-15 → SWARM: Full swarm with wave execution via /flow:go --swarm

Agent Selection Matrix

Based on the task fingerprint (what concerns are involved), select agents:

| Task Fingerprint | Mode | Agents | |---|---|---| | Feature + Tests | DUO | flow-executor(feature) + flow-executor(tests) | | Frontend + Backend | DUO/TEAM | flow-executor(frontend) + flow-executor(backend) + flow-verifier | | Bug + Root Cause | DUO | flow-debugger + flow-repo-analyst | | Research + Implement | TEAM | flow-external-researcher + flow-repo-analyst + flow-executor | | Multi-file Refactor | TEAM | flow-mapper + N×flow-executor + flow-verifier | | Full Feature (deep) | SWARM | flow-planner + 3×flow-executor + flow-verifier + flow-uat | | Code Review | TEAM | Use CE-005 multi-agent review (already built for this) | | Discovery/Research | TEAM | flow-external-researcher + flow-repo-analyst + flow-learnings-researcher + flow-research-synthesizer |

Orchestration Protocol

1. Score & Route

Run the complexity scoring on the task. Announce the score and routing decision:

Complexity: FILE=2, CONCERNS=3, RISK=1, ISOLATION=2, TIME=1 → Total: 9 → TEAM mode

2. Decompose

Break the task into independent subtasks. Write each to a coordination file:

.flow/swarm-{timestamp}/
  task-1.md   # e.g., "Implement API endpoint for /users"
  task-2.md   # e.g., "Create React component for user list"
  task-3.md   # e.g., "Write integration tests for user flow"

Each task file contains:

• Task description (what to do)
• Input files (what to read)
• Output files (what to create/modify)
• Constraints (don't modify files assigned to other agents)
• Success criteria

3. Spawn Agents

Use the Agent tool to spawn each agent. Each agent gets:

• Its task file
• Project CLAUDE.md for context
• Instruction to write results to result-{N}.md

For DUO mode, spawn both agents in a single message (parallel). For TEAM mode, spawn all agents in a single message. For SWARM mode, delegate to /flow:go --swarm (already handles wave dependencies).

4. Collect Results

After agents complete:

• Read all result-{N}.md files
• Check for file conflicts (did two agents modify the same file?)
• If conflicts: present diff to user or use flow-verifier to auto-merge

5. Synthesize

Write synthesis.md summarizing:

• What each agent accomplished
• Any conflicts resolved
• Files created/modified
• Test results
• Remaining work (if any)

6. Clean Up

• Archive swarm directory if fully successful
• Leave it if there's remaining work for the user

Tier Routing Integration

When spawning agents, apply rules/tier-routing.md model selection:

| Swarm Mode | Agent Role | Model Tier | |------------|-----------|------------| | SOLO | Single executor | Tier 2 (haiku) if trivial, Tier 3 (sonnet) otherwise | | DUO | Test writer | Tier 2 (haiku) — pattern-based | | DUO | Implementer | Tier 3 (sonnet) | | TEAM | Coordinator | Tier 4 (opus) — needs reasoning | | TEAM | Executors | Tier 3 (sonnet) | | TEAM | Verifier | Tier 3 (sonnet) | | SWARM | Planner | Tier 4 (opus) | | SWARM | Executors | Tier 3 (sonnet) | | SWARM | Verifier/UAT | Tier 3 (sonnet) |

Consult logs/agent-profiles-summary.json if available — prefer agents with reliability > 0.7. If an agent type consistently underperforms (reliability 50% used (risk of running out)

Integration with Flow

• Smart Swarm is a higher-level orchestrator that uses Flow agents
• For SWARM mode, it delegates entirely to /flow:go --swarm
• For DUO/TEAM mode, it handles coordination directly
• DUO mode: agents work in current branch (low conflict risk)
• TEAM mode: use isolation: "worktree" on the Agent tool when agents modify overlapping files
• SWARM mode: all agents get isolation: "worktree" for full isolation

Examples

Example: DUO (score 6)

Task: "Add a dark mode toggle with tests"
Score: FILES=2, CONCERNS=2, RISK=0, ISOLATION=2, TIME=0 → 6 → DUO
Agents: flow-executor(implement toggle) + flow-executor(write tests)
Result: Both agents work in parallel, results merged

Example: TEAM (score 9)

Task: "Build user authentication with frontend, backend, and database migration"
Score: FILES=2, CONCERNS=3, RISK=2, ISOLATION=2, TIME=0 → 9 → TEAM
Agents: flow-executor(backend+DB) + flow-executor(frontend) + flow-verifier(integration)
Result: 3 agents, coordinator checks no conflicts

Example: SWARM (score 13)

Task: "Refactor the entire payment system across 20 files"
Score: FILES=3, CONCERNS=3, RISK=3, ISOLATION=2, TIME=2 → 13 → SWARM
Action: Delegate to /flow:plan → /flow:go --swarm

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Leo-Atienza
• Source: Leo-Atienza/atlas-claude
• License: MIT

Install and usage instructions live in the source repository linked above.