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

code

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

code

TaskUpdate: taskId="task-123", status="in_progress"
TaskUpdate: taskId="task-123", status="completed"
TaskUpdate: taskId="task-123", description="Updated description"

TaskList: View all tasks

code

TaskList  // Shows all tasks with statuses

TaskGet: Get specific task details

code

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:

code

✅ 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:

code

✅ 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:

•User expectation setting: User knows workflow scope (8 phases, ~20 minutes)
•Progress visibility: User can see % complete (3/8 = 37.5%)
•Time estimation: User can estimate remaining time based on progress
•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):

code

✅ 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:

code

✅ 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:

code

✅ 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:

code

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:

code

✅ 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:

code

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:

code

✅ 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:

code

✅ 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:

code

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:

code

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:

code

✅ 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:

code

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:

code

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:

code

✅ 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:

code

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:

code

✅ 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:

code

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:

code

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:

code

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:

code

✅ 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:

code

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:

code

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:

code

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:

code

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:

code

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:

code

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

code

❌ 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

code

❌ 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

code

❌ 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