Task Orchestration

Intelligent decomposition and execution of complex features through staged workflows and specialist agent routing.

Status: Implemented (v3.10+). Sugar ships Task Orchestration for intelligent decomposition and execution of complex features through staged workflows and specialist agent routing.

Overview

When Sugar encounters a large feature request, the orchestration system:

1. Detects that the task requires decomposition
2. Researches context via web search and codebase analysis
3. Plans the implementation and generates sub-tasks
4. Routes each sub-task to the appropriate specialist agent
5. Executes sub-tasks in dependency order (sequentially within each wave; intra-wave parallelism is planned)
6. Reviews the completed work before marking done

The 4-Stage Workflow

Large Feature Task
        |
+-----------------------------------------------+
| Stage 1: RESEARCH                             |
| - Web search for best practices               |
| - Gather relevant documentation               |
| - Analyze existing codebase patterns          |
| Agent: tech-lead / Explore                    |
+-----------------------------------------------+
        | (context passes forward)
+-----------------------------------------------+
| Stage 2: PLANNING                             |
| - Create implementation plan                  |
| - Break into sub-tasks                        |
| - Identify specialist agents needed           |
| Agent: tech-lead / Plan                       |
+-----------------------------------------------+
        | (sub-tasks added to queue)
+-----------------------------------------------+
| Stage 3: IMPLEMENTATION (sequential waves)   |
| - Sub-task A: Auth UI    -> frontend-designer |
| - Sub-task B: Auth API   -> backend-developer |
| - Sub-task C: Auth tests -> qa-engineer       |
| - Sub-task D: Auth docs  -> general-purpose   |
+-----------------------------------------------+
        | (all sub-tasks complete)
+-----------------------------------------------+
| Stage 4: REVIEW & INTEGRATION                 |
| - Code review all changes                     |
| - Run full test suite                         |
| - Verify feature works end-to-end             |
| Agent: code-reviewer, qa-engineer             |
+-----------------------------------------------+

CLI Usage

Creating Orchestrated Tasks

# Add a task with explicit orchestration
sugar add "Add user authentication with OAuth support" --type feature --orchestrate

# Skip certain stages if not needed
sugar add "Add logout button" --type feature --orchestrate --skip-stages research,planning

Monitoring Orchestration

# View all orchestrating tasks
sugar orchestrate

# View specific task's orchestration status
sugar orchestrate task-abc123

# View detailed stage information
sugar orchestrate task-abc123 --stages

# View accumulated context from stages
sugar context task-abc123

Specialist Agents

Tasks are automatically routed to specialist agents based on content analysis:

Configuration

Configure orchestration behavior in .sugar/config.yaml:

orchestration:
  enabled: true

  # When to trigger orchestration
  # - auto: System detects complex tasks automatically
  # - explicit: Only when task has --orchestrate flag
  # - disabled: Never orchestrate
  auto_decompose: "auto"

  # Detection rules for auto mode
  detection:
    # Task types that always trigger orchestration
    task_types: ["feature", "epic"]

    # Keywords in title/description that trigger orchestration
    keywords:
      - "implement"
      - "build"
      - "create full"
      - "add complete"
      - "redesign"
      - "refactor entire"

    # Minimum estimated complexity
    min_complexity: "high"

  # Stage definitions
  stages:
    research:
      enabled: true
      agent: "Explore"
      timeout: 600  # 10 minutes
      read_only: true   # analysis only - no file writes

    planning:
      enabled: true
      agent: "Plan"
      timeout: 300  # 5 minutes
      read_only: true   # analysis only - no file writes

    implementation:
      parallel: true              # planned: intra-wave parallelism (not yet honored)
      max_concurrent: 3
      timeout_per_task: 1800  # 30 minutes

    review:
      enabled: true
      run_tests: true
      require_passing: true

Example Workflow

Input Task

sugar add "Add user authentication with OAuth support" --type feature --orchestrate

Stage 1: Research

The Explore agent searches web for "OAuth 2.0 best practices", analyzes codebase for existing auth patterns, checks for existing user models, and reviews dependencies. Research and planning run with a read-only tool set (Read, Glob, Grep, WebSearch, WebFetch) so the agent gathers context without writing files - set read_only: false on the stage to lift this.

Stage 2: Planning

The Plan agent creates implementation plan:

1. Create OAuth Configuration (backend-developer)
2. Implement OAuth Routes (backend-developer)
3. Create Login UI (frontend-designer)
4. Add Session Management (security-engineer)
5. Write Tests (qa-engineer)
6. Update Documentation (general-purpose)

Stage 3: Implementation

Sub-tasks execute in dependency order (sequentially within each wave; intra-wave parallelism is planned):

Parent: "Add user authentication with OAuth support" (orchestrating)
  +-- Sub-task 1: "Create OAuth Configuration" (pending)
  +-- Sub-task 2: "Implement OAuth Routes" (blocked by 1)
  +-- Sub-task 3: "Create Login UI" (blocked by 1)
  +-- Sub-task 4: "Add Session Management" (blocked by 1)
  +-- Sub-task 5: "Write Tests" (blocked by 2,3,4)
  +-- Sub-task 6: "Update Documentation" (pending)

Stage 4: Review

The code-reviewer agent reviews all file changes, and qa-engineer runs full test suite. If review passes, parent task is marked complete. If review fails, issues are added as new tasks.

Context Accumulation

Each stage accumulates context that passes to subsequent stages:

• Research stage saves findings to .sugar/orchestration/{task_id}/research.md
• Planning stage saves plan to .sugar/orchestration/{task_id}/plan.md
• Implementation stage tracks files modified across all sub-tasks
• Review stage has full context for comprehensive validation

Architecture

+------------------------------------------+
|          TaskOrchestrator                |  <- High-level workflow
|  - Stage management                      |
|  - Context accumulation                  |
|  - Sub-task generation                   |
+------------------------------------------+
                   |
                   v
+------------------------------------------+
|            AgentRouter                   |  <- Specialist selection
|  - Pattern matching on task content      |
|  - Maps to specialist agents             |
+------------------------------------------+
                   |
                   v
+------------------------------------------+
|         AgentSDKExecutor                 |  <- Task execution
|  - Agent SDK integration                 |
|  - Sequential dependency-wave execution |
+------------------------------------------+

Note: Subtasks execute in dependency order, sequentially within each wave. Intra-wave parallelism is planned future work (the cached agent mutates shared per-model state, so concurrent calls would race without per-subtask agent isolation). Research and planning stages run read-only.

When to Use Orchestration

Good Candidates

• Large features touching multiple areas (UI, API, DB)
• Features requiring research before implementation
• Complex refactoring spanning many files
• New subsystems or major additions

Not Needed For

• Simple bug fixes
• Single-file changes
• Documentation updates
• Minor UI tweaks

Next Steps

• Agent SDK Integration - Underlying execution engine
• CLI Reference - Full command documentation
• Configuration - All configuration options
• Examples - Real-world usage examples