agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/async-joinset-structured.md

@@ -1,195 +0,0 @@
-# async-joinset-structured
-
-> Use `JoinSet` for managing dynamic collections of spawned tasks
-
-## Why It Matters
-
-When spawning a variable number of tasks, collecting `JoinHandle`s in a `Vec` and using `join_all` works but lacks flexibility. `JoinSet` provides a better abstraction: add/remove tasks dynamically, get results as they complete, and abort all on drop. It's the idiomatic way to manage task collections.
-
-## Bad
-
-```rust
-// Manual handle management
-let mut handles: Vec<JoinHandle<Result<Data>>> = Vec::new();
-
-for url in urls {
-    handles.push(tokio::spawn(fetch(url)));
-}
-
-// Wait for all, in order (not as they complete)
-let results = futures::future::join_all(handles).await;
-
-// No easy way to cancel all, handle errors progressively, or add more tasks
-```
-
-## Good
-
-```rust
-use tokio::task::JoinSet;
-
-let mut set = JoinSet::new();
-
-for url in urls {
-    set.spawn(fetch(url.clone()));
-}
-
-// Process results as they complete
-while let Some(result) = set.join_next().await {
-    match result {
-        Ok(Ok(data)) => process(data),
-        Ok(Err(e)) => log::error!("Task failed: {}", e),
-        Err(e) => log::error!("Task panicked: {}", e),
-    }
-}
-
-// All tasks done, set is empty
-```
-
-## Dynamic Task Addition
-
-```rust
-use tokio::task::JoinSet;
-
-async fn worker_pool(mut rx: mpsc::Receiver<Task>) {
-    let mut set = JoinSet::new();
-    let max_concurrent = 10;
-    
-    loop {
-        tokio::select! {
-            // Accept new tasks if under limit
-            Some(task) = rx.recv(), if set.len() < max_concurrent => {
-                set.spawn(process_task(task));
-            }
-            
-            // Process completed tasks
-            Some(result) = set.join_next() => {
-                handle_result(result);
-            }
-            
-            // Exit when no tasks and channel closed
-            else => break,
-        }
-    }
-}
-```
-
-## Abort on Drop
-
-```rust
-use tokio::task::JoinSet;
-
-{
-    let mut set = JoinSet::new();
-    set.spawn(long_running_task());
-    set.spawn(another_task());
-    
-    // Early exit
-    return;
-}  // JoinSet dropped here - all tasks are aborted!
-
-// Explicit abort
-let mut set = JoinSet::new();
-set.spawn(task());
-set.abort_all();  // Cancel all tasks
-```
-
-## Error Handling Pattern
-
-```rust
-use tokio::task::JoinSet;
-
-async fn fetch_all(urls: &[String]) -> Vec<Result<Data, Error>> {
-    let mut set = JoinSet::new();
-    let mut results = Vec::new();
-    
-    for url in urls {
-        set.spawn(fetch(url.clone()));
-    }
-    
-    while let Some(join_result) = set.join_next().await {
-        let result = match join_result {
-            Ok(task_result) => task_result,
-            Err(join_error) => {
-                if join_error.is_panic() {
-                    Err(Error::TaskPanicked)
-                } else {
-                    Err(Error::TaskCancelled)
-                }
-            }
-        };
-        results.push(result);
-    }
-    
-    results
-}
-```
-
-## With Cancellation
-
-```rust
-use tokio::task::JoinSet;
-use tokio_util::sync::CancellationToken;
-
-async fn run_workers(shutdown: CancellationToken) {
-    let mut set = JoinSet::new();
-    
-    for i in 0..4 {
-        let token = shutdown.child_token();
-        set.spawn(async move {
-            loop {
-                tokio::select! {
-                    _ = token.cancelled() => break,
-                    _ = do_work(i) => {}
-                }
-            }
-        });
-    }
-    
-    // Wait for shutdown
-    shutdown.cancelled().await;
-    
-    // Abort remaining tasks
-    set.abort_all();
-    
-    // Wait for all to finish (drain aborted tasks)
-    while set.join_next().await.is_some() {}
-}
-```
-
-## Spawning with Context
-
-```rust
-use tokio::task::JoinSet;
-
-let mut set: JoinSet<(usize, Result<Data, Error>)> = JoinSet::new();
-
-for (index, url) in urls.iter().enumerate() {
-    let url = url.clone();
-    set.spawn(async move {
-        (index, fetch(&url).await)
-    });
-}
-
-// Results include their index
-while let Some(result) = set.join_next().await {
-    if let Ok((index, data)) = result {
-        results[index] = Some(data);
-    }
-}
-```
-
-## JoinSet vs join_all
-
-| Feature | JoinSet | join_all |
-|---------|---------|----------|
-| Add tasks dynamically | Yes | No |
-| Results as-completed | Yes | No (all at once) |
-| Abort all on drop | Yes | No |
-| Cancel individual | Yes | No |
-| Memory efficient | Yes | Pre-allocates |
-
-## See Also
-
-- [async-join-parallel](./async-join-parallel.md) - Static concurrent futures
-- [async-cancellation-token](./async-cancellation-token.md) - Cancellation patterns
-- [async-try-join](./async-try-join.md) - Error handling in joins

package/template/agent/skills/rust-developer/references/rust-rules/async-mpsc-queue.md

@@ -1,171 +0,0 @@
-# async-mpsc-queue
-
-> Use `mpsc` channels for async message queues between tasks
-
-## Why It Matters
-
-`tokio::sync::mpsc` (multi-producer, single-consumer) is the workhorse channel for async Rust. It provides async send/receive, backpressure via bounded capacity, and efficient cloning of senders. It's the default choice for task-to-task communication.
-
-## Bad
-
-```rust
-use std::sync::mpsc;  // Wrong! Blocks the async runtime
-
-let (tx, rx) = std::sync::mpsc::channel();
-
-tokio::spawn(async move {
-    tx.send("hello").unwrap();  // Might block
-});
-
-tokio::spawn(async move {
-    let msg = rx.recv().unwrap();  // BLOCKS the executor thread!
-});
-```
-
-## Good
-
-```rust
-use tokio::sync::mpsc;
-
-let (tx, mut rx) = mpsc::channel::<String>(100);
-
-tokio::spawn(async move {
-    tx.send("hello".to_string()).await.unwrap();
-});
-
-tokio::spawn(async move {
-    while let Some(msg) = rx.recv().await {
-        println!("Received: {}", msg);
-    }
-});
-```
-
-## Sender Cloning
-
-```rust
-use tokio::sync::mpsc;
-
-let (tx, mut rx) = mpsc::channel::<Event>(100);
-
-// Multiple producers
-for i in 0..10 {
-    let tx = tx.clone();  // Cheap clone
-    tokio::spawn(async move {
-        tx.send(Event { source: i }).await.unwrap();
-    });
-}
-
-// Drop original sender so channel closes when all clones dropped
-drop(tx);
-
-// Consumer
-while let Some(event) = rx.recv().await {
-    process(event);
-}
-// Loop exits when all senders dropped
-```
-
-## Message Handler Pattern
-
-```rust
-use tokio::sync::mpsc;
-
-enum Command {
-    Get { key: String, reply: oneshot::Sender<Option<Value>> },
-    Set { key: String, value: Value },
-    Delete { key: String },
-}
-
-async fn run_store(mut commands: mpsc::Receiver<Command>) {
-    let mut store = HashMap::new();
-    
-    while let Some(cmd) = commands.recv().await {
-        match cmd {
-            Command::Get { key, reply } => {
-                let _ = reply.send(store.get(&key).cloned());
-            }
-            Command::Set { key, value } => {
-                store.insert(key, value);
-            }
-            Command::Delete { key } => {
-                store.remove(&key);
-            }
-        }
-    }
-}
-
-// Usage
-async fn client(tx: mpsc::Sender<Command>) -> Option<Value> {
-    let (reply_tx, reply_rx) = oneshot::channel();
-    
-    tx.send(Command::Get { 
-        key: "foo".to_string(), 
-        reply: reply_tx 
-    }).await.unwrap();
-    
-    reply_rx.await.unwrap()
-}
-```
-
-## Graceful Shutdown
-
-```rust
-async fn worker(mut rx: mpsc::Receiver<Task>, shutdown: CancellationToken) {
-    loop {
-        tokio::select! {
-            _ = shutdown.cancelled() => {
-                // Drain remaining messages
-                while let Ok(task) = rx.try_recv() {
-                    process(task).await;
-                }
-                break;
-            }
-            Some(task) = rx.recv() => {
-                process(task).await;
-            }
-            else => break,  // Channel closed
-        }
-    }
-}
-```
-
-## WeakSender for Optional Producers
-
-```rust
-use tokio::sync::mpsc;
-
-let (tx, mut rx) = mpsc::channel::<Message>(100);
-let weak = tx.downgrade();  // Doesn't keep channel alive
-
-tokio::spawn(async move {
-    // Strong sender - keeps channel alive
-    tx.send("from strong".into()).await.unwrap();
-});
-
-tokio::spawn(async move {
-    // Weak sender - may fail if strong senders dropped
-    if let Some(tx) = weak.upgrade() {
-        tx.send("from weak".into()).await.unwrap();
-    }
-});
-```
-
-## Permit Pattern
-
-```rust
-// Reserve slot before preparing message
-let permit = tx.reserve().await?;
-
-// Now we have guaranteed capacity
-let message = expensive_to_create_message();
-permit.send(message);  // Never fails
-
-// Useful when message creation is expensive
-// and you don't want to create it if channel is full
-```
-
-## See Also
-
-- [async-bounded-channel](./async-bounded-channel.md) - Why bounded channels
-- [async-oneshot-response](./async-oneshot-response.md) - Request-response with oneshot
-- [async-broadcast-pubsub](./async-broadcast-pubsub.md) - Multiple consumers

package/template/agent/skills/rust-developer/references/rust-rules/async-no-lock-await.md

@@ -1,156 +0,0 @@
-# async-no-lock-await
-
-> Never hold `Mutex`/`RwLock` across `.await`
-
-## Why It Matters
-
-Holding a lock across an `.await` point can cause deadlocks and severely hurt performance. The task may be suspended while holding the lock, blocking all other tasks waiting for it - potentially indefinitely.
-
-## Bad
-
-```rust
-use tokio::sync::Mutex;
-
-async fn bad_update(state: &Mutex<State>) {
-    let mut guard = state.lock().await;
-    
-    // BAD: Lock held across await!
-    let data = fetch_from_network().await;
-    
-    guard.value = data;
-}  // Lock finally released
-
-// This can deadlock or starve other tasks
-```
-
-## Good
-
-```rust
-use tokio::sync::Mutex;
-
-async fn good_update(state: &Mutex<State>) {
-    // Fetch data BEFORE taking the lock
-    let data = fetch_from_network().await;
-    
-    // Lock only for the quick update
-    let mut guard = state.lock().await;
-    guard.value = data;
-}  // Lock released immediately
-
-// Alternative: Clone data out, process, then update
-async fn good_update_v2(state: &Mutex<State>) {
-    // Extract what we need
-    let id = {
-        let guard = state.lock().await;
-        guard.id.clone()
-    };  // Lock released!
-    
-    // Do async work without lock
-    let data = fetch_by_id(id).await;
-    
-    // Quick update
-    state.lock().await.value = data;
-}
-```
-
-## The Problem Visualized
-
-```rust
-// Task A:
-let guard = mutex.lock().await;    // Acquires lock
-expensive_io().await;              // Suspended, still holding lock!
-// ... many milliseconds pass ...
-drop(guard);                       // Finally releases
-
-// Task B, C, D:
-let guard = mutex.lock().await;    // All blocked waiting for A!
-```
-
-## Patterns for Extraction
-
-```rust
-use tokio::sync::Mutex;
-
-// Pattern 1: Clone out, process, update
-async fn pattern_clone(state: &Mutex<State>) {
-    let config = state.lock().await.config.clone();
-    let result = process_with_io(&config).await;
-    state.lock().await.result = result;
-}
-
-// Pattern 2: Compute closure, apply
-async fn pattern_closure(state: &Mutex<State>) {
-    let update = compute_update().await;
-    
-    state.lock().await.apply(update);
-}
-
-// Pattern 3: Message passing
-async fn pattern_message(
-    state: &Mutex<State>,
-    tx: mpsc::Sender<Update>,
-) {
-    let update = compute_update().await;
-    tx.send(update).await.unwrap();
-}
-
-// Separate task handles updates
-async fn state_manager(
-    state: Arc<Mutex<State>>,
-    mut rx: mpsc::Receiver<Update>,
-) {
-    while let Some(update) = rx.recv().await {
-        state.lock().await.apply(update);
-    }
-}
-```
-
-## Using RwLock
-
-```rust
-use tokio::sync::RwLock;
-
-async fn read_heavy(state: &RwLock<State>) {
-    // Multiple readers OK, but still don't hold across await
-    let value = {
-        let guard = state.read().await;
-        guard.value.clone()
-    };
-    
-    // Process without lock
-    let result = process(value).await;
-    
-    // Write lock for update
-    state.write().await.result = result;
-}
-```
-
-## std::sync::Mutex vs tokio::sync::Mutex
-
-```rust
-// std::sync::Mutex: Blocks the entire thread
-// - Use for quick, CPU-only operations
-// - NEVER use in async code with await inside
-
-// tokio::sync::Mutex: Async-aware, yields to runtime
-// - Use in async code
-// - Still don't hold across await points!
-
-// std::sync::Mutex in async (quick operation, OK):
-async fn quick_update(state: &std::sync::Mutex<State>) {
-    state.lock().unwrap().counter += 1;  // No await, OK
-}
-
-// tokio::sync::Mutex (must use if lock scope has await):
-async fn must_await_inside(state: &tokio::sync::Mutex<State>) {
-    let mut guard = state.lock().await;
-    // Only if you REALLY need the lock during async op
-    // (usually you don't - redesign instead)
-}
-```
-
-## See Also
-
-- [async-spawn-blocking](async-spawn-blocking.md) - Use spawn_blocking for CPU work
-- [async-clone-before-await](async-clone-before-await.md) - Clone data before await
-- [anti-lock-across-await](anti-lock-across-await.md) - Anti-pattern reference

package/template/agent/skills/rust-developer/references/rust-rules/async-oneshot-response.md

@@ -1,191 +0,0 @@
-# async-oneshot-response
-
-> Use `oneshot` channel for request-response patterns
-
-## Why It Matters
-
-When one task needs to send a request and wait for exactly one response, `oneshot` is the perfect fit. It's a single-use channel optimized for this pattern—no buffering, no clone overhead. Combined with `mpsc`, it enables clean actor-style message passing.
-
-## Bad
-
-```rust
-// Using mpsc for single response - wasteful
-let (tx, mut rx) = mpsc::channel::<Response>(1);
-send_request().await;
-let response = rx.recv().await.unwrap();
-// Channel persists, could accidentally receive more
-
-// Using shared state - complex
-let result = Arc::new(Mutex::new(None));
-send_request(result.clone()).await;
-while result.lock().await.is_none() {
-    tokio::time::sleep(Duration::from_millis(10)).await;  // Polling!
-}
-```
-
-## Good
-
-```rust
-use tokio::sync::oneshot;
-
-let (tx, rx) = oneshot::channel::<Response>();
-
-// Send request with reply channel
-send_request(Request { data, reply: tx }).await;
-
-// Wait for response
-let response = rx.await?;
-
-// Channel is consumed - can't accidentally reuse
-```
-
-## Request-Response Pattern
-
-```rust
-use tokio::sync::{mpsc, oneshot};
-
-enum Request {
-    Get {
-        key: String,
-        reply: oneshot::Sender<Option<Value>>,
-    },
-    Set {
-        key: String,
-        value: Value,
-        reply: oneshot::Sender<bool>,
-    },
-}
-
-// Service handler
-async fn service(mut rx: mpsc::Receiver<Request>) {
-    let mut store = HashMap::new();
-    
-    while let Some(req) = rx.recv().await {
-        match req {
-            Request::Get { key, reply } => {
-                let value = store.get(&key).cloned();
-                let _ = reply.send(value);  // Ignore if receiver dropped
-            }
-            Request::Set { key, value, reply } => {
-                store.insert(key, value);
-                let _ = reply.send(true);
-            }
-        }
-    }
-}
-
-// Client
-async fn get_value(tx: &mpsc::Sender<Request>, key: &str) -> Option<Value> {
-    let (reply_tx, reply_rx) = oneshot::channel();
-    
-    tx.send(Request::Get {
-        key: key.to_string(),
-        reply: reply_tx,
-    }).await.ok()?;
-    
-    reply_rx.await.ok()?
-}
-```
-
-## With Timeout
-
-```rust
-use tokio::time::{timeout, Duration};
-
-async fn request_with_timeout(
-    tx: &mpsc::Sender<Request>,
-    key: &str,
-) -> Result<Value, Error> {
-    let (reply_tx, reply_rx) = oneshot::channel();
-    
-    tx.send(Request::Get {
-        key: key.to_string(),
-        reply: reply_tx,
-    }).await.map_err(|_| Error::ServiceDown)?;
-    
-    timeout(Duration::from_secs(5), reply_rx)
-        .await
-        .map_err(|_| Error::Timeout)?
-        .map_err(|_| Error::ServiceDown)?
-        .ok_or(Error::NotFound)
-}
-```
-
-## Error Handling
-
-```rust
-use tokio::sync::oneshot;
-
-let (tx, rx) = oneshot::channel::<String>();
-
-// Sender dropped without sending
-drop(tx);
-match rx.await {
-    Ok(value) => println!("Got: {}", value),
-    Err(oneshot::error::RecvError { .. }) => {
-        println!("Sender dropped");
-    }
-}
-
-// Receiver dropped before send
-let (tx, rx) = oneshot::channel::<String>();
-drop(rx);
-match tx.send("hello".to_string()) {
-    Ok(()) => println!("Sent"),
-    Err(value) => println!("Receiver dropped, value: {}", value),
-}
-```
-
-## Closed Detection
-
-```rust
-// Check if receiver is still waiting
-let (tx, rx) = oneshot::channel::<i32>();
-
-// In producer
-if tx.is_closed() {
-    println!("Receiver already gone, skip expensive computation");
-} else {
-    let result = expensive_computation();
-    tx.send(result).ok();
-}
-
-// Async wait for close
-let tx_clone = tx.clone();  // Note: can't actually clone, just showing concept
-tokio::select! {
-    _ = tx.closed() => println!("Receiver dropped"),
-    result = compute() => { tx.send(result).ok(); }
-}
-```
-
-## Response Type Wrapper
-
-```rust
-// Standardize request-response pattern
-struct RpcRequest<Req, Res> {
-    request: Req,
-    reply: oneshot::Sender<Res>,
-}
-
-impl<Req, Res> RpcRequest<Req, Res> {
-    fn new(request: Req) -> (Self, oneshot::Receiver<Res>) {
-        let (tx, rx) = oneshot::channel();
-        (RpcRequest { request, reply: tx }, rx)
-    }
-    
-    fn respond(self, response: Res) {
-        let _ = self.reply.send(response);
-    }
-}
-
-// Usage
-let (req, rx) = RpcRequest::new(GetUser { id: 42 });
-tx.send(req).await?;
-let user = rx.await?;
-```
-
-## See Also
-
-- [async-mpsc-queue](./async-mpsc-queue.md) - Pair with oneshot for request-response
-- [async-bounded-channel](./async-bounded-channel.md) - Channel sizing
-- [async-select-racing](./async-select-racing.md) - Timeout patterns