Task Orchestration

---
skill: task-orchestration
description: Dependency-aware parallel task execution with automatic specialist routing, progress monitoring, and cascading completion. Replaces Task Management Skill with enhanced capabilities.
---

# Task Orchestration Skill

Intelligent task execution management with parallel processing, dependency-aware batching, and automatic specialist coordination.

## When to Use This Skill

**Activate for:**
- "Execute tasks for feature X"
- "What tasks are ready to start?"
- "Launch next batch of tasks"
- "Complete task Y"
- "Monitor parallel execution"
- "Show task progress"

**This skill handles:**
- Dependency-aware task batching
- Parallel specialist launching
- Progress monitoring
- Task completion with summaries
- Dependency cascade triggering
- Specialist routing

## Tools Available

- `query_container` - Read tasks, features, dependencies
- `query_sections` - Read sections with tag filtering (**Token optimized**)
- `manage_container` - Update task status, create tasks
- `query_workflow_state` - Check workflow state, cascade events, dependencies (**NEW**)
- `query_dependencies` - Analyze task dependencies
- `recommend_agent` - Route tasks to specialists
- `manage_sections` - Update task sections

## Section Tag Taxonomy

**When reading task/feature sections, use tag filtering for token efficiency:**

**Actionable Tags** (Implementation Specialist reads from tasks):
- **workflow-instruction** - Step-by-step implementation processes
- **checklist** - Validation checklists, completion criteria
- **commands** - Bash commands to execute
- **guidance** - Implementation patterns and best practices
- **process** - Workflow processes to follow
- **acceptance-criteria** - Definition of done, success conditions

**Contextual Tags** (Planning Specialist reads from features):
- **context** - Business context, user needs, dependencies
- **requirements** - Functional requirements, must-haves, constraints

**Reference Tags** (Read as needed):
- **reference** - Examples, patterns, reference material
- **technical-details** - Deep technical specifications

**Example - Efficient Task Section Reading:**
```javascript
// Implementation Specialist reads only actionable content from task
sections = query_sections(
  entityType="TASK",
  entityId=taskId,
  tags="workflow-instruction,checklist,commands,guidance,process,acceptance-criteria",
  includeContent=true
)
// Token cost: ~800-1,500 tokens (vs 3,000-5,000 with all sections)
// Savings: 45-60% token reduction

// Skip contextual sections (already in task description):
// - context (business context)
// - requirements (captured in description field)
```

**Note:** Implementation Specialist subagent automatically uses tag filtering. This reference is for direct tool usage.

## Dependency Cascade Detection (Automatic)

**Recommended Approach:** Use `query_workflow_state` to automatically check for dependency cascades and unblocked tasks.

```javascript
// After task completion, check for cascades
workflowState = query_workflow_state(
  containerType="task",
  id=taskId
)

// Check for detected cascade events (feature progression)
if (workflowState.detectedEvents.length > 0) {
  "✅ Task completion triggered cascade events:
  ${workflowState.detectedEvents.map(e => e.reason).join(', ')}

  Feature status may need to progress. Use Status Progression Skill."
}

// Check for unblocked dependencies (other tasks can now start)
dependencies = query_dependencies(
  taskId=taskId,
  direction="outgoing",
  includeTaskInfo=true
)

// Filter for now-unblocked tasks
for (dep of dependencies) {
  if (dep.toTask.status == "blocked" || dep.toTask.status == "pending") {
    "✅ Task ${dep.toTask.title} is now unblocked and ready to start!"
  }
}
```

**Benefits:**
- Automatic cascade detection based on config
- Dependency-aware unblocking
- Works with custom user workflows
- Handles complex prerequisite checking

## Status Progression Trigger Points (Manual Detection)

**Legacy Pattern:** Manual detection is still available but `query_workflow_state` is preferred.

**CRITICAL:** Never directly change task status. Always use Status Progression Skill for ALL status changes.

These are universal events that trigger status progression checks, regardless of the user's configured status flow:

| Event | When to Check | Detection Pattern | Condition | Action |
|-------|---------------|-------------------|-----------|--------|
| **work_started** | Specialist begins task implementation | Before specialist starts work | Task is in backlog/pending | Use Status Progression Skill to move to in-progress |
| **implementation_complete** | Code + tests written, sections updated | After specialist finishes coding | Summary populated (300-500 chars), sections updated | Use Status Progression Skill to move to next validation status |
| **tests_running** | Test execution begins | After triggering tests | Tests initiated | Use Status Progression Skill if needed |
| **tests_passed** | All tests successful | After test execution | `testResults.allPassed == true` | Use Status Progression Skill to move toward completion |
| **tests_failed** | Any tests failed | After test execution | `testResults.anyFailed == true` | Use Status Progression Skill (may move backward to in-progress) |
| **review_submitted** | Code submitted for review | After implementation complete | Code ready for review | Use Status Progression Skill to move to in-review |
| **review_approved** | Code review passed | After reviewer approval | Review completed with approval | Use Status Progression Skill to move forward (testing or completion) |
| **changes_requested** | Review rejected, needs rework | After reviewer rejection | Changes needed | Use Status Progression Skill (move backward to in-progress) |
| **blocker_detected** | Cannot proceed with work | When specialist encounters issue | External dependency or technical blocker | Use Status Progression Skill to move to blocked status |
| **task_cancelled** | Work no longer needed | User decides to cancel | Scope change | Use Status Progression Skill to move to cancelled |

### Detection Example: Implementation Complete

```javascript
// After specialist finishes code + tests
task = query_container(operation="get", containerType="task", id=taskId)

// Check implementation is complete
sectionsUpdated = true  // Specialist updated Implementation Details section
filesChanged = true     // Specialist created Files Changed section
summaryLength = task.summary?.length || 0

if (sectionsUpdated && filesChanged && summaryLength >= 300 && summaryLength <= 500) {
  // EVENT DETECTED: implementation_complete
  // Delegate to Status Progression Skill

  "Use Status Progression Skill to progress task status.
  Context: Implementation complete, summary populated (${summaryLength} chars)."

  // Status Progression Skill will:
  // 1. Call get_next_status(taskId, event="implementation_complete")
  // 2. get_next_status reads user's config.yaml
  // 3. Determines active flow based on task tags
  // 4. Recommends next status based on that flow
  // 5. Validates prerequisites
  // 6. Returns recommendation

  // Possible outcomes based on user's config:
  // - default_flow: in-progress → testing
  // - with_review: in-progress → in-review (code review first)
  // - documentation_flow: in-progress → in-review (no testing for docs)
  // - hotfix_flow: in-progress → completed (skip validation)
  // - bug_fix_flow: in-progress → testing
}
```

### Detection Example: Task Completion (Cascade Check)

```javascript
// After marking task complete, check for dependency cascade
completedTask = query_container(operation="get", containerType="task", id=taskId)

// Check if this unblocks other tasks
outgoingDeps = query_dependencies(
  taskId=taskId,
  direction="outgoing",
  includeTaskInfo=true
)

if (outgoingDeps.dependencies.length > 0) {
  // This task blocks other tasks
  // Check each dependent task to see if now unblocked

  for (dep of outgoingDeps.dependencies) {
    dependentTask = dep.toTask

    // Check all incoming dependencies for the dependent task
    incomingDeps = query_dependencies(
      taskId=dependentTask.id,
      direction="incoming",
      includeTaskInfo=true
    )

    // Count incomplete blockers
    incompleteBlockers = incomingDeps.dependencies.filter(d =>
      d.fromTask.status != "completed" && d.fromTask.status != "cancelled"
    ).length

    if (incompleteBlockers == 0) {
      // This task is now unblocked!
      notify(`Task "${dependentTask.title}" is now unblocked and ready to start.`)

      // Feature Orchestration Skill can now launch specialist for this task
    }
  }
}

// Also check if feature can progress (see Feature Orchestration Skill)
if (completedTask.featureId) {
  // Trigger Feature Orchestration Skill to check feature progress
  // (see Feature Orchestration Skill event: all_tasks_complete)
}
```

## Specialist Architecture (v2.0)

**Implementation Specialist (Haiku)** - Standard implementation (70-80% of tasks)
- Fast execution, cost-effective
- Loads domain Skills on-demand: backend-implementation, frontend-implementation, database-implementation, testing-implementation, documentation-implementation
- Escalates to Senior Engineer when blocked

**Senior Engineer (Sonnet)** - Complex problem solving (10-20%)
- Debugging, bug investigation, unblocking
- Performance optimization, tactical architecture

**Feature Architect (Opus)** - Feature design from ambiguous requirements
**Planning Specialist (Sonnet)** - Task decomposition with execution graphs

## Pre-Execution Checklist

**CRITICAL: Before launching specialists, ALWAYS check parent feature status.**

When starting task execution (Phase 3 of feature development):

1. **Check parent feature status:**
   ```javascript
   feature = query_container(operation="get", containerType="feature", id=featureId)

   if (feature.status == "planning" || feature.status == "draft") {
     // Feature status doesn't reflect execution phase
     // Delegate to Feature Orchestration Skill or Status Progression Skill

     "⚠️ Feature is still in ${feature.status}.
     Use Status Progression Skill to progress feature status before launching specialists.

     Cascade Event: tasks_ready_to_execute
     The skill will use get_next_status to determine the appropriate next status based on workflow config.

     Why: Feature status must reflect current development phase (not hardcoded - config determines next status)."

     // STOP - Don't proceed with specialist launches until feature status updated
     return
   }
   ```

2. **Identify ready tasks** (no blocking dependencies)
3. **Create execution batches** (parallel groups)
4. **Then proceed with specialist launches**

**Why this matters:**
- Feature status should accurately reflect the current development phase
- Cascade event system determines appropriate next status (config-driven)
- Missing this step causes feature to jump directly to completion, skipping execution phase statuses
- Different workflows may use different status names (default: "in-development", but config controls this)

**When to check:**
- At the start of Phase 3 (task execution)
- Before launching the first batch of specialists
- When resuming paused work

## Core Workflows

### 1. Dependency-Aware Batching

**High-level steps:**
1. Get all pending tasks: `query_container(operation="search", containerType="task", featureId="...", status="pending")`
2. For each task, check dependencies: `query_dependencies(taskId="...", direction="incoming", includeTaskInfo=true)`
3. Group into batches:
   - Batch 1: Tasks with NO incomplete blocking dependencies (parallel)
   - Batch 2: Tasks blocked only by Batch 1 (sequential)
   - Batch 3+: Continue until all tasks assigned
4. Detect circular dependencies (task blocked by another task that's also blocked)

See [examples.md](examples.md) for detailed batching examples and output format.

### 2. Parallel Specialist Launch

**High-level steps:**
1. For each task in parallel batch: `recommend_agent(taskId="...")`
2. Prepare launch instructions for orchestrator
3. Orchestrator launches specialists in parallel (using Task tool)

**Key:** Skill identifies WHICH specialists to launch; orchestrator does the actual launching.

See [examples.md](examples.md) for orchestrator instruction format.

### 3. Progress Monitoring

**High-level steps:**
1. Keep list of task IDs currently being worked on
2. Check each task status: `query_container(operation="overview", containerType="task", id="...")`
3. Analyze status distribution (completed, in-progress, blocked, pending)
4. Determine if batch complete
5. Report progress: "Batch X: Y/Z tasks complete (N%)"

### 4. Dependency Cascade

**High-level steps:**
1. After task completes, check if it unblocks others: `query_dependencies(taskId="...", direction="outgoing", includeTaskInfo=true)`
2. For each dependent task, check if ALL blockers complete
3. Report newly available tasks
4. Recommend launching next batch

See [examples.md](examples.md) for cascade detection pattern.

### 5. Specialist Routing

**High-level steps:**
1. Get recommendation: `recommend_agent(taskId="...")`
2. Use recommendation if provided
3. If no recommendation, use fallback (Implementation Specialist or ask user)

**Routing patterns:**
- [backend, frontend, database, testing, documentation] → Implementation Specialist (Haiku)
- [bug, error, blocker, complex] → Senior Engineer (Sonnet)
- [feature-creation] → Feature Architect (Opus)
- [planning, task-breakdown] → Planning Specialist (Sonnet)

### 6. Task Completion

**High-level steps:**
1. Create task summary section (300-500 chars)
2. Create files changed section
3. Use Status Progression Skill to mark complete (validates prerequisites)
4. Check for cascade (trigger next batch if available)

**Note:** Specialists typically mark their own tasks complete. This is for orchestrator-driven completion.

## Integration with Other Skills

**Works alongside:**
- **Feature Orchestration Skill** - Receives task execution requests
- **Dependency Orchestration Skill** - For complex dependency analysis
- **Status Progression Skill** - For ALL status changes

**Launches subagents:**
- All specialist subagents based on recommend_agent results

## Token Efficiency

- Use `overview` operations for batch status checks (95% token reduction)
- Batch specialist launches in single message
- Return minimal progress reports
- Query only necessary dependency information

**Savings:** Overview batch (1.2k tokens) vs Get each task fully (28k tokens for 10 tasks)

## Best Practices

1. **Always analyze dependencies** before execution
2. **Use recommend_agent** for all routing (never guess)
3. **Monitor parallel progress** actively
4. **Handle failures gracefully** without cascade
5. **Trigger cascades automatically** when batch completes
6. **Report clear progress** to users
7. **Maximum 3-5 parallel tasks** for manageable monitoring

## Success Metrics

- 40% reduction in feature completion time with parallelism
- 95% successful specialist routing on first attempt
- Zero circular dependencies in production
- Automated cascade triggering (no manual intervention)
- 500-900 token average per orchestration session

## Additional Resources

- **Detailed Examples**: See [examples.md](examples.md) for complete walkthroughs
- **Execution Patterns**: See [patterns.md](patterns.md) for strategies, configuration, and error handling