agy-superpowers 5.1.4 → 5.1.6

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

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

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

package/template/agent/skills/rust-developer/references/rust-rules/doc-errors-section.md

@@ -0,0 +1,122 @@
+# doc-errors-section
+
+> Include `# Errors` section for fallible functions
+
+## Why It Matters
+
+Functions returning `Result` can fail in specific, documented ways. The `# Errors` section tells users exactly when and why a function might return an error, enabling them to handle failures appropriately without reading source code.
+
+This is especially critical for library code where users cannot easily inspect implementation details.
+
+## Bad
+
+```rust
+/// Opens a file and reads its contents.
+pub fn read_file(path: &Path) -> Result<String, Error> {
+    // Users have no idea what errors to expect
+}
+
+/// Connects to the database.
+pub async fn connect(url: &str) -> Result<Connection, DbError> {
+    // Multiple failure modes, none documented
+}
+```
+
+## Good
+
+```rust
+/// Opens a file and reads its contents as a UTF-8 string.
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - The file does not exist ([`Error::NotFound`])
+/// - The process lacks permission to read the file ([`Error::PermissionDenied`])
+/// - The file contains invalid UTF-8 ([`Error::InvalidUtf8`])
+pub fn read_file(path: &Path) -> Result<String, Error> {
+    // ...
+}
+
+/// Establishes a connection to the database.
+///
+/// # Errors
+///
+/// This function will return an error if:
+/// - The URL is malformed ([`DbError::InvalidUrl`])
+/// - The database server is unreachable ([`DbError::ConnectionFailed`])
+/// - Authentication fails ([`DbError::AuthenticationFailed`])
+/// - The connection pool is exhausted ([`DbError::PoolExhausted`])
+pub async fn connect(url: &str) -> Result<Connection, DbError> {
+    // ...
+}
+```
+
+## Error Documentation Patterns
+
+### Simple Single Error
+
+```rust
+/// Parses a string as an integer.
+///
+/// # Errors
+///
+/// Returns [`ParseIntError`] if the string is not a valid integer.
+pub fn parse_int(s: &str) -> Result<i64, ParseIntError> {
+    s.parse()
+}
+```
+
+### Multiple Error Variants
+
+```rust
+/// Sends an HTTP request and returns the response.
+///
+/// # Errors
+///
+/// | Error | Condition |
+/// |-------|-----------|
+/// | [`HttpError::Timeout`] | Request exceeded timeout duration |
+/// | [`HttpError::InvalidUrl`] | URL could not be parsed |
+/// | [`HttpError::ConnectionRefused`] | Server refused connection |
+/// | [`HttpError::TlsError`] | TLS handshake failed |
+pub fn send(request: Request) -> Result<Response, HttpError> {
+    // ...
+}
+```
+
+### Propagated Errors
+
+```rust
+/// Loads configuration from a file.
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - The configuration file cannot be read (IO error)
+/// - The file contains invalid TOML syntax
+/// - Required fields are missing from the configuration
+///
+/// The underlying error is wrapped with context about which
+/// configuration file failed to load.
+pub fn load_config(path: &Path) -> Result<Config, anyhow::Error> {
+    // ...
+}
+```
+
+## Linking to Error Types
+
+Use intra-doc links to connect error variants to their definitions:
+
+```rust
+/// # Errors
+///
+/// Returns [`ValidationError::TooShort`] if the input is less than
+/// the minimum length, or [`ValidationError::InvalidChars`] if it
+/// contains forbidden characters.
+```
+
+## See Also
+
+- [doc-panics-section](./doc-panics-section.md) - Documenting panics
+- [err-doc-errors](./err-doc-errors.md) - Error documentation patterns
+- [doc-intra-links](./doc-intra-links.md) - Linking to types

package/template/agent/skills/rust-developer/references/rust-rules/doc-examples-section.md

@@ -0,0 +1,161 @@
+# doc-examples-section
+
+> Include `# Examples` with runnable code
+
+## Why It Matters
+
+Examples are the most valuable part of documentation. They show users exactly how to use your API. Rust's doc tests ensure examples stay correct as code evolves.
+
+## Bad
+
+```rust
+/// Parses a string into a Foo.
+pub fn parse(s: &str) -> Result<Foo, Error> {
+    // No examples - users have to guess usage
+}
+
+/// A widget for doing things.
+/// 
+/// This widget is very useful.
+pub struct Widget {
+    // Still no examples
+}
+```
+
+## Good
+
+```rust
+/// Parses a string into a Foo.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::parse;
+///
+/// let foo = parse("hello").unwrap();
+/// assert_eq!(foo.name(), "hello");
+/// ```
+///
+/// Handles empty strings:
+///
+/// ```
+/// use my_crate::parse;
+///
+/// let foo = parse("").unwrap();
+/// assert!(foo.is_empty());
+/// ```
+pub fn parse(s: &str) -> Result<Foo, Error> {
+    // ...
+}
+```
+
+## Use ? Not unwrap()
+
+```rust
+/// Loads configuration from a file.
+///
+/// # Examples
+///
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use my_crate::Config;
+///
+/// let config = Config::load("config.toml")?;
+/// println!("Port: {}", config.port);
+/// # Ok(())
+/// # }
+/// ```
+pub fn load(path: &str) -> Result<Config, Error> {
+    // ...
+}
+```
+
+## Hide Setup Code
+
+```rust
+/// Processes items from a database.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Database, Item};
+/// # fn get_db() -> Database { Database::mock() }
+/// let db = get_db();
+/// let items = db.process_items()?;
+/// assert!(!items.is_empty());
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+pub fn process_items(&self) -> Result<Vec<Item>, Error> {
+    // ...
+}
+```
+
+## Multiple Examples
+
+```rust
+/// Creates a new buffer with the specified capacity.
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// use my_crate::Buffer;
+///
+/// let buf = Buffer::with_capacity(1024);
+/// assert_eq!(buf.capacity(), 1024);
+/// ```
+///
+/// Zero capacity creates an empty buffer:
+///
+/// ```
+/// use my_crate::Buffer;
+///
+/// let buf = Buffer::with_capacity(0);
+/// assert!(buf.is_empty());
+/// ```
+pub fn with_capacity(cap: usize) -> Self {
+    // ...
+}
+```
+
+## Show Error Cases
+
+```rust
+/// Divides two numbers.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::divide;
+///
+/// assert_eq!(divide(10, 2), Ok(5));
+/// ```
+///
+/// Division by zero returns an error:
+///
+/// ```
+/// use my_crate::{divide, MathError};
+///
+/// assert_eq!(divide(10, 0), Err(MathError::DivisionByZero));
+/// ```
+pub fn divide(a: i32, b: i32) -> Result<i32, MathError> {
+    // ...
+}
+```
+
+## Running Doc Tests
+
+```bash
+# Run all doc tests
+cargo test --doc
+
+# Run doc tests for specific item
+cargo test --doc my_function
+```
+
+## See Also
+
+- [doc-question-mark](doc-question-mark.md) - Use ? in examples
+- [doc-hidden-setup](doc-hidden-setup.md) - Hide setup code with #
+- [doc-errors-section](doc-errors-section.md) - Document error conditions

package/template/agent/skills/rust-developer/references/rust-rules/doc-hidden-setup.md

@@ -0,0 +1,149 @@
+# doc-hidden-setup
+
+> Use `# ` prefix to hide example setup code
+
+## Why It Matters
+
+Doc examples often require setup code (imports, struct initialization, mock data) that distracts from the main point. The `# ` prefix hides lines from rendered documentation while keeping them in the compiled test, showing users only the relevant code.
+
+This keeps examples focused and readable while ensuring they still compile and run.
+
+## Bad
+
+```rust
+/// Processes a batch of items.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::{Processor, Config, Item};
+/// use std::sync::Arc;
+/// 
+/// let config = Config {
+///     batch_size: 100,
+///     timeout_ms: 5000,
+///     retry_count: 3,
+/// };
+/// let processor = Processor::new(Arc::new(config));
+/// let items = vec![
+///     Item::new("a"),
+///     Item::new("b"),
+///     Item::new("c"),
+/// ];
+/// 
+/// // This is the actual example - buried after 15 lines of setup
+/// let results = processor.process_batch(&items)?;
+/// assert!(results.all_succeeded());
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+pub fn process_batch(&self, items: &[Item]) -> Result<Results, Error> {
+    // ...
+}
+```
+
+## Good
+
+```rust
+/// Processes a batch of items.
+///
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Processor, Config, Item, Error};
+/// # use std::sync::Arc;
+/// # let config = Config { batch_size: 100, timeout_ms: 5000, retry_count: 3 };
+/// # let processor = Processor::new(Arc::new(config));
+/// # let items = vec![Item::new("a"), Item::new("b"), Item::new("c")];
+/// let results = processor.process_batch(&items)?;
+/// assert!(results.all_succeeded());
+/// # Ok::<(), Error>(())
+/// ```
+pub fn process_batch(&self, items: &[Item]) -> Result<Results, Error> {
+    // ...
+}
+```
+
+Users see only:
+
+```rust
+let results = processor.process_batch(&items)?;
+assert!(results.all_succeeded());
+```
+
+## What to Hide
+
+| Hide | Show |
+|------|------|
+| `use` statements | Core API usage |
+| Type definitions | Method calls |
+| Mock/test data setup | Key parameters |
+| Error handling boilerplate | Return value handling |
+| `Ok(())` return | Assertions (sometimes) |
+
+## Pattern: Hiding Multi-Line Setup
+
+```rust
+/// # Examples
+///
+/// ```
+/// # use my_crate::{Client, Request};
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// # let client = Client::builder()
+/// #     .timeout(30)
+/// #     .retry(3)
+/// #     .build()?;
+/// let response = client.send(Request::get("/users"))?;
+/// println!("Status: {}", response.status());
+/// # Ok(())
+/// # }
+/// ```
+```
+
+## Pattern: Showing Setup When Relevant
+
+Sometimes setup IS the point—don't hide it:
+
+```rust
+/// Creates a new client with custom configuration.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::Client;
+///
+/// // Configuration IS the example - show it
+/// let client = Client::builder()
+///     .base_url("https://api.example.com")
+///     .timeout_secs(30)
+///     .max_retries(3)
+///     .build()?;
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+```
+
+## Pattern: `ignore` and `no_run`
+
+For examples that shouldn't run in tests:
+
+```rust
+/// # Examples
+///
+/// ```no_run
+/// # use my_crate::Server;
+/// // This would actually start a server - don't run in tests
+/// let server = Server::bind("0.0.0.0:8080").await?;
+/// server.run().await?;
+/// # Ok::<(), my_crate::Error>(())
+/// ```
+
+/// ```ignore
+/// // Pseudocode or incomplete example
+/// let magic = do_something_undefined();
+/// ```
+```
+
+## See Also
+
+- [doc-examples-section](./doc-examples-section.md) - Writing examples
+- [doc-question-mark](./doc-question-mark.md) - Using `?` in examples
+- [test-doctest-examples](./test-doctest-examples.md) - Doctests as tests