task-orchestration

What this skill does

# Task Orchestration

**Version:** 2.0.0
**Purpose:** Patterns for using Tasks system in complex multi-phase workflows
**Status:** Production Ready

## Overview

Task orchestration is the practice of using the Tasks system (TaskCreate, TaskUpdate, TaskList, TaskGet) to provide **real-time progress visibility** in complex multi-phase workflows. It transforms opaque "black box" workflows into transparent, trackable processes where users can see:

- What phase is currently executing
- How many phases remain
- Which tasks are pending, in-progress, or completed
- Overall progress percentage
- Iteration counts in loops
- Task dependencies and blocking relationships

This skill provides battle-tested patterns for:
- **Phase initialization** (create complete task list before starting)
- **Task granularity** (how to break phases into trackable tasks)
- **Status transitions** (pending → in_progress → completed)
- **Real-time updates** (mark complete immediately, not batched)
- **Iteration tracking** (progress through loops)
- **Parallel task tracking** (multiple agents executing simultaneously)
- **Task dependencies** (blockedBy/blocks relationships)
- **Cross-session persistence** (resume work across sessions)

Task orchestration is especially valuable for workflows with >5 phases or >10 minutes duration, where users need progress feedback.

## Tasks System API

The Tasks system provides 4 tools:

**TaskCreate**: Create a new task
```
TaskCreate:
  subject: "PHASE 1: Gather requirements"
  description: "Ask user for feature requirements"
  activeForm: "Gathering requirements"
  status: "pending"
  blockedBy: ["prerequisite-task-id"]  // Optional
  owner: "agent-name"                   // Optional
```

**TaskUpdate**: Update task status or fields
```
TaskUpdate: taskId="task-123", status="in_progress"
TaskUpdate: taskId="task-123", status="completed"
TaskUpdate: taskId="task-123", description="Updated description"
```

**TaskList**: View all tasks
```
TaskList  // Shows all tasks with statuses
```

**TaskGet**: Get specific task details
```
TaskGet: taskId="task-123"
```

## Core Patterns

### Pattern 1: Phase Initialization

**Create Tasks BEFORE Starting:**

Initialize Tasks as **step 0** of your workflow, before any actual work begins:

```
✅ CORRECT - Initialize First:

Step 0: Initialize Tasks
  TaskCreate:
    subject: "PHASE 1: Gather user inputs"
    activeForm: "Gathering inputs"

  TaskCreate:
    subject: "PHASE 1: Validate inputs"
    activeForm: "Validating inputs"
    blockedBy: ["phase-1-gather-id"]

  TaskCreate:
    subject: "PHASE 2: Select AI models"
    activeForm: "Selecting models"

  TaskCreate:
    subject: "PHASE 2: Estimate costs"
    activeForm: "Estimating costs"

  TaskCreate:
    subject: "PHASE 3: Launch parallel reviews"
    activeForm: "Launching reviews"
    blockedBy: ["phase-2-approve-id"]

  TaskCreate:
    subject: "PHASE 4: Consolidate reviews"
    activeForm: "Consolidating"

  TaskCreate:
    subject: "PHASE 5: Present results"
    activeForm: "Presenting"

Step 1: Start actual work (PHASE 1)
  TaskUpdate: taskId="phase-1-gather-id", status="in_progress"
  ... do work ...
  TaskUpdate: taskId="phase-1-gather-id", status="completed"

  TaskUpdate: taskId="phase-1-validate-id", status="in_progress"
  ... do work ...

❌ WRONG - Create During Workflow:

Step 1: Do some work
  ... work happens ...
  TaskCreate: subject="Did some work", status="completed"

Step 2: Do more work
  ... work happens ...
  TaskCreate: subject="Did more work", status="completed"

Problem: User has no visibility into upcoming phases
```

**List All Phases Upfront:**

When initializing, create **all tasks** in the workflow, not just the current phase:

```
✅ CORRECT - Complete Visibility:

TaskCreate: subject="PHASE 1: Gather user inputs"
TaskCreate: subject="PHASE 1: Validate inputs"
TaskCreate: subject="PHASE 2: Architecture planning"
TaskCreate: subject="PHASE 3: Implementation"
TaskCreate: subject="PHASE 3: Run quality checks"
TaskCreate: subject="PHASE 4: Code review"
TaskCreate: subject="PHASE 5: User acceptance"
TaskCreate: subject="PHASE 6: Generate report"

User sees: "8 tasks total, 0 complete, Phase 1 starting"

❌ WRONG - Incremental Discovery:

TaskCreate: subject="PHASE 1: Gather user inputs"
TaskCreate: subject="PHASE 1: Validate inputs"

(User thinks workflow is 2 tasks, then surprised by 6 more phases)
```

**Why Initialize First:**

1. **User expectation setting:** User knows workflow scope (8 phases, ~20 minutes)
2. **Progress visibility:** User can see % complete (3/8 = 37.5%)
3. **Time estimation:** User can estimate remaining time based on progress
4. **Transparency:** No hidden phases or surprises

---

### Pattern 2: Task Granularity Guidelines

**One Task Per Significant Operation:**

Each task should represent a **significant operation** (1-5 minutes of work):

```
✅ CORRECT - Significant Operations:

TaskCreate: subject="PHASE 1: Ask user for inputs", activeForm="Asking user"
TaskCreate: subject="PHASE 2: Generate architecture plan", activeForm="Generating plan"
TaskCreate: subject="PHASE 3: Implement feature", activeForm="Implementing"
TaskCreate: subject="PHASE 4: Run tests", activeForm="Running tests"
TaskCreate: subject="PHASE 5: Code review", activeForm="Reviewing"

Each task = meaningful unit of work

❌ WRONG - Too Granular:

TaskCreate: subject="PHASE 1: Ask user question 1"
TaskCreate: subject="PHASE 1: Ask user question 2"
TaskCreate: subject="PHASE 1: Ask user question 3"
TaskCreate: subject="PHASE 2: Read file A"
TaskCreate: subject="PHASE 2: Read file B"
... (50 micro-tasks)

Problem: Too many updates, clutters user interface
```

**Multi-Step Phases: Break Into 2-3 Sub-Tasks:**

For complex phases (>5 minutes), break into 2-3 sub-tasks:

```
✅ CORRECT - Sub-Task Breakdown:

PHASE 3: Implementation (15 min total)
  → Sub-tasks:
    TaskCreate: subject="PHASE 3: Implement core logic", activeForm="Implementing core"
    TaskCreate: subject="PHASE 3: Add error handling", activeForm="Adding error handling"
    TaskCreate: subject="PHASE 3: Write tests", activeForm="Writing tests"

User sees progress within phase: "PHASE 3: 2/3 complete"

❌ WRONG - Single Monolithic Task:

TaskCreate: subject="PHASE 3: Implementation"

Problem: User sees "in_progress" for 15 min with no updates
```

**Avoid Too Many Tasks:**

Limit to **max 15-20 tasks** for readability:

```
✅ CORRECT - 12 Tasks (readable):

10-phase workflow:
  TaskCreate: subject="PHASE 1: Ask user"
  TaskCreate: subject="PHASE 2: Plan architecture"
  TaskCreate: subject="PHASE 2: Review plan"
  TaskCreate: subject="PHASE 3: Implement core"
  TaskCreate: subject="PHASE 3: Add error handling"
  TaskCreate: subject="PHASE 3: Write tests"
  TaskCreate: subject="PHASE 4: Test"
  TaskCreate: subject="PHASE 5: Review code"
  TaskCreate: subject="PHASE 5: Fix issues"
  TaskCreate: subject="PHASE 6: Re-review"
  TaskCreate: subject="PHASE 7: Accept"
  TaskCreate: subject="PHASE 8: Document"

Total: 12 tasks (clean, trackable)

❌ WRONG - 50 Tasks (overwhelming):

Every single action as separate task:
  TaskCreate: subject="Read file 1"
  TaskCreate: subject="Read file 2"
  TaskCreate: subject="Write file 3"
  ... (50 tasks)

Problem: User overwhelmed, can't see forest for trees
```

**Guideline by Workflow Duration:**

```
Workflow Duration → Task Count:

< 5 minutes:    3-5 tasks
5-15 minutes:   8-12 tasks
15-30 minutes:  12-18 tasks
> 30 minutes:   15-20 tasks (if more, group into phases)

Example:
  5-minute workflow (3 phases):
    TaskCreate: subject="PHASE 1: Prepare"
    TaskCreate: subject="PHASE 2: Execute"
    TaskCreate: subject="PHASE 3: Present"
  Total: 3 tasks ✓

  20-minute workflow (6 phases):
    TaskCreate: subject="PHASE 1: Ask user"
    TaskCreate: subject="PHASE 2: Plan architecture"
    TaskCreate: subject="PHASE 2: Review plan"
    TaskCreate: subject="PHASE 3: Implement core"
    TaskCreate: subject="PHASE 3: Add error handling"
    TaskCreate: s