agentic-team-templates 0.10.0 → 0.12.0

package/templates/rust-expert/.cursorrules/error-handling.md

@@ -0,0 +1,190 @@
+# Rust Error Handling
+
+Rust has no exceptions. `Result<T, E>` and `Option<T>` are the error handling primitives. The `?` operator propagates errors ergonomically, but every error path is still an explicit decision.
+
+## Custom Error Types
+
+### Using thiserror (Libraries)
+
+```rust
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum AppError {
+    #[error("configuration error: {message}")]
+    Config { message: String },
+
+    #[error("database query failed")]
+    Database(#[from] sqlx::Error),
+
+    #[error("request to {url} failed")]
+    Http {
+        url: String,
+        #[source]
+        source: reqwest::Error,
+    },
+
+    #[error("record not found: {entity} with id {id}")]
+    NotFound { entity: &'static str, id: String },
+
+    #[error("validation failed: {0}")]
+    Validation(String),
+}
+```
+
+### Using anyhow (Applications)
+
+```rust
+use anyhow::{Context, Result, bail, ensure};
+
+fn load_config(path: &Path) -> Result<Config> {
+    let contents = fs::read_to_string(path)
+        .with_context(|| format!("reading config from {}", path.display()))?;
+
+    let config: Config = toml::from_str(&contents)
+        .context("parsing config TOML")?;
+
+    ensure!(!config.database_url.is_empty(), "database_url must not be empty");
+
+    if config.port == 0 {
+        bail!("port must be non-zero");
+    }
+
+    Ok(config)
+}
+```
+
+### When to Use Which
+
+- **thiserror** — libraries, reusable crates, when callers need to match on error variants
+- **anyhow** — applications, binaries, when you just need to propagate context up to main
+- **Manual impl** — when you need full control or minimal dependencies
+
+### Manual Error Implementation
+
+```rust
+#[derive(Debug)]
+pub enum StorageError {
+    Io(std::io::Error),
+    Serialization(serde_json::Error),
+    NotFound { key: String },
+}
+
+impl fmt::Display for StorageError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io(e) => write!(f, "storage I/O error: {e}"),
+            Self::Serialization(e) => write!(f, "serialization error: {e}"),
+            Self::NotFound { key } => write!(f, "key not found: {key}"),
+        }
+    }
+}
+
+impl std::error::Error for StorageError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Io(e) => Some(e),
+            Self::Serialization(e) => Some(e),
+            Self::NotFound { .. } => None,
+        }
+    }
+}
+
+impl From<std::io::Error> for StorageError {
+    fn from(e: std::io::Error) -> Self {
+        Self::Io(e)
+    }
+}
+```
+
+## The ? Operator
+
+```rust
+// ? is sugar for early return on Err/None
+// It calls From::from() on the error, enabling automatic conversion
+
+fn process(path: &Path) -> Result<Data, AppError> {
+    let raw = fs::read(path)?;           // io::Error -> AppError via From
+    let parsed = serde_json::from_slice(&raw)?;  // serde::Error -> AppError via From
+    Ok(parsed)
+}
+
+// ? works with Option too
+fn first_word(s: &str) -> Option<&str> {
+    let end = s.find(' ')?; // Returns None if no space
+    Some(&s[..end])
+}
+```
+
+## Option Patterns
+
+```rust
+// Prefer combinators over match when they're clearer
+let name = user.name.as_deref().unwrap_or("anonymous");
+
+let parsed = input
+    .strip_prefix("v")
+    .and_then(|s| s.parse::<u32>().ok());
+
+// Use match when you need complex logic per variant
+match config.log_level {
+    Some(level) => logger.set_level(level),
+    None => logger.set_level(Level::Info),
+}
+
+// Use if let for single-variant checks
+if let Some(token) = headers.get("Authorization") {
+    authenticate(token)?;
+}
+```
+
+## Panic Policy
+
+```rust
+// Panics are for bugs, not for expected error conditions.
+
+// Acceptable: debug assertions
+debug_assert!(index < len, "index {index} out of bounds for length {len}");
+
+// Acceptable: unreachable code paths that truly can't happen
+match state {
+    State::Ready => process(),
+    State::Done => return,
+    // If we've exhaustively handled all variants and the compiler
+    // still wants a branch, use unreachable!() — but only when
+    // you can prove it's unreachable.
+}
+
+// Acceptable: unwrap() in tests
+#[cfg(test)]
+fn setup() -> TestDb {
+    TestDb::new().unwrap() // Fine in tests
+}
+
+// Never acceptable: unwrap() in library code without a VERY good reason
+// Never acceptable: panic!() for user input validation
+// Never acceptable: todo!() in shipped code
+```
+
+## Anti-Patterns
+
+```rust
+// Never: Silencing errors
+let _ = write!(f, "data"); // The write might fail — handle it or explain why not
+
+// Never: unwrap() with no context
+let config = load_config().unwrap(); // What failed? Where? Why?
+// At minimum:
+let config = load_config().expect("loading config from default path");
+
+// Never: Stringly-typed errors
+fn process() -> Result<(), String> { // Don't use String as an error type
+    Err("something went wrong".into())
+}
+
+// Never: Catching panics as error handling
+let result = std::panic::catch_unwind(|| dangerous_code()); // This is not error handling
+
+// Never: .ok() to discard error information without justification
+let maybe = fallible_operation().ok(); // Why is the error not important?
+```

package/templates/rust-expert/.cursorrules/overview.md

@@ -0,0 +1,142 @@
+# Rust Expert
+
+Guidelines for principal-level Rust engineering. Ownership, zero-cost abstractions, and fearless concurrency — wielded with precision.
+
+## Scope
+
+This ruleset applies to:
+- Systems programming and embedded targets
+- Web services and async runtimes (Tokio, async-std)
+- CLI tools and developer utilities
+- Libraries and crates published to crates.io
+- WebAssembly targets
+- FFI and interop with C/C++
+- Performance-critical applications
+
+## Core Philosophy
+
+Rust gives you power without sacrificing safety. The compiler is your closest collaborator — work with it, not against it.
+
+- **If it compiles, it's probably correct.** The borrow checker isn't an obstacle — it's catching bugs that would have been CVEs in another language. Trust it.
+- **Zero-cost abstractions are the point.** You should never have to choose between expressiveness and performance. If the abstraction has runtime cost, question whether it's the right abstraction.
+- **Make illegal states unrepresentable.** Use the type system to encode invariants. If a state shouldn't exist, make it impossible to construct.
+- **Explicit over implicit.** Lifetimes, ownership, error handling — Rust surfaces what other languages hide. This is a feature, not a flaw.
+- **Unsafe is a scalpel, not a sledgehammer.** Every `unsafe` block is a proof obligation. If you can't explain exactly why it's sound, don't write it.
+- **If you don't know, say so.** The Rust ecosystem is vast and evolving. Admitting uncertainty is better than guessing wrong about soundness.
+
+## Key Principles
+
+### 1. Ownership Is the Architecture
+
+Ownership isn't just memory management — it's your design tool:
+- Who owns this data? Who borrows it? For how long?
+- These questions force you to design clear APIs with explicit lifetimes and responsibilities
+- If you're fighting the borrow checker, the design likely needs rethinking — not an `unsafe` escape hatch
+
+### 2. Types Encode Invariants
+
+```rust
+// Make illegal states unrepresentable
+// Bad: bool flags that can be inconsistent
+struct Connection {
+    is_connected: bool,
+    is_authenticated: bool, // Can this be true if is_connected is false?
+}
+
+// Good: State machine as an enum
+enum Connection {
+    Disconnected,
+    Connected(TcpStream),
+    Authenticated { stream: TcpStream, token: AuthToken },
+}
+// It's impossible to be Authenticated without a stream
+```
+
+### 3. Error Handling Is Explicit
+
+```rust
+// Rust has no exceptions. Result and Option are the tools.
+// The ? operator is syntactic sugar, not an excuse to ignore errors.
+
+fn load_config(path: &Path) -> Result<Config, ConfigError> {
+    let contents = fs::read_to_string(path)
+        .map_err(|e| ConfigError::ReadFailed { path: path.to_owned(), source: e })?;
+    let config: Config = toml::from_str(&contents)
+        .map_err(|e| ConfigError::ParseFailed { source: e })?;
+    config.validate()?;
+    Ok(config)
+}
+```
+
+### 4. Clippy Is Non-Negotiable
+
+```bash
+# In CI, always:
+cargo clippy -- -D warnings
+# Clippy catches real bugs, not just style nits. Treat warnings as errors.
+```
+
+## Project Structure
+
+```
+my-project/
+├── Cargo.toml              # Workspace or package manifest
+├── Cargo.lock              # Committed for binaries, not for libraries
+├── src/
+│   ├── main.rs             # Binary entry point (or lib.rs for libraries)
+│   ├── lib.rs              # Library root — public API surface
+│   ├── config.rs           # Configuration loading and validation
+│   ├── error.rs            # Error types for this crate
+│   └── domain/             # Core business logic modules
+│       ├── mod.rs
+│       └── ...
+├── tests/                  # Integration tests (separate compilation unit)
+│   └── integration_test.rs
+├── benches/                # Benchmarks
+│   └── benchmark.rs
+├── examples/               # Runnable examples
+│   └── basic_usage.rs
+└── build.rs                # Build script (if needed)
+```
+
+### Workspace Layout (Multi-Crate)
+
+```
+workspace/
+├── Cargo.toml              # [workspace] members
+├── crates/
+│   ├── core/               # Domain logic — no IO, no async
+│   │   ├── Cargo.toml
+│   │   └── src/lib.rs
+│   ├── api/                # HTTP handlers, routes
+│   │   ├── Cargo.toml
+│   │   └── src/lib.rs
+│   ├── db/                 # Database access
+│   │   ├── Cargo.toml
+│   │   └── src/lib.rs
+│   └── cli/                # Binary entry point
+│       ├── Cargo.toml
+│       └── src/main.rs
+```
+
+### Layout Rules
+
+- `lib.rs` defines the public API — only `pub` items here are your contract
+- `mod.rs` or file-per-module — be consistent within a project
+- Integration tests in `tests/` are separate compilation units — they test your public API
+- `Cargo.lock` is committed for binaries and applications, not for libraries
+- Feature flags in `Cargo.toml` must be additive — enabling a feature must not break existing code
+
+## Definition of Done
+
+A Rust feature is complete when:
+- [ ] `cargo build` compiles with zero warnings
+- [ ] `cargo clippy -- -D warnings` passes
+- [ ] `cargo test` passes (including doc tests)
+- [ ] `cargo fmt -- --check` passes
+- [ ] No `unwrap()` or `expect()` in library code without justification
+- [ ] All `unsafe` blocks have `// SAFETY:` comments explaining the invariants
+- [ ] Error types are meaningful and implement `std::error::Error`
+- [ ] Public API has doc comments with examples
+- [ ] No unnecessary allocations in hot paths
+- [ ] `cargo deny check` passes (license and advisory audit)

package/templates/rust-expert/.cursorrules/ownership-and-borrowing.md

@@ -0,0 +1,204 @@
+# Rust Ownership and Borrowing
+
+Ownership is Rust's defining feature. It's not a constraint — it's a design tool that eliminates entire classes of bugs at compile time. Every memory safety guarantee flows from these rules.
+
+## The Three Rules
+
+1. Each value has exactly one owner
+2. When the owner goes out of scope, the value is dropped
+3. You can have either one mutable reference OR any number of shared references — never both
+
+## Ownership Patterns
+
+### Move Semantics
+
+```rust
+// Values are moved by default — this is the foundation
+let s = String::from("hello");
+let t = s; // s is MOVED into t
+// println!("{s}"); // Compile error: s has been moved
+
+// Functions take ownership unless they borrow
+fn consume(s: String) { /* s is dropped at end of function */ }
+fn borrow(s: &str) { /* s is borrowed — caller keeps ownership */ }
+
+// Return values transfer ownership back
+fn create() -> String {
+    String::from("created") // Ownership moves to caller
+}
+```
+
+### Borrowing
+
+```rust
+// Shared references: &T — read-only, multiple allowed
+fn len(s: &str) -> usize {
+    s.len()
+}
+
+// Mutable references: &mut T — exclusive access
+fn push_greeting(s: &mut String) {
+    s.push_str(", world!");
+}
+
+// The borrow checker enforces at compile time:
+let mut s = String::from("hello");
+let r1 = &s;      // Fine: shared borrow
+let r2 = &s;      // Fine: multiple shared borrows
+println!("{r1} {r2}");
+// r1 and r2 are no longer used after this point (NLL)
+let r3 = &mut s;  // Fine: no shared borrows are active
+r3.push_str("!");
+```
+
+### Lifetimes
+
+```rust
+// Lifetimes tell the compiler how long references are valid
+// Most of the time, elision handles this automatically
+
+// When the compiler needs help:
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+// Meaning: the returned reference lives at least as long as
+// the shorter of x and y
+
+// Structs that hold references need lifetime annotations
+struct Excerpt<'a> {
+    text: &'a str,
+}
+
+// If your struct has many lifetime parameters, consider
+// owning the data instead — complexity isn't always worth it
+struct Article {
+    title: String,    // Owned — simpler, no lifetime tracking
+    body: String,
+}
+```
+
+### Interior Mutability
+
+```rust
+// When you need mutation behind a shared reference
+
+// Cell<T> — for Copy types, single-threaded
+use std::cell::Cell;
+let counter = Cell::new(0);
+counter.set(counter.get() + 1); // Mutation through shared reference
+
+// RefCell<T> — runtime borrow checking, single-threaded
+use std::cell::RefCell;
+let data = RefCell::new(vec![1, 2, 3]);
+data.borrow_mut().push(4); // Panics if already borrowed
+
+// Mutex<T> / RwLock<T> — thread-safe interior mutability
+use std::sync::Mutex;
+let shared = Mutex::new(Vec::new());
+shared.lock().unwrap().push(42);
+
+// Choose the right tool:
+// Cell       — Copy types, no overhead, single-threaded
+// RefCell    — any type, runtime cost, single-threaded, panics on violation
+// Mutex      — any type, blocking, multi-threaded
+// RwLock     — any type, read-heavy workloads, multi-threaded
+// Atomic*    — primitives, lock-free, multi-threaded
+```
+
+## Smart Pointers
+
+```rust
+// Box<T> — heap allocation with single ownership
+let boxed: Box<dyn Error> = Box::new(MyError::new("failed"));
+// Use for: trait objects, recursive types, large values you want on heap
+
+// Rc<T> — reference-counted, single-threaded shared ownership
+use std::rc::Rc;
+let shared = Rc::new(ExpensiveData::new());
+let clone = Rc::clone(&shared); // Increments count, doesn't clone data
+// Use for: graph structures, multiple owners in single-threaded code
+
+// Arc<T> — atomic reference-counted, thread-safe shared ownership
+use std::sync::Arc;
+let shared = Arc::new(Config::load());
+let handle = {
+    let shared = Arc::clone(&shared);
+    thread::spawn(move || process(&shared))
+};
+// Use for: shared immutable data across threads
+
+// Cow<T> — clone-on-write
+use std::borrow::Cow;
+fn process(input: &str) -> Cow<'_, str> {
+    if input.contains("bad") {
+        Cow::Owned(input.replace("bad", "good"))
+    } else {
+        Cow::Borrowed(input) // No allocation when not needed
+    }
+}
+// Use for: avoiding allocation when mutation is conditional
+```
+
+## Common Borrow Checker Patterns
+
+### Splitting Borrows
+
+```rust
+// The borrow checker tracks borrows per-field, not per-struct
+struct State {
+    buffer: Vec<u8>,
+    index: usize,
+}
+
+impl State {
+    fn process(&mut self) {
+        // This works because buffer and index are separate fields
+        let buf = &self.buffer[self.index..];
+        self.index += buf.len();
+    }
+}
+```
+
+### Temporary Lifetimes
+
+```rust
+// Bad: temporary dropped while borrowed
+// let r = &String::from("temp"); // Won't compile — temporary is dropped
+
+// Good: bind to a variable to extend the lifetime
+let s = String::from("temp");
+let r = &s; // s lives as long as the scope
+```
+
+### Entry API for Maps
+
+```rust
+use std::collections::HashMap;
+
+let mut map = HashMap::new();
+
+// Entry API avoids double lookup and borrow conflicts
+map.entry("key")
+    .and_modify(|v| *v += 1)
+    .or_insert(0);
+```
+
+## Anti-Patterns
+
+```rust
+// Never: Clone to satisfy the borrow checker without understanding why
+let data = expensive_data.clone(); // Are you sure this is necessary?
+// If you're cloning to fix a borrow error, first ask: can I restructure the code?
+
+// Never: Leaking memory to avoid lifetimes
+let leaked: &'static str = Box::leak(Box::new(String::from("forever")));
+// This is almost never the right solution
+
+// Never: Rc<RefCell<T>> as a default — it's a code smell
+// If everything is Rc<RefCell<T>>, you've recreated garbage-collected mutable state
+// Restructure to use ownership and borrowing properly first
+
+// Never: Ignoring the borrow checker by reaching for unsafe
+// If the borrow checker rejects your code, the design usually needs to change
+// unsafe doesn't fix design problems — it hides them
+```