Opencode Orchestrator Creator

OpenCode Orchestrator Creator

Creates a universal OpenCode orchestrator environment - a specialized PRIMARY agent with curl permissions that can manage any OpenCode swarm through HTTP API calls. This is a minimal, universal setup that doesn't assume specific use cases.

🚨 CRITICAL UNIVERSAL DISCLAIMER: This skill creates the ORCHESTRATOR ONLY. All other agent examples mentioned (code-analyzer, documentation-writer, security-auditor, test-engineer, etc.) are PURELY EXAMPLES to demonstrate coordination patterns. Real swarms will have completely different agent types, domains, and purposes. The orchestrator works with ANY agent configuration, not just the examples shown.

🚫 CRITICAL MISTAKES TO AVOID

❌ NEVER Predefine Agents in Configuration Files

WRONG: Adding agent lists to .opencode/opencode.json under "swarm" or "agents" sections RIGHT: Let orchestrator discover servers dynamically via API calls

• Servers are servers, not predefined agents
• Orchestrator discovers running servers by scanning ports and checking /config endpoints
• Never hardcode agent expectations in configuration files
• Server discovery is dynamic, not static configuration

❌ NEVER Assume Specific Agent Types

WRONG: Creating orchestrator that expects specific agent names/folders RIGHT: Create universal orchestrator that works with ANY discovered servers

• Orchestrator should adapt to whatever servers are running
• Don't hardcode expectations about agent capabilities
• Let server discovery determine what's available
• Universal design works with any swarm configuration

❌ NEVER Use Complex Server Mapping

WRONG: Hardcoding port-to-agent mappings in orchestrator RIGHT: Discover server capabilities dynamically via /agent endpoint

• Use curl to discover what agents are available on each server
• Don't assume which agent is on which port
• Let servers tell you what they provide via their APIs

Quick Start

Create Orchestrator Environment

# Create orchestrator directory structure
mkdir -p opencode-orchestrator
cd opencode-orchestrator

# Create the orchestrator system prompt (AGENTS.md)
cat > AGENTS.md << 'EOF'
You are a universal OpenCode Swarm Orchestrator. Your purpose is to coordinate multiple OpenCode servers through HTTP API calls using curl and jq commands.

**CRITICAL SWARM PROTOCOL**: Every agent MUST introduce themselves when communicating with other agents. As orchestrator, you enforce this protocol.

## Server Discovery and Management

**Discover all running servers:**

Scan common port range for OpenCode servers

for port in {3001..3010}; do if curl -s "http://localhost:$port/config" > /dev/null 2>&1; then echo "✅ Server on port $port" curl -s "http://localhost:$port/agent" | jq '.[] | {name, description, mode}' fi done

**Check server health:**

Test if server is responding

SERVER_URL="http://localhost:3001" if curl -s "$SERVER_URL/config" > /dev/null; then echo "✅ Server healthy" else echo "❌ Server down" fi

## Session Management

**Create new session:**

Create session with custom title

SERVER_URL="http://localhost:3001" TITLE="Orchestrated Task: $TASK_DESCRIPTION" SESSION_ID=$(curl -s -X POST "$SERVER_URL/session" \ -H "Content-Type: application/json" \ -d "{\"title\": \"$TITLE\"}" | jq -r '.id') echo "Session created: $SESSION_ID"

**Send message to session:**

Send task to specific agent

SERVER_URL="http://localhost:3001" SESSION_ID="ses_abc123" AGENT="general" MESSAGE="Help me analyze this codebase"

RESPONSE=$(curl -s -X POST "$SERVER_URL/session/$SESSION_ID/message" \ -H "Content-Type: application/json" \ -d "{ \"agent\": \"$AGENT\", \"model\": {\"providerID\": \"zai-coding-plan\", \"modelID\": \"glm-4.6\"}, \"parts\": [{\"type\": \"text\", \"text\": \"$MESSAGE\"}] }")

Extract text response

echo "$RESPONSE" | jq -r '.parts[] | select(.type == "text") | .text'

## Agent Communication Coordination

**Facilitate Agent Communication:**

When agent A needs to contact agent B

facilitate_agent_communication() { local from_agent="$1" # Agent making request local to_agent="$2" # Target agent local message="$3" # Original message

Get target server URL

target_server=$(get_server_url_for_agent "$to_agent")

Create proper introduction format

formatted_message="I am the ${from_agent} agent from the '${from_agent}' folder. I am contacting you because I need assistance with [extracted from message]. I need you to [specific request]. Please respond with [expected format]. Original request: $message"

Send to target agent

response=$(curl -s -X POST "$target_server/session/$session_id/message" \ -H "Content-Type: application/json" \ -d "{ \"agent\": \"$to_agent\", \"model\": {\"providerID\": \"zai-coding-plan\", \"modelID\": \"glm-4.6\"}, \"parts\": [{\"type\": \"text\", \"text\": \"$formatted_message\"}] }")

echo "$response" | jq -r '.parts[] | select(.type == "text") | .text' }

## Your Workflow

When given a task:
1. **Analyze requirements** - What type of task? Any special needs?
2. **Discover servers** - Find running OpenCode servers and their capabilities
3. **Select optimal server** - Match task requirements with server agents
4. **Create session** - Set up session on chosen server
5. **Execute task** - Send request and handle response
6. **Coordinate communication** - Facilitate inter-agent communication if needed
7. **Enforce protocols** - Ensure agents follow introduction requirements
8. **Error handling** - Retry failed requests or try alternative servers
9. **Return results** - Provide consolidated response to user

## Agent Protocol Enforcement

**MANDATORY INTRODUCTION FORMAT**:

I am the [Agent_Name] agent from the [folder_name] folder. I am contacting you because [specific reason]. I need you to [specific request]. Please respond with [expected format].

**Protocol Violation Handling**:
- If agent fails to introduce: Reject communication and request proper introduction
- If introduction is incomplete: Ask for missing information
- If agent refuses protocol: Escalate to human operator

You coordinate distributed OpenCode capabilities while enforcing strict communication protocols, ensuring all agents identify themselves clearly and state their needs explicitly.
EOF


# OpenCode configuration (optional - for fine-tuning permissions)
mkdir -p .opencode
cat > .opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": true,
  "permission": {
    "bash": {
      "curl*": "allow",
      "jq*": "allow",
      "*": "ask"
    }
  }
}
EOF

echo "✅ Universal OpenCode orchestrator environment created"
echo "🔧 AGENTS.md contains all swarm coordination knowledge"
echo "🚀 Ready to coordinate any OpenCode swarm configuration"

8-Step Swarm Launch Procedure

The orchestrator supports this deployment sequence:

1. Create specialized agent folders - Use folder-creator skill to make agent-specific directories 2. Skip root server launch - Root orchestrator launched later 3. Agent folders created - Done in step 1 4. Primary agents created - Done by folder-creator skill 5. Launch swarm servers - Launch servers in each agent folder on different ports 6. Create root structure - Now create orchestrator setup in project root 7. Launch orchestrator - Start root orchestrator server on port 3000 8. Coordinate swarm - Send user instructions to orchestrator

Swarm Communication Protocol

MANDATORY INTRODUCTION FORMAT:

I am the [Agent_Name] agent from the [folder_name] folder. I am contacting you because [specific reason]. I need you to [specific request]. Please respond with [expected format].

Protocol Enforcement:

• Agents must introduce themselves when contacting others
• Orchestrator validates all inter-agent communications
• Communications without proper introduction are rejected
• Agents must specify exactly what they need

Root Orchestrator Structure

⚠️ EXAMPLE ROOT AGENTS.md CONTENT - The agents below are EXAMPLES only:

# OpenCode Swarm - Root Orchestrator

## Available Agents in Swarm

### 🏠 Orchestrator (Root)
- **Location**: Project root
- **Purpose**: Main coordination and task distribution
- **Port**: 3000

### 🔍 [EXAMPLE] Agent ([agent-folder] folder)
- **Purpose**: [Agent purpose and specialization]
- **Communication**: "I am the [Agent Title] agent from the '[agent-folder]' folder"

### 📚 [EXAMPLE] Agent ([different-folder] folder)
- **Purpose**: [Different agent purpose and specialization]
- **Communication**: "I am the [Agent Title] agent from the '[different-folder]' folder"

### 🛡️ [EXAMPLE] Agent ([another-folder] folder)
- **Purpose**: [Another agent purpose and specialization]
- **Communication**: "I am the [Agent Title] agent from the '[another-folder]' folder"

REAL SWARM EXAMPLES (NOT LIMITATIONS):

• marketing-director/ - Campaign strategy and brand management
• research-scientist/ - Scientific research and experimentation
• music-producer/ - Music production and audio engineering
• legal-consultant/ - Legal advice and compliance review
• fitness-coach/ - Workout planning and nutrition guidance
• financial-advisor/ - Investment planning and wealth management
• language-tutor/ - Language education and cultural training
• game-designer/ - Game mechanics and interactive storytelling

UNIVERSAL TRUTH: The orchestrator coordinates ANY agent types, ANY domains, ANY purposes. The examples above only illustrate the communication pattern.

Usage Example

# After swarm is deployed, send instruction to orchestrator
curl -X POST http://localhost:3000/session \
  -H "Content-Type: application/json" \
  -d '{"title": "Swarm Task"}'

# Then send your task:
curl -X POST http://localhost:3000/session/{session_id}/message \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "orchestrator",
    "model": {"providerID": "zai-coding-plan", "modelID": "glm-4.6"},
    "parts": [{"type": "text", "text": "Analyze this codebase for security issues and create documentation"}]
  }'

Configuration Options

The orchestrator is designed to be universal:

• No assumptions about server types or specializations
• Flexible routing based on discovered capabilities
• Adaptable to any swarm topology
• Generic API interaction patterns

Integration Points

The orchestrator can coordinate with:

• Any OpenCode servers (any version, any configuration)
• Custom agent specializations
• Different model providers
• Various deployment scenarios

This provides a minimal, universal foundation for OpenCode swarm orchestration that can adapt to any specific use case through the orchestrator agent's flexible HTTP API interactions.