agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/name-consts-screaming.md

@@ -0,0 +1,94 @@
+# name-consts-screaming
+
+> Use `SCREAMING_SNAKE_CASE` for constants and statics
+
+## Why It Matters
+
+Constants and statics are special—they're known at compile time and have program-wide lifetime. `SCREAMING_SNAKE_CASE` makes them visually distinct from runtime variables. This convention is enforced by the compiler and universally expected.
+
+## Bad
+
+```rust
+// lowercase/camelCase constants - compiler warns
+const maxConnections: u32 = 100;  // warning
+const default_timeout: u64 = 30;  // warning
+static globalCounter: AtomicU64 = AtomicU64::new(0);  // warning
+```
+
+## Good
+
+```rust
+// SCREAMING_SNAKE_CASE for constants
+const MAX_CONNECTIONS: u32 = 100;
+const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
+const BUFFER_SIZE: usize = 4096;
+
+// SCREAMING_SNAKE_CASE for statics
+static GLOBAL_COUNTER: AtomicU64 = AtomicU64::new(0);
+static CONFIG: OnceLock<Config> = OnceLock::new();
+
+// Type-level constants in impl blocks
+impl Buffer {
+    const INITIAL_CAPACITY: usize = 1024;
+    const MAX_CAPACITY: usize = 1024 * 1024;
+}
+```
+
+## Associated Constants
+
+```rust
+trait Limit {
+    const MAX: usize;
+    const MIN: usize;
+}
+
+impl Limit for SmallBuffer {
+    const MAX: usize = 256;
+    const MIN: usize = 16;
+}
+
+// Generic associated constants
+struct Container<T> {
+    data: Vec<T>,
+}
+
+impl<T> Container<T> {
+    const EMPTY: Self = Self { data: Vec::new() };
+}
+```
+
+## Environment and Config
+
+```rust
+// Environment variable names
+const ENV_DATABASE_URL: &str = "DATABASE_URL";
+const ENV_LOG_LEVEL: &str = "LOG_LEVEL";
+
+// Configuration keys
+const CONFIG_TIMEOUT_SECONDS: &str = "timeout_seconds";
+const CONFIG_MAX_RETRIES: &str = "max_retries";
+```
+
+## Lazy Static / OnceLock
+
+```rust
+use std::sync::OnceLock;
+
+// Global configuration
+static CONFIG: OnceLock<AppConfig> = OnceLock::new();
+
+// Compiled regex
+static EMAIL_REGEX: OnceLock<Regex> = OnceLock::new();
+
+fn get_email_regex() -> &'static Regex {
+    EMAIL_REGEX.get_or_init(|| {
+        Regex::new(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$").unwrap()
+    })
+}
+```
+
+## See Also
+
+- [name-funcs-snake](./name-funcs-snake.md) - Function/variable naming
+- [name-types-camel](./name-types-camel.md) - Type naming
+- [type-newtype-ids](./type-newtype-ids.md) - Type-safe constants

package/template/agent/skills/rust-developer/references/rust-rules/name-crate-no-rs.md

@@ -0,0 +1,78 @@
+# name-crate-no-rs
+
+> Don't suffix crate names with `-rs` or `-rust`
+
+## Why It Matters
+
+Adding `-rs` or `-rust` to crate names is redundant—you're already on crates.io, it's obviously Rust. These suffixes waste characters, clutter the namespace, and can make crate names harder to type. The Rust community discourages this pattern.
+
+## Bad
+
+```toml
+# Cargo.toml
+[package]
+name = "json-parser-rs"    # Redundant -rs
+name = "my-lib-rust"       # Redundant -rust
+name = "http-client-rs"    # We know it's Rust
+name = "rust-sqlite"       # rust- prefix equally bad
+```
+
+## Good
+
+```toml
+# Cargo.toml
+[package]
+name = "json-parser"
+name = "my-lib"
+name = "http-client"
+name = "sqlite-wrapper"
+
+# Real crate examples (no -rs):
+# serde (not serde-rs)
+# tokio (not tokio-rs)
+# reqwest (not reqwest-rs)
+# clap (not clap-rs)
+```
+
+## When Context Is Needed
+
+```toml
+# If you're porting a library from another language:
+name = "python-ast"        # Describes what it's for, not what it's written in
+
+# If you're providing bindings:
+name = "openssl"           # The Rust crate IS the Rust interface
+
+# Platform-specific:
+name = "windows-sys"       # Platform, not language
+```
+
+## Repository Naming
+
+```
+# GitHub repos don't need -rs either
+github.com/user/my-library      # Good
+github.com/user/my-library-rs   # Unnecessary
+
+# Though some do for disambiguation from other language versions
+github.com/rust-lang/rust       # The rust repo itself uses "rust"
+```
+
+## Exceptions
+
+```toml
+# Rare cases where disambiguation matters:
+# - If there's a widely-known non-Rust project with the same name
+# - Official Rust project repositories (rust-lang org)
+
+# But even then, consider alternatives:
+name = "fancy-lib"           # Instead of fancy-rs
+name = "better-json"         # Instead of json-rust
+name = "my-serde-impl"       # Instead of serde-rs-fork
+```
+
+## See Also
+
+- [proj-workspace-deps](./proj-workspace-deps.md) - Cargo configuration
+- [doc-cargo-metadata](./doc-cargo-metadata.md) - Package metadata
+- [name-funcs-snake](./name-funcs-snake.md) - Naming conventions

package/template/agent/skills/rust-developer/references/rust-rules/name-funcs-snake.md

@@ -0,0 +1,76 @@
+# name-funcs-snake
+
+> Use `snake_case` for functions, methods, variables, and modules
+
+## Why It Matters
+
+Rust uses `snake_case` for "value-level" names—functions, methods, variables, modules. This convention is enforced by the compiler and distinguishes runtime entities from types. Consistent naming makes code scannable and predictable.
+
+## Bad
+
+```rust
+// CamelCase functions - compiler warns
+fn calculateTotal() -> f64 { ... }  // warning: function `calculateTotal` should have a snake case name
+fn getUserName() -> String { ... }  // warning
+
+// Inconsistent naming
+fn get_user() -> User { ... }
+fn fetchOrder() -> Order { ... }  // Mixed conventions
+```
+
+## Good
+
+```rust
+// snake_case for functions
+fn calculate_total() -> f64 { ... }
+fn get_user_name() -> String { ... }
+fn fetch_order() -> Order { ... }
+
+// snake_case for methods
+impl User {
+    fn full_name(&self) -> String { ... }
+    fn is_active(&self) -> bool { ... }
+    fn set_email(&mut self, email: &str) { ... }
+}
+
+// snake_case for variables
+let user_count = 42;
+let max_connections = 100;
+let is_valid = true;
+
+// snake_case for modules
+mod user_service;
+mod http_client;
+mod json_parser;
+```
+
+## Acronyms in snake_case
+
+```rust
+// Lowercase acronyms in snake_case
+fn parse_json() -> Json { ... }   // Not parse_JSON
+fn connect_tcp() -> TcpStream { ... }   // Not connect_TCP
+fn generate_uuid() -> Uuid { ... }      // Not generate_UUID
+
+let http_response = fetch();
+let json_data = parse();
+```
+
+## Local Variables
+
+```rust
+fn process_data(input_data: &[u8]) -> Result<Output, Error> {
+    let raw_bytes = input_data;
+    let decoded_string = decode(raw_bytes)?;
+    let parsed_value = parse(&decoded_string)?;
+    let final_result = transform(parsed_value)?;
+    
+    Ok(final_result)
+}
+```
+
+## See Also
+
+- [name-types-camel](./name-types-camel.md) - Type naming
+- [name-consts-screaming](./name-consts-screaming.md) - Constant naming
+- [name-lifetime-short](./name-lifetime-short.md) - Lifetime naming

package/template/agent/skills/rust-developer/references/rust-rules/name-into-ownership.md

@@ -0,0 +1,123 @@
+# name-into-ownership
+
+> Use `into_` prefix for ownership-consuming conversions
+
+## Why It Matters
+
+The `into_` prefix signals "this method consumes self and returns something else." The original value is moved and no longer usable. This ownership transfer is usually cheap (no allocation), but the caller loses access to the original. Clear naming prevents "use after move" confusion.
+
+## Bad
+
+```rust
+impl Wrapper {
+    // Misleading: doesn't indicate ownership transfer
+    fn get_inner(self) -> Inner {  
+        self.inner
+    }
+    
+    // Misleading: suggests borrowing
+    fn as_inner(self) -> Inner {  // Takes self by value!
+        self.inner
+    }
+}
+```
+
+## Good
+
+```rust
+impl Wrapper {
+    // into_ clearly shows ownership transfer
+    fn into_inner(self) -> Inner {
+        self.inner
+    }
+}
+
+// Usage is clear
+let wrapper = Wrapper::new(inner);
+let inner = wrapper.into_inner();  // wrapper is consumed
+// wrapper.foo();  // Error: use of moved value
+```
+
+## Standard Library Examples
+
+```rust
+// All consume self and return owned data
+let string: String = "hello".to_string();
+let bytes: Vec<u8> = string.into_bytes();  // String consumed
+
+let path = PathBuf::from("/foo");
+let os_string: OsString = path.into_os_string();  // PathBuf consumed
+
+let boxed: Box<[i32]> = vec![1, 2, 3].into_boxed_slice();  // Vec consumed
+
+let vec: Vec<u8> = boxed.into_vec();  // Box consumed
+```
+
+## into_iter() Pattern
+
+```rust
+let vec = vec![1, 2, 3];
+
+// into_iter consumes the collection
+for item in vec.into_iter() {  // or just: for item in vec
+    // item is i32, not &i32
+}
+// vec is consumed, can't use anymore
+
+// Contrast with iter() which borrows
+let vec = vec![1, 2, 3];
+for item in vec.iter() {
+    // item is &i32
+}
+// vec still usable
+```
+
+## IntoIterator Trait
+
+```rust
+impl IntoIterator for MyCollection {
+    type Item = Element;
+    type IntoIter = std::vec::IntoIter<Element>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.elements.into_iter()  // Consumes self
+    }
+}
+```
+
+## Conversion Prefix Summary
+
+```rust
+struct Buffer {
+    data: Vec<u8>,
+    name: String,
+}
+
+impl Buffer {
+    // as_ : free borrow, returns reference
+    fn as_slice(&self) -> &[u8] {
+        &self.data
+    }
+    
+    // to_ : allocates, creates new value
+    fn to_vec(&self) -> Vec<u8> {
+        self.data.clone()
+    }
+    
+    // into_ : consumes self, usually cheap
+    fn into_inner(self) -> Vec<u8> {
+        self.data
+    }
+    
+    // into_ : can destructure into parts
+    fn into_parts(self) -> (Vec<u8>, String) {
+        (self.data, self.name)
+    }
+}
+```
+
+## See Also
+
+- [name-as-free](./name-as-free.md) - Borrowing conversions
+- [name-to-expensive](./name-to-expensive.md) - Allocating conversions
+- [api-from-not-into](./api-from-not-into.md) - From trait implementation

package/template/agent/skills/rust-developer/references/rust-rules/name-is-has-bool.md

@@ -0,0 +1,127 @@
+# name-is-has-bool
+
+> Use `is_`, `has_`, `can_`, `should_` prefixes for boolean-returning methods
+
+## Why It Matters
+
+Boolean methods answer yes/no questions. Prefixes like `is_`, `has_`, `can_` make the question explicit, so code reads naturally: `if user.is_active()`, `if buffer.has_remaining()`. Without prefixes, boolean methods are ambiguous and require reading documentation.
+
+## Bad
+
+```rust
+impl User {
+    // Unclear: does this check or set?
+    fn active(&self) -> bool { ... }
+    
+    // Unclear: does this delete or check?
+    fn deleted(&self) -> bool { ... }
+    
+    // Unclear return type
+    fn admin(&self) -> bool { ... }
+}
+
+// Reading code is confusing
+if user.active() { ... }  // Is this checking or activating?
+```
+
+## Good
+
+```rust
+impl User {
+    // Clear: answers "is the user active?"
+    fn is_active(&self) -> bool { ... }
+    
+    // Clear: answers "is the user deleted?"
+    fn is_deleted(&self) -> bool { ... }
+    
+    // Clear: answers "is the user an admin?"
+    fn is_admin(&self) -> bool { ... }
+    
+    // Clear: answers "does the user have permission X?"
+    fn has_permission(&self, perm: Permission) -> bool { ... }
+    
+    // Clear: answers "can the user edit?"
+    fn can_edit(&self) -> bool { ... }
+}
+
+// Reads naturally
+if user.is_active() && user.has_permission(Permission::Write) {
+    // ...
+}
+```
+
+## Common Prefixes
+
+| Prefix | Use For | Example |
+|--------|---------|---------|
+| `is_` | State/property check | `is_empty()`, `is_valid()`, `is_some()` |
+| `has_` | Possession/containment | `has_key()`, `has_children()`, `has_remaining()` |
+| `can_` | Capability/permission | `can_read()`, `can_write()`, `can_execute()` |
+| `should_` | Recommendation/policy | `should_retry()`, `should_cache()` |
+| `needs_` | Requirement | `needs_update()`, `needs_auth()` |
+| `will_` | Future action | `will_block()`, `will_overflow()` |
+
+## Standard Library Examples
+
+```rust
+// is_ prefix
+vec.is_empty()
+option.is_some()
+option.is_none()
+result.is_ok()
+result.is_err()
+char.is_alphabetic()
+str.is_ascii()
+path.is_file()
+path.is_dir()
+
+// has_ prefix (less common in std)
+iterator.has_next()  // conceptual
+
+// Checking methods
+str.contains("foo")      // Not is_ because takes argument
+str.starts_with("bar")   // Descriptive verb phrase
+str.ends_with("baz")
+```
+
+## Negation
+
+```rust
+// Prefer positive form with caller negation
+if !user.is_active() { ... }
+
+// Rather than negative method
+if user.is_inactive() { ... }  // Avoid double negatives: !is_inactive()
+
+// Exception: when negative is the common case
+fn is_empty(&self) -> bool { ... }     // Checking for empty is common
+fn is_not_empty(&self) -> bool { ... } // Rarely needed, use !is_empty()
+```
+
+## Boolean Fields
+
+```rust
+struct Config {
+    // Field names can omit prefix
+    enabled: bool,
+    verbose: bool,
+    debug: bool,
+}
+
+impl Config {
+    // But methods should have prefix
+    fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+    
+    fn is_verbose(&self) -> bool {
+        self.verbose
+    }
+}
+```
+
+## See Also
+
+- [name-no-get-prefix](./name-no-get-prefix.md) - Getter naming
+- [name-funcs-snake](./name-funcs-snake.md) - Function naming
+- [api-must-use](./api-must-use.md) - Boolean functions should be checked

package/template/agent/skills/rust-developer/references/rust-rules/name-iter-convention.md

@@ -0,0 +1,129 @@
+# name-iter-convention
+
+> Use iter/iter_mut/into_iter for iterator methods
+
+## Why It Matters
+
+Rust has a standard convention for iterator method names that signals ownership semantics. Following this convention makes APIs predictable and enables the `for item in collection` syntax to work correctly.
+
+## The Three Iterator Methods
+
+| Method | Returns | Ownership |
+|--------|---------|-----------|
+| `iter()` | `impl Iterator<Item = &T>` | Borrows collection |
+| `iter_mut()` | `impl Iterator<Item = &mut T>` | Mutably borrows |
+| `into_iter()` | `impl Iterator<Item = T>` | Consumes collection |
+
+## Implementation
+
+```rust
+struct MyCollection<T> {
+    items: Vec<T>,
+}
+
+impl<T> MyCollection<T> {
+    /// Returns an iterator over references.
+    fn iter(&self) -> impl Iterator<Item = &T> {
+        self.items.iter()
+    }
+    
+    /// Returns an iterator over mutable references.
+    fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.items.iter_mut()
+    }
+}
+
+// IntoIterator trait for into_iter()
+impl<T> IntoIterator for MyCollection<T> {
+    type Item = T;
+    type IntoIter = std::vec::IntoIter<T>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.items.into_iter()
+    }
+}
+
+// Also implement for references
+impl<'a, T> IntoIterator for &'a MyCollection<T> {
+    type Item = &'a T;
+    type IntoIter = std::slice::Iter<'a, T>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.items.iter()
+    }
+}
+
+impl<'a, T> IntoIterator for &'a mut MyCollection<T> {
+    type Item = &'a mut T;
+    type IntoIter = std::slice::IterMut<'a, T>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.items.iter_mut()
+    }
+}
+```
+
+## Usage
+
+```rust
+let collection = MyCollection { items: vec![1, 2, 3] };
+
+// Explicit methods
+for x in collection.iter() { }     // Borrows
+for x in collection.iter_mut() { } // Mutably borrows
+
+// IntoIterator enables for loop syntax
+for x in &collection { }      // Calls (&collection).into_iter()
+for x in &mut collection { }  // Calls (&mut collection).into_iter()
+for x in collection { }       // Consumes, calls collection.into_iter()
+```
+
+## Bad
+
+```rust
+impl MyCollection<T> {
+    // Non-standard names
+    fn elements(&self) -> impl Iterator<Item = &T> { }      // Should be iter()
+    fn get_items(&self) -> impl Iterator<Item = &T> { }     // Should be iter()
+    fn iterate(&self) -> impl Iterator<Item = &T> { }       // Should be iter()
+    fn as_iter(&self) -> impl Iterator<Item = &T> { }       // Should be iter()
+}
+```
+
+## Additional Iterator Methods
+
+```rust
+impl MyCollection<T> {
+    // Filter by predicate
+    fn iter_valid(&self) -> impl Iterator<Item = &T> {
+        self.iter().filter(|x| x.is_valid())
+    }
+    
+    // Specific slice
+    fn iter_range(&self, start: usize, end: usize) -> impl Iterator<Item = &T> {
+        self.items[start..end].iter()
+    }
+}
+```
+
+## Standard Library Examples
+
+```rust
+// Vec, slice, arrays
+vec.iter()      // &T
+vec.iter_mut()  // &mut T
+vec.into_iter() // T
+
+// HashMap
+map.iter()      // (&K, &V)
+map.iter_mut()  // (&K, &mut V)
+map.into_iter() // (K, V)
+map.keys()      // &K
+map.values()    // &V
+```
+
+## See Also
+
+- [name-iter-type-match](./name-iter-type-match.md) - Iterator type naming
+- [name-iter-method](./name-iter-method.md) - Iterator method names
+- [perf-iter-over-index](./perf-iter-over-index.md) - Prefer iterators