File-Transport Coordination, Staggered Launches, and Cloud Task Truth for Multi-Agent Swarms

Abstract

We document a multi-agent coordination pattern used alongside VibeSwarm and BridgeSpace: a file-backed harness (board markdown, per-agent inbox JSON, optional nudges and status files) augmented by a cloud task system (BridgeMind) as source of truth for priorities. We include the staggered agent startup schedule used to reduce vendor rate limits, environment variables required for mail routing, and parity notes between the headless harness and the Tauri desktop UI. The goal is reproducible operations design rather than a novel algorithm.

Introduction

When many LLM agents run in parallel, the failure mode is rarely “the model was wrong.” More often, two agents edit the same file, double-deploy, or hammer an API until the vendor throttles everyone. The WebMCP / VibeSwarm ecosystem mitigates this with two coordination layers: durable files on disk for fast local handoffs, and BridgeMind (or equivalent) for authoritative task state across sessions.

File-transport artifacts

The swarm harness defines concrete artifacts: a coordination board (SWARM_BOARD.md), inbound mail directories per agent label, optional nudges, JSON status files, and a roster (agents.json). The desktop product is described as a UI layer on top of the same file transport — the Tauri app watches the same folders the headless harness uses.

Why files: they are inspectable with ordinary tools, work when cloud APIs are down, and provide an audit trail for humans and automation. Agents with only shell access can still participate.

Mail routing identity

Before agents consume mail or emit notifications, the harness expects SWARM_AGENT_NAME (or equivalent) to identify the caller. Prompts in the architecture doc show launch patterns where that variable is set before invoking Claude Code or similar CLIs. This prevents mis-routed messages when multiple agents share one machine.

Staggered startup

A documented operator pattern launches roles on a delay — coordinator first, then scouts, builders, and reviewers several minutes apart — specifically to avoid synchronized bursts against GitHub, Vercel, BridgeMind, and other HTTP APIs. This is operations engineering, not model behavior.

Cloud versus local authority

The architecture text distinguishes what must happen next (often cloud task boards) from who is touching which file (local board locks). Agents are instructed to treat chat and ad-hoc markdown as non-authoritative relative to the task system when instructions conflict.

Parity gaps

The documentation lists explicit parity gaps between harness and product (for example, features still converging). Publishing those gaps matters so external readers do not assume UI features exist in the CLI or vice versa.

Conclusion

File transport plus cloud task truth is a pragmatic hybrid: files for speed and transparency, cloud state for global ordering. Teams adopting similar stacks should copy the identity and rate-limit practices, not just the folder layout.

References

Swarm architecture (env vars, staggered launch, parity table): vibeswarm/docs/specs/agent-prompts/swarm-architecture.md
VibeSwarm CLI checklist (swarm root resolution, mail): vibeswarm/docs/specs/vibeswarm-cli-capabilities-checklist.md