agy-superpowers 5.2.2 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/name-acronym-word.md

@@ -1,99 +0,0 @@
-# name-acronym-word
-
-> Treat acronyms as words in identifiers: `HttpServer`, not `HTTPServer`
-
-## Why It Matters
-
-When acronyms are written in ALL CAPS within identifiers, word boundaries become unclear: is `HTTPSHandler` "HTTPS Handler" or "HTTP SHandler"? Treating acronyms as words (`HttpsHandler`) maintains clear word boundaries and follows Rust convention. The standard library uses this consistently.
-
-## Bad
-
-```rust
-// ALL CAPS acronyms - unclear word boundaries
-struct HTTPServer { ... }      // HTTP + Server or H + TTP + Server?
-struct TCPIPConnection { ... } // TCP + IP? Or other splits?
-struct JSONParser { ... }
-struct XMLHTTPRequest { ... }  // Very confusing
-
-fn parseJSON(input: &str) { ... }
-fn connectTCP(addr: &str) { ... }
-```
-
-## Good
-
-```rust
-// Acronyms as words - clear boundaries
-struct HttpServer { ... }      // Http + Server
-struct TcpIpConnection { ... } // Tcp + Ip + Connection
-struct JsonParser { ... }
-struct XmlHttpRequest { ... }
-
-fn parse_json(input: &str) { ... }
-fn connect_tcp(addr: &str) { ... }
-
-// More examples
-struct Uuid { ... }            // Not UUID
-struct Uri { ... }             // Not URI
-struct Url { ... }             // Not URL
-struct Html { ... }            // Not HTML
-struct Css { ... }             // Not CSS
-struct Api { ... }             // Not API
-```
-
-## Standard Library Examples
-
-```rust
-// std uses acronyms as words
-std::net::TcpStream            // Not TCPStream
-std::net::TcpListener          // Not TCPListener
-std::net::UdpSocket            // Not UDPSocket
-std::net::IpAddr               // Not IPAddr
-std::io::IoError               // Not IOError (though Io is acceptable too)
-```
-
-## Two-Letter Acronyms
-
-```rust
-// Two-letter acronyms can go either way
-struct Io { ... }    // or IO - both acceptable
-struct Id { ... }    // or ID - both acceptable
-
-// Preference: treat as word for consistency
-struct IoHandler { ... }     // Preferred
-struct IdGenerator { ... }   // Preferred
-```
-
-## In snake_case
-
-```rust
-// Acronyms become lowercase in snake_case
-fn parse_json() { ... }
-fn connect_tcp() { ... }
-fn generate_uuid() { ... }
-fn fetch_http() { ... }
-fn encode_url() { ... }
-
-// Variables
-let json_response = fetch_json();
-let tcp_connection = connect_tcp();
-let user_id = generate_uuid();
-```
-
-## Mixed Cases
-
-```rust
-// When acronym is part of compound
-struct HttpsConnection { ... }   // Https (not HTTPS)
-struct Utf8String { ... }        // Utf8 (not UTF8)
-struct Base64Encoder { ... }     // Base64 as word
-
-// Multiple acronyms
-struct JsonApiClient { ... }     // Json + Api + Client
-struct RestApiHandler { ... }    // Rest + Api + Handler
-```
-
-## See Also
-
-- [name-types-camel](./name-types-camel.md) - Type naming conventions
-- [name-funcs-snake](./name-funcs-snake.md) - Function naming conventions
-- [name-consts-screaming](./name-consts-screaming.md) - Constant naming

package/template/agent/skills/rust-developer/references/rust-rules/name-as-free.md

@@ -1,104 +0,0 @@
-# name-as-free
-
-> `as_` prefix: free reference conversion
-
-## Why It Matters
-
-Consistent naming helps users understand API cost. `as_` prefix signals a free (O(1), no allocation) conversion that returns a reference. This convention is used throughout the standard library.
-
-## The Convention
-
-| Prefix | Cost | Ownership | Example |
-|--------|------|-----------|---------|
-| `as_` | Free | `&T -> &U` | `str::as_bytes()` |
-| `to_` | Expensive | `&T -> U` | `str::to_lowercase()` |
-| `into_` | Variable | `T -> U` | `String::into_bytes()` |
-
-## Examples
-
-```rust
-impl MyString {
-    // as_ - free reference conversion
-    pub fn as_str(&self) -> &str {
-        &self.inner
-    }
-    
-    pub fn as_bytes(&self) -> &[u8] {
-        self.inner.as_bytes()
-    }
-}
-
-impl Wrapper<T> {
-    // as_ - returns reference to inner
-    pub fn as_inner(&self) -> &T {
-        &self.inner
-    }
-    
-    pub fn as_inner_mut(&mut self) -> &mut T {
-        &mut self.inner
-    }
-}
-```
-
-## Standard Library Examples
-
-```rust
-// String
-let s = String::from("hello");
-let bytes: &[u8] = s.as_bytes();    // Free, returns &[u8]
-let str_ref: &str = s.as_str();     // Free, returns &str
-
-// Vec
-let v = vec![1, 2, 3];
-let slice: &[i32] = v.as_slice();   // Free, returns &[i32]
-
-// Path
-let p = PathBuf::from("/home");
-let path: &Path = p.as_path();      // Free, returns &Path
-
-// OsString
-let os = OsString::from("hello");
-let os_str: &OsStr = os.as_os_str(); // Free, returns &OsStr
-```
-
-## Bad
-
-```rust
-impl MyType {
-    // BAD: as_ but allocates
-    pub fn as_string(&self) -> String {
-        format!("{}", self.value)  // Allocates! Should be to_string()
-    }
-    
-    // BAD: as_ but expensive
-    pub fn as_processed(&self) -> &ProcessedData {
-        // Actually does expensive computation
-    }
-}
-```
-
-## Good
-
-```rust
-impl MyType {
-    // GOOD: Free reference
-    pub fn as_str(&self) -> &str {
-        &self.inner
-    }
-    
-    // GOOD: to_ signals allocation
-    pub fn to_string(&self) -> String {
-        format!("{}", self.value)
-    }
-    
-    // GOOD: into_ signals ownership transfer
-    pub fn into_inner(self) -> Inner {
-        self.inner
-    }
-}
-```
-
-## See Also
-
-- [name-to-expensive](name-to-expensive.md) - `to_` prefix for expensive conversions
-- [name-into-ownership](name-into-ownership.md) - `into_` prefix for ownership transfer

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

@@ -1,94 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,76 +0,0 @@
-# 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

@@ -1,123 +0,0 @@
-# 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

@@ -1,127 +0,0 @@
-# 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