agy-superpowers 5.2.1 → 5.2.3

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

@@ -1,131 +0,0 @@
-# name-iter-method
-
-> Name iterator methods `iter()`, `iter_mut()`, and `into_iter()` consistently
-
-## Why It Matters
-
-Rust has a strong convention for iterator method names. Following these conventions makes your types work predictably with `for` loops and iterator adapters. Users expect `iter()` for shared references, `iter_mut()` for mutable references, and `into_iter()` for owned iteration.
-
-## Bad
-
-```rust
-struct Collection<T> {
-    items: Vec<T>,
-}
-
-impl<T> Collection<T> {
-    // Non-standard names - confusing
-    fn elements(&self) -> impl Iterator<Item = &T> {
-        self.items.iter()
-    }
-    
-    fn get_iterator(&self) -> impl Iterator<Item = &T> {
-        self.items.iter()
-    }
-    
-    fn to_iter(self) -> impl Iterator<Item = T> {
-        self.items.into_iter()
-    }
-}
-```
-
-## Good
-
-```rust
-struct Collection<T> {
-    items: Vec<T>,
-}
-
-impl<T> Collection<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()
-    }
-}
-
-// Implement IntoIterator for for-loop support
-impl<T> IntoIterator for Collection<T> {
-    type Item = T;
-    type IntoIter = std::vec::IntoIter<T>;
-    
-    fn into_iter(self) -> Self::IntoIter {
-        self.items.into_iter()
-    }
-}
-
-impl<'a, T> IntoIterator for &'a Collection<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 Collection<T> {
-    type Item = &'a mut T;
-    type IntoIter = std::slice::IterMut<'a, T>;
-    
-    fn into_iter(self) -> Self::IntoIter {
-        self.items.iter_mut()
-    }
-}
-```
-
-## Iterator Convention Summary
-
-| Method | Receiver | Yields | Use Case |
-|--------|----------|--------|----------|
-| `iter()` | `&self` | `&T` | Read-only iteration |
-| `iter_mut()` | `&mut self` | `&mut T` | In-place modification |
-| `into_iter()` | `self` | `T` | Consuming iteration |
-
-## For Loop Integration
-
-```rust
-let col = Collection { items: vec![1, 2, 3] };
-
-// These all work with proper IntoIterator impls
-for item in &col {           // Calls (&col).into_iter() -> iter()
-    println!("{}", item);    // &i32
-}
-
-for item in &mut col {       // Calls (&mut col).into_iter() -> iter_mut()
-    *item += 1;              // &mut i32
-}
-
-for item in col {            // Calls col.into_iter()
-    process(item);           // i32, consumes col
-}
-```
-
-## Additional Iterator Methods
-
-```rust
-impl<T> Collection<T> {
-    // Domain-specific iterators follow similar patterns
-    
-    /// Iterates over keys (for map-like structures).
-    fn keys(&self) -> impl Iterator<Item = &K> { ... }
-    
-    /// Iterates over values.
-    fn values(&self) -> impl Iterator<Item = &V> { ... }
-    
-    /// Iterates over mutable values.
-    fn values_mut(&mut self) -> impl Iterator<Item = &mut V> { ... }
-    
-    /// Drains elements, leaving container empty.
-    fn drain(&mut self) -> impl Iterator<Item = T> { ... }
-}
-```
-
-## See Also
-
-- [name-as-free](./name-as-free.md) - Conversion naming conventions
-- [api-extension-trait](./api-extension-trait.md) - Iterator extensions
-- [api-common-traits](./api-common-traits.md) - Standard trait implementations

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

@@ -1,142 +0,0 @@
-# name-iter-type-match
-
-> Name iterator types after their source method
-
-## Why It Matters
-
-Iterator types should match the method that creates them. `iter()` returns `Iter`, `into_iter()` returns `IntoIter`, `keys()` returns `Keys`. This naming pattern is established by the standard library and makes types predictable.
-
-## Standard Library Pattern
-
-```rust
-// Vec
-impl<T> Vec<T> {
-    fn iter(&self) -> Iter<'_, T> { }       // Returns Iter
-    fn iter_mut(&mut self) -> IterMut<'_, T> { }  // Returns IterMut
-}
-
-impl<T> IntoIterator for Vec<T> {
-    type IntoIter = IntoIter<T>;  // Returns IntoIter
-}
-
-// HashMap
-impl<K, V> HashMap<K, V> {
-    fn iter(&self) -> Iter<'_, K, V> { }
-    fn keys(&self) -> Keys<'_, K, V> { }    // Returns Keys
-    fn values(&self) -> Values<'_, K, V> { }  // Returns Values
-    fn drain(&mut self) -> Drain<'_, K, V> { }  // Returns Drain
-}
-```
-
-## Implementation
-
-```rust
-mod my_collection {
-    pub struct MyCollection<T> {
-        items: Vec<T>,
-    }
-    
-    // Iterator types in same module
-    pub struct Iter<'a, T> {
-        inner: std::slice::Iter<'a, T>,
-    }
-    
-    pub struct IterMut<'a, T> {
-        inner: std::slice::IterMut<'a, T>,
-    }
-    
-    pub struct IntoIter<T> {
-        inner: std::vec::IntoIter<T>,
-    }
-    
-    impl<T> MyCollection<T> {
-        pub fn iter(&self) -> Iter<'_, T> {
-            Iter { inner: self.items.iter() }
-        }
-        
-        pub fn iter_mut(&mut self) -> IterMut<'_, T> {
-            IterMut { inner: self.items.iter_mut() }
-        }
-    }
-    
-    impl<T> IntoIterator for MyCollection<T> {
-        type Item = T;
-        type IntoIter = IntoIter<T>;
-        
-        fn into_iter(self) -> IntoIter<T> {
-            IntoIter { inner: self.items.into_iter() }
-        }
-    }
-    
-    // Implement Iterator for each type
-    impl<'a, T> Iterator for Iter<'a, T> {
-        type Item = &'a T;
-        fn next(&mut self) -> Option<Self::Item> {
-            self.inner.next()
-        }
-    }
-    
-    impl<'a, T> Iterator for IterMut<'a, T> {
-        type Item = &'a mut T;
-        fn next(&mut self) -> Option<Self::Item> {
-            self.inner.next()
-        }
-    }
-    
-    impl<T> Iterator for IntoIter<T> {
-        type Item = T;
-        fn next(&mut self) -> Option<Self::Item> {
-            self.inner.next()
-        }
-    }
-}
-```
-
-## Naming Convention
-
-| Method | Iterator Type |
-|--------|---------------|
-| `iter()` | `Iter` |
-| `iter_mut()` | `IterMut` |
-| `into_iter()` | `IntoIter` |
-| `keys()` | `Keys` |
-| `values()` | `Values` |
-| `values_mut()` | `ValuesMut` |
-| `drain()` | `Drain` |
-| `chunks()` | `Chunks` |
-| `windows()` | `Windows` |
-
-## Custom Iterator Methods
-
-```rust
-impl Graph {
-    // Method name -> Type name
-    fn nodes(&self) -> Nodes<'_> { }        // Custom: Nodes
-    fn edges(&self) -> Edges<'_> { }        // Custom: Edges
-    fn neighbors(&self, node: NodeId) -> Neighbors<'_> { }  // Custom: Neighbors
-}
-
-pub struct Nodes<'a> { /* ... */ }
-pub struct Edges<'a> { /* ... */ }
-pub struct Neighbors<'a> { /* ... */ }
-```
-
-## Bad
-
-```rust
-// Mismatched names
-impl MyCollection<T> {
-    fn iter(&self) -> MyCollectionIterator<'_, T> { }  // Should be Iter
-    fn keys(&self) -> KeyIterator<'_, K> { }           // Should be Keys
-}
-
-// Generic names that don't match method
-pub struct Iterator<T>;  // Conflicts with std::iter::Iterator
-pub struct I<T>;         // Too cryptic
-```
-
-## See Also
-
-- [name-iter-convention](./name-iter-convention.md) - iter/iter_mut/into_iter
-- [name-iter-method](./name-iter-method.md) - Iterator method names
-- [api-common-traits](./api-common-traits.md) - Implementing common traits

package/template/agent/skills/rust-developer/references/rust-rules/name-lifetime-short.md

@@ -1,86 +0,0 @@
-# name-lifetime-short
-
-> Use short, conventional lifetime names: `'a`, `'b`, `'de`, `'src`
-
-## Why It Matters
-
-Lifetime parameters are ubiquitous in Rust signatures. Short names like `'a` keep signatures readable. For domain-specific lifetimes, descriptive but short names like `'src` or `'de` communicate intent without clutter. The Rust community has established conventions that aid recognition.
-
-## Bad
-
-```rust
-// Overly verbose lifetimes
-fn parse<'input_lifetime, 'output_lifetime>(
-    input: &'input_lifetime str
-) -> Result<&'output_lifetime str, Error> { ... }
-
-// Meaningless long names
-struct Parser<'parser_instance_lifetime> {
-    source: &'parser_instance_lifetime str,
-}
-```
-
-## Good
-
-```rust
-// Standard short lifetimes
-fn parse<'a>(input: &'a str) -> Result<&'a str, Error> { ... }
-
-struct Parser<'a> {
-    source: &'a str,
-}
-
-// Multiple lifetimes: 'a, 'b, 'c
-fn merge<'a, 'b>(first: &'a str, second: &'b str) -> String { ... }
-
-// Descriptive when clarity helps
-fn deserialize<'de>(input: &'de [u8]) -> Result<Value<'de>, Error> { ... }
-```
-
-## Common Lifetime Conventions
-
-| Lifetime | Convention | Example |
-|----------|------------|---------|
-| `'a` | Generic, first lifetime | `fn foo<'a>(x: &'a str)` |
-| `'b` | Generic, second lifetime | `fn bar<'a, 'b>(x: &'a T, y: &'b U)` |
-| `'de` | Deserialization | serde's `Deserialize<'de>` |
-| `'src` | Source code/input | `struct Lexer<'src>` |
-| `'ctx` | Context | `struct Query<'ctx>` |
-| `'input` | Input data | `struct Parser<'input>` |
-| `'static` | Static lifetime | `&'static str` |
-
-## Elision Preferred
-
-```rust
-// Let elision work when possible
-fn first_word(s: &str) -> &str {  // Not fn first_word<'a>(s: &'a str) -> &'a str
-    s.split_whitespace().next().unwrap_or("")
-}
-
-impl User {
-    fn name(&self) -> &str {  // Elision handles this
-        &self.name
-    }
-}
-```
-
-## Serde Convention
-
-```rust
-use serde::{Deserialize, Serialize};
-
-// 'de is the standard serde lifetime for borrowed data
-#[derive(Deserialize)]
-struct Request<'de> {
-    #[serde(borrow)]
-    name: &'de str,
-    #[serde(borrow)]
-    tags: Vec<&'de str>,
-}
-```
-
-## See Also
-
-- [own-lifetime-elision](./own-lifetime-elision.md) - When to omit lifetimes
-- [name-type-param-single](./name-type-param-single.md) - Type parameter naming
-- [own-borrow-over-clone](./own-borrow-over-clone.md) - Borrowing patterns

package/template/agent/skills/rust-developer/references/rust-rules/name-no-get-prefix.md

@@ -1,154 +0,0 @@
-# name-no-get-prefix
-
-> Omit get_ prefix for simple getters
-
-## Why It Matters
-
-Rust convention omits the `get_` prefix for simple field access. Methods like `len()`, `name()`, `value()` are cleaner than `get_len()`, `get_name()`, `get_value()`. This follows the principle of making the common case concise.
-
-The `get` prefix is reserved for methods that DO something beyond simple field access.
-
-## Bad
-
-```rust
-struct User {
-    name: String,
-    age: u32,
-}
-
-impl User {
-    fn get_name(&self) -> &str {      // Verbose
-        &self.name
-    }
-    
-    fn get_age(&self) -> u32 {         // Verbose
-        self.age
-    }
-    
-    fn get_is_adult(&self) -> bool {   // Doubly verbose
-        self.age >= 18
-    }
-}
-
-let name = user.get_name();
-let age = user.get_age();
-```
-
-## Good
-
-```rust
-struct User {
-    name: String,
-    age: u32,
-}
-
-impl User {
-    fn name(&self) -> &str {           // Clean
-        &self.name
-    }
-    
-    fn age(&self) -> u32 {             // Clean
-        self.age
-    }
-    
-    fn is_adult(&self) -> bool {       // Boolean uses is_ prefix
-        self.age >= 18
-    }
-}
-
-let name = user.name();
-let age = user.age();
-```
-
-## When get_ IS Appropriate
-
-Use `get` when the method does more than simple access:
-
-```rust
-impl HashMap<K, V> {
-    // Returns Option - not just field access
-    fn get(&self, key: &K) -> Option<&V> { }
-    
-    // Mutable variant
-    fn get_mut(&mut self, key: &K) -> Option<&mut V> { }
-}
-
-impl Vec<T> {
-    // Returns Option - bounds checked
-    fn get(&self, index: usize) -> Option<&T> { }
-}
-
-impl Context {
-    // Does computation/lookup, not just field access
-    fn get_config(&self) -> Config {
-        self.configs.get(&self.current_env).cloned().unwrap_or_default()
-    }
-}
-```
-
-## Standard Library Examples
-
-```rust
-// No get_ prefix
-String::len()
-Vec::len()
-Vec::capacity()
-Vec::is_empty()
-Path::file_name()
-Option::is_some()
-Result::is_ok()
-
-// With get - returns Option or does lookup
-Vec::get(index)
-HashMap::get(key)
-BTreeMap::get(key)
-```
-
-## Pattern: Getter/Setter Pairs
-
-```rust
-impl Config {
-    // Getter: no prefix
-    fn timeout(&self) -> Duration {
-        self.timeout
-    }
-    
-    // Setter: use set_ prefix
-    fn set_timeout(&mut self, timeout: Duration) {
-        self.timeout = timeout;
-    }
-}
-```
-
-## Pattern: Builder Methods
-
-```rust
-impl ConfigBuilder {
-    // Builder methods: no get_, no set_
-    fn timeout(mut self, timeout: Duration) -> Self {
-        self.timeout = timeout;
-        self
-    }
-    
-    fn retries(mut self, retries: u32) -> Self {
-        self.retries = retries;
-        self
-    }
-}
-```
-
-## Decision Guide
-
-| Pattern | Naming |
-|---------|--------|
-| Simple field access | `name()`, `value()`, `len()` |
-| Boolean property | `is_valid()`, `has_items()` |
-| Fallible access | `get()`, `get_mut()` |
-| Setter | `set_name()`, `set_value()` |
-| Builder | `name()`, `value()` (consuming self) |
-
-## See Also
-
-- [name-is-has-bool](./name-is-has-bool.md) - Boolean naming
-- [name-is-has-bool](./name-is-has-bool.md) - Boolean naming
-- [api-builder-pattern](./api-builder-pattern.md) - Builder pattern

package/template/agent/skills/rust-developer/references/rust-rules/name-to-expensive.md

@@ -1,118 +0,0 @@
-# name-to-expensive
-
-> Use `to_` prefix for expensive conversions that allocate or compute
-
-## Why It Matters
-
-The `to_` prefix signals "this conversion has a cost"—typically allocation, cloning, or computation. Callers know to consider caching the result or avoiding repeated calls. This contrasts with `as_` (free reference conversion) and `into_` (ownership transfer).
-
-## Bad
-
-```rust
-impl Name {
-    // Misleading: suggests expensive operation
-    fn as_uppercase(&self) -> String {
-        self.0.to_uppercase()  // Allocates!
-    }
-    
-    // Misleading: suggests cheap reference
-    fn get_string(&self) -> String {
-        self.0.clone()  // Allocates!
-    }
-}
-```
-
-## Good
-
-```rust
-impl Name {
-    // to_ = allocates/computes
-    fn to_uppercase(&self) -> String {
-        self.0.to_uppercase()
-    }
-    
-    // to_ = creates new value
-    fn to_string(&self) -> String {
-        self.0.clone()
-    }
-    
-    // as_ = free reference (cheap)
-    fn as_str(&self) -> &str {
-        &self.0
-    }
-}
-```
-
-## Standard Library Examples
-
-```rust
-// to_ methods - all allocate or compute
-let s: String = slice.to_vec();           // Allocates Vec
-let s: String = "hello".to_string();      // Allocates String
-let s: String = "HELLO".to_lowercase();   // Allocates new String
-let s: String = path.to_string_lossy().into_owned();  // May allocate
-
-// Contrast with as_ methods - all are free
-let slice: &[u8] = s.as_bytes();          // Just reinterpret
-let str_ref: &str = string.as_str();      // Just reference
-let path: &Path = Path::new("foo");       // Just reference
-```
-
-## Conversion Method Prefixes
-
-| Prefix | Cost | Ownership | Example |
-|--------|------|-----------|---------|
-| `as_` | Free (O(1)) | Borrows `&T` | `as_str()`, `as_bytes()` |
-| `to_` | Allocates/Computes | Creates new | `to_string()`, `to_vec()` |
-| `into_` | Usually free | Takes ownership | `into_inner()`, `into_vec()` |
-
-## Custom Types
-
-```rust
-struct Email(String);
-
-impl Email {
-    // Cheap: just returns reference
-    fn as_str(&self) -> &str {
-        &self.0
-    }
-    
-    // Expensive: allocates
-    fn to_lowercase(&self) -> Email {
-        Email(self.0.to_lowercase())
-    }
-    
-    // Expensive: allocates
-    fn to_display_format(&self) -> String {
-        format!("<{}>", self.0)
-    }
-    
-    // Ownership transfer: usually cheap
-    fn into_string(self) -> String {
-        self.0
-    }
-}
-```
-
-## to_owned() Pattern
-
-```rust
-// to_owned() for getting owned version of borrowed data
-let borrowed: &str = "hello";
-let owned: String = borrowed.to_owned();  // Allocates
-
-let borrowed: &[i32] = &[1, 2, 3];
-let owned: Vec<i32> = borrowed.to_owned();  // Allocates
-
-// ToOwned trait
-trait ToOwned {
-    type Owned;
-    fn to_owned(&self) -> Self::Owned;
-}
-```
-
-## See Also
-
-- [name-as-free](./name-as-free.md) - Free reference conversions
-- [name-into-ownership](./name-into-ownership.md) - Ownership transfer
-- [own-cow-conditional](./own-cow-conditional.md) - Avoiding unnecessary allocations