agentic-team-templates 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-team-templates",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "AI coding assistant templates for Cursor IDE. Pre-configured rules and guidelines that help AI assistants write better code. - use at your own risk",
   "keywords": [
     "cursor",

package/src/index.js

@@ -56,6 +56,10 @@ const TEMPLATES = {
     description: 'Mobile applications (React Native, Flutter, native iOS/Android)',
     rules: ['navigation.md', 'offline-first.md', 'overview.md', 'performance.md', 'testing.md']
   },
+  'rust-expert': {
+    description: 'Principal-level Rust engineering (ownership, concurrency, unsafe, traits, async)',
+    rules: ['concurrency.md', 'ecosystem-and-tooling.md', 'error-handling.md', 'overview.md', 'ownership-and-borrowing.md', 'performance-and-unsafe.md', 'testing.md', 'traits-and-generics.md']
+  },
   'platform-engineering': {
     description: 'Internal developer platforms, infrastructure automation, and reliability engineering',
     rules: ['ci-cd.md', 'developer-experience.md', 'infrastructure-as-code.md', 'kubernetes.md', 'observability.md', 'overview.md', 'security.md', 'testing.md']

package/src/index.test.js

@@ -82,6 +82,7 @@ describe('Constants', () => {
         'javascript-expert',
         'ml-ai',
         'mobile',
+        'rust-expert',
         'platform-engineering',
         'product-manager',
         'qa-engineering',

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

@@ -0,0 +1,250 @@
+# Rust Concurrency
+
+Rust prevents data races at compile time through ownership and the `Send`/`Sync` marker traits. Fearless concurrency is real — but it doesn't mean you can ignore deadlocks, race conditions at the logic level, or performance pitfalls.
+
+## Send and Sync
+
+```rust
+// Send: safe to transfer ownership to another thread
+// Sync: safe to share references (&T) between threads
+// These are auto-traits — the compiler derives them automatically
+
+// Most types are Send + Sync
+// Rc<T> is NOT Send or Sync — use Arc<T> for multi-threaded code
+// RefCell<T> is Send but NOT Sync — use Mutex<T> for multi-threaded code
+// Raw pointers are neither — wrap them in types that uphold invariants
+```
+
+## Threading
+
+### std::thread
+
+```rust
+use std::thread;
+
+// Scoped threads (Go 1.63+) — borrows from the parent stack are allowed
+let mut data = vec![1, 2, 3, 4];
+thread::scope(|s| {
+    let (left, right) = data.split_at_mut(2);
+
+    s.spawn(|| {
+        left.iter_mut().for_each(|x| *x *= 2);
+    });
+    s.spawn(|| {
+        right.iter_mut().for_each(|x| *x *= 3);
+    });
+});
+// Both threads are guaranteed to finish before scope exits
+// No Arc, no clone, no join handles to manage
+assert_eq!(data, [2, 4, 9, 12]);
+```
+
+### Shared State with Arc + Mutex
+
+```rust
+use std::sync::{Arc, Mutex};
+
+let counter = Arc::new(Mutex::new(0));
+let mut handles = vec![];
+
+for _ in 0..10 {
+    let counter = Arc::clone(&counter);
+    handles.push(thread::spawn(move || {
+        let mut num = counter.lock().unwrap();
+        *num += 1;
+    }));
+}
+
+for handle in handles {
+    handle.join().unwrap();
+}
+```
+
+### RwLock for Read-Heavy Workloads
+
+```rust
+use std::sync::RwLock;
+
+let config = Arc::new(RwLock::new(Config::default()));
+
+// Multiple readers — no blocking
+let cfg = config.read().unwrap();
+println!("{}", cfg.setting);
+
+// Single writer — exclusive access
+let mut cfg = config.write().unwrap();
+cfg.setting = new_value;
+```
+
+## Channels
+
+```rust
+use std::sync::mpsc;
+
+// Multiple producers, single consumer
+let (tx, rx) = mpsc::channel();
+
+let tx2 = tx.clone(); // Clone sender for second producer
+
+thread::spawn(move || {
+    tx.send(Message::Data(vec![1, 2, 3])).unwrap();
+});
+
+thread::spawn(move || {
+    tx2.send(Message::Data(vec![4, 5, 6])).unwrap();
+});
+
+// Receive all messages
+for msg in rx {
+    process(msg);
+}
+
+// crossbeam-channel for multi-producer multi-consumer, select!, bounded channels
+use crossbeam_channel::{bounded, select};
+
+let (tx, rx) = bounded(100); // Backpressure at 100 items
+
+select! {
+    recv(rx) -> msg => handle(msg.unwrap()),
+    default(Duration::from_secs(1)) => println!("timeout"),
+}
+```
+
+## Async/Await
+
+### Tokio Runtime
+
+```rust
+#[tokio::main]
+async fn main() -> Result<()> {
+    let listener = TcpListener::bind("0.0.0.0:8080").await?;
+
+    loop {
+        let (stream, addr) = listener.accept().await?;
+        tokio::spawn(async move {
+            if let Err(e) = handle_connection(stream).await {
+                eprintln!("connection error from {addr}: {e}");
+            }
+        });
+    }
+}
+```
+
+### Async Patterns
+
+```rust
+// Concurrent execution with join
+let (users, posts) = tokio::join!(
+    fetch_users(&client),
+    fetch_posts(&client),
+);
+
+// Race — first to complete wins
+tokio::select! {
+    result = fetch_data() => handle_data(result),
+    _ = tokio::time::sleep(Duration::from_secs(5)) => {
+        return Err(anyhow!("fetch timed out"));
+    }
+}
+
+// Bounded concurrency with semaphore
+use tokio::sync::Semaphore;
+
+let semaphore = Arc::new(Semaphore::new(10));
+let mut handles = vec![];
+
+for url in urls {
+    let permit = semaphore.clone().acquire_owned().await?;
+    handles.push(tokio::spawn(async move {
+        let result = fetch(url).await;
+        drop(permit); // Release when done
+        result
+    }));
+}
+
+// Stream processing
+use tokio_stream::StreamExt;
+
+let mut stream = tokio_stream::iter(items)
+    .map(|item| async move { process(item).await })
+    .buffer_unordered(10); // Process up to 10 concurrently
+
+while let Some(result) = stream.next().await {
+    handle(result?);
+}
+```
+
+### Async Traits
+
+```rust
+// Since Rust 1.75: async fn in traits works natively
+pub trait Repository {
+    async fn find_by_id(&self, id: &str) -> Result<Option<Entity>>;
+    async fn save(&self, entity: &Entity) -> Result<()>;
+}
+
+// For trait objects (dyn), use the async-trait crate or
+// return Pin<Box<dyn Future>> manually
+```
+
+### Cancellation Safety
+
+```rust
+// tokio::select! can cancel futures — understand what that means
+// A future dropped mid-execution won't run its remaining code
+
+// Cancellation-safe: reading from a channel (no partial state)
+// NOT cancellation-safe: reading into a buffer (partial read lost)
+
+tokio::select! {
+    // Safe: mpsc::Receiver::recv is cancellation-safe
+    msg = rx.recv() => { ... }
+
+    // DANGEROUS if buf has partial state from a previous iteration
+    n = reader.read(&mut buf) => { ... }
+}
+
+// When in doubt, consult tokio's docs for each method's cancellation safety
+```
+
+## Atomics
+
+```rust
+use std::sync::atomic::{AtomicU64, Ordering};
+
+static REQUEST_COUNT: AtomicU64 = AtomicU64::new(0);
+
+fn handle_request() {
+    REQUEST_COUNT.fetch_add(1, Ordering::Relaxed);
+}
+
+// Ordering guide:
+// Relaxed  — no ordering guarantees, just atomicity (counters)
+// Acquire  — subsequent reads see writes before the Release
+// Release  — previous writes are visible to Acquire loads
+// SeqCst   — total order, strongest guarantee, rarely needed
+// If unsure, use SeqCst and optimize later with profiling data
+```
+
+## Anti-Patterns
+
+```rust
+// Never: Holding a MutexGuard across an await point
+let guard = mutex.lock().await;
+do_async_work().await; // Deadlock risk — guard is held across await
+drop(guard);
+// Instead: lock, extract data, drop guard, then await
+
+// Never: Spawning tasks without cancellation or shutdown strategy
+tokio::spawn(async { loop { do_work().await; } }); // How does this stop?
+
+// Never: Blocking in async context
+std::thread::sleep(Duration::from_secs(1)); // Blocks the executor thread!
+tokio::time::sleep(Duration::from_secs(1)).await; // Use this instead
+
+// For CPU-bound work in async context:
+tokio::task::spawn_blocking(|| expensive_computation()).await?;
+
+// Never: Using std::sync::Mutex in async code (blocks the executor)
+// Use tokio::sync::Mutex instead when you must hold across awaits
+```

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