The Unified Swarm
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Unified Swarm (US) is a decentralized, collaborative network of specialized AI agents designed to solve complex, heterogeneous tasks within the IDAHO-VAULT project. Unlike monolithic systems, the Swarm utilizes self-organization, structured coordination, and shared state to achieve scalability and robustness. It operates as a "silicon workforce" that plans, acts, and adapts under the ultimate authority of a human principal, Logan Finney.
The Swarm's purpose is to establish a deterministic coordination layer that allows multiple agents—including Claude, Gemini, and specialized runners like CrewAI—to collaborate without duplicating effort or drifting permissions. It functions as a higher-order layer that coordinates and governs various AI ecosystems (Factory, CrewAI, OpenAI Swarm) as composable subsystems within the project's Architecture & Infrastructure (A&I).
Sources: 2026-05-19_hermes_agent-swarming.md:12-21, HANDOFF-Swarm-Coordination-2026-03-29.md:83-88, BIG IFS — UNIFIED SWARM.md:103-107
Swarm Architecture and Coordination
The Unified Swarm is structured as a hierarchical system with the Human Principal at the top, followed by a coordination layer and specialized agent pools.
Core Components
- Principal (Logan Finney): The final arbiter and ultimate decision-making authority.
- Coordination Layer: Utilizes the Model Context Protocol (MCP) and dedicated agents (like the Linear Workspace Manager) to track status and synchronize state.
- Artifact Layer (Vault): The canonical repository and primary source of truth for durable artifacts, documentation, and code.
- Agent Pool: Specialized agents with persistent identities and roles (e.g., Researcher, Coder, Analyst).
Sources: HANDOFF-Swarm-Coordination-2026-03-29.md:83-93, LEVELSET 1.md:65-71, 2026-05-19_hermes_agent-swarming.md:241-260
Coordination Flow
The following diagram illustrates the relationship between the human principal, the execution layers, and the canonical storage.
The hierarchy ensures that while agents execute tasks, all durable changes flow through a human-gated review process and are anchored in the Vault.
Sources: HANDOFF-Swarm-Coordination-2026-03-29.md:83-93, CONSTITUTION.md:65-75
Interaction Mechanisms
The Swarm employs three primary coordination methods to manage inter-agent communication and task execution:
1. Stigmergy (Indirect Communication)
Agents coordinate by modifying the shared environment (the Vault) rather than direct messaging. This is implemented via the Stigmergic Blackboard Protocol (SBP), where agents leave "digital pheromones" or signals in shared spaces like !/CREWAI/ or the SWARM/deadletters/ directory.
Sources: 2026-05-19_hermes_agent-swarming.md:92-108, coordination.md:23-28
2. Direct Communication
Explicit information sharing through message passing. The project uses the Agent Communication Protocol (ACP) for precise coordination and peer-to-peer task delegation.
Sources: 2026-05-19_hermes_agent-swarming.md:110-120
3. Shared State and Deadletters
The system utilizes a "Deadletter" routing mechanism for orphaned handoffs. If a sender node has no clear recipient, the handoff is documented in /SWARM/deadletters/ for principal triage.
Sources: coordination.md:23-35, LEVELSET 1.md:38-40
| Mechanism | Implementation | Best Use Case |
|---|---|---|
| SBP | Shared Blackboard | Non-linear workflows, dynamic task pickup |
| ACP | Direct Messaging | Precise task handoffs, immediate coordination |
| MCP | Coordination Layer | State sync, locking, structured routing |
Sources: 2026-05-19_hermes_agent-swarming.md:144-180, HANDOFF-Swarm-Coordination-2026-03-29.md:90-93
Operational Governance and Principles
Swarm behavior is strictly governed by the Vault Constitution and specific operational constraints to prevent "agentic drift" and maintain security.
Core Constraints
- Vault = Authority: Agents do not name themselves; Logan names agents.
- Human Gate: No agent merges or governance changes (CONSTITUTION, PROTOCOL) without Logan's explicit approval.
- No Vault Writes for Managers: Coordination agents (like the Linear agent) provide support and curation but have no direct vault write access.
- Identity Decoupling: Agents must not assume their software name (e.g., Claude) is synonymous with their functional office (e.g., Code Authority).
Sources: HANDOFF-Swarm-Coordination-2026-03-29.md:55-65, CONSTITUTION.md:51-60, coordination.md:14-16
Conflict Resolution Protocol
When nodes receive conflicting instructions, the following sequence is mandatory:
Sources: coordination.md:37-43
Implementation Layers: The TRIUNE Mapping
For specialized execution like CrewAI, the Swarm implements a TRIUNE Covenant mapping to ensure alignment with existing project infrastructure.
- Logan (Directs): Provides Human-in-the-Loop kickoff inputs.
- Agents (Execute): Organized into "Crews" with specific tasks and tools.
- Vault (Witnesses): Acts as the permanent record for all outputs.
JFAC Crew Example
A practical implementation for legislative analysis utilizes roles mapped to the "5Ws":
- Budget Scout: Identifies Who and What (agencies, sponsors, appropriations).
- Legislative Tracker: Identifies When and Where (timeline, chamber routing).
- H911 Parser: Identifies Why (policy intent).
Sources: !-GRIMOIRE_caution_contains-false-doctrines-NETWEB-CREWAI-ALIGNMENT.md:55-106
Summary
The Unified Swarm represents a transition from ephemeral AI chats to a persistent, governed silicon workforce. By anchoring coordination in Linear and GitHub, and doctrine in the Vault, the system ensures that multi-agent collaboration remains deterministic, auditable, and strictly under human authority. This architecture mitigates common swarm failure modes such as duplicate work and state corruption through disciplined coordination and explicit handoff protocols.
Sources: HANDOFF-Swarm-Coordination-2026-03-29.md:83-88, AGENTIC SWARM SYSTEMS — CAPABILITIES, LIMITS, AND TRADEOFFS.md:179-190