🐝 Swarm Systems Guide

1. Three systems at a glance

2. System 1 — /swarm (general multi-engine)

Code: tools/swarm/ — swarm_run.py (fan-out), worker_runner.py (single-engine worker), swarm_followup.py (multi-turn chain), api_consult.py (HTTP API caller), safety.py (read-only allowlist).

Slash commands

Engines

API: deepseek, xai, cerebras, inception, openrouter, groq, gemini_api, pollinations (keyless), nous, ollama_*. CLI: claude, gemini, kilo, opencode, copilot, agent (Cursor). Presets: consensus-3, fast-cheap, deep-strict, non-opus-4.

Fan-out YAML template

name: my_run_${TS}
prompt_file: swarm_runs/briefing_my_task.md
out_dir: swarm_runs/run_${TS}
max_parallel: 4
preset: consensus-3        # OR an explicit engines: list
red_team: true             # adds a claude-opus red-team pass
cost_cap_usd: 5.0

Multi-turn followup — prompts per round

1. priming — feed a briefing file as warm-up context.
2. analysis — "narrow to the problem, cite specific numbers."
3. critique — "which claim is weakest, what unstated assumption, what would you retract."
4. final — "emit valid JSON only, per this schema."

3. System 2 — /swarm-ruflo (Hermes orchestrator)

Code: .ruflo/orchestrator.py, wizard.py, agents/*.yaml.

/swarm-ruflo [audit|github|strategy|bugs|wizard] [--tier free|paid|hybrid]

Tiers: free (OpenRouter free models via Hermes in WSL), paid (direct API), hybrid. New agents: copy .ruflo/agents/TEMPLATE_agent.yaml, fill role/model/goal/metadata.dataSources. Ruflo agents never write code — JSON findings only.

4. System 3 — /swarmv2-* (enhanced typed swarm) — NEW

Code: tools/swarm_v2/swarms/. Install: cd tools/swarm_v2 && pip install -e ".[dev]". CLI: python -m swarms.cli.main <command>.

4.0 What changed today — and what did NOT

4.1 The six swarm types

Memory: outputs are stored in a ChromaDB vector store with hybrid BM25 + vector search. swarm memory search "<query>" finds prior results; swarm memory export-skill turns a result into a reusable Claude skill.

5. Quick-start

/swarm second-opinion "Should we size up COMMODITY given PF 2.49 / n=322?"

cd tools/swarm_v2
python -m swarms.cli.main coding task.md --agents 3 --strict

/swarm-ruflo audit --tier hybrid

6. Sample end-to-end flow — code todos with the coding swarm

1. Write the task file tools/swarm_v2/task.md — a task or short spec, stating what to implement and what the tests must cover.
2. Run python -m swarms.cli.main coding task.md --agents 3 --strict.
3. Pipeline: decompose → 3 generators write code+tests in parallel (each may use a different provider) → test_writer enriches tests + re-runs pytest → 2 reviewers score each artifact → generator revises on flagged issues (≤3 rounds) → artifacts with failing tests dropped.
4. Collect surviving artifacts (source + tests + review comments + results).
5. Apply the winning diff yourself or via a cavecrew-builder subagent — the swarm does not auto-commit.

7. Bulk-reviewing many files (e.g. 50 files)

8. Use case per swarm type

One concrete, project-specific scenario for every swarm type.

swarm_v2 (/swarmv2-*)

/swarm (System 1)

/swarm-ruflo (System 2)

9. Recommended usage in this project

• Stock/crypto prediction — /swarm run with asset-class specialist personas, or /swarm-ruflo audit. /swarmv2-ensemble does weighted signal voting; /swarmv2-hierarchical mirrors macro→tactician→risk-veto. These produce signals/analysis — they do not place trades.
• Coding a backlog faster — /swarmv2-coding: multiple agents attempt each task, tests are mandatory, reviewers gate quality. Divergent attempts surface edge-cases a single pass misses, and the revise loop is enforced rather than optional.
• PR triage — /swarm pr-review. CI health — /swarmv2-actions or /swarm-ruflo github.

Full markdown reference: docs/SWARM_SYSTEMS_GUIDE.md. Per-system docs: tools/swarm/README.md, .ruflo/agents/TEMPLATE_agent.yaml, tools/swarm_v2/README.md.