agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/async-broadcast-pubsub.md

@@ -1,185 +0,0 @@
-# async-broadcast-pubsub
-
-> Use `broadcast` channel for pub/sub where all subscribers receive all messages
-
-## Why It Matters
-
-Unlike `mpsc` where one consumer receives each message, `broadcast` delivers each message to all subscribers. This is ideal for event broadcasting, real-time notifications, or when multiple components need to react to the same events independently.
-
-## Bad
-
-```rust
-use tokio::sync::mpsc;
-
-// mpsc only delivers to ONE consumer
-let (tx, mut rx) = mpsc::channel::<Event>(100);
-
-// Only one of these receives each message!
-let mut rx2 = ???;  // Can't clone receiver
-```
-
-## Good
-
-```rust
-use tokio::sync::broadcast;
-
-// broadcast delivers to ALL subscribers
-let (tx, _) = broadcast::channel::<Event>(100);
-
-// Each subscriber gets ALL messages
-let mut rx1 = tx.subscribe();
-let mut rx2 = tx.subscribe();
-
-tokio::spawn(async move {
-    while let Ok(event) = rx1.recv().await {
-        handle_in_logger(event);
-    }
-});
-
-tokio::spawn(async move {
-    while let Ok(event) = rx2.recv().await {
-        handle_in_metrics(event);
-    }
-});
-
-// Both subscribers receive this
-tx.send(Event::UserLogin { user_id: 42 })?;
-```
-
-## Broadcast Semantics
-
-```rust
-use tokio::sync::broadcast;
-
-let (tx, mut rx1) = broadcast::channel::<i32>(16);
-let mut rx2 = tx.subscribe();
-
-tx.send(1)?;
-tx.send(2)?;
-
-// Both receive all messages
-assert_eq!(rx1.recv().await?, 1);
-assert_eq!(rx1.recv().await?, 2);
-assert_eq!(rx2.recv().await?, 1);
-assert_eq!(rx2.recv().await?, 2);
-```
-
-## Handling Lagging Receivers
-
-```rust
-use tokio::sync::broadcast::{self, error::RecvError};
-
-let (tx, mut rx) = broadcast::channel::<Event>(16);
-
-loop {
-    match rx.recv().await {
-        Ok(event) => {
-            process(event);
-        }
-        Err(RecvError::Lagged(count)) => {
-            // Receiver couldn't keep up, missed `count` messages
-            log::warn!("Missed {} events", count);
-            // Continue receiving new messages
-        }
-        Err(RecvError::Closed) => {
-            break;  // All senders dropped
-        }
-    }
-}
-```
-
-## Event Bus Pattern
-
-```rust
-use tokio::sync::broadcast;
-
-#[derive(Clone, Debug)]
-enum AppEvent {
-    UserLoggedIn { user_id: u64 },
-    OrderCreated { order_id: u64 },
-    SystemShutdown,
-}
-
-struct EventBus {
-    tx: broadcast::Sender<AppEvent>,
-}
-
-impl EventBus {
-    fn new() -> Self {
-        let (tx, _) = broadcast::channel(1000);
-        EventBus { tx }
-    }
-    
-    fn publish(&self, event: AppEvent) {
-        // Ignore error if no subscribers
-        let _ = self.tx.send(event);
-    }
-    
-    fn subscribe(&self) -> broadcast::Receiver<AppEvent> {
-        self.tx.subscribe()
-    }
-}
-
-// Usage
-let bus = EventBus::new();
-
-// Logger subscribes
-let mut log_rx = bus.subscribe();
-tokio::spawn(async move {
-    while let Ok(event) = log_rx.recv().await {
-        log::info!("Event: {:?}", event);
-    }
-});
-
-// Metrics subscribes
-let mut metrics_rx = bus.subscribe();
-tokio::spawn(async move {
-    while let Ok(event) = metrics_rx.recv().await {
-        record_metric(&event);
-    }
-});
-
-// Publish events
-bus.publish(AppEvent::UserLoggedIn { user_id: 42 });
-```
-
-## Broadcast vs Watch
-
-```rust
-// broadcast: subscribers get ALL messages
-// Good for: events, logs, notifications
-let (tx, _) = broadcast::channel::<Event>(100);
-
-// watch: subscribers get LATEST value only
-// Good for: config changes, state updates
-let (tx, _) = watch::channel(initial_state);
-
-// If subscriber is slow:
-// - broadcast: they receive old messages (or lag)
-// - watch: they skip to latest (no history)
-```
-
-## Clone Requirement
-
-```rust
-// broadcast requires Clone because message is cloned to each receiver
-use tokio::sync::broadcast;
-
-#[derive(Clone)]  // Required for broadcast
-struct Event {
-    data: String,
-}
-
-let (tx, _) = broadcast::channel::<Event>(100);
-
-// For non-Clone types, wrap in Arc
-use std::sync::Arc;
-
-let (tx, _) = broadcast::channel::<Arc<LargeNonClone>>(100);
-```
-
-## See Also
-
-- [async-mpsc-queue](./async-mpsc-queue.md) - Single-consumer channels
-- [async-watch-latest](./async-watch-latest.md) - Latest-value only
-- [async-bounded-channel](./async-bounded-channel.md) - Buffer sizing

package/template/agent/skills/rust-developer/references/rust-rules/async-cancellation-token.md

@@ -1,203 +0,0 @@
-# async-cancellation-token
-
-> Use `CancellationToken` for graceful shutdown and task cancellation
-
-## Why It Matters
-
-Dropping a `JoinHandle` doesn't cancel the task—it just detaches it. For graceful shutdown, you need explicit cancellation. `tokio_util::sync::CancellationToken` provides a cooperative cancellation mechanism that tasks can check and respond to, enabling clean resource cleanup.
-
-## Bad
-
-```rust
-// Dropping handle doesn't stop the task
-let handle = tokio::spawn(async {
-    loop {
-        do_work().await;
-    }
-});
-
-drop(handle);  // Task continues running in background!
-
-// Using bool flag - not async-aware
-let running = Arc::new(AtomicBool::new(true));
-
-tokio::spawn({
-    let running = running.clone();
-    async move {
-        while running.load(Ordering::Relaxed) {
-            do_work().await;  // Can't wake up if blocked here
-        }
-    }
-});
-
-running.store(false, Ordering::Relaxed);
-// Task won't stop until current do_work() completes
-```
-
-## Good
-
-```rust
-use tokio_util::sync::CancellationToken;
-
-let token = CancellationToken::new();
-
-let handle = tokio::spawn({
-    let token = token.clone();
-    async move {
-        loop {
-            tokio::select! {
-                _ = token.cancelled() => {
-                    println!("Shutting down gracefully");
-                    cleanup().await;
-                    break;
-                }
-                _ = do_work() => {
-                    // Work completed
-                }
-            }
-        }
-    }
-});
-
-// Later: trigger cancellation
-token.cancel();
-handle.await?;  // Task completes cleanly
-```
-
-## CancellationToken API
-
-```rust
-use tokio_util::sync::CancellationToken;
-
-// Create token
-let token = CancellationToken::new();
-
-// Clone for sharing (cheap Arc-based clone)
-let token2 = token.clone();
-
-// Check if cancelled (non-blocking)
-if token.is_cancelled() {
-    return;
-}
-
-// Wait for cancellation (async)
-token.cancelled().await;
-
-// Trigger cancellation
-token.cancel();
-
-// Child tokens - cancelled when parent is cancelled
-let child = token.child_token();
-```
-
-## Hierarchical Cancellation
-
-```rust
-async fn run_server(shutdown: CancellationToken) {
-    let listener = TcpListener::bind("0.0.0.0:8080").await?;
-    
-    loop {
-        tokio::select! {
-            _ = shutdown.cancelled() => {
-                println!("Server shutting down");
-                break;
-            }
-            result = listener.accept() => {
-                let (socket, _) = result?;
-                // Each connection gets child token
-                let conn_token = shutdown.child_token();
-                tokio::spawn(handle_connection(socket, conn_token));
-            }
-        }
-    }
-    
-    // Child tokens auto-cancelled when we exit
-}
-
-async fn handle_connection(socket: TcpStream, token: CancellationToken) {
-    loop {
-        tokio::select! {
-            _ = token.cancelled() => {
-                // Connection cleanup
-                break;
-            }
-            data = socket.read() => {
-                // Handle data
-            }
-        }
-    }
-}
-```
-
-## Graceful Shutdown Pattern
-
-```rust
-use tokio::signal;
-
-async fn main() -> Result<()> {
-    let shutdown = CancellationToken::new();
-    
-    // Spawn signal handler
-    let shutdown_trigger = shutdown.clone();
-    tokio::spawn(async move {
-        signal::ctrl_c().await.expect("failed to listen for Ctrl+C");
-        println!("Received Ctrl+C, initiating shutdown...");
-        shutdown_trigger.cancel();
-    });
-    
-    // Run application with shutdown token
-    run_app(shutdown).await
-}
-
-async fn run_app(shutdown: CancellationToken) -> Result<()> {
-    let mut tasks = JoinSet::new();
-    
-    tasks.spawn(worker_task(shutdown.child_token()));
-    tasks.spawn(server_task(shutdown.child_token()));
-    
-    // Wait for shutdown or task completion
-    tokio::select! {
-        _ = shutdown.cancelled() => {
-            println!("Shutdown requested, waiting for tasks...");
-        }
-        Some(result) = tasks.join_next() => {
-            // A task completed/failed
-            result??;
-        }
-    }
-    
-    // Wait for remaining tasks with timeout
-    tokio::time::timeout(
-        Duration::from_secs(30),
-        async { while tasks.join_next().await.is_some() {} }
-    ).await.ok();
-    
-    Ok(())
-}
-```
-
-## DropGuard Pattern
-
-```rust
-use tokio_util::sync::CancellationToken;
-
-// Auto-cancel on drop
-let token = CancellationToken::new();
-let guard = token.clone().drop_guard();
-
-tokio::spawn({
-    let token = token.clone();
-    async move {
-        token.cancelled().await;
-        println!("Cancelled!");
-    }
-});
-
-drop(guard);  // Automatically calls token.cancel()
-```
-
-## See Also
-
-- [async-joinset-structured](./async-joinset-structured.md) - Managing multiple tasks
-- [async-select-racing](./async-select-racing.md) - select! for cancellation
-- [async-tokio-runtime](./async-tokio-runtime.md) - Runtime shutdown

package/template/agent/skills/rust-developer/references/rust-rules/async-clone-before-await.md

@@ -1,171 +0,0 @@
-# async-clone-before-await
-
-> Clone Arc/Rc data before await points to avoid holding references across suspension
-
-## Why It Matters
-
-References held across `.await` points extend the future's lifetime and can cause borrow checker issues or prevent `Send` bounds. Cloning `Arc`/`Rc` before the await ensures the future only holds owned data, making it `Send` and avoiding lifetime complications.
-
-## Bad
-
-```rust
-use std::sync::Arc;
-
-async fn process(data: Arc<Data>) {
-    // Borrow extends across await - future is not Send
-    let slice = &data.items[..];  // Borrow of Arc contents
-    
-    expensive_async_operation().await;  // Await with active borrow
-    
-    use_slice(slice);  // Still using the borrow
-}
-
-// Error: future cannot be sent between threads safely
-// because `&[Item]` cannot be sent between threads safely
-tokio::spawn(process(data));
-```
-
-## Good
-
-```rust
-use std::sync::Arc;
-
-async fn process(data: Arc<Data>) {
-    // Clone what you need before await
-    let items = data.items.clone();  // Owned Vec
-    
-    expensive_async_operation().await;
-    
-    use_items(&items);  // Using owned data
-}
-
-// Or clone the Arc itself
-async fn share_data(data: Arc<Data>) {
-    let data = data.clone();  // Another Arc handle
-    
-    some_async_work().await;
-    
-    process(&data);  // Safe - we own the Arc
-}
-```
-
-## The Send Problem
-
-```rust
-// Futures must be Send to spawn on multi-threaded runtime
-async fn not_send() {
-    let rc = Rc::new(42);  // Rc is !Send
-    
-    tokio::time::sleep(Duration::from_secs(1)).await;
-    
-    println!("{}", rc);  // rc held across await
-}
-
-tokio::spawn(not_send());  // ERROR: future is not Send
-
-// Fix: use Arc or don't hold across await
-async fn is_send() {
-    let arc = Arc::new(42);  // Arc is Send
-    
-    tokio::time::sleep(Duration::from_secs(1)).await;
-    
-    println!("{}", arc);
-}
-
-tokio::spawn(is_send());  // OK
-```
-
-## Minimizing Clones
-
-```rust
-// Bad: clone everything eagerly
-async fn wasteful(data: Arc<LargeData>) {
-    let data = (*data).clone();  // Clones entire LargeData
-    async_work().await;
-    use_one_field(&data.small_field);
-}
-
-// Good: clone only what you need
-async fn efficient(data: Arc<LargeData>) {
-    let small = data.small_field.clone();  // Clone only needed field
-    async_work().await;
-    use_one_field(&small);
-}
-
-// Good: if you need the whole thing, keep the Arc
-async fn arc_efficient(data: Arc<LargeData>) {
-    let data = data.clone();  // Cheap Arc clone
-    async_work().await;
-    use_data(&data);  // Access through Arc
-}
-```
-
-## Spawn Pattern
-
-```rust
-// Common pattern: clone for spawned task
-let shared = Arc::new(SharedState::new());
-
-for i in 0..10 {
-    let shared = shared.clone();  // Clone before moving into spawn
-    tokio::spawn(async move {
-        // Task owns its Arc clone
-        shared.do_something(i).await;
-    });
-}
-```
-
-## Scope-Based Approach
-
-```rust
-// Limit borrow scope to before await
-async fn scoped(data: Arc<Data>) {
-    // Scope 1: borrow, compute, drop borrow
-    let computed = {
-        let slice = &data.items[..];  // Borrow
-        compute_something(slice)       // Use
-    };  // Borrow ends here
-    
-    // Now safe to await
-    expensive_async_operation().await;
-    
-    use_computed(computed);
-}
-```
-
-## MutexGuard Across Await
-
-```rust
-use tokio::sync::Mutex;
-
-// BAD: holding guard across await
-async fn bad(mutex: Arc<Mutex<Data>>) {
-    let mut guard = mutex.lock().await;
-    guard.value += 1;
-    
-    slow_operation().await;  // Guard held during await!
-    
-    guard.value += 1;
-}
-
-// GOOD: release before await
-async fn good(mutex: Arc<Mutex<Data>>) {
-    {
-        let mut guard = mutex.lock().await;
-        guard.value += 1;
-    }  // Guard released
-    
-    slow_operation().await;
-    
-    {
-        let mut guard = mutex.lock().await;
-        guard.value += 1;
-    }
-}
-```
-
-## See Also
-
-- [async-no-lock-await](./async-no-lock-await.md) - Lock guards across await
-- [own-arc-shared](./own-arc-shared.md) - Arc usage patterns
-- [async-spawn-blocking](./async-spawn-blocking.md) - Blocking in async

package/template/agent/skills/rust-developer/references/rust-rules/async-join-parallel.md

@@ -1,158 +0,0 @@
-# async-join-parallel
-
-> Use `join!` or `try_join!` for concurrent independent futures
-
-## Why It Matters
-
-Awaiting futures sequentially takes the sum of their durations. `join!` runs futures concurrently, taking only as long as the slowest one. For independent operations like multiple API calls or parallel file reads, this can dramatically reduce latency.
-
-## Bad
-
-```rust
-async fn fetch_data() -> (User, Posts, Comments) {
-    // Sequential: 300ms total (100 + 100 + 100)
-    let user = fetch_user().await;        // 100ms
-    let posts = fetch_posts().await;      // 100ms  
-    let comments = fetch_comments().await; // 100ms
-    
-    (user, posts, comments)
-}
-
-async fn read_configs() -> Result<(Config, Settings)> {
-    // Sequential: 20ms + 20ms = 40ms
-    let config = fs::read_to_string("config.toml").await?;
-    let settings = fs::read_to_string("settings.json").await?;
-    
-    Ok((parse_config(&config)?, parse_settings(&settings)?))
-}
-```
-
-## Good
-
-```rust
-use tokio::join;
-
-async fn fetch_data() -> (User, Posts, Comments) {
-    // Concurrent: ~100ms total (max of all three)
-    let (user, posts, comments) = join!(
-        fetch_user(),
-        fetch_posts(),
-        fetch_comments(),
-    );
-    
-    (user, posts, comments)
-}
-
-use tokio::try_join;
-
-async fn read_configs() -> Result<(Config, Settings)> {
-    // Concurrent: ~20ms total
-    let (config_str, settings_str) = try_join!(
-        fs::read_to_string("config.toml"),
-        fs::read_to_string("settings.json"),
-    )?;
-    
-    Ok((parse_config(&config_str)?, parse_settings(&settings_str)?))
-}
-```
-
-## join! vs try_join!
-
-```rust
-// join! - all futures run to completion, returns tuple
-let (a, b, c) = join!(future_a, future_b, future_c);
-
-// try_join! - short-circuits on first error
-let (a, b, c) = try_join!(fallible_a, fallible_b, fallible_c)?;
-// If fallible_b fails, returns Err immediately
-// Other futures may still be running (cancellation is async)
-```
-
-## futures::join_all for Dynamic Collections
-
-```rust
-use futures::future::join_all;
-
-async fn fetch_all_users(ids: &[u64]) -> Vec<User> {
-    let futures: Vec<_> = ids.iter()
-        .map(|id| fetch_user(*id))
-        .collect();
-    
-    join_all(futures).await
-}
-
-// With fallible futures
-use futures::future::try_join_all;
-
-async fn fetch_all_users(ids: &[u64]) -> Result<Vec<User>> {
-    let futures: Vec<_> = ids.iter()
-        .map(|id| fetch_user(*id))
-        .collect();
-    
-    try_join_all(futures).await
-}
-```
-
-## Limiting Concurrency
-
-```rust
-use futures::stream::{self, StreamExt};
-
-async fn fetch_with_limit(ids: &[u64]) -> Vec<Result<User>> {
-    stream::iter(ids)
-        .map(|id| fetch_user(*id))
-        .buffer_unordered(10)  // Max 10 concurrent requests
-        .collect()
-        .await
-}
-
-// Or with tokio::sync::Semaphore
-use tokio::sync::Semaphore;
-
-async fn fetch_with_semaphore(ids: &[u64]) -> Vec<User> {
-    let semaphore = Arc::new(Semaphore::new(10));
-    
-    let futures: Vec<_> = ids.iter().map(|id| {
-        let semaphore = semaphore.clone();
-        async move {
-            let _permit = semaphore.acquire().await.unwrap();
-            fetch_user(*id).await
-        }
-    }).collect();
-    
-    join_all(futures).await
-}
-```
-
-## When NOT to Use join!
-
-```rust
-// ❌ Dependent futures - must be sequential
-async fn create_and_populate() -> Result<()> {
-    let db = create_database().await?;   // Must complete first
-    populate_tables(&db).await?;          // Depends on db
-    Ok(())
-}
-
-// ❌ Short-circuiting logic
-async fn find_first() -> Option<Data> {
-    // Want to stop when one succeeds
-    // Use select! instead
-}
-
-// ❌ Shared mutable state
-async fn bad_shared_state() {
-    let counter = Arc::new(Mutex::new(0));
-    // This might work but can cause contention
-    join!(
-        increment(counter.clone()),
-        increment(counter.clone()),
-    );
-}
-```
-
-## See Also
-
-- [async-try-join](./async-try-join.md) - Error handling in concurrent futures
-- [async-select-racing](./async-select-racing.md) - Racing futures
-- [async-joinset-structured](./async-joinset-structured.md) - Dynamic task sets