agy-superpowers 5.1.4 → 5.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.1.4",
+  "version": "5.1.5",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/skills/rust-developer/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: rust-developer
+description: Use when writing Rust code, reviewing Rust, debugging ownership/borrow errors, designing APIs in Rust, or choosing async patterns, memory strategies, and idiomatic Rust conventions
+---
+
+# Rust Developer Lens
+
+> **Philosophy:** Make invalid states unrepresentable. Let the compiler prove correctness.
+> If it compiles without `unsafe`, `unwrap`, or `clone` sprawl, it's probably right.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+If the context is unspecified, ask:
+
+| What | Why it matters |
+|------|----------------|
+| **Async runtime?** Tokio / async-std / none | Shapes the entire async stack |
+| **Library or application?** | Changes error handling strategy (`thiserror` vs `anyhow`) |
+| **Target?** WASM / embedded / server / CLI | Changes allowed dependencies and allocation model |
+| **Edition?** 2021 / 2018 | Affects imports, closures, `let`-chains |
+
+---
+
+## Core Instincts
+
+- **Borrow, don't clone** — every `.clone()` is a cost; most can be avoided with `&T`
+- **`unwrap()` is a panic bug waiting to happen** — use `?`, `.context()`, or pattern match
+- **Parse, don't validate** — convert untrusted input into a well-typed value at the boundary
+- **Make illegal states unrepresentable** — enums over booleans, newtypes over raw primitives
+- **Async is not free** — wrong executor choices and `Mutex` across `.await` cause silent deadlocks
+- **Run `cargo clippy` and `cargo fmt`** — treat clippy warnings as errors in CI
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| `.unwrap()` in production | Panics on unexpected input | Use `?` operator with proper error types |
+| `&String` / `&Vec<T>` as params | Unnecessarily restrictive | Accept `&str` / `&[T]` |
+| `.clone()` to satisfy borrow checker | Wasted allocation | Restructure ownership or borrow correctly |
+| `Box<dyn Error>` as return type | Loses type info, hard to match | Use `thiserror` enum or `anyhow::Error` |
+| `std::fs` in async code | Blocks the executor thread | Use `tokio::fs` |
+| Holding `Mutex` across `.await` | Deadlock risk | Release lock before awaiting |
+| Stringly-typed IDs / states | Runtime errors, no compiler help | Newtypes: `UserId(u64)`, enums for state |
+| `format!()` to build strings repeatedly | Unnecessary allocations | Use `write!()` or `String::with_capacity()` |
+| `Vec<T>` when size is fixed | Heap indirection | `Box<[T]>` or `ArrayVec` |
+| Ignoring clippy lint | Dead code, perf issues, bugs | Fix or `#[allow(...)]` with comment |
+| `unsafe` without justification | Undefined behavior, soundness hole | Minimize scope, document invariants, wrap in safe API |
+
+---
+
+## Ownership Quick Reference
+
+| Situation | Pattern |
+|-----------|---------|
+| Shared read-only | `&T` — borrow |
+| Shared multi-thread | `Arc<T>` |
+| Single-thread shared mutable | `Rc<RefCell<T>>` |
+| Multi-thread shared mutable | `Arc<Mutex<T>>` |
+| Read-heavy shared mutable | `Arc<RwLock<T>>` |
+| Conditional ownership | `Cow<'a, T>` |
+| Small, `Copy`able types | Derive `Copy` |
+| Large data transfer | Move, don't clone |
+| Function param (read) | `&str` / `&[T]` / `&T` |
+| Function param (owned) | `impl Into<T>` |
+
+---
+
+## Error Handling Strategy
+
+```
+Library crate? → thiserror + custom enum
+Application? → anyhow + .context("what failed")
+Both? → thiserror internally, anyhow at main/binary layer
+```
+
+**Pattern:**
+```rust
+// Library: typed, matchable errors
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("user {0} not found")]
+    NotFound(UserId),
+    #[error("database error")]
+    Db(#[from] sqlx::Error),
+}
+
+// Application: add context at call site
+let user = db.find_user(id).await.context("loading user for request")?;
+```
+
+**Rules:**
+- Error messages: lowercase, no trailing punctuation
+- Use `?` for propagation — not `match Ok/Err`
+- Document errors with `# Errors` section in doc comments
+- `.expect()` only for programming errors (invariants): `vec.first().expect("vec always has one element")`
+
+---
+
+## Async Patterns
+
+| Pattern | Use when |
+|---------|----------|
+| `tokio::spawn` | Fire-and-forget task |
+| `tokio::join!` | Parallel independent futures |
+| `tokio::try_join!` | Parallel fallible futures |
+| `tokio::select!` | Race / timeout |
+| `JoinSet` | Dynamic set of tasks |
+| `mpsc` channel | Work queue, producer → consumer |
+| `broadcast` channel | Pub/sub, one → many |
+| `watch` channel | Latest value (config, state) |
+| `oneshot` channel | Request/response pattern |
+| `spawn_blocking` | CPU-bound work from async context |
+| `CancellationToken` | Graceful shutdown signal |
+
+**Critical rules:**
+- Never hold `Mutex` / `RwLock` guard across `.await`
+- Use `tokio::fs`, not `std::fs` in async code
+- Clone data *before* await points, release locks *before* yield
+
+---
+
+## Memory Optimization Quick Reference
+
+| Situation | Tool |
+|-----------|------|
+| Know the size upfront | `Vec::with_capacity(n)` |
+| Usually small (≤ ~8 items) | `SmallVec<[T; 8]>` |
+| Bounded max size | `ArrayVec<T, N>` |
+| Often-empty vec | `ThinVec<T>` |
+| Fixed-size, no growth | `Box<[T]>` |
+| Small strings (≤ 24 bytes) | `CompactString` |
+| Reuse allocation in loop | `vec.clear()` (don't drop) |
+| Zero-copy reads | `&[u8]` / `bytes::Bytes` |
+
+---
+
+## API Design Rules
+
+- **Builder pattern** for structs with ≥ 3 optional fields; add `#[must_use]` to builder type
+- **Newtype** for domain primitives: `struct UserId(u64)`, `struct Email(String)`
+- **Typestate** for compile-time state machines: `Connection<Connected>` vs `Connection<Idle>`
+- **`impl Into<T>`** for string parameters (accepts `&str`, `String`, `Cow<str>`)
+- **`impl AsRef<T>`** for borrowed inputs (accepts `String`, `&str`, `Path`, etc.)
+- **`From<X> for Y`**, not `Into<Y> for X` — `Into` is auto-derived
+- **`#[non_exhaustive]`** on enums / structs you may extend in a minor version
+- **`#[must_use]`** on `Result`-returning functions
+- Gate `serde` behind a feature flag in libraries
+
+---
+
+## Naming Conventions
+
+| Item | Convention | Example |
+|------|------------|---------|
+| Types, traits, enums | `UpperCamelCase` | `UserService` |
+| Enum variants | `UpperCamelCase` | `NotFound` |
+| Functions, methods, modules | `snake_case` | `find_user` |
+| Constants, statics | `SCREAMING_SNAKE_CASE` | `MAX_RETRIES` |
+| Lifetimes | Short lowercase | `'a`, `'de`, `'src` |
+| Type params | Single uppercase | `T`, `E`, `K`, `V` |
+| Getter (cheap) | No `get_` prefix | `.name()` not `.get_name()` |
+| Boolean methods | `is_`, `has_`, `can_` | `.is_empty()` |
+| Free conversion (ref) | `as_` prefix | `.as_str()` |
+| Expensive conversion | `to_` prefix | `.to_string()` |
+| Ownership transfer | `into_` prefix | `.into_bytes()` |
+| Acronyms | Treat as word | `Uuid`, `HttpClient` |
+| Crate names | No `-rs` suffix | `my-tool` not `my-tool-rs` |
+
+---
+
+## Testing Checklist
+
+```rust
+// Unit tests: inline, same file
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_name_describes_what_and_expected_result() {
+        // Arrange
+        // Act
+        // Assert
+    }
+
+    #[tokio::test]
+    async fn async_test_name() { ... }
+}
+```
+
+- Integration tests → `tests/` directory
+- Property-based testing → `proptest` crate
+- Trait mocking → `mockall` crate
+- Benchmarks → `criterion` crate
+- Doc examples must be runnable (they are tested)
+- RAII pattern for test cleanup (implement `Drop`)
+
+---
+
+## Questions You Always Ask
+
+**When writing Rust code:**
+- Is this a library or an application? (determines error handling strategy)
+- Can I borrow instead of clone here?
+- What happens if this `.unwrap()` receives `None` / `Err` in production?
+- Is this `unsafe` block minimized and its invariants documented?
+
+**When reviewing Rust code:**
+- Are all `?` propagations wrapped with `.context()`?
+- Would a newtype prevent misuse here (e.g., mixing up `UserId` and `PostId`)?
+- Is this async code holding a lock guard across an `.await`?
+- Does `cargo clippy` pass clean? Any suppressed lints without justification?
+
+---
+
+## Validation Checklist Before Finishing
+
+```bash
+cargo fmt          # Format
+cargo clippy       # Lint (treat warnings as errors)
+cargo test         # All tests pass
+cargo doc --open   # Docs render correctly (check `# Errors`, examples)
+```
+
+For performance-sensitive code:
+```bash
+cargo bench        # via criterion
+RUSTFLAGS="-C target-cpu=native" cargo build --release
+```
+
+---
+
+## Red Flags in Code Review
+
+**Must fix:**
+- [ ] `.unwrap()` or `.expect()` in non-obvious invariant code
+- [ ] `&String` / `&Vec<T>` function parameters
+- [ ] `Box<dyn Error>` as error type in library
+- [ ] `std::fs` used in async function
+- [ ] Mutex/RwLock guard held across `.await`
+- [ ] Clones that could be borrows
+
+**Should fix:**
+- [ ] Missing `# Errors` doc section on fallible public functions
+- [ ] No error context added (`?` with no `.context()`)
+- [ ] Missing `with_capacity` when size is known
+- [ ] Stringly-typed IDs or status values
+- [ ] Clippy warnings left unaddressed
+
+---
+
+## Platform References
+
+When this skill is invoked for a Rust project, check `references/rust-rules/`
+for 179 individual rule files from [leonardomso/rust-skills](https://github.com/leonardomso/rust-skills).
+
+Each rule covers one specific pattern with:
+- Why it matters
+- Bad code example
+- Good code example
+- Links to official docs
+
+Read `references/rust-rules/_sections.md` for the full index organized by
+priority (CRITICAL → REFERENCE). Reference individual rules when working
+on specific areas (ownership, error handling, async, memory, API design, etc.).
+
+---
+
+## Sources
+
+Rules curated from:
+- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- [Rust Performance Book](https://nnethercote.github.io/perf-book/)
+- [Rust Design Patterns](https://rust-unofficial.github.io/patterns/)
+- [leonardomso/rust-skills](https://github.com/leonardomso/rust-skills) — 179 rules for AI coding agents
+- [Ranrar/rustic-prompt](https://github.com/Ranrar/rustic-prompt) — multi-agent Rust instruction set
+- Real-world code from: ripgrep, tokio, serde, axum, polars

package/template/agent/skills/rust-developer/references/rust-rules/_sections.md

@@ -0,0 +1,231 @@
+# Rust Rules Index
+
+179 rules from [leonardomso/rust-skills](https://github.com/leonardomso/rust-skills), organized by priority.
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix | Rules |
+|----------|----------|--------|--------|-------|
+| 1 | Ownership & Borrowing | CRITICAL | `own-` | 12 |
+| 2 | Error Handling | CRITICAL | `err-` | 12 |
+| 3 | Memory Optimization | CRITICAL | `mem-` | 15 |
+| 4 | API Design | HIGH | `api-` | 15 |
+| 5 | Async/Await | HIGH | `async-` | 15 |
+| 6 | Compiler Optimization | HIGH | `opt-` | 12 |
+| 7 | Naming Conventions | MEDIUM | `name-` | 16 |
+| 8 | Type Safety | MEDIUM | `type-` | 10 |
+| 9 | Testing | MEDIUM | `test-` | 13 |
+| 10 | Documentation | MEDIUM | `doc-` | 11 |
+| 11 | Performance Patterns | MEDIUM | `perf-` | 11 |
+| 12 | Project Structure | LOW | `proj-` | 11 |
+| 13 | Clippy & Linting | LOW | `lint-` | 11 |
+| 14 | Anti-patterns | REFERENCE | `anti-` | 15 |
+
+---
+
+### 1. Ownership & Borrowing (CRITICAL)
+- `own-borrow-over-clone` - Prefer `&T` borrowing over `.clone()`
+- `own-slice-over-vec` - Accept `&[T]` not `&Vec<T>`, `&str` not `&String`
+- `own-cow-conditional` - Use `Cow<'a, T>` for conditional ownership
+- `own-arc-shared` - Use `Arc<T>` for thread-safe shared ownership
+- `own-rc-single-thread` - Use `Rc<T>` for single-threaded sharing
+- `own-refcell-interior` - Use `RefCell<T>` for interior mutability (single-thread)
+- `own-mutex-interior` - Use `Mutex<T>` for interior mutability (multi-thread)
+- `own-rwlock-readers` - Use `RwLock<T>` when reads dominate writes
+- `own-copy-small` - Derive `Copy` for small, trivial types
+- `own-clone-explicit` - Make `Clone` explicit, avoid implicit copies
+- `own-move-large` - Move large data instead of cloning
+- `own-lifetime-elision` - Rely on lifetime elision when possible
+
+### 2. Error Handling (CRITICAL)
+- `err-thiserror-lib` - Use `thiserror` for library error types
+- `err-anyhow-app` - Use `anyhow` for application error handling
+- `err-result-over-panic` - Return `Result`, don't panic on expected errors
+- `err-context-chain` - Add context with `.context()` or `.with_context()`
+- `err-no-unwrap-prod` - Never use `.unwrap()` in production code
+- `err-expect-bugs-only` - Use `.expect()` only for programming errors
+- `err-question-mark` - Use `?` operator for clean propagation
+- `err-from-impl` - Use `#[from]` for automatic error conversion
+- `err-source-chain` - Use `#[source]` to chain underlying errors
+- `err-lowercase-msg` - Error messages: lowercase, no trailing punctuation
+- `err-doc-errors` - Document errors with `# Errors` section
+- `err-custom-type` - Create custom error types, not `Box<dyn Error>`
+
+### 3. Memory Optimization (CRITICAL)
+- `mem-with-capacity` - Use `with_capacity()` when size is known
+- `mem-smallvec` - Use `SmallVec` for usually-small collections
+- `mem-arrayvec` - Use `ArrayVec` for bounded-size collections
+- `mem-box-large-variant` - Box large enum variants to reduce type size
+- `mem-boxed-slice` - Use `Box<[T]>` instead of `Vec<T>` when fixed
+- `mem-thinvec` - Use `ThinVec` for often-empty vectors
+- `mem-clone-from` - Use `clone_from()` to reuse allocations
+- `mem-reuse-collections` - Reuse collections with `clear()` in loops
+- `mem-avoid-format` - Avoid `format!()` when string literals work
+- `mem-write-over-format` - Use `write!()` instead of `format!()`
+- `mem-arena-allocator` - Use arena allocators for batch allocations
+- `mem-zero-copy` - Use zero-copy patterns with slices and `Bytes`
+- `mem-compact-string` - Use `CompactString` for small string optimization
+- `mem-smaller-integers` - Use smallest integer type that fits
+- `mem-assert-type-size` - Assert hot type sizes to prevent regressions
+
+### 4. API Design (HIGH)
+- `api-builder-pattern` - Use Builder pattern for complex construction
+- `api-builder-must-use` - Add `#[must_use]` to builder types
+- `api-newtype-safety` - Use newtypes for type-safe distinctions
+- `api-typestate` - Use typestate for compile-time state machines
+- `api-sealed-trait` - Seal traits to prevent external implementations
+- `api-extension-trait` - Use extension traits to add methods to foreign types
+- `api-parse-dont-validate` - Parse into validated types at boundaries
+- `api-impl-into` - Accept `impl Into<T>` for flexible string inputs
+- `api-impl-asref` - Accept `impl AsRef<T>` for borrowed inputs
+- `api-must-use` - Add `#[must_use]` to `Result` returning functions
+- `api-non-exhaustive` - Use `#[non_exhaustive]` for future-proof enums/structs
+- `api-from-not-into` - Implement `From`, not `Into` (auto-derived)
+- `api-default-impl` - Implement `Default` for sensible defaults
+- `api-common-traits` - Implement `Debug`, `Clone`, `PartialEq` eagerly
+- `api-serde-optional` - Gate `Serialize`/`Deserialize` behind feature flag
+
+### 5. Async/Await (HIGH)
+- `async-tokio-runtime` - Use Tokio for production async runtime
+- `async-no-lock-await` - Never hold `Mutex`/`RwLock` across `.await`
+- `async-spawn-blocking` - Use `spawn_blocking` for CPU-intensive work
+- `async-tokio-fs` - Use `tokio::fs` not `std::fs` in async code
+- `async-cancellation-token` - Use `CancellationToken` for graceful shutdown
+- `async-join-parallel` - Use `tokio::join!` for parallel operations
+- `async-try-join` - Use `tokio::try_join!` for fallible parallel ops
+- `async-select-racing` - Use `tokio::select!` for racing/timeouts
+- `async-bounded-channel` - Use bounded channels for backpressure
+- `async-mpsc-queue` - Use `mpsc` for work queues
+- `async-broadcast-pubsub` - Use `broadcast` for pub/sub patterns
+- `async-watch-latest` - Use `watch` for latest-value sharing
+- `async-oneshot-response` - Use `oneshot` for request/response
+- `async-joinset-structured` - Use `JoinSet` for dynamic task groups
+- `async-clone-before-await` - Clone data before await, release locks
+
+### 6. Compiler Optimization (HIGH)
+- `opt-inline-small` - Use `#[inline]` for small hot functions
+- `opt-inline-always-rare` - Use `#[inline(always)]` sparingly
+- `opt-inline-never-cold` - Use `#[inline(never)]` for cold paths
+- `opt-cold-unlikely` - Use `#[cold]` for error/unlikely paths
+- `opt-likely-hint` - Use `likely()`/`unlikely()` for branch hints
+- `opt-lto-release` - Enable LTO in release builds
+- `opt-codegen-units` - Use `codegen-units = 1` for max optimization
+- `opt-pgo-profile` - Use PGO for production builds
+- `opt-target-cpu` - Set `target-cpu=native` for local builds
+- `opt-bounds-check` - Use iterators to avoid bounds checks
+- `opt-simd-portable` - Use portable SIMD for data-parallel ops
+- `opt-cache-friendly` - Design cache-friendly data layouts (SoA)
+
+### 7. Naming Conventions (MEDIUM)
+- `name-types-camel` - Use `UpperCamelCase` for types, traits, enums
+- `name-variants-camel` - Use `UpperCamelCase` for enum variants
+- `name-funcs-snake` - Use `snake_case` for functions, methods, modules
+- `name-consts-screaming` - Use `SCREAMING_SNAKE_CASE` for constants/statics
+- `name-lifetime-short` - Use short lowercase lifetimes: `'a`, `'de`, `'src`
+- `name-type-param-single` - Use single uppercase for type params: `T`, `E`, `K`, `V`
+- `name-as-free` - `as_` prefix: free reference conversion
+- `name-to-expensive` - `to_` prefix: expensive conversion
+- `name-into-ownership` - `into_` prefix: ownership transfer
+- `name-no-get-prefix` - No `get_` prefix for simple getters
+- `name-is-has-bool` - Use `is_`, `has_`, `can_` for boolean methods
+- `name-iter-convention` - Use `iter`/`iter_mut`/`into_iter` for iterators
+- `name-iter-method` - Name iterator methods consistently
+- `name-iter-type-match` - Iterator type names match method
+- `name-acronym-word` - Treat acronyms as words: `Uuid` not `UUID`
+- `name-crate-no-rs` - Crate names: no `-rs` suffix
+
+### 8. Type Safety (MEDIUM)
+- `type-newtype-ids` - Wrap IDs in newtypes: `UserId(u64)`
+- `type-newtype-validated` - Newtypes for validated data: `Email`, `Url`
+- `type-enum-states` - Use enums for mutually exclusive states
+- `type-option-nullable` - Use `Option<T>` for nullable values
+- `type-result-fallible` - Use `Result<T, E>` for fallible operations
+- `type-phantom-marker` - Use `PhantomData<T>` for type-level markers
+- `type-never-diverge` - Use `!` type for functions that never return
+- `type-generic-bounds` - Add trait bounds only where needed
+- `type-no-stringly` - Avoid stringly-typed APIs, use enums/newtypes
+- `type-repr-transparent` - Use `#[repr(transparent)]` for FFI newtypes
+
+### 9. Testing (MEDIUM)
+- `test-cfg-test-module` - Use `#[cfg(test)] mod tests { }`
+- `test-use-super` - Use `use super::*;` in test modules
+- `test-integration-dir` - Put integration tests in `tests/` directory
+- `test-descriptive-names` - Use descriptive test names
+- `test-arrange-act-assert` - Structure tests as arrange/act/assert
+- `test-proptest-properties` - Use `proptest` for property-based testing
+- `test-mockall-mocking` - Use `mockall` for trait mocking
+- `test-mock-traits` - Use traits for dependencies to enable mocking
+- `test-fixture-raii` - Use RAII pattern (Drop) for test cleanup
+- `test-tokio-async` - Use `#[tokio::test]` for async tests
+- `test-should-panic` - Use `#[should_panic]` for panic tests
+- `test-criterion-bench` - Use `criterion` for benchmarking
+- `test-doctest-examples` - Keep doc examples as executable tests
+
+### 10. Documentation (MEDIUM)
+- `doc-all-public` - Document all public items with `///`
+- `doc-module-inner` - Use `//!` for module-level documentation
+- `doc-examples-section` - Include `# Examples` with runnable code
+- `doc-errors-section` - Include `# Errors` for fallible functions
+- `doc-panics-section` - Include `# Panics` for panicking functions
+- `doc-safety-section` - Include `# Safety` for unsafe functions
+- `doc-question-mark` - Use `?` in examples, not `.unwrap()`
+- `doc-hidden-setup` - Use `# ` prefix to hide example setup code
+- `doc-intra-links` - Use intra-doc links: `[Vec]`
+- `doc-link-types` - Link related types and functions in docs
+- `doc-cargo-metadata` - Fill `Cargo.toml` metadata
+
+### 11. Performance Patterns (MEDIUM)
+- `perf-iter-over-index` - Prefer iterators over manual indexing
+- `perf-iter-lazy` - Keep iterators lazy, collect() only when needed
+- `perf-collect-once` - Don't `collect()` intermediate iterators
+- `perf-entry-api` - Use `entry()` API for map insert-or-update
+- `perf-drain-reuse` - Use `drain()` to reuse allocations
+- `perf-extend-batch` - Use `extend()` for batch insertions
+- `perf-chain-avoid` - Avoid `chain()` in hot loops
+- `perf-collect-into` - Use `collect_into()` for reusing containers
+- `perf-black-box-bench` - Use `black_box()` in benchmarks
+- `perf-release-profile` - Optimize release profile settings
+- `perf-profile-first` - Profile before optimizing
+
+### 12. Project Structure (LOW)
+- `proj-lib-main-split` - Keep `main.rs` minimal, logic in `lib.rs`
+- `proj-mod-by-feature` - Organize modules by feature, not type
+- `proj-flat-small` - Keep small projects flat
+- `proj-mod-rs-dir` - Use `mod.rs` for multi-file modules
+- `proj-pub-crate-internal` - Use `pub(crate)` for internal APIs
+- `proj-pub-super-parent` - Use `pub(super)` for parent-only visibility
+- `proj-pub-use-reexport` - Use `pub use` for clean public API
+- `proj-prelude-module` - Create `prelude` module for common imports
+- `proj-bin-dir` - Put multiple binaries in `src/bin/`
+- `proj-workspace-large` - Use workspaces for large projects
+- `proj-workspace-deps` - Use workspace dependency inheritance
+
+### 13. Clippy & Linting (LOW)
+- `lint-deny-correctness` - `#![deny(clippy::correctness)]`
+- `lint-warn-suspicious` - `#![warn(clippy::suspicious)]`
+- `lint-warn-style` - `#![warn(clippy::style)]`
+- `lint-warn-complexity` - `#![warn(clippy::complexity)]`
+- `lint-warn-perf` - `#![warn(clippy::perf)]`
+- `lint-pedantic-selective` - Enable `clippy::pedantic` selectively
+- `lint-missing-docs` - `#![warn(missing_docs)]`
+- `lint-unsafe-doc` - `#![warn(clippy::undocumented_unsafe_blocks)]`
+- `lint-cargo-metadata` - `#![warn(clippy::cargo)]` for published crates
+- `lint-rustfmt-check` - Run `cargo fmt --check` in CI
+- `lint-workspace-lints` - Configure lints at workspace level
+
+### 14. Anti-patterns (REFERENCE)
+- `anti-unwrap-abuse` - Don't use `.unwrap()` in production code
+- `anti-expect-lazy` - Don't use `.expect()` for recoverable errors
+- `anti-clone-excessive` - Don't clone when borrowing works
+- `anti-lock-across-await` - Don't hold locks across `.await`
+- `anti-string-for-str` - Don't accept `&String` when `&str` works
+- `anti-vec-for-slice` - Don't accept `&Vec<T>` when `&[T]` works
+- `anti-index-over-iter` - Don't use indexing when iterators work
+- `anti-panic-expected` - Don't panic on expected/recoverable errors
+- `anti-empty-catch` - Don't use empty `if let Err(_) = ...` blocks
+- `anti-over-abstraction` - Don't over-abstract with excessive generics
+- `anti-premature-optimize` - Don't optimize before profiling
+- `anti-type-erasure` - Don't use `Box<dyn Trait>` when `impl Trait` works
+- `anti-format-hot-path` - Don't use `format!()` in hot paths
+- `anti-collect-intermediate` - Don't `collect()` intermediate iterators
+- `anti-stringly-typed` - Don't use strings for structured data

package/template/agent/skills/rust-developer/references/rust-rules/anti-clone-excessive.md

@@ -0,0 +1,124 @@
+# anti-clone-excessive
+
+> Don't clone when borrowing works
+
+## Why It Matters
+
+`.clone()` allocates memory and copies data. When you only need to read data, borrowing (`&T`) is free. Excessive cloning wastes memory, CPU cycles, and often indicates misunderstanding of ownership.
+
+## Bad
+
+```rust
+// Cloning to pass to a function that only reads
+fn print_name(name: String) {  // Takes ownership
+    println!("{}", name);
+}
+let name = "Alice".to_string();
+print_name(name.clone());  // Unnecessary clone
+print_name(name);          // Could have just done this
+
+// Cloning in a loop
+for item in items.clone() {  // Clones entire Vec
+    process(&item);
+}
+
+// Cloning for comparison
+if input.clone() == expected {  // Pointless clone
+    // ...
+}
+
+// Cloning struct fields
+fn get_name(&self) -> String {
+    self.name.clone()  // Caller might not need ownership
+}
+```
+
+## Good
+
+```rust
+// Accept reference if only reading
+fn print_name(name: &str) {
+    println!("{}", name);
+}
+let name = "Alice".to_string();
+print_name(&name);  // Borrow, no clone
+
+// Iterate by reference
+for item in &items {
+    process(item);
+}
+
+// Compare by reference
+if input == expected {
+    // ...
+}
+
+// Return reference when possible
+fn get_name(&self) -> &str {
+    &self.name
+}
+```
+
+## When to Clone
+
+```rust
+// Need owned data for async move
+let name = name.clone();
+tokio::spawn(async move {
+    process(name).await;
+});
+
+// Storing in a new struct
+struct Cache {
+    data: String,
+}
+impl Cache {
+    fn store(&mut self, data: &str) {
+        self.data = data.to_string();  // Must own
+    }
+}
+
+// Multiple owners (use Arc instead if frequent)
+let shared = data.clone();
+thread::spawn(move || use_data(shared));
+```
+
+## Alternatives to Clone
+
+| Instead of | Use |
+|------------|-----|
+| `s.clone()` for reading | `&s` |
+| `vec.clone()` for iteration | `&vec` or `vec.iter()` |
+| `Clone` for shared ownership | `Arc<T>` |
+| Clone in hot loop | Move outside loop |
+| `s.to_string()` from `&str` | Accept `&str` if possible |
+
+## Pattern: Clone on Write
+
+```rust
+use std::borrow::Cow;
+
+fn process(input: Cow<str>) -> Cow<str> {
+    if needs_modification(&input) {
+        Cow::Owned(modify(&input))  // Clone only if needed
+    } else {
+        input  // No clone
+    }
+}
+```
+
+## Detecting Excessive Clones
+
+```toml
+# Cargo.toml
+[lints.clippy]
+clone_on_copy = "warn"
+clone_on_ref_ptr = "warn"
+redundant_clone = "warn"
+```
+
+## See Also
+
+- [own-borrow-over-clone](./own-borrow-over-clone.md) - Borrowing patterns
+- [own-cow-conditional](./own-cow-conditional.md) - Clone on write
+- [own-arc-shared](./own-arc-shared.md) - Shared ownership