Boomerang Tasks: Orchestrate Complex Workflows

Boomerang Tasks (also known as subtasks or task orchestration) allow you to break down complex projects into smaller, manageable pieces using the built-in 🪃 Orchestrator Mode (aka Boomerang Mode). Think of it like delegating parts of your work to specialized assistants. Each subtask runs in its own context, often using a different Roo Code mode tailored for that specific job (like 💻 Code, 🏗️ Architect, or 🪲 Debug). The Orchestrator mode manages this process.

Orchestrator Mode is Built-In

The 🪃 Orchestrator mode (previously achieved via a custom "Boomerang Mode") is now a built-in mode specifically designed to orchestrate workflows by breaking down tasks and delegating them to other modes. You no longer need to create a custom mode for this functionality.

Learn more about Built-in Modes.

Why Use Boomerang Tasks?

• Tackle Complexity: Break large, multi-step projects (e.g., building a full feature) into focused subtasks (e.g., design, implementation, documentation).
• Use Specialized Modes: Automatically delegate subtasks to the mode best suited for that specific piece of work, leveraging specialized capabilities for optimal results.
• Maintain Focus & Efficiency: Each subtask operates in its own isolated context with a separate conversation history. This prevents the parent (orchestrator) task from becoming cluttered with the detailed execution steps (like code diffs or file analysis results), allowing it to focus efficiently on the high-level workflow and manage the overall process based on concise summaries from completed subtasks.
• Streamline Workflows: Results from one subtask can be automatically passed to the next, creating a smooth flow (e.g., architectural decisions feeding into the coding task).

How It Works

1. When in the 🪃 Orchestrator mode (aka Boomerang Mode), Roo analyzes a complex task and suggests breaking it down into a subtask¹.

2. The parent task (in Orchestrator mode) pauses, and the new subtask begins in a different, specialized mode².

3. When the subtask's goal is achieved, Roo signals completion.

4. The parent task resumes with only the summary³ of the subtask. The parent uses this summary to continue the main workflow.

Key Considerations

• Approval Required: By default, you must approve the creation and completion of each subtask. This can be automated via the Auto-Approving Actions settings if desired.
• Context Isolation and Transfer: Each subtask operates in complete isolation with its own conversation history. It does not automatically inherit the parent's context. Information must be explicitly passed:
  • Down: Via the initial instructions provided when the subtask is created.
  • Up: Via the final summary provided when the subtask finishes. Be mindful that only this summary returns to the parent.
• Navigation: Roo's interface helps you see the hierarchy of tasks (which task is the parent, which are children). You can typically navigate between active and paused tasks.

Boomerang Tasks provide a powerful way to manage complex development workflows directly within Roo Code, leveraging specialized modes for maximum efficiency.

Keep Tasks Focused

Use subtasks (delegated via Orchestrator mode) to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one.

Footnotes

1. This context is passed via the message parameter of the new_task tool when the Orchestrator mode delegates the task. ↩

2. The mode for the subtask is specified via the mode parameter of the new_task tool during initiation by the Orchestrator mode. ↩

3. This summary is passed via the result parameter of the attempt_completion tool when the subtask finishes. ↩