agy-superpowers 5.2.2 → 5.2.4

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

@@ -1,172 +0,0 @@
-# async-try-join
-
-> Use `try_join!` for concurrent fallible operations with early return on error
-
-## Why It Matters
-
-When running multiple fallible operations concurrently, `try_join!` returns `Err` as soon as any future fails, without waiting for the others. This provides fail-fast behavior while still running operations in parallel. For many operations, use `futures::future::try_join_all`.
-
-## Bad
-
-```rust
-// Sequential - slow and no early return benefit
-async fn fetch_all() -> Result<(A, B, C)> {
-    let a = fetch_a().await?;  // If this fails, we wait for nothing
-    let b = fetch_b().await?;  // But if this fails, we waited for A
-    let c = fetch_c().await?;
-    Ok((a, b, c))
-}
-
-// join! ignores errors
-async fn fetch_all() -> (Result<A>, Result<B>, Result<C>) {
-    let (a, b, c) = join!(fetch_a(), fetch_b(), fetch_c());
-    // All complete even if first one failed
-    (a, b, c)  // Now we have to handle three Results
-}
-```
-
-## Good
-
-```rust
-use tokio::try_join;
-
-async fn fetch_all() -> Result<(A, B, C)> {
-    // Concurrent AND fail-fast
-    let (a, b, c) = try_join!(
-        fetch_a(),
-        fetch_b(),
-        fetch_c(),
-    )?;
-    
-    Ok((a, b, c))
-}
-
-// For dynamic collections
-use futures::future::try_join_all;
-
-async fn fetch_users(ids: &[u64]) -> Result<Vec<User>> {
-    let futures: Vec<_> = ids.iter()
-        .map(|id| fetch_user(*id))
-        .collect();
-    
-    try_join_all(futures).await
-}
-```
-
-## Error Handling Patterns
-
-```rust
-// Different error types - need common error type
-async fn mixed_operations() -> Result<(A, B), Error> {
-    let (a, b) = try_join!(
-        fetch_a().map_err(Error::from),  // Convert errors
-        fetch_b().map_err(Error::from),
-    )?;
-    Ok((a, b))
-}
-
-// Collect all results, then handle errors
-async fn all_or_nothing(ids: &[u64]) -> Result<Vec<User>> {
-    try_join_all(ids.iter().map(|id| fetch_user(*id))).await
-}
-
-// Collect successes, log failures
-async fn best_effort(ids: &[u64]) -> Vec<User> {
-    let results = futures::future::join_all(
-        ids.iter().map(|id| fetch_user(*id))
-    ).await;
-    
-    results.into_iter()
-        .filter_map(|r| match r {
-            Ok(user) => Some(user),
-            Err(e) => {
-                log::warn!("Failed to fetch user: {}", e);
-                None
-            }
-        })
-        .collect()
-}
-```
-
-## Cancellation Behavior
-
-```rust
-// try_join! cancels remaining futures on error
-async fn with_cancellation() -> Result<()> {
-    // If fetch_a() fails, fetch_b() and fetch_c() are dropped
-    // But "dropped" != "immediately stopped"
-    // They stop at their next .await point
-    
-    try_join!(
-        async {
-            fetch_a().await?;
-            cleanup_a().await;  // May not run if other future fails
-            Ok::<_, Error>(())
-        },
-        async {
-            fetch_b().await?;
-            cleanup_b().await;  // May not run if other future fails
-            Ok::<_, Error>(())
-        },
-    )?;
-    
-    Ok(())
-}
-
-// For guaranteed cleanup, use Drop guards or explicit handling
-```
-
-## With Timeout
-
-```rust
-use tokio::time::{timeout, Duration};
-
-async fn fetch_with_timeout() -> Result<(A, B)> {
-    timeout(
-        Duration::from_secs(10),
-        try_join!(fetch_a(), fetch_b())
-    )
-    .await
-    .map_err(|_| Error::Timeout)?
-}
-
-// Per-operation timeout
-async fn individual_timeouts() -> Result<(A, B)> {
-    try_join!(
-        timeout(Duration::from_secs(5), fetch_a())
-            .map_err(|_| Error::Timeout)
-            .and_then(|r| async { r }),
-        timeout(Duration::from_secs(5), fetch_b())
-            .map_err(|_| Error::Timeout)
-            .and_then(|r| async { r }),
-    )
-}
-```
-
-## try_join! vs FuturesUnordered
-
-```rust
-use futures::stream::{FuturesUnordered, StreamExt};
-
-// try_join!: wait for all, fail fast
-let (a, b, c) = try_join!(fa, fb, fc)?;
-
-// FuturesUnordered: process as they complete
-let mut futures = FuturesUnordered::new();
-futures.push(fetch_a());
-futures.push(fetch_b());
-futures.push(fetch_c());
-
-while let Some(result) = futures.next().await {
-    match result {
-        Ok(data) => process(data),
-        Err(e) => return Err(e),  // Can fail fast manually
-    }
-}
-```
-
-## See Also
-
-- [async-join-parallel](./async-join-parallel.md) - Non-fallible concurrent futures
-- [async-select-racing](./async-select-racing.md) - First-to-complete semantics
-- [err-question-mark](./err-question-mark.md) - Error propagation

package/template/agent/skills/rust-developer/references/rust-rules/async-watch-latest.md

@@ -1,189 +0,0 @@
-# async-watch-latest
-
-> Use `watch` channel for sharing the latest value with multiple observers
-
-## Why It Matters
-
-`watch` is optimized for scenarios where receivers only care about the most recent value, not the history of changes. Unlike `broadcast`, slow receivers don't lag—they simply skip intermediate values. This is perfect for configuration, state, or status that should always reflect the current situation.
-
-## Bad
-
-```rust
-// Using broadcast when only latest value matters
-let (tx, _) = broadcast::channel::<Config>(100);
-
-// Receivers might process stale configs if they're slow
-// And they waste time processing intermediate values
-
-// Using mpsc with buffered stale values
-let (tx, mut rx) = mpsc::channel::<Status>(100);
-// Receiver might process outdated statuses
-```
-
-## Good
-
-```rust
-use tokio::sync::watch;
-
-let (tx, rx) = watch::channel(Config::default());
-
-// Multiple observers
-let rx1 = rx.clone();
-let rx2 = rx.clone();
-
-// Observer 1: waits for changes
-tokio::spawn(async move {
-    let mut rx = rx1;
-    while rx.changed().await.is_ok() {
-        let config = rx.borrow();
-        apply_config(&*config);
-    }
-});
-
-// Observer 2: also sees all changes
-tokio::spawn(async move {
-    let mut rx = rx2;
-    while rx.changed().await.is_ok() {
-        let config = rx.borrow();
-        log_config_change(&*config);
-    }
-});
-
-// Update the value
-tx.send(Config::new())?;
-```
-
-## watch Semantics
-
-```rust
-use tokio::sync::watch;
-
-let (tx, mut rx) = watch::channel("initial");
-
-// Immediate read - no waiting
-assert_eq!(*rx.borrow(), "initial");
-
-// Wait for change
-tx.send("updated")?;
-rx.changed().await?;
-assert_eq!(*rx.borrow(), "updated");
-
-// Multiple rapid updates - receiver sees latest
-tx.send("v1")?;
-tx.send("v2")?;
-tx.send("v3")?;
-rx.changed().await?;
-assert_eq!(*rx.borrow(), "v3");  // Skipped v1, v2
-```
-
-## Configuration Reload Pattern
-
-```rust
-use tokio::sync::watch;
-use std::sync::Arc;
-
-struct AppConfig {
-    log_level: Level,
-    max_connections: usize,
-}
-
-async fn config_watcher(tx: watch::Sender<Arc<AppConfig>>) {
-    loop {
-        tokio::time::sleep(Duration::from_secs(60)).await;
-        
-        if let Ok(new_config) = reload_config_from_disk() {
-            // Only notifies if value actually changed
-            tx.send_if_modified(|current| {
-                if *current != new_config {
-                    *current = Arc::new(new_config);
-                    true
-                } else {
-                    false
-                }
-            });
-        }
-    }
-}
-
-async fn worker(mut config_rx: watch::Receiver<Arc<AppConfig>>) {
-    loop {
-        tokio::select! {
-            _ = config_rx.changed() => {
-                let config = config_rx.borrow().clone();
-                reconfigure(&config);
-            }
-            _ = do_work() => {}
-        }
-    }
-}
-```
-
-## State Machine Updates
-
-```rust
-#[derive(Clone, PartialEq)]
-enum ConnectionState {
-    Disconnected,
-    Connecting,
-    Connected,
-    Error(String),
-}
-
-struct Connection {
-    state_tx: watch::Sender<ConnectionState>,
-    state_rx: watch::Receiver<ConnectionState>,
-}
-
-impl Connection {
-    async fn wait_connected(&mut self) -> Result<(), Error> {
-        loop {
-            let state = self.state_rx.borrow().clone();
-            match state {
-                ConnectionState::Connected => return Ok(()),
-                ConnectionState::Error(e) => return Err(Error::Connection(e)),
-                _ => {
-                    self.state_rx.changed().await?;
-                }
-            }
-        }
-    }
-}
-```
-
-## Borrow vs Clone
-
-```rust
-use tokio::sync::watch;
-
-let (tx, rx) = watch::channel(vec![1, 2, 3]);
-
-// borrow() returns Ref - must not hold across await
-{
-    let data = rx.borrow();
-    println!("{:?}", *data);
-}  // Ref dropped here
-
-// For use across await, clone the data
-let data = rx.borrow().clone();
-some_async_operation().await;
-use_data(&data);  // Safe
-
-// Or use borrow_and_update() to mark as seen
-let data = rx.borrow_and_update().clone();
-```
-
-## watch vs broadcast vs mpsc
-
-| Feature | watch | broadcast | mpsc |
-|---------|-------|-----------|------|
-| Receivers | Multiple | Multiple | Single |
-| Message delivery | Latest only | All messages | All messages |
-| Slow receiver | Skips to latest | Lags/misses | Backpressure |
-| Clone required | No | Yes | No |
-| Best for | Config, status | Events | Work queues |
-
-## See Also
-
-- [async-broadcast-pubsub](./async-broadcast-pubsub.md) - When history matters
-- [async-mpsc-queue](./async-mpsc-queue.md) - Work queue patterns
-- [async-cancellation-token](./async-cancellation-token.md) - Related pattern

package/template/agent/skills/rust-developer/references/rust-rules/doc-all-public.md

@@ -1,113 +0,0 @@
-# doc-all-public
-
-> Document all public items with `///` doc comments
-
-## Why It Matters
-
-Public items define your crate's API contract. Without documentation, users must read source code to understand how to use your library. Well-documented APIs reduce support burden, improve adoption, and serve as the primary reference for users.
-
-Rust's `cargo doc` generates beautiful HTML documentation from doc comments, but only if you write them.
-
-## Bad
-
-```rust
-pub struct Config {
-    pub timeout: Duration,
-    pub retries: u32,
-    pub base_url: String,
-}
-
-pub fn connect(config: Config) -> Result<Connection, Error> {
-    // ...
-}
-
-pub enum Status {
-    Pending,
-    Active,
-    Failed,
-}
-```
-
-## Good
-
-```rust
-/// Configuration for establishing a connection to the service.
-///
-/// # Examples
-///
-/// ```
-/// use my_crate::Config;
-/// use std::time::Duration;
-///
-/// let config = Config {
-///     timeout: Duration::from_secs(30),
-///     retries: 3,
-///     base_url: "https://api.example.com".to_string(),
-/// };
-/// ```
-pub struct Config {
-    /// Maximum time to wait for a response before timing out.
-    pub timeout: Duration,
-    
-    /// Number of retry attempts for failed requests.
-    pub retries: u32,
-    
-    /// Base URL for all API requests.
-    pub base_url: String,
-}
-
-/// Establishes a connection using the provided configuration.
-///
-/// # Errors
-///
-/// Returns an error if the connection cannot be established
-/// or if the configuration is invalid.
-pub fn connect(config: Config) -> Result<Connection, Error> {
-    // ...
-}
-
-/// Represents the current status of a job.
-pub enum Status {
-    /// Job is waiting to be processed.
-    Pending,
-    /// Job is currently being processed.
-    Active,
-    /// Job has failed and will not be retried.
-    Failed,
-}
-```
-
-## What to Document
-
-| Item Type | Required Content |
-|-----------|------------------|
-| Structs | Purpose, usage example |
-| Struct fields | What the field represents |
-| Enums | When to use each variant |
-| Enum variants | What state it represents |
-| Functions | What it does, parameters, return value |
-| Traits | Contract and expected behavior |
-| Trait methods | Default implementation behavior |
-| Type aliases | Why the alias exists |
-| Constants | What the value represents |
-
-## Enforcement
-
-Enable the `missing_docs` lint to catch undocumented public items:
-
-```rust
-#![warn(missing_docs)]
-```
-
-Or in `Cargo.toml` for workspace-wide enforcement:
-
-```toml
-[workspace.lints.rust]
-missing_docs = "warn"
-```
-
-## See Also
-
-- [doc-module-inner](./doc-module-inner.md) - Module-level documentation
-- [doc-examples-section](./doc-examples-section.md) - Adding examples
-- [lint-missing-docs](./lint-missing-docs.md) - Enforcing documentation

package/template/agent/skills/rust-developer/references/rust-rules/doc-cargo-metadata.md

@@ -1,147 +0,0 @@
-# doc-cargo-metadata
-
-> Fill `Cargo.toml` metadata for published crates
-
-## Why It Matters
-
-Cargo.toml metadata appears on crates.io, in search results, and helps users evaluate your crate. Missing metadata makes your crate look unprofessional, harder to find, and harder to trust. Complete metadata improves discoverability and adoption.
-
-## Bad
-
-```toml
-[package]
-name = "my-awesome-crate"
-version = "0.1.0"
-edition = "2021"
-
-[dependencies]
-# ...
-```
-
-## Good
-
-```toml
-[package]
-name = "my-awesome-crate"
-version = "0.1.0"
-edition = "2021"
-rust-version = "1.70"
-
-# Required for crates.io
-description = "A fast, ergonomic HTTP client for Rust"
-license = "MIT OR Apache-2.0"
-repository = "https://github.com/username/my-awesome-crate"
-
-# Highly recommended
-documentation = "https://docs.rs/my-awesome-crate"
-readme = "README.md"
-keywords = ["http", "client", "async", "networking"]
-categories = ["network-programming", "web-programming::http-client"]
-authors = ["Your Name <you@example.com>"]
-homepage = "https://my-awesome-crate.dev"
-
-# Optional but helpful
-include = ["src/**/*", "Cargo.toml", "LICENSE*", "README.md"]
-exclude = ["tests/fixtures/*", ".github/*"]
-
-[badges]
-maintenance = { status = "actively-developed" }
-
-[dependencies]
-# ...
-```
-
-## Required Fields for Publishing
-
-| Field | Purpose |
-|-------|---------|
-| `name` | Crate name on crates.io |
-| `version` | Semver version |
-| `license` or `license-file` | SPDX license identifier |
-| `description` | One-line summary (≤256 chars) |
-
-## Recommended Fields
-
-| Field | Purpose | Example |
-|-------|---------|---------|
-| `repository` | Link to source code | `https://github.com/user/repo` |
-| `documentation` | Link to docs | `https://docs.rs/crate` |
-| `readme` | Path to README | `README.md` |
-| `keywords` | Search terms (max 5) | `["http", "async"]` |
-| `categories` | crates.io categories | `["network-programming"]` |
-| `rust-version` | MSRV | `"1.70"` |
-
-## Keywords Best Practices
-
-```toml
-# Good: specific, searchable terms
-keywords = ["json", "serialization", "serde", "parsing"]
-
-# Bad: too generic or redundant
-keywords = ["rust", "library", "awesome", "fast", "best"]
-```
-
-## Categories
-
-Choose from [crates.io categories](https://crates.io/category_slugs):
-
-```toml
-categories = [
-    "network-programming",
-    "web-programming::http-client",
-    "asynchronous",
-]
-```
-
-## License Patterns
-
-```toml
-# Single license
-license = "MIT"
-
-# Dual license (common in Rust ecosystem)
-license = "MIT OR Apache-2.0"
-
-# Custom license file
-license-file = "LICENSE"
-```
-
-## Include/Exclude
-
-Control what gets published:
-
-```toml
-# Explicit include (whitelist)
-include = [
-    "src/**/*",
-    "Cargo.toml",
-    "LICENSE*",
-    "README.md",
-    "CHANGELOG.md",
-]
-
-# Or exclude (blacklist)
-exclude = [
-    "tests/fixtures/large-file.bin",
-    ".github/*",
-    "benches/*",
-]
-```
-
-## Verification
-
-Check your package before publishing:
-
-```bash
-# See what will be included
-cargo package --list
-
-# Check metadata
-cargo publish --dry-run
-```
-
-## See Also
-
-- [doc-module-inner](./doc-module-inner.md) - Crate-level documentation
-- [lint-cargo-metadata](./lint-cargo-metadata.md) - Linting Cargo.toml
-- [proj-workspace-deps](./proj-workspace-deps.md) - Workspace management