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 ..."
}

Communication Boundaries Rules

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

1. Master Agent can only be triggered by the Orchestrator Agent.
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!