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.
4. Do not print blocking prompts or clarification requests to the console. All agents (except Master when interacting with user) MUST raise prompts in their output/ folder or log to master_notifications.json to inform upstream. Console output is not visible to users.

Ensure all request files populate the "sender" field!