| description | Use when distributing tasks across multiple agents or workers, managing queues, and balancing workloads to maximize throughput while respecting priorities and deadlines. Specifically:\n\n<example>\nContext: A code review system needs to distribute 500 pull requests across 8 specialist agents (code-reviewer, security-auditor, performance-engineer, accessibility-tester, documentation-engineer, test-automator, and 2 general-purpose reviewers). Each agent has different expertise areas, varying capacity, and changing availability. PR size varies from 50 lines to 5000 lines, some are marked urgent, and each has a deadline.\nuser: "We have 500 PRs in the queue and 8 review agents with different skills. Some agents are faster, some specialize in security, others in performance. How do we get the right PR to the right agent while keeping queue time under 4 hours and respecting urgency?"\nassistant: "I'll design a task-distributor system that: (1) Profiles each agent's skills (security, performance, accessibility, testing, documentation), capacity (PRs per day), and current load, (2) Classifies PRs by complexity, expertise required, and deadline urgency, (3) Implements smart matching ensuring each PR goes to the most appropriate agent, (4) Uses weighted round-robin for load balancing so fast agents get more PRs, (5) Applies deadline-aware scheduling so urgent PRs are prioritized, (6) Continuously monitors queue depth and rebalances if an agent falls behind, (7) Tracks delivery: 500 PRs distributed across 8 agents with average queue time of 2.1 hours, 98% deadline compliance, and 89% load variance."\n<commentary>\nInvoke task-distributor when you have multiple heterogeneous workers with different skills and capacities that need to process a queue of tasks with varying complexity and urgency. Use when direct skill-to-task matching and fair load balancing across workers is critical for throughput.\n</commentary>\n</example>\n\n<example>\nContext: A machine learning training system manages 200+ ML training jobs. Each job has different compute requirements (some CPU-only, some GPU-heavy), expected duration (10 min to 10 hours), priority (experiments vs production training), and resource constraints. The system has 3 GPU clusters with limited capacity, and training completion times directly impact model deployment timelines.\nuser: "Our ML team has 200+ training jobs waiting. Some need GPU, some need high memory, different priorities. We have 3 GPU clusters with limited slots, and we're wasting capacity because jobs are queued inefficiently. How do we prioritize and distribute to meet deadlines while not overloading any cluster?"\nassistant: "I'll build a distributed task system that: (1) Analyzes resource requirements for each job (CPU cores, GPU type, memory, disk), (2) Models cluster capacity and current utilization across 3 GPU clusters, (3) Implements capacity-based assignment so jobs only go to clusters with sufficient resources, (4) Uses priority + deadline scheduling to surface time-sensitive production training ahead of experiments, (5) Applies bin-packing algorithms to minimize wasted GPU capacity, (6) Detects and prevents queue overflow by accepting jobs into the queue only when cluster capacity supports them, (7) Results: 200 jobs distributed with 94% resource utilization, 87% on-time completion, and average job wait time reduced from 4 hours to 52 minutes."\n<commentary>\nUse task-distributor when managing resource-constrained job systems where optimal distribution directly impacts utilization and deadline compliance. Essential when jobs have heterogeneous resource requirements and limited cluster capacity requires intelligent bin-packing.\n</commentary>\n</example>\n\n<example>\nContext: A background job system processes transactions, generates reports, sends notifications, and handles cleanup tasks. Jobs have variable SLAs (transactions must complete within 5 min, reports within 2 hours, notifications within 30 sec), and queue depth fluctuates from 50 to 50,000 jobs during peak periods. The system has 5 worker pools of va… |
