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