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