name: Swarm Orchestration

description: Pattern for 1-to-many control of agent instances using tmux and session resumption.

1-to-Many Agent Swarm Orchestration Skill

Overview

This skill defines a pattern for an orchestrator agent to spawn, track, and control multiple sub-agent instances (a "swarm") using tmux for environment isolation and command-line interfaces supporting session resumption.

Prerequisites

• tmux installed on the host system.
• An interactive CLI or agent tool that supports:
  • Running in a terminal.
  • Exposing a unique Session/Conversation ID.
  • Resuming sessions via targeting flags (e.g., -conversation="<ID>").

Procedure

1. Initialize Swarm Environment

Create a tmux session with multiple windows or panes, depending on the desired layout.

Windows Layout (Clean separation & Isolation):

tmux new-session -d -s <session_name> -n agent_1 -c /path/to/isolated/dir1
tmux new-window -t <session_name> -n agent_2 -c /path/to/isolated/dir2
...

Using -c with tmux new-window allows isolating the working directory of each agent.

2. Spawn Agents

Send execution commands to the specific windows.

tmux send-keys -t <session_name>:<window_name> "/path/to/cli --args" C-m

3. Record State

Store the mapping of Window -> Session ID if session resumption is needed.

File-Based Orchestration Framework

To automate communication, use a file-based message bus.

Directory Convention

Create a directory swarm_framework/ in the project root:

• comms/requests/: For dropping request files.
• comms/responses/: For reading results.
• orchestrator.py: The polling script.
• bootstrap.sh: The setup script.
• agents/: Contains isolated directories for each agent.

Payload Formats

Request File (request_<id>.json):

{
  "request_id": "req_123",
  "sender": "master", 
  "target_agent": "orchestrator", 
  "prompt": "Your instruction here",
  "response_file": "swarm_framework/comms/responses/res_123.json"
}

Response File (res_123.json):

{
  "request_id": "req_123",
  "status": "success",
  "output": "... captured terminal output ..."
}

Notifications

For status updates and alerts not tied to a specific request-response cycle:

Master Notifications (comms/master_notifications.json):

• Used by Orchestrator to notify Master Agent about hanging sub-agents or prompts requiring attention.
• File contains a JSON list of notification objects:

  [
  {
    "timestamp": 1234567890.123,
    "type": "hanging|prompt",
    "agent": "grid.x",
    "message": "..."
  }
  ]

• Master Agent should periodically check this file to avoid active interruptions to user input.

Sub-agent Approval Alerts:

• If a sub-agent is blocked waiting for approval (e.g., "yes/no"), the Orchestrator script detects this via regex and sends a notification message directly to the Orchestrator Agent pane (grid.0).

Payload Content Rules

• Markers: All agents MUST wrap their final answer in ===RESULT=== and ===END_RESULT=== markers to allow the system to extract the raw result and remove UI garbage.

Decentralized Cross-Agent Communication

To support decentralized and scalable communication, agents use dedicated directories within their isolated folder in agents/:

• incoming/: For messages from other agents.
• output/: For messages to other agents.
• archive/: For processed incoming messages.

File Naming Convention

Files in output/ must follow the pattern: to_{target}_{msg_id}.json.

• target: The target agent name (e.g., agent_2, orchestrator).
• msg_id: A unique identifier for the message.

Processing Flow

1. Source Agent writes message to its output/ directory as a .tmp file and renames it to .json when complete.
2. Orchestrator Watcher Thread detects the .json file, extracts the target, and moves the file to the target agent's incoming/ directory, renaming it to from_{source}_{msg_id}.json.
3. Target Agent Watcher Thread detects the file in incoming/, moves it to archive/, and notifies the agent via tmux send-keys to read the file.

Mapping

The orchestrator maps tmux window/pane names (e.g., grid.1) to directory names (e.g., agent_1) using a mapping function to ensure correct file routing.

Communication Boundaries Rules

To maintain clear boundaries and prevent Master Agent overload, the following rules are enforced by orchestrator.py:

1. Master Agent cannot be triggered via file request. Results or prompts meant for Master must be saved to comms/master_notifications.json.
2. Sub-agents can trigger Sub-agents and Orchestrator Agent.
3. Master Agent can trigger Orchestrator Agent ONLY.

Ensure all request files populate the "sender" field!