Agent Orchestration Skill

Overview

This skill provides patterns for orchestrating multi-agent workflows using the Hub Architecture. In this pattern:

• Subagents cannot directly spawn other subagents
• The main conversation acts as a hub that routes requests between agents
• Agents communicate via structured delegation requests

Delegation Request Protocol

Single Agent Request

When an agent needs help from one other agent:

{
  "delegation_request": {
    "agent": "database",
    "reason": "Need users schema before implementing auth",
    "prompt": "Create users table with id, email, password_hash, created_at",
    "blocking": true
  }
}

Field	Description
agent	Target agent: database, backend, frontend, ios, devops, designer
reason	Why this delegation is needed
prompt	Specific instructions for the target agent
blocking	If true, wait for completion before continuing

Multi-Agent Request

When orchestrating multiple agents (typically from architect):

{
  "delegation_request": {
    "type": "sequential",
    "agents": [
      {
        "agent": "database",
        "task_id": "auth-001",
        "prompt": "Create users and sessions tables",
        "depends_on": null
      },
      {
        "agent": "backend",
        "task_id": "auth-001",
        "prompt": "Implement auth endpoints",
        "depends_on": "database"
      },
      {
        "agent": "frontend",
        "task_id": "auth-001",
        "prompt": "Create login/register forms",
        "depends_on": "backend"
      },
      {
        "agent": "ios",
        "task_id": "auth-001",
        "prompt": "Create auth screens",
        "depends_on": "backend"
      }
    ],
    "parallel_groups": [
      ["frontend", "ios"]
    ],
    "context_file": ".agents/architect/current-plan.md",
    "return_to": "architect"
  }
}

Field	Description
type	sequential, parallel, or mixed
agents	Array of agent tasks
depends_on	Agent that must complete first (null = no dependency)
parallel_groups	Arrays of agents that can run concurrently
context_file	Shared context file for all agents (JSON format: .agents/architect/current-plan.json)
return_to	Agent to receive aggregated results

Hub Processing

When the hub receives a delegation request:

Step 1: Parse Request

Extract the delegation_request JSON from the agent's response.

Step 2: Build Execution Graph

database (no deps) ──┐
                     ├──► backend ──┬──► frontend
                     │              │
                     │              └──► ios (parallel with frontend)
                     │
designer (no deps) ──┘

Step 3: Execute in Order

1. Run agents with no dependencies first
2. Pass results to dependent agents
3. Run parallel groups concurrently
4. Collect all results

Step 4: Spawn Agents

Task(
  subagent_type="database",
  prompt="Task auth-001: Create users and sessions tables.

Read: .agents/architect/current-plan.json

Return summary under 500 tokens including:
- Tables/schemas created
- Key decisions
- Notes for dependent agents"
)

Step 5: Pass Context Forward

Task(
  subagent_type="backend",
  prompt="Task auth-001: Implement auth endpoints.

Read: .agents/architect/current-plan.json

Previous agent results:
- database: Created users(id, email, password_hash) and sessions(id, user_id, token) tables

Return summary under 500 tokens."
)

Step 6: Handle Parallel Execution

When agents can run in parallel, spawn them in the same message:

// Both run concurrently
Task(subagent_type="frontend", prompt="...")
Task(subagent_type="ios", prompt="...")

Step 7: Aggregate Results

{
  "hub_results": {
    "task_id": "auth-001",
    "completed_agents": [
      {
        "agent": "database",
        "status": "completed",
        "summary": "Created users and sessions tables",
        "files": ["prisma/schema.prisma"]
      },
      {
        "agent": "backend",
        "status": "completed",
        "summary": "Created POST /auth/login, /auth/register, /auth/logout",
        "files": ["src/routes/auth.ts"]
      }
    ],
    "failed_agents": [],
    "total_files_modified": 5
  }
}

Step 8: Return to Requesting Agent

Task(
  subagent_type="architect",
  prompt="Hub completed delegation for task auth-001.

Results:
[hub_results JSON]

All agents completed successfully. Continue with synthesis."
)

Handling Nested Delegations

Agents may return their own delegation requests:

backend returns:
{
  "work_completed": "Implemented auth endpoints",
  "delegation_request": {
    "agent": "database",
    "reason": "Need to add email_verified column",
    "prompt": "Add email_verified boolean to users table"
  }
}

The hub should:

1. Note the work completed
2. Process the nested delegation
3. Return combined results

Error Handling

Agent Failure

{
  "hub_results": {
    "completed_agents": [...],
    "failed_agents": [
      {
        "agent": "frontend",
        "status": "failed",
        "error": "Could not find component structure",
        "suggestion": "Run designer agent first"
      }
    ]
  }
}

Dependency Failure

If a dependency fails, mark dependent agents as blocked:

{
  "blocked_agents": [
    {
      "agent": "backend",
      "blocked_by": "database",
      "reason": "Database agent failed to create schema"
    }
  ]
}

Workflow Examples

Full Stack Feature

Architect → Hub:
  delegation_request:
    designer → database → backend → [frontend, ios] → devops

Hub executes:
  1. designer: Create tokens
  2. database: Create schema
  3. backend: Create API
  4. frontend + ios: Create UI (parallel)
  5. devops: Setup deployment
  6. Return to architect

Quick Fix

Backend → Hub:
  delegation_request:
    agent: database
    prompt: "Add index on users.email"

Hub executes:
  1. database: Add index
  2. Return to backend

Cross-Platform UI

Designer → Hub:
  delegation_request:
    parallel_groups: [[frontend, ios]]
    prompt: "Apply new button styles"

Hub executes:
  1. frontend + ios (parallel): Update buttons
  2. Return to designer

Best Practices

1. Keep prompts specific - Include exact requirements, not vague goals
2. Include context files - Always reference shared plan documents
3. Limit delegation depth - Avoid deep nesting (max 2 levels)
4. Use parallel when possible - Frontend/iOS can often run together
5. Handle failures gracefully - Always check for failed agents
6. Aggregate meaningfully - Combine results into actionable summaries