Orchestration Skill Guidelines

When to Use This Skill

• Multi-agent coordination requiring centralized orchestration
• Complex workflows with multiple dependent tasks
• Parallel execution benefiting from concurrent agent spawning
• Quality-controlled delivery needing validation and consensus
• Production workflows requiring audit trails and state management

When NOT to Use This Skill

• Single-agent tasks with no coordination requirements
• Simple sequential work completing in <30 minutes
• Trivial operations with no quality gates
• Exploratory work not needing formal orchestration

Success Criteria

• All agents complete successfully with 100% task completion
• Coordination overhead minimal (<20% of total execution time)
• No orphaned agents - All spawned agents tracked and terminated
• State fully recoverable - Can resume from any failure point
• Quality gates pass - All validation checks successful

Edge Cases to Handle

• Agent failures - Detect and replace failed agents automatically
• Timeout scenarios - Configure per-agent timeout with escalation
• Resource exhaustion - Limit concurrent agents, queue excess work
• Conflicting results - Implement conflict resolution strategy
• Partial completion - Support incremental progress with rollback

Guardrails (NEVER Violate)

• NEVER lose orchestration state - Persist to memory after each phase
• ALWAYS track all agents - Maintain real-time agent registry
• ALWAYS cleanup resources - Terminate agents and free memory on completion
• NEVER skip validation - Run quality checks before marking complete
• ALWAYS handle errors - Every orchestration step needs error handling

Evidence-Based Validation

• Verify all agent outputs - Check actual results vs expected contracts
• Validate execution order - Confirm dependencies respected
• Measure performance - Track execution time vs baseline
• Check resource usage - Monitor memory, CPU, network during execution
• Audit state consistency - Verify orchestration state matches reality

Web-CLI Teleport SOP

Overview

Bridge web interfaces with CLI workflows for seamless integration, enabling web applications to trigger CLI commands and CLI tools to display web interfaces.

Agents & Responsibilities

backend-dev

Role: Implement bridge API and integration logic Responsibilities:

• Build REST API for CLI integration
• Implement WebSocket for real-time communication
• Handle authentication and security
• Manage state synchronization

system-architect

Role: Design bridge architecture and patterns Responsibilities:

• Design integration architecture
• Define communication protocols
• Plan security model
• Ensure scalability

Phase 1: Design Bridge Architecture

Objective

Design architecture for bidirectional web-CLI communication.

Scripts

# Generate architecture diagram
npx claude-flow@alpha architect design \
  --type "web-cli-bridge" \
  --output bridge-architecture.json

# Define API specification
cat > api-spec.yaml <<EOF
openapi: 3.0.0
info:
  title: Web-CLI Bridge API
  version: 1.0.0
paths:
  /cli/execute:
    post:
      summary: Execute CLI command from web
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                command: { type: string }
                args: { type: array }
      responses:
        '200':
          description: Command output
  /web/render:
    post:
      summary: Render web UI from CLI
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                component: { type: string }
                data: { type: object }
EOF

# Store architecture
npx claude-flow@alpha memory store \
  --key "bridge/architecture" \
  --file bridge-architecture.json

Architecture Patterns

Web → CLI:

Web UI → REST API → CLI Executor → Command → Output → API → Web UI

CLI → Web:

CLI Tool → WebSocket → Web Server → Browser → UI Render

Bidirectional:

Web UI ←→ WebSocket ←→ Bridge Server ←→ CLI Tools

Phase 2: Implement Web Interface

Objective

Build web interface that can trigger and monitor CLI commands.

Scripts

# Create web application
npx create-react-app web-cli-bridge
cd web-cli-bridge

# Install dependencies
npm install axios socket.io-client

# Generate web components
npx claude-flow@alpha generate component \
  --name "CLIExecutor" \
  --type "react" \
  --output src/components/CLIExecutor.jsx

# Build web interface
npm run build

# Deploy web app
npx claude-flow@alpha deploy web \
  --source ./build \
  --target ./deploy/web

Web Component Example

// src/components/CLIExecutor.jsx
import React, { useState, useEffect } from 'react';
import axios from 'axios';
import io from 'socket.io-client';

function CLIExecutor() {
  const [command, setCommand] = useState('');
  const [output, setOutput] = useState('');
  const [socket, setSocket] = useState(null);

  useEffect(() => {
    const newSocket = io('http://localhost:3001');
    setSocket(newSocket);

    newSocket.on('cli-output', (data) => {
      setOutput(prev => prev + data + '\n');
    });

    return () => newSocket.close();
  }, []);

  const executeCommand = async () => {
    try {
      const response = await axios.post('/api/cli/execute', {
        command,
        args: command.split(' ').slice(1)
      });
      setOutput(response.data.output);
    } catch (error) {
      setOutput(`Error: ${error.message}`);
    }
  };

  return (
    <div className="cli-executor">
      <input
        type="text"
        value={command}
        onChange={(e) => setCommand(e.target.value)}
        placeholder="Enter CLI command..."
      />
      <button onClick={executeCommand}>Execute</button>
      <pre className="output">{output}</pre>
    </div>
  );
}

export default CLIExecutor;

Phase 3: Implement CLI Bridge

Objective

Build CLI-side bridge that connects to web interface.

Scripts

# Create bridge server
mkdir cli-bridge
cd cli-bridge
npm init -y
npm install express socket.io cors child_process

# Generate bridge server
npx claude-flow@alpha generate server \
  --type "bridge" \
  --output server.js

# Start bridge server
node server.js &

# Test connection
curl -X POST http://localhost:3001/api/cli/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "ls", "args": ["-la"]}'

Bridge Server Implementation

// server.js
const express = require('express');
const http = require('http');
const socketIo = require('socket.io');
const { exec } = require('child_process');
const cors = require('cors');

const app = express();
const server = http.createServer(app);
const io = socketIo(server, { cors: { origin: '*' } });

app.use(cors());
app.use(express.json());

// Execute CLI command from web
app.post('/api/cli/execute', (req, res) => {
  const { command, args = [] } = req.body;
  const fullCommand = `${command} ${args.join(' ')}`;

  exec(fullCommand, (error, stdout, stderr) => {
    if (error) {
      return res.status(500).json({
        error: error.message,
        stderr
      });
    }

    res.json({
      output: stdout,
      stderr
    });

    // Broadcast to all connected clients
    io.emit('cli-output', stdout);
  });
});

// Render web UI from CLI
app.post('/api/web/render', (req, res) => {
  const { component, data } = req.body;

  io.emit('render-component', {
    component,
    data
  });

  res.json({ success: true });
});

// WebSocket connection
io.on('connection', (socket) => {
  console.log('Client connected');

  socket.on('disconnect', () => {
    console.log('Client disconnected');
  });
});

server.listen(3001, () => {
  console.log('Bridge server running on port 3001');
});

CLI Tool Integration

#!/bin/bash
# cli-tool-with-web.sh

# Function to render web UI from CLI
render_web_ui() {
  local component=$1
  local data=$2

  curl -X POST http://localhost:3001/api/web/render \
    -H "Content-Type: application/json" \
    -d "{\"component\": \"$component\", \"data\": $data}"
}

# Example: Show analysis results in web UI
analyze_code() {
  local path=$1
  local results=$(npx claude-flow@alpha analyze "$path" --format json)

  # Send results to web interface
  render_web_ui "AnalysisResults" "$results"

  echo "Results sent to web interface"
}

analyze_code ./src

Phase 4: Test Integration

Objective

Validate bidirectional communication and error handling.

Scripts

# Test web → CLI
curl -X POST http://localhost:3001/api/cli/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "npx", "args": ["claude-flow@alpha", "swarm", "status"]}'

# Test CLI → web
bash cli-tool-with-web.sh

# Test WebSocket connection
node test-websocket.js

# Run integration tests
npm test -- --testPathPattern=integration

# Load testing
npx artillery quick --count 10 -n 20 http://localhost:3001/api/cli/execute

Integration Tests

// tests/integration.test.js
const request = require('supertest');
const io = require('socket.io-client');
const app = require('../server');

describe('Web-CLI Bridge Integration', () => {
  let socket;

  beforeAll((done) => {
    socket = io('http://localhost:3001');
    socket.on('connect', done);
  });

  afterAll(() => {
    socket.close();
  });

  it('should execute CLI command from web', async () => {
    const response = await request(app)
      .post('/api/cli/execute')
      .send({ command: 'echo', args: ['test'] });

    expect(response.status).toBe(200);
    expect(response.body.output).toContain('test');
  });

  it('should broadcast CLI output via WebSocket', (done) => {
    socket.on('cli-output', (data) => {
      expect(data).toBeDefined();
      done();
    });

    request(app)
      .post('/api/cli/execute')
      .send({ command: 'echo', args: ['websocket test'] });
  });

  it('should render web UI from CLI', async () => {
    const response = await request(app)
      .post('/api/web/render')
      .send({
        component: 'TestComponent',
        data: { test: true }
      });

    expect(response.status).toBe(200);
    expect(response.body.success).toBe(true);
  });
});

Phase 5: Deploy and Monitor

Objective

Deploy bridge to production and monitor performance.

Scripts

# Build for production
npm run build:web
npm run build:server

# Deploy with Docker
cat > Dockerfile <<EOF
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3001
CMD ["node", "server.js"]
EOF

docker build -t web-cli-bridge .
docker run -d -p 3001:3001 web-cli-bridge

# Monitor with Prometheus
cat > prometheus.yml <<EOF
scrape_configs:
  - job_name: 'bridge'
    static_configs:
      - targets: ['localhost:3001']
EOF

# Setup logging
mkdir logs
node server.js > logs/bridge.log 2>&1 &

# Monitor logs
tail -f logs/bridge.log

# Health check
curl http://localhost:3001/health

Success Criteria

• Bridge architecture designed
• Web interface functional
• CLI bridge operational
• Integration tested
• Deployed and monitored

Performance Targets

• API response time: <200ms
• WebSocket latency: <50ms
• Command execution: <5s
• Uptime: >99.9%

Best Practices

1. Security: Implement authentication and authorization
2. Error Handling: Graceful error handling on both sides
3. Logging: Comprehensive logging for debugging
4. Rate Limiting: Prevent abuse
5. Validation: Validate all inputs
6. Monitoring: Track performance metrics
7. Documentation: Document API and protocols
8. Testing: Comprehensive integration tests

Common Issues & Solutions

Issue: Command Execution Timeout

Symptoms: Long-running commands hang Solution: Implement timeout mechanism, use async execution

Issue: WebSocket Disconnections

Symptoms: Frequent disconnections Solution: Implement reconnection logic, use heartbeat

Issue: Security Vulnerabilities

Symptoms: Unauthorized command execution Solution: Implement authentication, whitelist commands

Integration Points

• swarm-orchestration: Execute orchestration from web
• performance-analysis: Display metrics in web UI
• slash-commands: Expose commands via web

References

• WebSocket Protocol
• REST API Design
• CLI Integration Patterns
• Security Best Practices