feature: add swarm mode for multi-instance collaboration

[Zhaoyikaiii]

Summary

• Add pkg/swarm/ — a NATS-based multi-instance collaboration system that lets multiple PicoClaw nodes discover each other, distribute tasks by capability, and coordinate work through a coordinator/worker architecture
• Introduce SwarmConfig in pkg/config/ with NATS and optional Temporal settings, plus picoclaw swarm CLI subcommands (start, status, nodes)

Architecture

Coordinator ──NATS──> Worker A (capability: code)
     │                Worker B (capability: research)
     │                Specialist C (capability: ml)
     └── Discovery (heartbeat, node registry, load-based selection)

What's in the box

Component	File	What it does
Types	types.go	NodeInfo, SwarmTask, TaskResult, Heartbeat, etc.
NATS Bridge	nats.go	Pub/sub, queue groups, discovery queries
Embedded NATS	embedded.go	In-process NATS server for dev/testing
Discovery	discovery.go	Heartbeat loop, stale node cleanup, capability-based worker selection
Coordinator	coordinator.go	Task routing (direct/broadcast/workflow), local fallback
Worker	worker.go	Concurrent task execution, progress reporting, load tracking
Temporal	temporal.go	Optional workflow engine (graceful degradation if unavailable)
Workflows	workflows.go	Decompose → parallel execute → synthesize pipeline
Manager	manager.go	Top-level orchestrator, startup/shutdown sequencing

Covers: type serialization, embedded NATS lifecycle, pub/sub mechanics, discovery registry, coordinator dispatch (direct + local fallback + timeout), worker execution, and full coordinator↔worker integration round-trips.

[cosmic-gao]

I want multiple picoclaw nodes to coordinate their work, divided into:

1. Task planning node (https://www.vibekanban.com/vibe-guide#solve-dev-servers)

2. Opencode coding node

3. Requirements design node

4. Review and analysis node
   The task planning for all nodes will be displayed on vibekanban.

[Zhaoyikaiii]

I want multiple picoclaw nodes to coordinate their work, divided into:

1. Task planning node (https://www.vibekanban.com/vibe-guide#solve-dev-servers)
2. Opencode coding node
3. Requirements design node
4. Review and analysis node
   The task planning for all nodes will be displayed on vibekanban.

We are adhering to a minimalist implementation to ensure the swarm remains lightweight. The goal is to prove the coordination mechanism works—specifically via NATS—while leaving advanced features like dynamic load balancing or LLM-driven decomposition for subsequent iterations.

[Leeaandrob]

Why no libp2p to do that? I was implementing it using libp2p. What do you guys think?

[Leeaandrob]

@Zepan This PR addresses roadmap issue #284 (Swarm Mode — priority: medium, status: Todo). At +5473 lines, it's the largest open PR.

Important consideration: The roadmap defines a clear dependency chain: #294 (Base Multi-agent Framework) should land first, then #295 (Model Routing), and finally #284 (Swarm Mode). Swarm Mode builds on top of the multi-agent foundation.

PR #131 currently addresses #294 (base multi-agent framework). It would be cleaner to merge #131 first, then evolve this PR to build on that foundation rather than implementing everything from scratch.

Recommendation: Defer until #294 (multi-agent base) is merged. The scope (+5473 lines) is very large and would benefit from being built on top of the base framework rather than as a standalone implementation.

[Zhaoyikaiii]

Just a heads-up: this branch/PR will be closed because we’re currently refactoring the channel system, and the swarm-mode work is being moved to the refactor/channel-system branch instead. To keep things maintainable, we’re also keeping the existing swarm implementation lightweight until the refactor lands.

For the active work, please follow:

#709