Subagent Coordination

Patterns for coordinating work across multiple specialized AI agents, managing agent roles and responsibilities, and orchestrating delegated workflows.

When to use this skill

Use this skill when:

• Determining which agent should handle a specific task
• Delegating work between specialized agents
• Designing multi-agent workflows
• Managing agent capability discovery
• Handling agent handoffs and escalation
• Orchestrating complex tasks across agents

Agent Roles and Boundaries

Core Agent Types

From agents/ directory structure:

// Primary agents (initiative)
cody-admin.json      → Project coordination, planning, infrastructure
cody-builder.json    → Build processes, compilation, deployment

// Specialized agents (reactive)
cody-general.json     → General assistance, undefined tasks
cody-planner.json     → Task breakdown, dependency analysis
cody-release-manager → Release management, versioning, publishing
qa-subagent.json       → Quality assurance, testing, validation
security-subagent.json  → Security audits, vulnerability scanning
frontend-specialist   → Frontend development (React, Vue, etc.)

Role Responsibility Matrix

Capabilities by Agent

// Agent capability mapping
const AGENT_CAPABILITIES = {
  'cody-admin': [
    'task-management',
    'agent-orchestration',
    'build-automation'
  ],
  'cody-planner': [
    'task-decomposition',
    'dependency-analysis',
    'planning'
  ],
  'qa-subagent': [
    'testing-strategy',
    'test-execution',
    'quality-gate-enforcement'
  ],
  'security-subagent': [
    'vulnerability-scanning',
    'security-audit',
    'compliance-validation'
  ],
  'frontend-specialist': [
    'component-creation',
    'styling',
    'ui-testing'
  ]
};

Delegation Patterns

Capability-Based Routing

function findBestAgent(task: Task): string {
  const taskType = inferTaskType(task);

  // Map task types to agents
  const agentMapping: Record<string, string> = {
    'testing': 'qa-subagent',
    'security': 'security-subagent',
    'frontend': 'frontend-specialist',
    'release': 'cody-release-manager',
    'planning': 'cody-planner',
    'infrastructure': 'cody-admin',
    'general': 'cody-general'
  };

  return agentMapping[taskType] || 'cody-general';
}

// Usage
const agent = findBestAgent({ type: 'security-audit' });
console.log(`Delegating to: ${agent}`);
await delegateToAgent(agent, task);

Sequential Delegation

async function executeMultiAgentWorkflow(workflow: Workflow): Promise<void> {
  const steps = workflow.steps;

  for (let i = 0; i < steps.length; i++) {
    const step = steps[i];
    const agent = findBestAgent(step);

    console.log(`Step ${i + 1}/${steps.length}: ${step.name} → ${agent}`);

    const result = await delegateToAgent(agent, step);

    if (!result.success) {
      console.error(`Agent ${agent} failed at step ${i + 1}`);
      await escalateFailure(step, result);
      break;
    }

    // Pass results to next step
    workflow.context[step.name] = result;
  }
}

Parallel Delegation

async function executeParallelTasks(tasks: Task[]): Promise<TaskResult[]> {
  // Group tasks by agent type
  const agentTasks: Record<string, Task[]> = {};

  for (const task of tasks) {
    const agent = findBestAgent(task);
    agentTasks[agent] = agentTasks[agent] || [];
    agentTasks[agent].push(task);
  }

  // Execute each agent's tasks in parallel
  const results = await Promise.all(
    Object.entries(agentTasks).map(([agent, tasks]) =>
      executeAgentBatch(agent, tasks)
    )
  );

  return results.flat();
}

Agent Handoff Procedures

Context Passing

interface AgentHandoff {
  fromAgent: string;
  toAgent: string;
  context: {
    task: string;
    results: any;
    decisions: string[];
    partialState?: any;
  };
}

function handoffAgent(handoff: AgentHandoff): Promise<void> {
  console.log(`Handoff: ${handoff.fromAgent} → ${handoff.toAgent}`);

  // Transfer context to next agent
  const newAgent = loadAgent(handoff.toAgent);
  await newAgent.initialize(handoff.context);

  // Clear previous agent state
  const previousAgent = loadAgent(handoff.fromAgent);
  await previousAgent.cleanup();
}

Handoff Templates

// From cody-planner to qa-subagent
const handoffToQA = {
  fromAgent: 'cody-planner',
  toAgent: 'qa-subagent',
  context: {
    task: 'Validate implementation',
    results: {
      implementationFiles: ['src/command.ts', 'src/utils.ts'],
      decisions: ['Used Bun test runner', 'Implemented with 80% coverage']
    },
    taskBreakdown: {
      'unit-tests': 'cody-general',
      'integration-tests': 'qa-subagent',
      'e2e-tests': 'qa-subagent'
    }
  };
}

Error Escalation

Failure Detection

async function delegateWithRetry(agent: string, task: Task, maxRetries = 3): Promise<any> {
  let lastError: Error | null = null;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await executeAgentTask(agent, task);
      return result;
    } catch (error) {
      lastError = error as Error;
      console.warn(`Agent ${agent} attempt ${attempt} failed: ${error.message}`);

      if (attempt < maxRetries) {
        await sleep(2000 * attempt); // Exponential backoff
      }
    }
  }

  // All retries exhausted - escalate
  return await escalateFailure(agent, task, lastError);
}

Escalation Paths

// Agent → More specialized agent
const escalationPath = {
  'cody-general': 'qa-subagent',
  'cody-planner': 'cody-admin',
  'frontend-specialist': 'security-subagent',
  'qa-subagent': 'cody-admin',
  'security-subagent': 'cody-admin'
};

function escalateToSupervisor(failedAgent: string, error: Error): Promise<void> {
  const supervisor = escalationPath[failedAgent];

  console.error(`Escalating from ${failedAgent} to ${supervisor}`);

  await notifySupervisor(supervisor, {
    agent: failedAgent,
    error: error.message,
    timestamp: new Date()
  });
}

Workflow Orchestration

Agent Graph Definition

interface AgentNode {
  id: string;
  agent: string;
  dependencies: string[];
  outputDependencies: string[];
}

const WORKFLOW_GRAPH: AgentNode[] = [
  {
    id: 'plan',
    agent: 'cody-planner',
    dependencies: [],
    outputDependencies: ['implement']
  },
  {
    id: 'implement',
    agent: 'cody-general',
    dependencies: ['plan'],
    outputDependencies: ['test']
  },
  {
    id: 'test',
    agent: 'qa-subagent',
    dependencies: ['implement'],
    outputDependencies: ['deploy']
  },
  {
    id: 'deploy',
    agent: 'cody-builder',
    dependencies: ['test'],
    outputDependencies: []
  }
];

function executeWorkflow(graph: AgentNode[]): Promise<void> {
  const executionOrder = topologicalSort(graph);

  for (const node of executionOrder) {
    const agent = loadAgent(node.agent);
    console.log(`Executing ${node.id} with ${node.agent}`);

    // Wait for dependencies
    await waitForDependencies(node.dependencies);

    // Execute
    const result = await agent.execute(node);

    // Notify dependent agents
    notifyDependencies(node.outputDependencies, result);
  }
}

Orchestration with Liaison

# Create workflow in liaison
liaison workflow create "multi-agent-release" \
  --trigger "agent:delegated:agent=cody-planner" \
  --actions "delegate-to-general,notify-builder" \
  --condition "all-dependencies-met"

# Trigger workflow
liaison task create "Prepare release" --auto-trigger "multi-agent-release"

Inter-Agent Communication

Message Format

interface AgentMessage {
  from: string;
  to: string;
  type: 'task' | 'result' | 'error' | 'status';
  payload: any;
  timestamp: Date;
  correlationId: string;
}

async function sendAgentMessage(message: AgentMessage): Promise<void> {
  await messageBus.publish({
    topic: `agent.${message.to}`,
    message,
    headers: {
      'X-Agent-From': message.from,
      'X-Correlation-ID': message.correlationId
    }
  });
}

Status Broadcasting

// Agent status updates
async function broadcastStatus(agent: string, status: 'working' | 'idle' | 'error'): Promise<void> {
  await messageBus.publish({
    topic: 'agent.status',
    message: { agent, status, timestamp: new Date() }
  });
}

// Subscribe to agent status
function subscribeToAgentStatus(callback: (status: AgentStatus) => void): void {
  messageBus.subscribe('agent.status', callback);
}

Agent Discovery

Capability Registration

// Agents register their capabilities
interface AgentCapabilities {
  agent: string;
  capabilities: string[];
  maxConcurrency: number;
  supportedTaskTypes: string[];
}

// cody-admin registers agents
await liaison.registerAgent({
  agent: 'qa-subagent',
  capabilities: ['testing', 'validation', 'quality-gates'],
  maxConcurrency: 1,
  supportedTaskTypes: ['testing', 'validation']
});

Finding Agents

# List available agents
liaison agent list

# Find agent by capability
liaison agent find --capability testing

# Check agent status
liaison agent status qa-subagent

Verification

After implementing agent coordination:

• Agent roles and responsibilities clearly defined
• Delegation logic routes tasks to appropriate agents
• Handoff procedures transfer context between agents
• Escalation paths are defined for failures
• Inter-agent communication is standardized
• Workflow graphs are validated for cycles
• Agent capabilities are registered and discoverable
• Parallel delegation doesn't exceed agent concurrency
• Error handling includes retry and escalation

Examples from liaison-toolkit

Example 1: Multi-Agent Release

# 1. cody-planner breaks down release task
liaison task create "Prepare release" --auto-trigger planning

# 2. cody-general implements changes
liaison task create "Implement version bump" --assign cody-general

# 3. qa-subagent validates
liaison task create "Run tests" --assign qa-subagent

# 4. security-subagent scans
liaison task create "Security audit" --assign security-subagent

# 5. cody-builder deploys
liaison task create "Build and publish" --assign cody-builder

Example 2: Error Escalation

// cody-planner delegates to cody-general
const result = await delegateToAgent('cody-general', task);

if (!result.success) {
  // Escalate to cody-admin
  console.error('General agent failed, escalating to admin...');

  await escalateToAdmin({
    originalAgent: 'cody-general',
    task,
    error: result.error
  });
}

Example 3: Capability Discovery

// Find agent for security task
const agent = liaison.findAgent({
  capabilities: ['security-audit', 'vulnerability-scanning']
});

// Returns: 'security-subagent'
console.log(`Delegating security task to: ${agent}`);
await executeAgent(agent, task);

Related Resources

• Multi-Agent Systems
• Agent Orchestration Patterns
• Task Delegation
• Service Discovery