task-orchestration

# 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: 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"
  Total: 11 tasks ✓
```

---

### Pattern 3: Status Transitions

**Exactly ONE Task In Progress at a Time:**

Maintain the invariant: **exactly one task in_progress** at any moment:

```
✅ CORRECT - One In-Progress:

State at time T1:
  [✓] PHASE 1: Ask user (completed)
  [✓] PHASE 2: Plan (completed)
  [→] PHASE 3: Implement (in_progress)  ← Only one
  [ ] PHASE 4: Test (pending)
  [ ] PHASE 5: Review (pending)

State at time T2 (after PHASE 3 completes):
  [✓] PHASE 1: Ask user (completed)
  [✓] PHASE 2: Plan (completed)
  [✓] PHASE 3: Implement (completed)
  [→] PHASE 4: Test (in_progress)  ← Only one
  [ ] PHASE 5: Review (pending)

❌ WRONG - Multiple In-Progress:

State:
  [✓] PHASE 1: Ask user (completed)
  [→] PHASE 2: Plan (in_progress)  ← Two in-progress?
  [→] PHASE 3: Implement (in_progress)  ← Confusing!
  [ ] PHASE 4: Test (pending)

Problem: User confused about current phase
```

**Status Transition Sequence:**

```
Lifecycle of a Task:

1. Created: pending
   TaskCreate: subject="PHASE 1: Gather inputs", status="pending"

2. Started: pending → in_progress
   TaskUpdate: taskId="phase-1-id", status="in_progress"

3. Completed: in_progress → completed
   TaskUpdate: taskId="phase-1-id", status="completed"

4. Next task: Mark next task as in_progress
   TaskUpdate: taskId="phase-2-id", status="in_progress"

Example Timeline:

T=0s:  TaskUpdate: taskId="task-1-id", status="in_progress"
       [→] Task 1 (in_progress), [ ] Task 2 (pending)

T=30s: TaskUpdate: taskId="task-1-id", status="completed"
       TaskUpdate: taskId="task-2-id", status="in_progress"
       [✓] Task 1 (completed), [→] Task 2 (in_progress)

T=60s: TaskUpdate: taskId="task-2-id", status="completed"
       [✓] Task 1 (completed), [✓] Task 2 (completed)
```

**NEVER Batch Completions:**

Mark tasks completed **immediately** after finishing, not at end of phase:

```
✅ CORRECT - Immediate Updates:

TaskUpdate: taskId="phase-1-ask-id", status="in_progress"
... do work (30s) ...
TaskUpdate: taskId="phase-1-ask-id", status="completed"  ← Immediate

TaskUpdate: taskId="phase-1-validate-id", status="in_progress"
... do work (20s) ...
TaskUpdate: taskId="phase-1-validate-id", status="completed"  ← Immediate

User sees real-time progress

❌ WRONG - Batched Updates:

TaskUpdate: taskId="phase-1-ask-id", status="in_progress"
... do work (30s) ...

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

(At end of PHASE 1, batch update both to completed)

Problem: User doesn't see progress for 50s, thinks workflow is stuck
```

---

### Pattern 4: Real-Time Progress Tracking

**TaskUpdate As Work Progresses:**

Tasks should reflect **current state**, not past state:

```
✅ CORRECT - Real-Time Updates:

T=0s:  Initialize Tasks (8 tasks, all pending)
T=5s:  TaskUpdate: taskId="phase-1-id", status="in_progress"
T=35s: TaskUpdate: taskId="phase-1-id", status="completed"
       TaskUpdate: taskId="phase-2-id", status="in_progress"
T=90s: TaskUpdate: taskId="phase-2-id", status="completed"
       TaskUpdate: taskId="phase-3-id", status="in_progress"
...

User always sees accurate current state

❌ WRONG - Delayed Updates:

T=0s:   Initialize Tasks
T=300s: Workflow completes
T=301s: Update all tasks to completed

Problem: No progress visibility for 5 minutes
```

**Add New Tasks If Discovered During Execution:**

If you discover additional work during execution, create new tasks:

```
Scenario: During implementation, realize refactoring needed

Initial Tasks:
  [✓] PHASE 1: Plan (completed)
  [→] PHASE 2: Implement (in_progress)
  [ ] PHASE 3: Test (pending)
  [ ] PHASE 4: Review (pending)

During PHASE 2, discover:
  "Implementation requires refactoring legacy code"

TaskUpdate: taskId="phase-2-id", status="completed"
TaskCreate: subject="PHASE 2: Refactor legacy code", activeForm="Refactoring"
TaskUpdate: taskId="new-refactor-id", status="in_progress"

Updated Tasks:
  [✓] PHASE 1: Plan
  [✓] PHASE 2: Implement core logic
  [→] PHASE 2: Refactor legacy code (in_progress)  ← New task
  [ ] PHASE 3: Test
  [ ] PHASE 4: Review

User sees: "Additional work discovered: refactoring. Total now 5 tasks."
```

**User Can See Current Progress at Any Time:**

With real-time updates, user can check progress:

```
User checks at T=120s:

TaskList shows:
  [✓] PHASE 1: Ask user
  [✓] PHASE 2: Plan architecture
  [→] PHASE 3: Implement core logic (in_progress)
  [ ] PHASE 3: Add error handling
  [ ] PHASE 3: Write tests
  [ ] PHASE 4: Code review
  [ ] PHASE 5: Accept

User sees: "3/7 tasks complete (42.8%), currently implementing core logic"
```

---

### Pattern 5: Iteration Loop Tracking

**Create Task Per Iteration:**

For iteration loops, create a task for each iteration:

```
✅ CORRECT - Iteration Tasks:

Design Validation Loop (max 10 iterations):

Initial Tasks:
  TaskCreate: subject="Iteration 1/10: Designer validation"
  TaskCreate: subject="Iteration 2/10: Designer validation"
  TaskCreate: subject="Iteration 3/10: Designer validation"
  ... (create all 10 upfront)

Progress:
  [✓] Iteration 1/10: Designer validation (NEEDS IMPROVEMENT)
  [✓] Iteration 2/10: Designer validation (NEEDS IMPROVEMENT)
  [→] Iteration 3/10: Designer validation (in_progress)
  [ ] Iteration 4/10: Designer validation
  ...

User sees: "Iteration 3/10 in progress, 2 complete"

❌ WRONG - Single Loop Task:

TaskCreate: subject="Design validation loop"

Problem: User sees "in_progress" for 10 minutes, no iteration visibility
```

**Mark Iteration Complete When Done:**

```
Iteration Lifecycle:

Iteration 1:
  TaskUpdate: taskId="iter-1-id", status="in_progress"
  Run designer validation
  If NEEDS IMPROVEMENT: Run developer fixes
  TaskUpdate: taskId="iter-1-id", status="completed"

Iteration 2:
  TaskUpdate: taskId="iter-2-id", status="in_progress"
  Run designer validation
  If PASS: Exit loop early
  TaskUpdate: taskId="iter-2-id", status="completed"

Result: Loop exited after 2 iterations
  [✓] Iteration 1/10 (completed)
  [✓] Iteration 2/10 (completed)
  [ ] Iteration 3/10 (not needed, loop exited)
  ...

User sees: "Loop completed in 2/10 iterations"
```

**Track Total Iterations vs Max Limit:**

```
Iteration Progress:

Max: 10 iterations
Current: 5

TaskList shows:
  [✓] Iteration 1/10
  [✓] Iteration 2/10
  [✓] Iteration 3/10
  [✓] Iteration 4/10
  [→] Iteration 5/10
  [ ] Iteration 6/10
  ...

User sees: "Iteration 5/10 (50% through max)"

Warning at Iteration 8:
  "Iteration 8/10 - approaching max, may escalate to user if not PASS"
```

---

### Pattern 6: Parallel Task Tracking

**Multiple Agents Executing Simultaneously:**

When running agents in parallel, track each separately:

```
✅ CORRECT - Separate Tasks for Parallel Agents:

Multi-Model Review (3 models in parallel):

TaskCreate: subject="PHASE 1: Prepare review context"
TaskCreate: subject="PHASE 2: Claude review", owner="claude-agent"
TaskCreate: subject="PHASE 2: Grok review", owner="grok-agent"
TaskCreate: subject="PHASE 2: Gemini review", owner="gemini-agent"
TaskCreate: subject="PHASE 3: Consolidate reviews"

Launch parallel reviews:
  TaskUpdate: taskId="claude-review-id", status="in_progress"
  TaskUpdate: taskId="grok-review-id", status="in_progress"
  TaskUpdate: taskId="gemini-review-id", status="in_progress"

State:
  [✓] PHASE 1: Prepare review context
  [→] PHASE 2: Claude review (in_progress)
  [→] PHASE 2: Grok review (in_progress)
  [→] PHASE 2: Gemini review (in_progress)
  [ ] PHASE 3: Consolidate reviews

Note: 3 tasks "in_progress" is OK for parallel execution
      (Exception to "one in_progress" rule)

As models complete:
  [✓] PHASE 1: Prepare review context
  [✓] PHASE 2: Claude review (completed)  ← First to finish
  [→] PHASE 2: Grok review (in_progress)
  [→] PHASE 2: Gemini review (in_progress)
  [ ] PHASE 3: Consolidate reviews

User sees: "1/3 reviews complete, 2 in progress"

❌ WRONG - Single Task for Parallel Work:

TaskCreate: subject="PHASE 2: Run 3 reviews"

Problem: No visibility into which reviews are complete
```

**Update As Each Agent Completes:**

```
Parallel Execution Timeline:

T=0s:  Launch 3 reviews in parallel
  TaskUpdate: taskId="claude-id", status="in_progress"
  TaskUpdate: taskId="grok-id", status="in_progress"
  TaskUpdate: taskId="gemini-id", status="in_progress"

  [→] Claude review (in_progress)
  [→] Grok review (in_progress)
  [→] Gemini review (in_progress)

T=60s: Claude completes first
  TaskUpdate: taskId="claude-id", status="completed"

  [✓] Claude review (completed)
  [→] Grok review (in_progress)
  [→] Gemini review (in_progress)

T=120s: Gemini completes
  TaskUpdate: taskId="gemini-id", status="completed"

  [✓] Claude review (completed)
  [→] Grok review (in_progress)
  [✓] Gemini review (completed)

T=180s: Grok completes
  TaskUpdate: taskId="grok-id", status="completed"

  [✓] Claude review (completed)
  [✓] Grok review (completed)
  [✓] Gemini review (completed)

User sees real-time completion updates
```

---

### Pattern 7: Task Dependencies

**Use blockedBy for Phase Dependencies:**

Track which tasks must complete before others can start:

```
✅ CORRECT - Dependency Tracking:

TaskCreate:
  subject: "PHASE 1: Gather requirements"
  activeForm: "Gathering requirements"
  // Returns taskId: "phase-1-id"

TaskCreate:
  subject: "PHASE 2: Design architecture"
  activeForm: "Designing"
  blockedBy: ["phase-1-id"]  ← Blocks until PHASE 1 complete

TaskCreate:
  subject: "PHASE 3: Implementation"
  activeForm: "Implementing"
  blockedBy: ["phase-2-id"]  ← Blocks until PHASE 2 complete

When PHASE 1 completes:
  TaskUpdate: taskId="phase-1-id", status="completed"
  → PHASE 2 automatically unblocked

Benefits:
- System prevents starting PHASE 2 before PHASE 1 complete
- User sees dependency chain
- Automatic unblocking when prerequisites complete
```

**Parallel Tasks with Shared Blocker:**

Multiple tasks can depend on same prerequisite:

```
TaskCreate:
  subject: "PHASE 1: Prepare context"
  // Returns: "context-id"

TaskCreate:
  subject: "PHASE 2: Claude review"
  owner: "claude-agent"
  blockedBy: ["context-id"]

TaskCreate:
  subject: "PHASE 2: Grok review"
  owner: "grok-agent"
  blockedBy: ["context-id"]

TaskCreate:
  subject: "PHASE 2: Gemini review"
  owner: "gemini-agent"
  blockedBy: ["context-id"]

When context preparation completes:
  TaskUpdate: taskId="context-id", status="completed"
  → All 3 reviews automatically unblocked and can start in parallel
```

**Complex Dependency Chains:**

```
Sequential with parallel phases:

TaskCreate: subject="PHASE 1: Requirements"
  → phase-1-id

TaskCreate: subject="PHASE 2: Design"
  blockedBy: ["phase-1-id"]
  → phase-2-id

TaskCreate: subject="PHASE 3: Implement Backend"
  owner: "backend-developer"
  blockedBy: ["phase-2-id"]
  → backend-id

TaskCreate: subject="PHASE 3: Implement Frontend"
  owner: "frontend-developer"
  blockedBy: ["phase-2-id"]
  → frontend-id

TaskCreate: subject="PHASE 4: Integration Tests"
  blockedBy: ["backend-id", "frontend-id"]  ← Waits for both
  → integration-id

Execution:
1. PHASE 1 completes → Unblocks PHASE 2
2. PHASE 2 completes → Unblocks Backend + Frontend (parallel)
3. Both Backend + Frontend complete → Unblocks Integration Tests
```

---

### Pattern 8: Cross-Session Persistence

**Resume Work Across Sessions:**

Tasks persist across Claude Code sessions when using CLAUDE_CODE_TASK_LIST_ID:

```
Session 1 (Initial Implementation):

# Set task list ID for this feature
export CLAUDE_CODE_TASK_LIST_ID=feature-auth
claude

# Create tasks
TaskCreate: subject="PHASE 1: Design auth flow"
TaskCreate: subject="PHASE 2: Implement backend"
TaskCreate: subject="PHASE 3: Implement frontend"
TaskCreate: subject="PHASE 4: Testing"

# Complete PHASE 1
TaskUpdate: taskId="phase-1-id", status="in_progress"
... work ...
TaskUpdate: taskId="phase-1-id", status="completed"

# Start PHASE 2 (not finished)
TaskUpdate: taskId="phase-2-id", status="in_progress"
... partial work ...
exit

---

Session 2 (Resume Later):

# Same task list ID
export CLAUDE_CODE_TASK_LIST_ID=feature-auth
claude

# Tasks still visible!
TaskList shows:
  [✓] PHASE 1: Design auth flow (completed)
  [→] PHASE 2: Implement backend (in_progress)  ← Resume here
  [ ] PHASE 3: Implement frontend
  [ ] PHASE 4: Testing

# Continue where left off
... complete PHASE 2 ...
TaskUpdate: taskId="phase-2-id", status="completed"

# Start PHASE 3
TaskUpdate: taskId="phase-3-id", status="in_progress"
```

**Benefits:**

- Work on large features across multiple sessions
- Never lose progress tracking
- Team members can see task status
- Clear handoff points between sessions

**Best Practices:**

```
✅ Use meaningful task list IDs:
  export CLAUDE_CODE_TASK_LIST_ID=feature-auth
  export CLAUDE_CODE_TASK_LIST_ID=bug-payment-failure
  export CLAUDE_CODE_TASK_LIST_ID=refactor-api

❌ Avoid generic IDs:
  export CLAUDE_CODE_TASK_LIST_ID=work
  export CLAUDE_CODE_TASK_LIST_ID=tasks
```

---

## Integration with Other Skills

**task-orchestration + multi-agent-coordination:**

```
Use Case: Multi-phase implementation workflow

Step 1: Initialize Tasks (task-orchestration)
  TaskCreate: subject="PHASE 1: Requirements"
  TaskCreate: subject="PHASE 2: Architecture"
  TaskCreate: subject="PHASE 3: Backend Implementation"
  TaskCreate: subject="PHASE 4: Frontend Implementation"
  TaskCreate: subject="PHASE 5: Testing"
  ... (8 total phases)

Step 2: Sequential Agent Delegation (multi-agent-coordination)
  Phase 1: api-architect
    TaskUpdate: taskId="phase-1-id", status="in_progress"
    Delegate to api-architect
    TaskUpdate: taskId="phase-1-id", status="completed"

  Phase 2: backend-developer
    TaskUpdate: taskId="phase-2-id", status="in_progress"
    Delegate to backend-developer
    TaskUpdate: taskId="phase-2-id", status="completed"

  ... continue for all phases
```

**task-orchestration + multi-model-validation:**

```
Use Case: Multi-model review with progress tracking

Step 1: Initialize Tasks (task-orchestration)
  TaskCreate: subject="PHASE 1: Prepare context"
  TaskCreate: subject="PHASE 2: Claude review", owner="claude"
  TaskCreate: subject="PHASE 2: Grok review", owner="grok"
  TaskCreate: subject="PHASE 2: Gemini review", owner="gemini"
  TaskCreate: subject="PHASE 2: GPT-5 review", owner="gpt"
  TaskCreate: subject="PHASE 2: DeepSeek review", owner="deepseek"
  TaskCreate: subject="PHASE 3: Consolidate results"

Step 2: Parallel Execution (multi-model-validation)
  TaskUpdate: taskId="phase-1-id", status="in_progress"
  ... prepare context ...
  TaskUpdate: taskId="phase-1-id", status="completed"

  Launch all 5 models simultaneously
  TaskUpdate: taskId="claude-id", status="in_progress"
  TaskUpdate: taskId="grok-id", status="in_progress"
  ... (all 5 in_progress)

  As each completes: TaskUpdate with status="completed"

Step 3: Real-Time Visibility (task-orchestration)
  User sees: "PHASE 2: 3/5 reviews complete..."
```

**task-orchestration + quality-gates:**

```
Use Case: Iteration loop with Tasks tracking

Step 1: Initialize Tasks (task-orchestration)
  TaskCreate: subject="Iteration 1/10: Designer validation"
  TaskCreate: subject="Iteration 2/10: Designer validation"
  TaskCreate: subject="Iteration 3/10: Designer validation"
  ... (10 iterations)

Step 2: Iteration Loop (quality-gates)
  For i = 1 to 10:
    TaskUpdate: taskId="iter-i-id", status="in_progress"
    Run designer validation
    If PASS: Exit loop
    TaskUpdate: taskId="iter-i-id", status="completed"

Step 3: Progress Visibility
  User sees: "Iteration 5/10 complete, 5 remaining"
```

---

## Best Practices

**Do:**
- ✅ Initialize Tasks BEFORE starting work (step 0)
- ✅ Create ALL phase tasks upfront (user sees complete scope)
- ✅ Use 8-15 tasks for typical workflows (readable)
- ✅ TaskUpdate to completed IMMEDIATELY after finishing (real-time)
- ✅ Keep exactly ONE task in_progress (except parallel tasks)
- ✅ Track iterations separately (Iteration 1/10, 2/10, ...)
- ✅ Update as work progresses (not batched at end)
- ✅ Create new tasks if discovered during execution
- ✅ Use blockedBy for dependencies
- ✅ Use owner field for parallel agent tracking
- ✅ Use CLAUDE_CODE_TASK_LIST_ID for cross-session work

**Don't:**
- ❌ Create tasks during workflow (initialize first)
- ❌ Hide phases from user (create all upfront)
- ❌ Create too many tasks (>20 overwhelms user)
- ❌ Batch completions at end of phase (update real-time)
- ❌ Leave multiple tasks in_progress (pick one, except parallel)
- ❌ Use single task for loop (track iterations separately)
- ❌ Update only at start/end (update during execution)

**Performance:**
- TaskUpdate overhead: <1s per update (negligible)
- User visibility benefit: Reduces perceived wait time 30-50%
- Workflow confidence: User knows progress, less likely to cancel

---

## Examples

### Example 1: 8-Phase Implementation Workflow

**Scenario:** Full-cycle implementation with Tasks tracking

**Execution:**

```
Step 0: Initialize Tasks

TaskCreate:
  subject: "PHASE 1: Ask user for requirements"
  activeForm: "Asking user"
  // Returns: "phase-1-id"

TaskCreate:
  subject: "PHASE 2: Generate architecture plan"
  activeForm: "Generating plan"
  blockedBy: ["phase-1-id"]
  // Returns: "phase-2-id"

TaskCreate:
  subject: "PHASE 3: Implement core logic"
  activeForm: "Implementing core"
  blockedBy: ["phase-2-id"]
  // Returns: "phase-3a-id"

TaskCreate:
  subject: "PHASE 3: Add error handling"
  activeForm: "Adding error handling"
  blockedBy: ["phase-3a-id"]
  // Returns: "phase-3b-id"

TaskCreate:
  subject: "PHASE 3: Write tests"
  activeForm: "Writing tests"
  blockedBy: ["phase-3b-id"]
  // Returns: "phase-3c-id"

TaskCreate:
  subject: "PHASE 4: Run test suite"
  activeForm: "Running tests"
  blockedBy: ["phase-3c-id"]
  // Returns: "phase-4-id"

TaskCreate:
  subject: "PHASE 5: Code review"
  activeForm: "Reviewing"
  blockedBy: ["phase-4-id"]
  // Returns: "phase-5-id"

TaskCreate:
  subject: "PHASE 6: Fix review issues"
  activeForm: "Fixing issues"
  blockedBy: ["phase-5-id"]
  // Returns: "phase-6-id"

TaskCreate:
  subject: "PHASE 7: User acceptance"
  activeForm: "User validating"
  blockedBy: ["phase-6-id"]
  // Returns: "phase-7-id"

TaskCreate:
  subject: "PHASE 8: Generate report"
  activeForm: "Generating report"
  blockedBy: ["phase-7-id"]
  // Returns: "phase-8-id"

User sees: "10 tasks, 0 complete, Phase 1 starting..."

---

Step 1: PHASE 1

TaskUpdate: taskId="phase-1-id", status="in_progress"
... gather requirements (30s) ...
TaskUpdate: taskId="phase-1-id", status="completed"
→ Automatically unblocks PHASE 2

User sees: "1/10 tasks complete (10%)"

---

Step 2: PHASE 2

TaskUpdate: taskId="phase-2-id", status="in_progress"
... generate plan (2 min) ...
TaskUpdate: taskId="phase-2-id", status="completed"
→ Automatically unblocks PHASE 3

User sees: "2/10 tasks complete (20%)"

---

Step 3: PHASE 3 (3 sub-tasks)

TaskUpdate: taskId="phase-3a-id", status="in_progress"
... implement core (3 min) ...
TaskUpdate: taskId="phase-3a-id", status="completed"
→ Automatically unblocks "Add error handling"

User sees: "3/10 tasks complete (30%)"

TaskUpdate: taskId="phase-3b-id", status="in_progress"
... add error handling (2 min) ...
TaskUpdate: taskId="phase-3b-id", status="completed"
→ Automatically unblocks "Write tests"

User sees: "4/10 tasks complete (40%)"

TaskUpdate: taskId="phase-3c-id", status="in_progress"
... write tests (3 min) ...
TaskUpdate: taskId="phase-3c-id", status="completed"
→ Automatically unblocks PHASE 4

User sees: "5/10 tasks complete (50%)"

---

... continue through all phases ...

---

Final State:

TaskList shows:
  [✓] PHASE 1: Ask user for requirements
  [✓] PHASE 2: Generate architecture plan
  [✓] PHASE 3: Implement core logic
  [✓] PHASE 3: Add error handling
  [✓] PHASE 3: Write tests
  [✓] PHASE 4: Run test suite
  [✓] PHASE 5: Code review
  [✓] PHASE 6: Fix review issues
  [✓] PHASE 7: User acceptance
  [✓] PHASE 8: Generate report

User sees: "10/10 tasks complete (100%). Workflow finished!"

Total Duration: ~15 minutes
User Experience: Continuous progress updates every 1-3 minutes
```

---

### Example 2: Iteration Loop with Progress Tracking

**Scenario:** Design validation with 10 max iterations

**Execution:**

```
Step 0: Initialize Tasks

TaskCreate:
  subject: "PHASE 1: Gather design reference"
  activeForm: "Gathering design"
  // Returns: "phase-1-id"

TaskCreate:
  subject: "Iteration 1/10: Designer validation"
  activeForm: "Designer validating (iter 1)"
  blockedBy: ["phase-1-id"]
  // Returns: "iter-1-id"

TaskCreate:
  subject: "Iteration 2/10: Designer validation"
  activeForm: "Designer validating (iter 2)"
  // Returns: "iter-2-id"

TaskCreate:
  subject: "Iteration 3/10: Designer validation"
  activeForm: "Designer validating (iter 3)"
  // Returns: "iter-3-id"

... (create all 10 iterations) ...

TaskCreate:
  subject: "PHASE 3: User validation gate"
  activeForm: "User validating"
  // Returns: "phase-3-id"

---

Step 1: PHASE 1

TaskUpdate: taskId="phase-1-id", status="in_progress"
... gather design (20s) ...
TaskUpdate: taskId="phase-1-id", status="completed"
→ Unblocks Iteration 1

---

Step 2: Iteration Loop

Iteration 1:
  TaskUpdate: taskId="iter-1-id", status="in_progress"
  Designer: "NEEDS IMPROVEMENT - 5 issues"
  Developer: Fix 5 issues
  TaskUpdate: taskId="iter-1-id", status="completed"
  User sees: "Iteration 1/10 complete, 5 issues fixed"

Iteration 2:
  TaskUpdate: taskId="iter-2-id", status="in_progress"
  Designer: "NEEDS IMPROVEMENT - 3 issues"
  Developer: Fix 3 issues
  TaskUpdate: taskId="iter-2-id", status="completed"
  User sees: "Iteration 2/10 complete, 3 issues fixed"

Iteration 3:
  TaskUpdate: taskId="iter-3-id", status="in_progress"
  Designer: "NEEDS IMPROVEMENT - 1 issue"
  Developer: Fix 1 issue
  TaskUpdate: taskId="iter-3-id", status="completed"
  User sees: "Iteration 3/10 complete, 1 issue fixed"

Iteration 4:
  TaskUpdate: taskId="iter-4-id", status="in_progress"
  Designer: "PASS ✓"
  TaskUpdate: taskId="iter-4-id", status="completed"
  Exit loop (early exit)
  User sees: "Loop completed in 4/10 iterations"

---

Step 3: PHASE 3

TaskUpdate: taskId="phase-3-id", status="in_progress"
... user validates ...
TaskUpdate: taskId="phase-3-id", status="completed"

---

Final State:

TaskList shows:
  [✓] PHASE 1: Gather design
  [✓] Iteration 1/10 (5 issues fixed)
  [✓] Iteration 2/10 (3 issues fixed)
  [✓] Iteration 3/10 (1 issue fixed)
  [✓] Iteration 4/10 (PASS)
  [ ] Iteration 5/10 (not needed)
  [ ] Iteration 6/10 (not needed)
  ... (iterations 5-10 skipped)
  [✓] PHASE 3: User validation

User Experience: Clear iteration progress, early exit visible
```

---

### Example 3: Parallel Multi-Model Review

**Scenario:** 5 AI models reviewing code in parallel

**Execution:**

```
Step 0: Initialize Tasks

TaskCreate:
  subject: "PHASE 1: Prepare review context"
  activeForm: "Preparing context"
  // Returns: "phase-1-id"

TaskCreate:
  subject: "PHASE 2: Claude review"
  owner: "claude-agent"
  activeForm: "Claude reviewing"
  blockedBy: ["phase-1-id"]
  // Returns: "claude-id"

TaskCreate:
  subject: "PHASE 2: Grok review"
  owner: "grok-agent"
  activeForm: "Grok reviewing"
  blockedBy: ["phase-1-id"]
  // Returns: "grok-id"

TaskCreate:
  subject: "PHASE 2: Gemini review"
  owner: "gemini-agent"
  activeForm: "Gemini reviewing"
  blockedBy: ["phase-1-id"]
  // Returns: "gemini-id"

TaskCreate:
  subject: "PHASE 2: GPT-5 review"
  owner: "gpt-agent"
  activeForm: "GPT-5 reviewing"
  blockedBy: ["phase-1-id"]
  // Returns: "gpt-id"

TaskCreate:
  subject: "PHASE 2: DeepSeek review"
  owner: "deepseek-agent"
  activeForm: "DeepSeek reviewing"
  blockedBy: ["phase-1-id"]
  // Returns: "deepseek-id"

TaskCreate:
  subject: "PHASE 3: Consolidate reviews"
  activeForm: "Consolidating"
  blockedBy: ["claude-id", "grok-id", "gemini-id", "gpt-id", "deepseek-id"]
  // Returns: "phase-3-id"

TaskCreate:
  subject: "PHASE 4: Present results"
  activeForm: "Presenting"
  blockedBy: ["phase-3-id"]
  // Returns: "phase-4-id"

---

Step 1: PHASE 1

TaskUpdate: taskId="phase-1-id", status="in_progress"
... prepare context (30s) ...
TaskUpdate: taskId="phase-1-id", status="completed"
→ Unblocks all 5 review tasks

---

Step 2: PHASE 2 (Parallel Execution)

Launch all 5 in parallel:
  TaskUpdate: taskId="claude-id", status="in_progress"
  TaskUpdate: taskId="grok-id", status="in_progress"
  TaskUpdate: taskId="gemini-id", status="in_progress"
  TaskUpdate: taskId="gpt-id", status="in_progress"
  TaskUpdate: taskId="deepseek-id", status="in_progress"

TaskList shows:
  [✓] PHASE 1: Prepare context
  [→] PHASE 2: Claude review (in_progress)
  [→] PHASE 2: Grok review (in_progress)
  [→] PHASE 2: Gemini review (in_progress)
  [→] PHASE 2: GPT-5 review (in_progress)
  [→] PHASE 2: DeepSeek review (in_progress)
  [ ] PHASE 3: Consolidate reviews (blocked)
  [ ] PHASE 4: Present results (blocked)

Launch all 5 models (4-Message Pattern for parallel execution)

As each completes:

T=60s:  Claude completes first
  TaskUpdate: taskId="claude-id", status="completed"
  User sees: "1/5 reviews complete"

T=90s:  Gemini completes
  TaskUpdate: taskId="gemini-id", status="completed"
  User sees: "2/5 reviews complete"

T=120s: GPT-5 completes
  TaskUpdate: taskId="gpt-id", status="completed"
  User sees: "3/5 reviews complete"

T=150s: Grok completes
  TaskUpdate: taskId="grok-id", status="completed"
  User sees: "4/5 reviews complete"

T=180s: DeepSeek completes
  TaskUpdate: taskId="deepseek-id", status="completed"
  User sees: "5/5 reviews complete!"
  → Automatically unblocks PHASE 3

---

Step 3: PHASE 3

TaskUpdate: taskId="phase-3-id", status="in_progress"
... consolidate reviews (30s) ...
TaskUpdate: taskId="phase-3-id", status="completed"
→ Automatically unblocks PHASE 4

---

Step 4: PHASE 4

TaskUpdate: taskId="phase-4-id", status="in_progress"
... present results (10s) ...
TaskUpdate: taskId="phase-4-id", status="completed"

---

Final State:

TaskList shows:
  [✓] PHASE 1: Prepare review context
  [✓] PHASE 2: Claude review
  [✓] PHASE 2: Grok review
  [✓] PHASE 2: Gemini review
  [✓] PHASE 2: GPT-5 review
  [✓] PHASE 2: DeepSeek review
  [✓] PHASE 3: Consolidate reviews
  [✓] PHASE 4: Present results

User sees: "Multi-model review complete in 3 minutes"

User Experience:
  - Real-time progress as each model completes
  - Clear visibility: "3/5 reviews complete"
  - Automatic phase progression when all reviews done
  - Reduces perceived wait time (user knows progress)
```

---

## Troubleshooting

**Problem: User thinks workflow is stuck**

Cause: No task updates for >1 minute

Solution: TaskUpdate more frequently, or add sub-tasks

```
❌ Wrong:
  [→] PHASE 3: Implementation (in_progress for 10 minutes)

✅ Correct:
  [✓] PHASE 3: Implement core logic (2 min)
  [✓] PHASE 3: Add error handling (3 min)
  [→] PHASE 3: Write tests (in_progress, 2 min so far)

User sees progress every 2-3 minutes
```

---

**Problem: Too many tasks (>20), overwhelming**

Cause: Too granular task breakdown

Solution: Group micro-tasks into larger operations

```
❌ Wrong (25 tasks):
  TaskCreate: subject="Read file 1"
  TaskCreate: subject="Read file 2"
  TaskCreate: subject="Write file 3"
  ... (25 micro-tasks)

✅ Correct (8 tasks):
  TaskCreate: subject="PHASE 1: Gather inputs" (includes reading files)
  TaskCreate: subject="PHASE 2: Process data"
  ... (8 significant operations)
```

---

**Problem: Multiple tasks "in_progress" (not parallel execution)**

Cause: Forgot to mark previous task as completed

Solution: Always TaskUpdate to completed before starting next

```
❌ Wrong:
  [→] PHASE 1: Ask user (in_progress)
  [→] PHASE 2: Plan (in_progress)  ← Both in_progress?

✅ Correct:
  TaskUpdate: taskId="phase-1-id", status="completed"
  TaskUpdate: taskId="phase-2-id", status="in_progress"

  [✓] PHASE 1: Ask user (completed)
  [→] PHASE 2: Plan (in_progress)  ← Only one
```

---

## Summary

Task orchestration provides real-time progress visibility through:

- **Phase initialization** (create task list before starting with TaskCreate)
- **Appropriate granularity** (8-15 tasks, significant operations)
- **Real-time updates** (TaskUpdate to completed immediately)
- **Exactly one in_progress** (except parallel execution)
- **Iteration tracking** (separate task per iteration)
- **Parallel task tracking** (update as each completes with owner field)
- **Task dependencies** (blockedBy/blocks for automatic phase management)
- **Cross-session persistence** (CLAUDE_CODE_TASK_LIST_ID for resumable work)

Master these patterns and users will always know:
- What's happening now
- What's coming next
- How much progress has been made
- How much remains
- Which tasks are blocked and why

This transforms "black box" workflows into transparent, trackable processes.

---

**Extracted From:**
- `/review` command (10-task initialization, phase-based tracking)
- `/implement` command (8-phase workflow with sub-tasks)
- `/validate-ui` command (iteration tracking, user feedback rounds)
- All multi-phase orchestration workflows