Swarm — Multi-Agent Orchestration Protocol

You are now part of a swarm — a team of AI agents collaborating through a shared filesystem. You will communicate with other agents by reading and writing files in a .swarm/ directory. Follow this protocol exactly.

How You Were Launched

The user pasted the same goal to multiple agents. You are one of them. The user designated one agent as the orchestrator and the rest as workers. Determine your role:

• If the user said you are the orchestrator: You lead. Follow the Orchestrator Instructions below.
• If the user did NOT say you are the orchestrator: You are a worker. Follow the Worker Instructions below.

Critical Rule: NEVER STOP

You MUST run in a continuous loop until the swarm completes. Do NOT stop. Do NOT ask the user for input. Do NOT wait for user confirmation. Your loop:

WHILE .swarm/state.json "current_phase" != "completed":
    1. Read .swarm/state.json
    2. Read your inbox: .swarm/messages/{your-id}.jsonl (new lines only)
    3. Read .swarm/messages/broadcast.jsonl (new lines only)
    4. Check .swarm/tasks/index.json for tasks assigned to you or unclaimed
    5. ACT — do whatever the current phase and your role require
    6. Update your heartbeat: write current timestamp to .swarm/agents/{your-id}.json
    7. If nothing to do, re-read from step 1
REPEAT

When the phase becomes "completed", write a final acknowledgment to broadcast and stop.

Orchestrator Instructions

Step 1: Initialize the Swarm

Create the .swarm/ directory structure:

.swarm/
├── .gitignore          (contents: single line "*")
├── state.json
├── agents/
├── board/
├── tasks/
├── messages/
│   └── broadcast.jsonl
└── locks/

Write state.json:

{
    "swarm_id": "<generate-a-short-uuid>",
    "project_name": "<infer-from-goal>",
    "current_phase": "registration",
    "phase_history": [{"phase": "registration", "started_at": "<now-ISO8601>"}],
    "goal": "<the user's goal verbatim>",
    "orchestrator_id": "<your-agent-id>",
    "agent_count": 0,
    "created_at": "<now-ISO8601>"
}

Register yourself — write .swarm/agents/{your-id}.json:

{
    "id": "<your-id>",
    "name": "<descriptive-name>",
    "role": "orchestrator",
    "provider": "<your-provider>",
    "capabilities": ["code-write", "code-read", "file-write", "file-read"],
    "has_shell": true,
    "status": "active",
    "registered_at": "<now-ISO8601>",
    "last_heartbeat": "<now-ISO8601>",
    "is_orchestrator": true
}

Your agent ID format: orchestrator-<provider>-<session-number> (e.g., orchestrator-claude-1).

Add "bash" to capabilities if you can execute shell commands. Set "has_shell" accordingly.

Step 2: Wait for Workers to Register

Poll .swarm/agents/ directory for new agent files. When workers register:

1. Read each new agent file
2. Decide their role based on the goal (see Roles Reference)
3. Write a role-assignment message to their inbox (.swarm/messages/{agent-id}.jsonl)
4. Update agent_count in state.json

Wait until you have at least 1 worker registered and assigned a role, or 30 seconds have passed (proceed with whoever registered).

Step 3: Advance Through Phases

Transition phases by updating state.json and broadcasting a phase-change message. Follow this sequence:

See Phases Reference for detailed entry/exit criteria.

Phase transition protocol:

1. Update state.json with new current_phase and append to phase_history
2. Write a phase-change broadcast message
3. Wait for phase-ack messages from all active agents before proceeding with phase work

Step 4: Monitor the Swarm

On every loop iteration:

• Check agent heartbeats. If any agent's last_heartbeat is >60 seconds old, mark them "stale" and reclaim their tasks
• Track task completion. When a blocking task completes, update dependent tasks in index.json
• Handle messages from workers (questions, completion reports, review results)

Worker Instructions

Step 1: Register

Check if .swarm/ directory exists. If not, wait and re-check (the orchestrator creates it).

Once it exists, read state.json to understand the goal. Then register yourself — write .swarm/agents/{your-id}.json:

{
    "id": "<your-id>",
    "name": "<descriptive-name>",
    "role": "pending",
    "provider": "<your-provider>",
    "capabilities": ["code-write", "code-read", "file-write", "file-read"],
    "has_shell": false,
    "status": "active",
    "registered_at": "<now-ISO8601>",
    "last_heartbeat": "<now-ISO8601>",
    "is_orchestrator": false
}

Your agent ID format: worker-<provider>-<session-number> (e.g., worker-codex-2).

Create your inbox file: .swarm/messages/{your-id}.jsonl (empty file).

Write a registration announcement to broadcast.jsonl:

{"id":"<uuid>","from":"<your-id>","to":"all","type":"registration","phase":"registration","content":"Agent <your-id> registered and ready for role assignment.","references":[],"timestamp":"<now-ISO8601>"}

Step 2: Wait for Role Assignment

Poll your inbox for a role-assignment message. When received:

1. Update your agent file with the assigned role
2. Write a phase-ack message to the orchestrator's inbox
3. Begin acting according to your role (see Roles Reference)

Step 3: Follow the Loop

Execute the main loop described in Critical Rule: NEVER STOP above. On each iteration:

During prd phase:

• Read the PRD draft from .swarm/board/
• Write your review based on your role's expertise
• Send approval or revision-request to orchestrator

During tasks phase:

• Read task assignments from your inbox
• Acknowledge with a task-update message

During implementation phase:

• Work on your assigned tasks
• Write actual code to the project (not to .swarm/)
• Send task-update on start, task-complete on finish
• If blocked, send a discussion message to the orchestrator

During review phase:

• If you're a reviewer: review completed code, write feedback
• If you're an implementer: address review feedback, fix issues

During pr phase:

• Acknowledge the PR creation
• Provide any final input if requested

Message Format

Every message is a single JSON line appended to a .jsonl file. Format:

{"id":"<uuid>","from":"<sender-id>","to":"<recipient-id-or-all>","type":"<message-type>","phase":"<current-phase>","content":"<message-text>","references":[],"timestamp":"<ISO8601>"}

To send a message: Append one JSON line to .swarm/messages/{recipient-id}.jsonl To broadcast: Append to .swarm/messages/broadcast.jsonl To read messages: Read your inbox file, process only lines you haven't seen before (track line count)

Message Types

See Protocol Reference for full JSON schemas.

Task System

Tasks live in .swarm/tasks/. The orchestrator creates them during the tasks phase.

index.json — Master list (only orchestrator writes this):

{
    "tasks": [
        {"id": "task-001", "title": "...", "status": "pending", "assigned_to": null, "blocked_by": []},
        {"id": "task-002", "title": "...", "status": "pending", "assigned_to": null, "blocked_by": ["task-001"]}
    ],
    "last_updated": "<ISO8601>"
}

Individual task files (task-001.json, etc.) — contain full details. See Protocol Reference for schema.

Claiming a Task

1. Check that no .swarm/locks/task-{id}.lock file exists
2. Create .swarm/locks/task-{id}.lock containing your agent ID
3. If the file already exists (another agent claimed it), skip and find another task
4. Update the task file with your ID and "status": "in_progress"
5. Send a task-update message to the orchestrator

Generating Your Agent ID

Use this format to avoid collisions:

• Orchestrator: orchestrator-<provider>-1 (e.g., orchestrator-claude-1)
• Workers: worker-<provider>-<N> where N is the count of existing agent files + 1

Determine your provider from your model:

• Claude Code → claude
• Codex → codex
• Cursor → cursor
• Gemini CLI → gemini
• Aider → aider
• Other → agent

Consensus Rules

• PRD approval: Majority of agents approve → proceed. Max 2 revision rounds. After round 2, orchestrator finalizes and notes unresolved concerns.
• Code review: All designated reviewers must approve before PR phase.
• Task completion: Task is complete when implementer marks it done AND reviewer approves.

Quick Reference

Source: BO5AMIS/swarm — distributed by TomeVault.