parallellisted

# Parallel Pool Management ## Overview Manage a pool of subagents with a precise concurrency limit, dispatching new tasks immediately as slots free up. Unlike fire-all-at-once approaches, this maintains steady parallelism without overwhelming systems. ## When to Use ✅ **Use when:** - Processing 5+ independent tasks (chapters, files, API calls, etc.) - Need to limit concurrent execution (API rate limits, memory constraints, system overload) - Want parallelism benefits without fire-all-at-once resource spikes - Tasks can complete incrementally (don't need all results simultaneously) ❌ **Don't use when:** - Tasks have sequential dependencies or shared state - Only 1-4 tasks (just dispatch them directly) - Need all results simultaneously before proceeding (use `superpowers:dispatching-parallel-agents` instead) ## Core Pattern ### Pool Management Algorithm ``` 1. INITIALIZE: Set concurrency limit (default 3), create task queue 2. DISPATCH: Fire min(limit, queue_size) subagents initially 3. WAIT: Monitor for ANY completion (not polling - check notification) 4. REFILL: When slot frees, immediately dispatch next task from queue 5. REPEAT: Until queue empty AND all slots free ``` **Critical**: Refill slots **immediately when ANY completes**, not "wait for all then dispatch next batch." ### Implementation Pattern ```javascript // Pool state management const limit = 3; // or custom limit from args const queue = [...tasks]; // remaining tasks const running = new Set();