Workflow Engineering Patterns

Boomerang Coordination Pattern Core

A systematic approach to multi-agent coordination where tasks originate from an Orchestrator, are processed by specialists, and reliably return with structured results.

System-level abstraction Orchestration Production maturity Updated Nov 2025

Context

Complex AI workflows require coordination between multiple specialized agents, each with distinct capabilities and responsibilities. Traditional linear coordination patterns lead to single points of failure and difficulty in error recovery.

Problem

How to coordinate multiple agents in a way that:

Maintains deterministic behavior
Enables reliable error recovery
Supports progressive complexity
Preserves context across agent boundaries

Solution

Implement a boomerang coordination system where:

Tasks originate from an Orchestrator with clear assignment parameters
Specialist agents process assigned tasks within defined boundaries and return structured results
Completed tasks "boomerang" back to the Orchestrator for verification and integration
Explicit mode transitions occur only through boomerang returns with structured JSON payloads

Structure & Participants

Participants

Orchestrator - Coordinates task decomposition, assignment, and integration
Specialist Agents - Execute domain-specific tasks within bounded responsibilities
State Manager - Maintains workflow state and task tracking
Validation Layer - Ensures schema compliance and boundary enforcement

Collaborations

The Orchestrator receives user requests and decomposes them into subtasks with clear boundaries. Each subtask is assigned to a specialist agent with complete context. Specialist agents execute within their domain and return structured JSON payloads. The Orchestrator validates returns, updates state, and triggers dependent tasks. All mode transitions flow through the Orchestrator, creating a boomerang pattern.

Implementation

Use structured JSON payloads with required fields: task_id, origin_mode, destination_mode, result, state, and error_handling
Store state in persistent storage (e.g., .roo/boomerang-state.json)
Implement schema validation for all boomerang returns
Enforce boundary constraints preventing specialists from operating outside their domain
Enable automatic retry logic for failed boomerangs

Consequences

Benefits

Eliminates single points of failure through distributed responsibility
Enables systematic error recovery and retry logic
Maintains deterministic behavior through explicit state transitions
Supports progressive complexity through bounded agent responsibilities
Provides clear separation of concerns between coordination and execution
Facilitates debugging through explicit state tracking

Trade-offs

Increased complexity in initial system design
Additional overhead for boomerang validation
Potential latency increases from coordination loops
Requires well-defined interfaces between agents

Risks

Risk of infinite boomerang loops if validation fails
Risk of state inconsistency if boomerang payloads are malformed
Risk of coordination deadlock in complex multi-agent scenarios
Risk of context loss if delegation scope is too broad

Implementation Guide

Current State

Roo already implements a variant of this pattern through its mode-switching architecture. The system supports multiple specialized modes (Architect, Builder, Guardian, Planner, Debug) with distinct capabilities.

Target State

Enhanced boomerang coordination with formalized JSON payloads, persistent state tracking, automatic validation, and systematic retry logic for all mode transitions.

Implementation Steps

Create .roo/boomerang-state.json for persistent task tracking
Define boomerang payload schema with required fields
Standardize mode return formats with JSON schema validation
Implement boomerang validation in Orchestrator mode
Add automatic retry logic for failed boomerangs
Create mode coordination protocol documenting handoff procedures
Implement state snapshot mechanism for recovery
Add monitoring and logging for boomerang flow

Prerequisites

Multiple agent modes or specialists available
JSON-based communication capability
File system access for state persistence
Schema validation capability

Leverage existing multi-mode architecture. Store boomerang state in .roo/boomerang-state.json. Use mode-specific system prompts as specialist boundaries. Implement validation in Orchestrator mode's tool processing.

Mode-specific returns:

Architect returns design docs + ADRs
Builder returns implementation + tests
Guardian returns security analysis + recommendations
Planner returns user stories + acceptance criteria

Adapt state location to .kilo/boomerang-state.json. Use Kilo's existing task queue system for coordination. Leverage Kilo's mode structure with enhanced payload validation. Implement boomerang tracking in Kilo's orchestration layer.

Store state in accessible persistent location
Define clear agent interfaces with capability matrices
Implement timeout handling for long-running tasks
Use structured logging for boomerang flow visibility
Create fallback mechanisms for coordination failures

Examples

Example 1: Multi-File Code Refactoring

User requests refactoring of authentication system across 5 files. Orchestrator creates task map:

Architect analyzes current structure and designs new architecture
Builder implements changes with tests
Guardian reviews security implications

Each specialist completes their task and boomerangs back with structured results. Orchestrator validates each return before triggering the next phase.

{
  "task_id": "auth-refactor-2025-11",
  "origin_mode": "orchestrator",
  "destination_mode": "architect",
  "task_description": "Analyze and design improved authentication architecture",
  "context_snapshot": {
    "files": ["auth.ts", "user.ts", "session.ts"],
    "current_issues": ["tight coupling", "no token refresh"]
  },
  "return_criteria": {
    "deliverable": "architecture_design.md",
    "validation": ["addresses coupling", "includes token refresh"]
  }
}

Outcome: Successfully refactored authentication system with zero rework. Each specialist completed their bounded task. Full traceability through boomerang state tracking. Clean handoffs with validation at each stage.

Example 2: Feature Development Pipeline

Orchestrator receives feature request and creates pipeline: Planner defines user stories → Architect designs system changes → Builder implements → Guardian deploys. Each stage boomerangs back with artifacts. If validation fails at any stage, automatic retry with feedback.

Outcome: Feature delivered through coordinated specialist work. Automatic rollback when Guardian identified security issue. Re-delegation to Builder with specific guidance. Successful deployment on retry.

Validation Criteria

Success Criteria

All mode transitions use structured boomerang payloads
State remains consistent throughout execution
Boomerang validation catches malformed returns before state corruption
Retry logic successfully recovers from transient failures
Zero information loss during mode transitions
Specialist agents operate only within defined boundaries

Anti-Patterns to Avoid

Orchestrator executing specialist work (violates separation of concerns)
Proceeding without validating boomerang returns
Specialists initiating mode switches directly (bypasses orchestrator)
Storing state in specialist modes rather than central orchestrator
Creating circular dependencies between modes

Testing Strategy

Start with single delegation: Create task, delegate to specialist, validate return
Progress to sequential chains: Task A → Task B → Task C with validation at each boomerang
Test error recovery: Introduce validation failures and verify retry logic
Test complex scenarios: Parallel delegations, dependencies, rollback procedures
Monitor state consistency: Throughout all tests

Prompt Engineering Guide