agentic-team-templates 0.9.2 → 0.11.0

package/templates/rust-expert/.cursorrules/ecosystem-and-tooling.md

@@ -0,0 +1,299 @@
+# Rust Ecosystem and Tooling
+
+The Rust ecosystem is mature and opinionated. The toolchain is best-in-class. Know the tools and the community-standard crates.
+
+## Cargo
+
+### Cargo.toml Best Practices
+
+```toml
+[package]
+name = "my-crate"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.75"        # Minimum supported Rust version (MSRV)
+description = "A brief description"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/user/repo"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["full"] }
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+proptest = "1"
+tempfile = "3"
+
+[profile.release]
+lto = true          # Link-time optimization
+codegen-units = 1   # Slower compile, better optimization
+strip = true        # Strip debug symbols from binary
+
+[profile.dev]
+opt-level = 0       # Fast compile for development
+
+# Feature flags must be additive
+[features]
+default = []
+metrics = ["prometheus"]
+tracing = ["tracing-subscriber", "tracing-opentelemetry"]
+```
+
+### Workspace Management
+
+```toml
+# Root Cargo.toml
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+# Share dependencies across workspace
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["full"] }
+anyhow = "1"
+
+# In member Cargo.toml:
+[dependencies]
+serde = { workspace = true }
+tokio = { workspace = true }
+```
+
+### Essential Cargo Commands
+
+```bash
+cargo build --release          # Optimized build
+cargo test -- --nocapture      # Show println! output in tests
+cargo doc --open               # Build and open docs
+cargo tree                     # Dependency tree
+cargo tree -d                  # Show duplicate dependencies
+cargo update                   # Update Cargo.lock to latest compatible
+cargo audit                    # Check for known vulnerabilities
+cargo deny check               # License and advisory checks
+cargo expand                   # Show macro expansion
+cargo outdated                 # Show outdated dependencies
+```
+
+## Linting and Formatting
+
+### Clippy Configuration
+
+```toml
+# clippy.toml or .clippy.toml
+cognitive-complexity-threshold = 25
+too-many-arguments-threshold = 7
+type-complexity-threshold = 250
+```
+
+```rust
+// In lib.rs or main.rs — project-wide lint configuration
+#![warn(clippy::all, clippy::pedantic)]
+#![allow(clippy::module_name_repetitions)] // Allow if your API style needs it
+#![deny(clippy::unwrap_used)]             // No unwrap in library code
+#![deny(unsafe_code)]                      // Deny unsafe unless explicitly needed
+
+// Per-module overrides when justified
+#[allow(clippy::cast_possible_truncation)]
+// Justification: value is guaranteed < 256 by the protocol spec
+fn protocol_byte(value: u32) -> u8 {
+    value as u8
+}
+```
+
+### rustfmt
+
+```toml
+# rustfmt.toml
+edition = "2021"
+max_width = 100
+use_field_init_shorthand = true
+use_try_shorthand = true
+imports_granularity = "Crate"
+group_imports = "StdExternalCrate"
+```
+
+## Essential Crates
+
+### Serialization
+- **serde** + **serde_json** — the serialization framework, period
+- **toml** — config files
+- **bincode** — compact binary format
+
+### Async Runtime
+- **tokio** — the dominant async runtime (multi-threaded, work-stealing)
+- **async-std** — alternative, closer to std API
+
+### Web
+- **axum** — ergonomic web framework built on Tower and Hyper
+- **reqwest** — HTTP client
+- **tonic** — gRPC
+
+### Database
+- **sqlx** — compile-time checked SQL queries
+- **diesel** — ORM with type-safe query builder
+- **sea-orm** — async ORM built on sqlx
+
+### Error Handling
+- **thiserror** — derive Error for library error types
+- **anyhow** — flexible error handling for applications
+
+### CLI
+- **clap** — argument parsing (derive or builder API)
+
+### Observability
+- **tracing** — structured, async-aware instrumentation
+- **metrics** — application metrics
+- **opentelemetry** — distributed tracing
+
+### Testing
+- **proptest** — property-based testing
+- **criterion** — statistical benchmarking
+- **mockall** — mocking framework
+- **wiremock** — HTTP mocking for integration tests
+- **tempfile** — temporary files and directories for tests
+- **insta** — snapshot testing
+
+## CI/CD
+
+### GitHub Actions
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: "-Dwarnings"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+
+      - run: cargo fmt -- --check
+      - run: cargo clippy --all-targets --all-features
+      - run: cargo test --all-features
+      - run: cargo doc --no-deps --all-features
+
+  # Miri for crates with unsafe code
+  miri:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: miri
+      - run: cargo +nightly miri test
+
+  # Security audit
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rustsec/audit-check@v2
+```
+
+### Makefile
+
+```makefile
+.PHONY: check test lint fmt doc
+
+check: fmt lint test
+
+fmt:
+	cargo fmt -- --check
+
+lint:
+	cargo clippy --all-targets --all-features -- -D warnings
+
+test:
+	cargo test --all-features
+
+doc:
+	cargo doc --no-deps --all-features --open
+
+audit:
+	cargo audit
+	cargo deny check
+
+bench:
+	cargo bench
+
+coverage:
+	cargo tarpaulin --out Html --output-dir target/coverage
+```
+
+## Documentation
+
+```rust
+//! # My Crate
+//!
+//! `my_crate` provides utilities for processing data efficiently.
+//!
+//! ## Quick Start
+//!
+//! ```rust
+//! use my_crate::process;
+//!
+//! let result = process("input data")?;
+//! println!("{result}");
+//! # Ok::<(), my_crate::Error>(())
+//! ```
+
+/// Processes the input data and returns a formatted result.
+///
+/// # Arguments
+///
+/// * `input` - A string slice containing the raw data
+///
+/// # Errors
+///
+/// Returns [`Error::InvalidInput`] if the input is malformed.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::process;
+///
+/// let output = process("valid input").unwrap();
+/// assert_eq!(output, "processed: valid input");
+/// ```
+pub fn process(input: &str) -> Result<String, Error> {
+    // ...
+}
+
+// Document panic conditions
+/// # Panics
+///
+/// Panics if `divisor` is zero.
+pub fn divide(a: i64, divisor: i64) -> i64 {
+    assert_ne!(divisor, 0, "divisor must be non-zero");
+    a / divisor
+}
+
+// Document safety requirements for unsafe functions
+/// # Safety
+///
+/// - `ptr` must be valid for reads of `len` bytes
+/// - `ptr` must be properly aligned for `T`
+/// - The memory referenced must not be mutated during the lifetime of the returned slice
+pub unsafe fn from_raw_parts<'a, T>(ptr: *const T, len: usize) -> &'a [T] {
+    std::slice::from_raw_parts(ptr, len)
+}
+```
+
+## Dependency Hygiene
+
+- **Audit regularly**: `cargo audit` for security advisories
+- **Check licenses**: `cargo deny check licenses`
+- **Minimize dependencies**: Every dependency is attack surface and compile time
+- **Pin workspace deps**: Use `[workspace.dependencies]` for consistency
+- **Review before adding**: Check maintenance status, download counts, and bus factor
+- **Feature flags**: Only enable features you actually use

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)