@softspark/ai-toolkit 3.0.2 → 3.1.1

package/app/skills/ruby-rules/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: ruby-rules
+description: "Ruby coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop. Load when writing, reviewing, or editing Ruby code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Ruby Rules
+
+These rules come from `app/rules/ruby/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Ruby. Apply them when writing or
+reviewing Ruby code.
+
+# Ruby Coding Style
+
+## Naming
+- PascalCase: classes, modules.
+- snake_case: methods, variables, file names, directories.
+- UPPER_SNAKE: constants (`MAX_RETRIES = 3`).
+- Prefix boolean methods with predicate: `empty?`, `valid?`, `admin?`.
+- Suffix dangerous methods with `!`: `save!`, `sort!`, `strip!`.
+- Use `_` prefix for intentionally unused variables: `_unused`.
+
+## Methods
+- Keep methods short: 5-10 lines ideal. Extract helper methods.
+- Use keyword arguments for methods with >2 parameters.
+- Use default parameter values instead of checking for nil.
+- Use `def method_name = expression` (Ruby 3.0+) for one-liners.
+- Prefer `each` over `for` loops. Use block-style iteration.
+- Return values implicitly (last expression). Use explicit `return` only for early exit.
+
+## Blocks, Procs, Lambdas
+- Use `{ }` for single-line blocks. Use `do...end` for multi-line blocks.
+- Use `&:method` shorthand: `names.map(&:upcase)`.
+- Use lambdas for strict argument checking. Use procs for flexible arity.
+- Use `yield` for single-block methods. Use explicit `&block` for storing/forwarding.
+
+## Classes
+- Use `attr_reader`, `attr_writer`, `attr_accessor` for simple getters/setters.
+- Use `Struct` for simple data containers. Use `Data.define` (Ruby 3.2+) for immutable.
+- Use modules for mixins: `include` for instance methods, `extend` for class methods.
+- Use `frozen_string_literal: true` magic comment at the top of every file.
+- Use `private` / `protected` keywords to control method visibility.
+
+## Collections
+- Use `map`, `select`, `reject`, `reduce`, `flat_map` for transformations.
+- Use `each_with_object` over `inject` when accumulating into a mutable object.
+- Use `dig` for safe nested hash/array access: `data.dig(:user, :address, :city)`.
+- Use `Hash#fetch` with default for explicit missing-key handling.
+- Use `Enumerable#lazy` for large collection processing.
+
+## Pattern Matching (Ruby 3+)
+- Use `case/in` for structural pattern matching on hashes and arrays.
+- Use `=>` pin operator to match against existing variables.
+- Use `in` pattern for conditional deconstruction in `if` statements.
+- Use pattern matching for API response parsing and validation.
+
+## Formatting
+- Use RuboCop for automated style enforcement.
+- Use `.rubocop.yml` committed to the repository for project conventions.
+- Max line length: 120 characters.
+- Two-space indentation. No tabs.
+- Use trailing commas in multi-line arrays and hashes.
+
+# Ruby Frameworks
+
+## Rails (General)
+- Follow Rails conventions: convention over configuration.
+- Use `rails generate` for scaffolding models, controllers, migrations.
+- Use strong parameters: `params.require(:user).permit(:name, :email)`.
+- Use concerns for shared controller/model behavior.
+- Use `config/routes.rb` with resourceful routing: `resources :users`.
+- Use environment-specific configuration in `config/environments/`.
+
+## ActiveRecord
+- Use migrations for all schema changes. Never modify the database directly.
+- Use `has_many`, `belongs_to`, `has_many :through` for associations.
+- Use scopes for reusable query chains: `scope :active, -> { where(active: true) }`.
+- Use `includes()` for eager loading to prevent N+1 queries.
+- Use `find_each` for batch processing large record sets.
+- Use `transaction` blocks for atomic multi-record operations.
+
+## ActionController
+- Keep controllers thin: max 7 RESTful actions per controller.
+- Use `before_action` for authentication and authorization checks.
+- Use `respond_to` for content negotiation (JSON, HTML).
+- Use `rescue_from` for centralized error handling in controllers.
+- Use `render json:` with serializers (e.g., `ActiveModelSerializers`, `Blueprinter`).
+
+## Background Jobs
+- Use Sidekiq for Redis-backed background job processing.
+- Use ActiveJob as the abstraction layer over queue backends.
+- Use `perform_later` for async execution. Use `perform_now` only in tests.
+- Set `retry` count and `discard_on` / `retry_on` for error handling.
+- Use `Sidekiq::Cron` or `clockwork` for scheduled recurring jobs.
+
+## Sinatra / Hanami
+- Use Sinatra for lightweight APIs and microservices.
+- Use Hanami for structured, modular Ruby web applications.
+- Use Hanami actions (single-purpose) instead of fat controllers.
+- Use Hanami repositories for data access abstraction.
+
+## API Mode
+- Use `rails new --api` for API-only applications (no views, sessions).
+- Use `Jbuilder` or `Blueprinter` for JSON serialization.
+- Use `Rack::Attack` for rate limiting and throttling.
+- Use versioned API namespaces: `namespace :v1 do ... end`.
+- Use pagination with `kaminari` or `pagy` for collection endpoints.
+
+## Hotwire / Turbo
+- Use Turbo Frames for partial page updates without JavaScript.
+- Use Turbo Streams for real-time server-pushed DOM updates.
+- Use Stimulus for lightweight JavaScript behavior on HTML elements.
+- Keep JavaScript minimal: let the server render HTML.
+
+# Ruby Patterns
+
+## Error Handling
+- Rescue specific exceptions. Never bare `rescue` (catches `StandardError`).
+- Create domain exception hierarchies: `class AppError < StandardError; end`.
+- Use `raise` with message and optional cause: `raise AppError, "msg"`.
+- Use `retry` with a counter for transient failures.
+- Use `ensure` for cleanup. Use `else` for code that runs only on success.
+
+## Service Objects
+- Use single-purpose service classes with a `call` method.
+- Use `Dry::Monads` Result type for operation outcomes.
+- Return `Success(value)` or `Failure(error)` from service calls.
+- Chain services with `bind` / `fmap` for pipeline composition.
+- Keep services stateless. Pass all data through method parameters.
+
+## Value Objects
+- Use `Data.define` (Ruby 3.2+) for immutable value objects.
+- Use `Struct` with `keyword_init: true` for lightweight data containers.
+- Use `freeze` on objects that should not be mutated after creation.
+- Override `==` and `hash` for value-based equality when needed.
+
+## Metaprogramming (Use Sparingly)
+- Use `define_method` over `method_missing` when possible.
+- Always define `respond_to_missing?` alongside `method_missing`.
+- Use `class_attribute` (Rails) for inheritable class-level configuration.
+- Prefer explicit code over DSL magic for maintainability.
+- Document metaprogrammed methods with YARD `@!method` directives.
+
+## Concurrency
+- Use `Concurrent::Future` (concurrent-ruby) for parallel operations.
+- Use `Concurrent::Promise` for composable async chains.
+- Use thread pools (`Concurrent::FixedThreadPool`) for bounded concurrency.
+- Use `Ractor` (Ruby 3+) for true parallel execution without GVL.
+- Use `Mutex` and `Queue` for thread-safe shared state access.
+
+## Module Patterns
+- Use `include` for shared behavior (instance methods).
+- Use `prepend` for wrapping/overriding existing methods (decorating).
+- Use `extend` for adding class-level methods from a module.
+- Use `Concern` (ActiveSupport) for Rails modules with class methods.
+- Keep modules focused: one responsibility per module.
+
+## Decorator Pattern
+- Use `SimpleDelegator` for transparent object wrapping.
+- Use `Draper` gem for view-layer decorators in Rails.
+- Prefer composition (wrapping) over inheritance for adding behavior.
+- Use `Module#prepend` for method-level decoration without wrapper classes.
+
+## Anti-Patterns
+- Monkey-patching core classes: use refinements or wrapper methods.
+- Callbacks for business logic (Rails): use service objects.
+- God objects: split into focused classes with single responsibility.
+- N+1 queries: use `includes()`, `preload()`, `eager_load()`.
+- Using `eval` or `send` with user input: remote code execution risk.
+
+# Ruby Security
+
+## Mass Assignment
+- Use strong parameters in controllers: `params.require(:user).permit(:name, :email)`.
+- Never use `params.permit!` or pass unsanitized params to `create`/`update`.
+- Use `attr_readonly` for fields that should never be updated after creation.
+- Audit `update_columns` and `update_attribute` usage (bypass validations).
+
+## SQL Injection
+- Use ActiveRecord query interface with parameterized conditions.
+- Use `where(name: value)` hash syntax or `where("name = ?", value)` placeholders.
+- Never interpolate user input into `where()` strings: `where("name = '#{input}'")`.
+- Use `sanitize_sql_array` if building raw SQL fragments is unavoidable.
+- Audit all `find_by_sql`, `execute`, and `Arel.sql` calls.
+
+## XSS Prevention
+- Rails auto-escapes ERB output with `<%= %>`. Never use `raw()` with user data.
+- Use `sanitize()` helper for allowing limited HTML tags.
+- Set `Content-Security-Policy` header in `config/initializers/content_security_policy.rb`.
+- Use `content_tag` helper for safe HTML generation.
+- Mark strings as `html_safe` only when content is guaranteed safe.
+
+## CSRF Protection
+- Use `protect_from_forgery with: :exception` in `ApplicationController`.
+- Use `authenticity_token` in all forms (Rails includes it by default).
+- Use `X-CSRF-Token` header for AJAX requests from JavaScript.
+- Exempt only webhook endpoints from CSRF (with payload signature verification).
+
+## Authentication
+- Use Devise or `has_secure_password` for authentication.
+- Use `bcrypt` for password hashing (included with `has_secure_password`).
+- Implement account lockout after N failed login attempts.
+- Use `SecureRandom.urlsafe_base64` for generating tokens.
+- Store sessions server-side (Redis/database) instead of cookie store in production.
+
+## Authorization
+- Use Pundit or CanCanCan for authorization logic.
+- Define policies per model: `class UserPolicy < ApplicationPolicy`.
+- Check ownership in policies, not just role membership.
+- Use `authorize @resource` in every controller action.
+- Default deny: require explicit authorization for all actions.
+
+## Secrets Management
+- Use `Rails.application.credentials` for encrypted secrets.
+- Use `EDITOR="vim" bin/rails credentials:edit` to manage secrets.
+- Use per-environment credentials: `credentials/production.yml.enc`.
+- Never commit `master.key` or `production.key` to version control.
+- Use environment variables for CI/CD and containerized deployments.
+
+## Dependency Security
+- Run `bundle audit check --update` for known vulnerability scanning.
+- Use `Dependabot` for automated dependency update PRs.
+- Pin gem versions in `Gemfile`. Review `Gemfile.lock` changes carefully.
+- Use `bundler-audit` in CI pipeline as a required check.
+- Update Rails promptly when security patches are released.
+
+# Ruby Testing
+
+## Framework
+- Use RSpec as the primary test framework.
+- Use Minitest for lightweight, stdlib-based testing.
+- Use FactoryBot for test data generation.
+- Use WebMock or VCR for HTTP request stubbing.
+
+## File Naming
+- RSpec: `spec/models/user_spec.rb` mirroring `app/models/user.rb`.
+- Minitest: `test/models/user_test.rb` mirroring source structure.
+- Support files: `spec/support/` for shared helpers and configurations.
+- Use `spec/rails_helper.rb` for Rails-specific RSpec configuration.
+
+## Structure (RSpec)
+- Use `describe` for the class/method under test. Use `context` for scenarios.
+- Use `it` for individual test cases with clear descriptions.
+- Use `let` for lazy-evaluated test data. Use `let!` for eager evaluation.
+- Use `before` / `after` blocks for setup and teardown.
+- Use `subject` for the primary object under test.
+
+## Matchers (RSpec)
+- Use `expect(result).to eq(expected)` for equality.
+- Use `expect(result).to be_truthy`, `be_falsy`, `be_nil`.
+- Use `expect { action }.to raise_error(FooError)` for exception testing.
+- Use `expect { action }.to change { User.count }.by(1)` for side effects.
+- Use `expect(list).to include(item)`, `contain_exactly(a, b, c)`.
+- Use `expect(result).to match(hash_including(key: value))` for partial matching.
+
+## Mocking (RSpec)
+- Use `instance_double(UserService)` for verified doubles.
+- Stub: `allow(mock).to receive(:find).with(1).and_return(user)`.
+- Verify: `expect(mock).to have_received(:save).once`.
+- Use `receive_messages(method1: val1, method2: val2)` for multi-stubbing.
+- Use `class_double` for stubbing class methods.
+- Avoid stubbing the object under test. Stub only collaborators.
+
+## FactoryBot
+- Define factories in `spec/factories/`: `FactoryBot.define { factory :user { ... } }`.
+- Use `create` for persisted records. Use `build` for in-memory only.
+- Use traits for variations: `create(:user, :admin)`.
+- Use `build_stubbed` for fast tests that do not need database.
+- Use sequences for unique attributes: `sequence(:email) { |n| "user#{n}@test.com" }`.
+
+## Rails Testing
+- Use `request specs` for API endpoint testing (RSpec).
+- Use `system specs` with Capybara for browser integration tests.
+- Use `DatabaseCleaner` or `use_transactional_fixtures` for test isolation.
+- Use `travel_to` for time-dependent test scenarios.
+- Use `ActiveJob::TestHelper` for testing background jobs inline.
+
+## Best Practices
+- Test behavior, not implementation. Do not test private methods directly.
+- Use `shared_examples` for testing common behavior across classes.
+- Use `aggregate_failures` to collect multiple assertion failures.
+- Keep tests fast: stub external services, use `build_stubbed`.
+- Run `bundle exec rspec --format documentation` for readable output.

package/app/skills/rust-rules/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: rust-rules
+description: "Rust coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test. Load when writing, reviewing, or editing Rust code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Rust Rules
+
+These rules come from `app/rules/rust/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Rust. Apply them when writing or
+reviewing Rust code.
+
+# Rust Coding Style
+
+## Naming
+- snake_case: functions, methods, variables, modules, crates.
+- PascalCase: types, traits, enums, structs, type parameters.
+- SCREAMING_SNAKE: constants and statics.
+- Short lifetimes: `'a`, `'b`. Descriptive only when multiple coexist: `'input`, `'output`.
+- Crate names: kebab-case in Cargo.toml, snake_case in code.
+
+## Ownership
+- Borrow (`&T`) when you only need to read. Own (`T`) when storing or consuming.
+- Use `&str` over `String` in function parameters when possible.
+- Use `Cow<'_, str>` when you sometimes need to allocate.
+- Avoid `.clone()` as a first resort -- restructure ownership instead.
+- Use `Arc<T>` only when shared ownership across threads is required.
+
+## Types
+- Use newtypes for domain primitives: `struct UserId(Uuid)`.
+- Use `#[derive(Debug, Clone, PartialEq)]` on data types.
+- Implement `Display` for user-facing output, `Debug` for developer output.
+- Use `#[non_exhaustive]` on public enums and structs for future compatibility.
+- Prefer enums over boolean flags for state representation.
+
+## Functions
+- Return `Result<T, E>` for operations that can fail. Avoid panicking.
+- Use `impl Trait` in argument position for flexibility, return position for simplicity.
+- Use `where` clauses for complex bounds instead of inline.
+- Prefer iterators over index-based loops.
+- Use `let-else` (1.65+) for early-exit pattern matching.
+
+## Modules
+- Use `mod.rs` or filename-based modules. Be consistent within the project.
+- Re-export public API from `lib.rs` for a clean surface.
+- Keep modules focused. One major type or concept per module.
+- Use `pub(crate)` for internal-only visibility.
+
+## Formatting
+- Use `rustfmt` with default settings. Do not fight the formatter.
+- Use `clippy` with `-D warnings` in CI. Fix all warnings.
+- Set MSRV (Minimum Supported Rust Version) in `Cargo.toml`.
+
+## Cargo
+- Use workspace dependencies to unify versions across crates.
+- Use feature flags for optional functionality.
+- Set `edition = "2021"` (or latest stable edition).
+- Use `[profile.release]` with `lto = true` and `codegen-units = 1` for production.
+
+# Rust Frameworks
+
+## Axum
+- Use extractors for typed request parsing: `Path`, `Query`, `Json`, `State`.
+- Use `Router::new().route("/path", get(handler))` for route definitions.
+- Share state via `State(Arc<AppState>)` extractor.
+- Implement `IntoResponse` on error types for clean error handling.
+- Use Tower middleware layers for auth, logging, tracing, rate limiting.
+
+## Actix-web
+- Use extractors: `web::Path`, `web::Json`, `web::Data`.
+- Use `App::new().service()` for route configuration.
+- Share state with `web::Data<Arc<State>>`.
+- Use `actix-web::middleware` for logging and error handling.
+
+## Tokio
+- Use `#[tokio::main]` for the entry point. Use `tokio::spawn` for tasks.
+- Use `tokio::select!` for waiting on multiple futures.
+- Use `tokio::time::timeout()` for operation deadlines.
+- Use `tokio::sync::broadcast` for pub/sub, `mpsc` for work queues.
+- Use `tokio::task::spawn_blocking()` for CPU-intensive work in async context.
+
+## SQLx
+- Use compile-time checked queries: `sqlx::query_as!(User, "SELECT ...")`.
+- Use `PgPool` for connection pooling. Pass as shared state.
+- Use migrations: `sqlx migrate add` and `sqlx migrate run`.
+- Use `sqlx::FromRow` derive for automatic struct mapping.
+- Set `DATABASE_URL` for compile-time query verification.
+
+## Serde
+- Use `#[derive(Serialize, Deserialize)]` on all DTOs.
+- Use `#[serde(rename_all = "camelCase")]` for JSON API compatibility.
+- Use `#[serde(deny_unknown_fields)]` for strict deserialization.
+- Use `#[serde(default)]` for optional fields with defaults.
+- Use `#[serde(skip_serializing_if = "Option::is_none")]` for clean output.
+
+## Clap
+- Use `#[derive(Parser)]` for CLI argument parsing.
+- Use subcommands with enum variants: `#[derive(Subcommand)]`.
+- Use `#[arg(env = "VAR_NAME")]` for env var fallback.
+- Use `value_parser` for custom validation of arguments.
+
+## Tracing
+- Use `tracing` crate over `log` for structured, async-aware logging.
+- Use `#[instrument]` attribute on functions for automatic span creation.
+- Use `tracing_subscriber` with `EnvFilter` for runtime log level control.
+- Add `trace_id` to all log entries for distributed tracing correlation.
+
+## Testing Crates
+- `mockall`: auto-generate mocks from traits.
+- `wiremock`: HTTP mock server for integration tests.
+- `testcontainers`: Docker containers for database tests.
+- `proptest` / `quickcheck`: property-based testing.
+
+# Rust Patterns
+
+## Error Handling
+- Use `thiserror` for library error types (structured, typed enums).
+- Use `anyhow` for application/binary code (flexible, context-rich).
+- Wrap errors with context: `.with_context(|| format!("loading {path}"))?`.
+- Use `#[from]` attribute for automatic error conversion in thiserror enums.
+- Map domain errors to HTTP/gRPC errors at API boundaries only.
+
+## Builder Pattern
+- Use builder for structs with many optional fields.
+- Return `Result` from `build()` when validation is needed.
+- Use `#[derive(Default)]` + `TypedBuilder` derive macro for compile-time safety.
+- Chain setter methods returning `Self` for ergonomic API.
+
+## Newtype Pattern
+- Wrap primitive types for type safety: `struct Email(String)`.
+- Validate in constructor: `Email::new(raw) -> Result<Self, ValidationError>`.
+- Implement `Deref` only when the inner type's full API is appropriate.
+- Use `#[repr(transparent)]` for zero-cost newtypes in FFI.
+
+## Trait Design
+- Keep traits small and focused. Compose with supertraits.
+- Use associated types for output types: `type Output;`.
+- Use default method implementations for common behavior.
+- Use extension traits to add methods to foreign types.
+
+## Async Patterns
+- Use `tokio` as the async runtime for most applications.
+- Use `tokio::spawn` for concurrent tasks, `tokio::select!` for racing.
+- Use `tokio::sync::mpsc` for channels, `tokio::sync::Mutex` for async locks.
+- Prefer `async fn` in traits (Rust 1.75+) over manual `Pin<Box<dyn Future>>`.
+- Use `tower` middleware pattern for layered request processing.
+
+## Iterator Patterns
+- Use `.iter()` / `.into_iter()` / `.iter_mut()` appropriately.
+- Chain: `filter().map().collect()` instead of manual loops.
+- Use `collect::<Result<Vec<_>, _>>()` to short-circuit on first error.
+- Implement `IntoIterator` for custom collections.
+
+## State Machine
+- Use enums with data variants for state machines.
+- Use `match` exhaustively -- compiler prevents missing states.
+- Encode valid transitions in the type system when possible.
+- Use typestate pattern for compile-time state transition enforcement.
+
+## Anti-Patterns
+- `.unwrap()` in library code -- return `Result` or `Option`.
+- `.clone()` to fix borrow checker -- restructure ownership.
+- `Arc<Mutex<T>>` as first approach -- consider channels or actors.
+- `Box<dyn Error>` in libraries -- use typed error enums.
+- Ignoring `#[must_use]` warnings -- handle or explicitly discard with `let _ =`.
+
+# Rust Security
+
+## Memory Safety
+- Rust's ownership system prevents most memory bugs. Do not circumvent it.
+- Minimize `unsafe` blocks. Document every safety invariant with `// SAFETY:`.
+- Use `#![forbid(unsafe_code)]` in library crates when possible.
+- Audit all `unsafe` code during review. Treat it as a security boundary.
+- Use `miri` in CI for detecting undefined behavior in unsafe code.
+
+## Input Validation
+- Validate all external input before processing. Use newtypes with validation.
+- Use `serde` with `#[serde(deny_unknown_fields)]` for strict deserialization.
+- Set size limits on deserialized data: `#[serde(deserialize_with = "...")]`.
+- Validate string lengths, numeric ranges, and formats at API boundaries.
+
+## SQL Injection
+- Use `sqlx` parameterized queries: `sqlx::query!("SELECT * WHERE id = $1", id)`.
+- Never build SQL strings with `format!()` using user input.
+- Use `sqlx::query_builder::QueryBuilder` for dynamic query construction.
+- Type-check queries at compile time with `sqlx::query!` macro.
+
+## Cryptography
+- Use `ring` or `rustcrypto` crates for cryptographic operations.
+- Use `argon2` crate for password hashing.
+- Use `subtle::ConstantTimeEq` for timing-safe comparisons.
+- Use `rand` crate with `OsRng` for cryptographically secure random values.
+- Never implement custom cryptographic algorithms.
+
+## Dependencies
+- Run `cargo audit` in CI to check for known vulnerabilities.
+- Run `cargo deny check` for license compliance and advisory checking.
+- Use `cargo tree -d` to find duplicate dependencies.
+- Review `build.rs` scripts in dependencies -- they execute at compile time.
+- Minimize dependency count. Each crate is a potential attack surface.
+
+## Secrets
+- Load secrets from environment: `std::env::var("SECRET")`.
+- Use `secrecy` crate for values that should not be logged or displayed.
+- Zeroize sensitive data after use with `zeroize` crate.
+- Never hardcode secrets, tokens, or keys in source code.
+
+## Panic Safety
+- Use `Result` and `Option` instead of panicking in library code.
+- Use `catch_unwind` at FFI boundaries to prevent unwinding across languages.
+- Set `panic = "abort"` in release profile to prevent panic exploitation.
+- Avoid `unwrap()` and `expect()` on user-controlled data.
+
+## Network Security
+- Use `rustls` over OpenSSL for TLS (pure Rust, memory-safe).
+- Set timeouts on all network operations.
+- Implement rate limiting on public endpoints.
+- Validate and sanitize URLs before making outbound requests.
+
+## Supply Chain
+- Use `cargo-vet` to track third-party audit status.
+- Use `cargo-crev` for community code reviews.
+- Enable `Cargo.lock` in version control for applications (not libraries).
+- Prefer well-maintained crates with recent activity and security audits.
+
+# Rust Testing
+
+## Unit Tests
+- Place unit tests in `#[cfg(test)] mod tests` at the bottom of each file.
+- Use `#[test]` attribute. Use `#[tokio::test]` for async tests.
+- Name tests descriptively: `fn rejects_invalid_email()`.
+- Access private items directly -- unit test modules are inside the parent module.
+
+## Integration Tests
+- Place in `tests/` directory. Each file compiles as a separate crate.
+- Test only the public API from integration tests.
+- Use `tests/common/mod.rs` for shared test utilities.
+- Name files by feature area: `tests/api_test.rs`, `tests/auth_test.rs`.
+
+## Assertions
+- Use `assert_eq!(actual, expected)` with the actual value first.
+- Use `assert!(matches!(result, Ok(_)))` for pattern matching in assertions.
+- Use custom error messages: `assert_eq!(x, 5, "expected x to be 5, got {x}")`.
+- Use `#[should_panic(expected = "message")]` for testing panics.
+
+## Result Testing
+- Use `-> Result<(), Box<dyn Error>>` return type in tests for `?` support.
+- Test error variants: `assert!(matches!(result, Err(AppError::NotFound(_))))`.
+- Use `.unwrap()` in tests when failure means a bug in the test.
+
+## Mocking
+- Use `mockall` crate with `#[automock]` on trait definitions.
+- Use `expect_*` methods to set expectations on mock behavior.
+- Prefer trait-based DI for testability. Accept `impl Trait` in constructors.
+- Use `fake` crate for generating realistic test data.
+
+## Property Testing
+- Use `proptest` for property-based testing on parsing and validation.
+- Define strategies: `prop::string::string_regex("[a-z]+@[a-z]+\\.[a-z]{2,4}")`.
+- Use `proptest!` macro for concise property test definitions.
+- Test invariants: serialization roundtrips, ordering consistency.
+
+## Benchmarks
+- Use `criterion` crate for statistical benchmarks (not built-in `#[bench]`).
+- Use `black_box()` to prevent compiler optimization of benchmark code.
+- Run benchmarks before and after optimization to measure impact.
+- Use `cargo bench` with `-- --save-baseline` for regression tracking.
+
+## CI Pipeline
+- Minimum: `cargo fmt --check && cargo clippy -- -D warnings && cargo test`.
+- Add `cargo audit` for vulnerability scanning.
+- Use `cargo nextest` for parallel test execution and better output.
+- Enable `-Z randomize-layout` in nightly CI to catch layout-dependent code.