Initial commit

skills/task-orchestration/patterns.md

@@ -0,0 +1,652 @@
+# Task Orchestration - Execution Patterns
+
+Comprehensive guide to execution strategies, configuration patterns, and error handling.
+
+## Execution Strategies
+
+### Strategy 1: Sequential Execution
+
+**When to use:**
+- All tasks have dependencies on previous tasks
+- No parallelization opportunities
+- Linear workflow required
+
+**Pattern:**
+```
+T1 → T2 → T3 → T4
+```
+
+**Implementation:**
+```javascript
+// Launch one task at a time
+for (task of tasks) {
+  recommendedAgent = recommend_agent(taskId=task.id)
+  launchSpecialist(recommendedAgent)
+  waitForCompletion()
+}
+```
+
+**Time:** Total = sum of all task durations
+**Use case:** Data pipeline, migration scripts, deployment steps
+
+---
+
+### Strategy 2: Full Parallel Execution
+
+**When to use:**
+- No dependencies between tasks
+- Independent work streams
+- Maximum speed required
+
+**Pattern:**
+```
+T1
+T2
+T3
+T4
+```
+
+**Implementation:**
+```javascript
+// Launch all tasks simultaneously (respecting max_parallel_tasks)
+allTasks = query_container(operation="search", containerType="task", featureId="...", status="pending")
+
+for (task of allTasks) {
+  recommendedAgent = recommend_agent(taskId=task.id)
+  launchSpecialistAsync(recommendedAgent)  // Don't wait
+}
+
+// Monitor all in parallel
+monitorParallelExecution(allTasks)
+```
+
+**Time:** Total = longest task duration
+**Savings:** Up to 75% if all tasks equal duration
+**Use case:** Independent features, test suites, documentation tasks
+
+---
+
+### Strategy 3: Hybrid Batched Execution
+
+**When to use:**
+- Mix of dependencies and parallel opportunities
+- Most common real-world scenario
+- Optimize for both speed and correctness
+
+**Pattern:**
+```
+Batch 1: T1, T3 (parallel)
+Batch 2: T2 (depends on T1)
+Batch 3: T4 (depends on T2, T3)
+```
+
+**Implementation:**
+```javascript
+// Step 1: Build dependency graph
+batches = createExecutionBatches(featureId)
+
+// Step 2: Execute batch by batch
+for (batch of batches) {
+  if (batch.parallel) {
+    // Launch all tasks in batch simultaneously
+    for (task of batch.tasks) {
+      launchSpecialistAsync(task)
+    }
+    waitForBatchComplete(batch)
+  } else {
+    // Launch tasks sequentially within batch
+    for (task of batch.tasks) {
+      launchSpecialist(task)
+      waitForCompletion()
+    }
+  }
+}
+```
+
+**Time:** Total = sum of batch durations (batches run sequentially, tasks within batch run in parallel)
+**Savings:** 30-50% typical for standard features
+**Use case:** Standard feature development (database → backend → frontend → tests)
+
+---
+
+### Strategy 4: Resource-Aware Execution
+
+**When to use:**
+- Configuration specifies resource limits
+- System constraints (memory, API limits)
+- Controlled parallelism required
+
+**Pattern:**
+```
+max_parallel_tasks: 3
+Batch 1a: T1, T2, T3 (parallel)
+Batch 1b: T4, T5 (wait for slot)
+```
+
+**Implementation:**
+```javascript
+// Step 1: Get resource limit from config
+maxParallel = 3  // From .taskorchestrator/config.yaml
+
+// Step 2: Split large batches
+batch = batches[0]  // Has 5 parallelizable tasks
+
+if (batch.tasks.length > maxParallel) {
+  // Split into sub-batches
+  subBatch1 = batch.tasks.slice(0, maxParallel)  // T1, T2, T3
+  subBatch2 = batch.tasks.slice(maxParallel)     // T4, T5
+
+  // Launch first sub-batch
+  for (task of subBatch1) {
+    launchSpecialistAsync(task)
+  }
+
+  // Queue remaining tasks
+  queuedTasks = subBatch2
+}
+
+// Step 3: Fill slots as tasks complete
+onTaskComplete = (completedTaskId) => {
+  if (queuedTasks.length > 0) {
+    nextTask = queuedTasks.shift()
+    launchSpecialist(nextTask)
+  }
+}
+```
+
+**Time:** Total = (total tasks / max_parallel) × average task duration
+**Use case:** Resource-constrained environments, rate-limited APIs, memory-intensive tasks
+
+---
+
+## Configuration Guidance
+
+**Note:** Configuration patterns are documented here for AI reference. Configuration is NOT dynamically loaded via MCP tools.
+
+### Parallelism Strategy
+
+**Default recommended settings:**
+
+```yaml
+# .taskorchestrator/config.yaml (documented pattern)
+parallelism:
+  max_parallel_tasks: 5        # Maximum concurrent tasks
+  auto_launch: true            # Auto-cascade to next batch
+  respect_dependencies: true   # Always check dependencies (CRITICAL)
+```
+
+**Best practices:**
+- **max_parallel_tasks**: 3-5 for most projects (manageable monitoring)
+- **auto_launch**: `true` for automation, `false` for manual control
+- **respect_dependencies**: ALWAYS `true` (prevents blocking issues)
+
+### Specialist Routing
+
+**Routing rules (from agent-mapping.yaml pattern):**
+
+```yaml
+# Tags → Specialist mapping
+backend:        Implementation Specialist (Haiku)
+frontend:       Implementation Specialist (Haiku)
+database:       Implementation Specialist (Haiku)
+testing:        Implementation Specialist (Haiku)
+documentation:  Implementation Specialist (Haiku)
+
+bug:            Senior Engineer (Sonnet)
+error:          Senior Engineer (Sonnet)
+blocker:        Senior Engineer (Sonnet)
+complex:        Senior Engineer (Sonnet)
+
+feature-creation:  Feature Architect (Opus)
+planning:          Planning Specialist (Sonnet)
+task-breakdown:    Planning Specialist (Sonnet)
+```
+
+**Routing algorithm:**
+1. Call `recommend_agent(taskId)`
+2. If recommendation provided → use it
+3. If no recommendation:
+   - Check fallback_behavior in config
+   - If `ask_user` → prompt user for specialist choice
+   - If `use_default` → use default_specialist (Implementation Specialist Haiku)
+4. **Never guess** or hardcode specialist assignments
+
+**Fallback configuration pattern:**
+
+```yaml
+specialist_routing:
+  fallback_behavior: "use_default"  # or "ask_user"
+  default_specialist: "Implementation Specialist"
+```
+
+### Quality Gates (Optional)
+
+**Hook-based validation pattern:**
+
+```yaml
+quality_gates:
+  enabled: false  # Disable until hooks implemented
+
+  task_gates:
+    testing:
+      hook: "run_tests"
+      required: true
+
+    completion:
+      hook: "validate_summary"
+      required: false  # Warning only
+```
+
+**Behavior:**
+- `required: true` → Blocks status transition if gate fails
+- `required: false` → Shows warning but allows progression
+
+**Use case:** CI/CD integration, automated testing, code coverage checks
+
+---
+
+## Error Handling
+
+### Error 1: Task Blocked During Execution
+
+**Symptom:**
+Task status changes to "blocked" mid-execution
+
+**Detection:**
+```javascript
+// Monitor task status
+task = query_container(operation="get", containerType="task", id=taskId)
+
+if (task.status == "blocked") {
+  // Specialist encountered blocker
+}
+```
+
+**Actions:**
+1. Notify orchestrator: "Task T2 blocked - waiting for external API access"
+2. Suggest unblocking actions based on blocker type:
+   - External dependency → "Contact team X for access"
+   - Technical issue → "Launch Senior Engineer to investigate"
+   - Missing information → "Clarify requirements with stakeholder"
+3. Do NOT cascade to next batch
+4. Report blocker in batch progress: "Batch 2: 0/1 (blocked)"
+
+**Resolution:**
+```javascript
+// After blocker resolved
+"Use Status Progression Skill to unblock task and resume work"
+```
+
+---
+
+### Error 2: Specialist Fails Task
+
+**Symptom:**
+Task marked as failed by specialist
+
+**Detection:**
+```javascript
+task = query_container(operation="get", containerType="task", id=taskId)
+
+if (task.status == "failed") {
+  // Specialist could not complete task
+}
+```
+
+**Actions:**
+1. Report failure to user: "Task T3 failed - specialist encountered errors"
+2. Analyze failure reason (from task sections/specialist report)
+3. Suggest remediation:
+   - Code errors → "Fix issues and retry task"
+   - Test failures → "Address failing tests"
+   - Blocker → "Resolve external dependency"
+4. **Do NOT cascade** to next batch (prevents cascading failures)
+5. Pause feature execution until issue resolved
+
+**Resolution:**
+```javascript
+// After fixing issues
+"Use Status Progression Skill to reset task to pending and retry"
+```
+
+---
+
+### Error 3: Max Parallel Limit Reached
+
+**Symptom:**
+Trying to launch more tasks than max_parallel_tasks allows
+
+**Detection:**
+```javascript
+inProgressTasks = query_container(
+  operation="search",
+  containerType="task",
+  status="in-progress"
+)
+
+if (inProgressTasks.length >= maxParallelTasks) {
+  // At capacity
+}
+```
+
+**Actions:**
+1. Queue remaining tasks: "5 tasks in progress (max). Queueing 2 additional tasks."
+2. Wait for slot to open
+3. When task completes, automatically launch next queued task
+4. Report queued tasks to user: "Sub-batch 1b queued (2 tasks waiting for slots)"
+
+**Implementation:**
+```javascript
+// Maintain queue
+queuedTasks = []
+
+onTaskComplete = (completedTaskId) => {
+  if (queuedTasks.length > 0) {
+    nextTask = queuedTasks.shift()
+    launchSpecialist(nextTask)
+    notify(`Launched queued task: ${nextTask.title}`)
+  }
+}
+```
+
+---
+
+### Error 4: No Specialist Matched
+
+**Symptom:**
+recommend_agent returns no recommendation
+
+**Detection:**
+```javascript
+recommendation = recommend_agent(taskId=taskId)
+
+if (!recommendation.recommended) {
+  // No specialist matched by tags
+}
+```
+
+**Actions:**
+1. Check fallback_behavior from config (documented pattern, not dynamically loaded)
+2. If `ask_user`:
+   ```
+   Task: Optimize performance
+   Tags: optimization, performance (no domain match)
+
+   No specialist matched by tags.
+   Which specialist should handle this task?
+   1. Backend Engineer
+   2. Frontend Developer
+   3. Senior Engineer (complex)
+   ```
+3. If `use_default`:
+   ```
+   No specialist matched.
+   Using fallback: Implementation Specialist (default)
+
+   Note: Consider adding more specific tags:
+   - For DB: database, query-optimization
+   - For frontend: frontend, ui-performance
+   - For backend: backend, api-optimization
+   ```
+
+**Prevention:**
+- Improve task tagging during creation
+- Update agent-mapping.yaml with missing patterns
+- Add domain-specific tags (backend, frontend, database, etc.)
+
+---
+
+### Error 5: Circular Dependency Detected
+
+**Symptom:**
+Cannot create execution batches due to circular dependency
+
+**Detection:**
+```javascript
+batches = createExecutionBatches(featureId)
+
+if (batches.error == "circular_dependency") {
+  // T2 → T5 → T7 → T2
+}
+```
+
+**Actions:**
+1. Report circular dependency to user:
+   ```
+   ✗ Error: Circular Dependencies Detected
+
+   Cycle found:
+   T2 (Implement API) → T5 (Add caching) → T7 (Update API) → T2
+
+   Resolution options:
+   1. Remove T7 → T2 dependency (likely unnecessary)
+   2. Split T2 into two tasks (API-v1, API-v2)
+   3. Reorder: Complete T2 before T5
+   ```
+
+2. Suggest using Dependency Orchestration Skill for detailed analysis:
+   ```
+   Use Dependency Orchestration Skill to:
+   - Visualize dependency graph
+   - Identify critical path
+   - Suggest dependency removals
+   ```
+
+3. **Do NOT proceed** with execution until resolved
+
+**Resolution:**
+User must manually resolve circular dependency by removing or reordering dependencies.
+
+---
+
+### Error 6: Batch Timeout
+
+**Symptom:**
+Batch taking longer than expected
+
+**Detection:**
+```javascript
+batchStartTime = Date.now()
+expectedDuration = batch.estimatedDuration
+
+checkInterval = setInterval(() => {
+  elapsed = Date.now() - batchStartTime
+
+  if (elapsed > expectedDuration * 1.5) {  // 50% overtime
+    // Batch running long
+  }
+}, 60000)  // Check every minute
+```
+
+**Actions:**
+1. Report delay to user: "Batch 2 running 50% over estimated time (45 min vs 30 min)"
+2. Check task statuses for issues:
+   ```javascript
+   for (task of batch.tasks) {
+     taskStatus = query_container(operation="get", containerType="task", id=task.id)
+     if (taskStatus.status == "blocked") {
+       report(`Task ${task.title} is blocked`)
+     }
+   }
+   ```
+3. Suggest user intervention if needed
+4. Continue monitoring until batch completes or user intervenes
+
+**Not an error if:**
+- Complex task legitimately taking longer
+- Specialist working through issues
+- All tasks still in-progress (not blocked/failed)
+
+---
+
+## Token Efficiency Patterns
+
+### Pattern 1: Batch Status Checks
+
+**Inefficient:**
+```javascript
+// Get full task details for each task
+for (task of batchTasks) {
+  fullTask = query_container(
+    operation="get",
+    containerType="task",
+    id=task.id,
+    includeSections=true  // 2,800 tokens per task
+  )
+}
+// Total: 2,800 × 10 tasks = 28,000 tokens
+```
+
+**Efficient:**
+```javascript
+// Get minimal task overview for batch
+tasks = query_container(
+  operation="search",
+  containerType="task",
+  featureId=featureId,
+  status="in-progress"
+)
+// Total: ~1,200 tokens for all 10 tasks (95% savings)
+```
+
+---
+
+### Pattern 2: Specialist Launch Instructions
+
+**Inefficient:**
+```javascript
+// Pass full task context to orchestrator
+fullTask = query_container(
+  operation="get",
+  containerType="task",
+  id=taskId,
+  includeSections=true
+)
+
+"Launch Backend Engineer with this task: [full task JSON]"
+// Total: ~2,900 tokens
+```
+
+**Efficient:**
+```javascript
+// Minimal specialist reference
+recommendation = recommend_agent(taskId=taskId)
+
+"Launch ${recommendation.agent} for task ${taskId}"
+// Specialist reads full context themselves
+// Total: ~50 tokens (98% savings)
+```
+
+---
+
+### Pattern 3: Progress Reporting
+
+**Inefficient:**
+```javascript
+// Return full batch details
+return {
+  batch: fullBatchData,
+  tasks: allTaskDetails,
+  progress: calculations
+}
+// Total: ~3,500 tokens
+```
+
+**Efficient:**
+```javascript
+// Minimal progress summary
+return "Batch 1: 3/5 tasks complete (60%)"
+// Total: ~20 tokens (99% savings)
+```
+
+---
+
+## Best Practices Summary
+
+### 1. Dependency Management
+- ✅ **Always** check dependencies before launching tasks
+- ✅ Use `query_dependencies` with `includeTaskInfo=true`
+- ✅ Validate no circular dependencies before batching
+- ❌ **Never** launch tasks without dependency analysis
+
+### 2. Specialist Routing
+- ✅ **Always** use `recommend_agent` tool
+- ✅ Respect recommendation if provided
+- ✅ Use documented fallback behavior if no match
+- ❌ **Never** guess or hardcode specialist assignments
+
+### 3. Resource Management
+- ✅ Respect `max_parallel_tasks` configuration
+- ✅ Queue tasks when at capacity
+- ✅ Monitor resource usage during execution
+- ❌ **Never** exceed parallelism limits
+
+### 4. Progress Monitoring
+- ✅ Check task status regularly during execution
+- ✅ Report progress to user proactively
+- ✅ Detect blockers and failures early
+- ❌ **Never** launch and forget (silent execution)
+
+### 5. Error Handling
+- ✅ Handle failures gracefully without cascade
+- ✅ Report clear error messages with remediation steps
+- ✅ Pause execution on critical errors
+- ❌ **Never** cascade to next batch on failure
+
+### 6. Token Efficiency
+- ✅ Use `overview` operations for status checks
+- ✅ Return minimal progress reports
+- ✅ Batch specialist launches in single message
+- ✅ Cache batch information to avoid re-querying
+- ❌ **Never** include full task details in progress reports
+
+### 7. Status Management
+- ✅ **Always** use Status Progression Skill for status changes
+- ✅ Detect events and delegate to Status Progression Skill
+- ✅ Let Status Progression Skill read config and validate
+- ❌ **Never** directly change task status
+
+---
+
+## Configuration Reference
+
+**Note:** These are documented patterns for AI reference. Configuration is NOT dynamically loaded via MCP tools. All configuration should be documented in CLAUDE.md or skill files.
+
+```yaml
+# .taskorchestrator/config.yaml (documented pattern)
+
+# Parallelism settings
+parallelism:
+  max_parallel_tasks: 5      # Concurrent task limit
+  auto_launch: true          # Auto-cascade to next batch
+  respect_dependencies: true # Always validate dependencies (CRITICAL)
+
+# Specialist routing
+specialist_routing:
+  fallback_behavior: "use_default"  # or "ask_user"
+  default_specialist: "Implementation Specialist"
+
+# Quality gates (optional)
+quality_gates:
+  enabled: false
+  task_gates:
+    testing:
+      hook: "run_tests"
+      required: true
+```
+
+**Key settings:**
+- `max_parallel_tasks`: 3-5 recommended
+- `auto_launch`: `true` for automation, `false` for manual control
+- `respect_dependencies`: ALWAYS `true`
+- `fallback_behavior`: `use_default` recommended
+- `quality_gates.enabled`: `false` until hooks implemented
+
+---
+
+## Related Documentation
+
+- **Examples**: See `examples.md` for detailed walkthroughs
+- **SKILL.md**: See `SKILL.md` for core workflows and trigger points
+- **Status Progression**: See `.claude/skills/status-progression/SKILL.md`
+- **Event-Driven Pattern**: See `docs/event-driven-status-progression-pattern.md`