Agent Coordination

Coordinate multiple specialized agents to solve complex multi-step tasks efficiently through strategic execution patterns.

Coordination Strategies

1. Parallel Coordination

Use When: Independent tasks, no dependencies, maximize throughput

Implementation:

• •Single message with multiple Task tool calls
• •All agents start simultaneously
• •Results collected and merged

Example:

Task: "Review code and run tests"

├─ code-reviewer: Review code quality
└─ test-runner: Execute test suite

Execution: One message, both Task tools

2. Sequential Coordination

Use When: Strong dependencies, each task needs previous output

Implementation:

• •Chain of messages, each waits for previous
• •Explicit handoffs between agents
• •Output of one is input to next

Example:

Task: "Implement feature, test it, then review"

└─ feature-implementer: Build feature
   └─ test-runner: Test implementation
      └─ code-reviewer: Review code

Execution: Sequential messages with context transfer

3. Swarm Coordination

Use When: Complex problem needs multiple perspectives

Implementation:

• •Phase 1: Parallel investigation (multiple Skills or Agents)
• •Phase 2: Synthesis (combine findings)
• •Phase 3: Coordinated resolution

Example A - Skill-Based Swarm (Analysis/Review):

Task: "Validate v0.1.0 implementation quality"

Phase 1 [Parallel Skills]:
├─ Skill(command="rust-code-quality")
├─ Skill(command="architecture-validation")
└─ Skill(command="plan-gap-analysis")

Phase 2: Synthesize findings → identify gaps and issues
Phase 3: Create prioritized action plan

Example B - Agent-Based Swarm (Execution/Testing):

Task: "Diagnose performance degradation"

Phase 1 [Parallel Agents]:
├─ Task(subagent_type="debugger", prompt="Profile runtime performance")
├─ Task(subagent_type="code-reviewer", prompt="Analyze code efficiency")
└─ Task(subagent_type="test-runner", prompt="Run performance benchmarks")

Phase 2: Synthesize findings → identify root cause
Phase 3: Apply coordinated fix

4. Hybrid Coordination

Use When: Complex workflows with mixed dependencies

Implementation:

• •Multiple phases with different strategies
• •Parallel within phases, sequential between phases
• •Validation gates between phases

Example:

Task: "Refactor module, update tests, verify"

Phase 1 [Parallel]: Assessment
├─ code-reviewer: Assess current code
└─ test-runner: Run existing tests

Phase 2 [Sequential]: Implementation
└─ refactorer: Apply improvements

Phase 3 [Parallel]: Validation
├─ test-runner: Verify refactored code
└─ code-reviewer: Final quality check

5. Iterative/Loop Coordination

Use When: Tasks require progressive refinement until criteria met

Implementation:

• •Repeat agent execution with feedback from previous iteration
• •Track progress across iterations
• •Terminate when success criteria met or convergence detected
• •Use loop-agent for orchestration

Example:

Task: "Iteratively improve code quality until standards met"

Loop Configuration:
- Max Iterations: 5
- Success: All clippy warnings resolved + tests pass
- Agent: refactorer

Execution: loop-agent orchestrates iterations
Iteration 1: refactorer → 15 issues → Continue
Iteration 2: refactorer → 3 issues → Continue
Iteration 3: refactorer → 0 issues ✓ → Success

Use loop-agent for: test-fix-retest cycles, performance optimization loops,
progressive quality improvements, convergence-based refinement

CRITICAL: Understanding Skills vs Task Agents

There are TWO different types of workers you can coordinate:

Skills (invoked via Skill tool)

Skills are instruction sets that guide Claude directly. They provide specialized knowledge and workflows.

How to invoke: Skill(command="skill-name")

Available Skills:

• •rust-code-quality - Comprehensive Rust code quality review
• •architecture-validation - Validate implementation vs architecture plans
• •plan-gap-analysis - Compare plans vs actual implementation
• •analysis-swarm - Multi-perspective code analysis (RYAN, FLASH, SOCRATES)
• •test-fix - Systematic test debugging and fixing
• •build-compile - Build and compilation management
• •debug-troubleshoot - Debug async Rust issues
• •feature-implement - Feature implementation workflow
• •storage-sync - Storage synchronization between Turso and redb
• •task-decomposition - Break down complex tasks

Task Agents (invoked via Task tool)

Task Agents are autonomous sub-processes that execute tasks independently using tools.

How to invoke: Task(subagent_type="agent-name", prompt="...", description="...")

Available Task Agents:

When to Use Which?

Use Skills when:

• •You need specialized knowledge/workflow guidance
• •The task requires deep domain expertise (Rust quality, architecture validation)
• •You want to follow a proven methodology
• •Examples: Code quality review, gap analysis, architecture validation

Use Task Agents when:

• •You need autonomous task execution
• •The task requires tool usage (Read, Edit, Bash, etc.)
• •You want parallel/independent execution
• •Examples: Running tests, implementing features, debugging

Common Coordination Patterns

Pattern 1: Skill-Based Swarm (for analysis tasks)

Phase 1 [Parallel Skills]:
├─ Skill(command="rust-code-quality")
├─ Skill(command="architecture-validation")
└─ Skill(command="plan-gap-analysis")

Phase 2: Synthesize findings
Phase 3: Create action plan

Pattern 2: Agent-Based Swarm (for execution tasks)

Phase 1 [Parallel Agents]:
├─ Task(subagent_type="code-reviewer", ...)
├─ Task(subagent_type="test-runner", ...)
└─ Task(subagent_type="debugger", ...)

Phase 2: Aggregate results
Phase 3: Apply fixes

Pattern 3: Hybrid Coordination (combine Skills and Agents)

Phase 1: Skill(command="task-decomposition")  # Plan the work
Phase 2 [Parallel Agents]:                     # Execute in parallel
├─ Task(subagent_type="feature-implementer", ...)
└─ Task(subagent_type="test-runner", ...)
Phase 3: Skill(command="rust-code-quality")   # Validate quality

Coordination Workflow

Phase 1: Strategy Selection

Decision Matrix:

• •Independent tasks + Time-critical → Parallel
• •Strong dependencies + Order matters → Sequential
• •Complex problem + Multiple perspectives → Swarm
• •Multi-phase + Mixed dependencies → Hybrid
• •Progressive refinement + Convergence needed → Iterative/Loop

Phase 2: Agent Assignment

Match Tasks to Agents:

1. •Capability matching (does agent have required skills?)
2. •Workload balancing (distribute evenly)
3. •Expertise routing (specialized tasks to expert agents)

Phase 3: Execution Planning

## Execution Plan

### Strategy: [Parallel/Sequential/Swarm/Hybrid]

### Phase 1: [Name]
**Mode**: [Parallel/Sequential]
**Agents**:
- Agent: [name] | Task: [description] | Deps: [dependencies]

**Quality Gate**:
- [Validation criteria]

### Overall Success Criteria:
- [Criterion 1]
- [Criterion 2]

Phase 4: Execution & Monitoring

Monitoring Checklist:

• • Agent has started
• • Agent is making progress
• • Agent output meets quality criteria
• • No errors or failures
• • Completion within expected time

Phase 5: Quality Validation

Validation Gates (between phases):

1. •Output validation (format, completeness, quality)
2. •Success criteria check (phase goals met?)
3. •Error handling (can errors be recovered?)

Phase 6: Result Synthesis

## Execution Summary

### Completed Tasks:
- [Task 1]: ✓ [Agent] - [Outcome]

### Deliverables:
- [Item 1]: [Location/Description]

### Quality Validation:
- [Criterion 1]: ✓ Met

### Performance Metrics:
- Total time: [duration]
- Success rate: [percentage]

Communication Patterns

Agent-to-Agent Handoff

Context Transfer:

Agent A completes, produces output X

Message to Agent B:
"Previous agent (A) produced X. Use this as input.
Task: [specific instructions for B]
Success criteria: [how to validate]"

Synchronization Points

Parallel Convergence:

1. •Wait for all agents to complete
2. •Collect outputs from each
3. •Validate each output
4. •If all valid → proceed, else handle errors

Quality Gates:

1. •Validate all outputs from phase
2. •Check success criteria
3. •Decision: proceed / retry / adjust / abort

Error Handling

Recovery Strategies

Retry: For transient failures (max 2-3 attempts) Alternative Approach: Different agent or technical approach Plan Adjustment: Remove optional tasks, simplify requirements Graceful Degradation: Partial completion with documentation

Failure Scenarios

Best Practices

DO:

✓ Use Skill tool for analysis/review tasks (rust-code-quality, architecture-validation, plan-gap-analysis) ✓ Use Task tool for execution tasks (code-reviewer, test-runner, feature-implementer) ✓ Choose appropriate strategy for task dependencies ✓ Match workers (Skills/Agents) to tasks based on capabilities ✓ Validate at quality gates before proceeding ✓ Provide clear context in handoffs ✓ Monitor progress during execution ✓ Handle errors gracefully with recovery ✓ Aggregate results comprehensively

DON'T:

✗ Use Task tool with skill names (e.g., Task(subagent_type="rust-code-quality") → ERROR!) ✗ Use Skill tool with agent names (e.g., Skill(command="code-reviewer") → May not work as expected) ✗ Force parallel execution when dependencies exist ✗ Assign tasks to inappropriate workers ✗ Skip quality validation ✗ Proceed after failed quality gates ✗ Provide insufficient context

Coordination Metrics

Efficiency Metrics

• •Execution Time: Track total time and per-agent time
• •Resource Utilization: Agents active / available
• •Throughput: Tasks completed / time

Quality Metrics

• •Success Rate: Tasks successful / total (should be >95%)
• •Quality Gate Passage: All gates should pass (100%)
• •Rework Rate: Tasks requiring retry (should be <10%)

Integration with GOAP Agent

The GOAP agent uses this skill as its core coordination engine:

1. •Decompose task (task-decomposition skill)
2. •Select coordination strategy (this skill)
3. •Assign agents to tasks (this skill)
4. •Execute coordination (this skill + parallel-execution skill)
5. •Validate and report (this skill)

Troubleshooting Common Errors

Error: "Agent type 'X' not found"

Cause: Trying to use a Skill name with the Task tool

Example of Error:

Task(subagent_type="rust-code-quality", ...)
→ ERROR: Agent type 'rust-code-quality' not found

Solution: Use the Skill tool instead:

Skill(command="rust-code-quality")
→ SUCCESS

Available Task Agents ONLY:

• •code-reviewer
• •test-runner
• •feature-implementer
• •refactorer
• •debugger
• •agent-creator
• •goap-agent
• •loop-agent
• •analysis-swarm

Everything else is a Skill - use Skill(command="...")

Quick Reference: Which Tool to Use?

Mnemonic

• •Skills = Knowledge/Methodology (invoked with Skill tool)
• •Agents = Autonomous Executors (invoked with Task tool)

Summary

Effective agent coordination requires:

• •Right tool (Skill vs Task) for the worker type
• •Right strategy for the task structure
• •Right workers (Skills/Agents) for each sub-task
• •Clear communication and context transfer
• •Quality validation at key checkpoints
• •Graceful error handling and recovery
• •Comprehensive result synthesis

Use this skill to coordinate any multi-agent workflow effectively.