Version:
← All Docs

Task Orchestration

Sugar 3.0 introduces 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 with parallelism where possible
  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 (parallel)            |
| - 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:

Agent Use Case Pattern Match
frontend-designer UI/UX, components, styling *ui*, *frontend*, *component*, *design*
backend-developer APIs, databases, server logic *api*, *backend*, *endpoint*, *service*
qa-engineer Testing, test strategies *test*, *spec*, *coverage*
security-engineer Auth, vulnerabilities *security*, *auth*, *permission*
devops-engineer CI/CD, infrastructure *devops*, *deploy*, *ci*, *docker*
code-reviewer Code review, refactoring Used in review stage
tech-lead Architecture, planning Used in research/planning stages
general-purpose Default for most tasks *doc*, *readme*, *guide*, default

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

    planning:
      enabled: true
      agent: "Plan"
      timeout: 300  # 5 minutes

    implementation:
      parallel: true
      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.

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 parallel (respecting dependencies):

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
+------------------------------------------+
|          SubAgentManager                 |  <- Parallel execution
|  - Concurrency control                   |
|  - Isolated execution                    |
+------------------------------------------+
                   |
                   v
+------------------------------------------+
|         AgentSDKExecutor                 |  <- Task execution
|  - Agent SDK integration                 |
+------------------------------------------+

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