@softspark/ai-toolkit 3.0.2 → 3.1.0

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

@@ -0,0 +1,282 @@
+---
+name: csharp-rules
+description: "C#/.NET coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .cs, .csproj, .sln, ASP.NET, ASP.NET Core, EF Core, LINQ, NUnit, xUnit, dotnet. Load when writing, reviewing, or editing C#/.NET code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# C#/.NET Rules
+
+These rules come from `app/rules/csharp/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in C#/.NET. Apply them when writing or
+reviewing C#/.NET code.
+
+# C# Coding Style
+
+## Naming
+- PascalCase: classes, structs, enums, interfaces, methods, properties, events.
+- camelCase: local variables, parameters, private fields.
+- Prefix interfaces with `I`: `IUserRepository`, `IDisposable`.
+- Prefix private fields with `_`: `private readonly ILogger _logger;`.
+- UPPER_SNAKE: not conventional in C#. Use PascalCase for constants.
+
+## Nullable Reference Types
+- Enable `<Nullable>enable</Nullable>` in all projects.
+- Use `string?` only when null is semantically meaningful.
+- Use `!` (null-forgiving) operator sparingly -- only when compiler cannot infer.
+- Use `??` (null-coalescing) and `?.` (null-conditional) for safe navigation.
+- Use `required` modifier (C# 11) on properties that must be set at initialization.
+
+## Records and Types
+- Use `record` for immutable value objects and DTOs.
+- Use `record struct` for small, stack-allocated value types.
+- Use `init` properties for immutable-after-construction objects.
+- Use `with` expressions for non-destructive mutation of records.
+- Use primary constructors (C# 12) for concise class definitions.
+
+## Pattern Matching
+- Use `is` pattern for type checks: `if (obj is string s)`.
+- Use `switch` expressions for exhaustive matching over enums/types.
+- Use property patterns: `user is { Age: > 18, Role: "admin" }`.
+- Use relational patterns: `size is > 0 and < 100`.
+- Use list patterns (C# 11): `numbers is [1, 2, .., var last]`.
+
+## Async/Await
+- Suffix async methods with `Async`: `GetUserAsync()`.
+- Return `Task<T>` or `ValueTask<T>`, never `void` (except event handlers).
+- Use `await` with `ConfigureAwait(false)` in library code.
+- Use `CancellationToken` parameters in all async public APIs.
+- Prefer `ValueTask<T>` when synchronous completion is common.
+
+## File Organization
+- One type per file. File name matches type name.
+- Use file-scoped namespaces (C# 10): `namespace MyApp.Services;`.
+- Order members: fields, constructors, properties, public methods, private methods.
+- Use `global using` directives in a single `GlobalUsings.cs` file.
+
+## Formatting
+- Use `.editorconfig` with C# style rules committed to the repository.
+- Use `dotnet format` for automated formatting.
+- Use Roslyn analyzers for compile-time style enforcement.
+- Max line length: 120 characters.
+
+# C# Frameworks
+
+## ASP.NET Core
+- Use minimal APIs for simple endpoints. Use controllers for complex APIs.
+- Use `[ApiController]` attribute for automatic model validation and error responses.
+- Use `Results.Ok()`, `Results.NotFound()` for typed HTTP results.
+- Use endpoint filters / middleware for cross-cutting concerns.
+- Use `IHostedService` / `BackgroundService` for long-running background tasks.
+- Map routes with `app.MapGet()`, `app.MapPost()` for minimal API style.
+
+## Entity Framework Core
+- Use code-first migrations: `dotnet ef migrations add`, `dotnet ef database update`.
+- Use `DbContext` with scoped lifetime (one per request).
+- Use `AsNoTracking()` for read-only queries. Use `AsTracking()` only for updates.
+- Use `Include()` / `ThenInclude()` for eager loading related entities.
+- Use shadow properties for audit fields (`CreatedAt`, `UpdatedAt`).
+- Use `HasQueryFilter()` for soft-delete and multi-tenancy global filters.
+
+## Blazor
+- Use Blazor Server for internal tools. Use Blazor WASM for public-facing SPAs.
+- Use `@inject` for dependency injection in components.
+- Use `EventCallback<T>` for parent-child component communication.
+- Use `CascadingValue` for deeply shared state (theme, auth).
+- Use `StateContainer` pattern with events for cross-component state management.
+
+## SignalR
+- Use strongly-typed hubs: `Hub<IClientMethods>` for compile-time safety.
+- Use `HubContext<T>` for sending messages from outside hubs.
+- Use groups for targeted broadcasting: `Groups.AddToGroupAsync()`.
+- Configure automatic reconnection on the client side.
+
+## MassTransit / Messaging
+- Use MassTransit for message bus abstraction over RabbitMQ/Azure Service Bus.
+- Define messages as `record` types for immutability.
+- Use consumers (`IConsumer<T>`) for message handling.
+- Use sagas for long-running, multi-step workflows with state.
+- Use retry and circuit breaker policies for transient failures.
+
+## Logging
+- Use `ILogger<T>` via DI. Never instantiate loggers manually.
+- Use structured logging: `_logger.LogInformation("User {UserId} logged in", userId)`.
+- Use Serilog with sinks for structured, centralized logging.
+- Use log scopes for request correlation: `using (_logger.BeginScope(...))`.
+
+## Configuration
+- Use `appsettings.json` + environment-specific overrides + environment variables.
+- Bind configuration sections to strongly-typed classes with `IOptions<T>`.
+- Use `IOptionsMonitor<T>` for configuration that changes at runtime.
+- Validate configuration at startup with `ValidateDataAnnotations()`.
+
+## Health Checks
+- Use `app.MapHealthChecks("/health")` for liveness probes.
+- Register custom health checks for database, cache, and external service dependencies.
+- Use `AspNetCore.HealthChecks.*` NuGet packages for common checks.
+
+# C# Patterns
+
+## Error Handling
+- Use exceptions for truly exceptional conditions. Use `Result<T>` pattern for expected failures.
+- Create domain exception hierarchies: `class DomainException : Exception`.
+- Use `when` clause in catch: `catch (HttpRequestException e) when (e.StatusCode == 404)`.
+- Use `ExceptionDispatchInfo.Capture(e).Throw()` to preserve original stack trace.
+- Return `Result<T, Error>` types for operations with expected failure modes.
+
+## Async Patterns
+- Use `Task.WhenAll()` for concurrent independent operations.
+- Use `SemaphoreSlim` for async-compatible resource limiting.
+- Use `Channel<T>` for async producer-consumer patterns.
+- Use `IAsyncEnumerable<T>` for streaming data from async sources.
+- Use `Polly` for retry, circuit breaker, and timeout policies.
+- Never use `.Result` or `.Wait()` on tasks (deadlock risk). Always `await`.
+
+## Dependency Injection
+- Use constructor injection exclusively. Avoid service locator pattern.
+- Register services in `Program.cs` or `IServiceCollection` extension methods.
+- Use `Scoped` for request-lifetime services, `Singleton` for stateless, `Transient` for lightweight.
+- Use `IOptions<T>` pattern for configuration injection.
+- Validate DI registrations at startup with `ValidateOnBuild = true`.
+
+## LINQ
+- Use method syntax for complex queries. Use query syntax for joins.
+- Use `FirstOrDefault()` over `First()` for safe access.
+- Use `AsNoTracking()` for read-only EF Core queries (performance).
+- Avoid materializing large collections: use `IQueryable<T>` until final projection.
+- Use `Select()` to project only needed columns from database queries.
+
+## Disposable Pattern
+- Implement `IAsyncDisposable` for async cleanup.
+- Use `await using var resource = ...;` for deterministic async disposal.
+- Use `IDisposable` with `using` declaration (C# 8) for scope-based cleanup.
+- Register disposable services in DI container (auto-disposed at scope end).
+
+## Mediator / CQRS
+- Use MediatR for command/query separation and pipeline behaviors.
+- Commands: `IRequest<Result>` for mutations. Queries: `IRequest<T>` for reads.
+- Use pipeline behaviors for cross-cutting: validation, logging, transactions.
+- Keep handlers thin: delegate to domain services for business logic.
+
+## Value Objects
+- Use `record` types for value objects with structural equality.
+- Use factory methods with validation: `public static Result<Email> Create(string value)`.
+- Override `ToString()` for logging-friendly representations.
+- Use implicit/explicit operators sparingly for primitive wrapper conversions.
+
+## Anti-Patterns
+- Service locator: inject dependencies, do not resolve from container.
+- `async void`: use only for event handlers. Everything else returns `Task`.
+- Nested `try-catch`: flatten with early returns or guard clauses.
+- Anemic domain model: put behavior in domain objects, not only services.
+- Over-abstracting: do not create interfaces for classes with only one implementation.
+
+# C# Security
+
+## Input Validation
+- Use data annotations (`[Required]`, `[StringLength]`, `[Range]`) on request models.
+- Use `[ApiController]` for automatic 400 responses on validation failure.
+- Use FluentValidation for complex, rule-based validation logic.
+- Never trust client-provided IDs. Verify resource ownership server-side.
+- Sanitize HTML input with a library like HtmlSanitizer. Never render raw user HTML.
+
+## SQL Injection
+- Use EF Core parameterized queries exclusively. Never concatenate SQL.
+- Use `FromSqlInterpolated()` over `FromSqlRaw()` for raw SQL (auto-parameterized).
+- Use stored procedures via `context.Database.ExecuteSqlInterpolatedAsync()`.
+- Audit all `FromSqlRaw()` calls for parameter interpolation risks.
+- Use Dapper with parameterized queries: `@param` syntax in SQL strings.
+
+## Authentication
+- Use ASP.NET Core Identity for user management and password hashing.
+- Use `AddAuthentication().AddJwtBearer()` for JWT-based API auth.
+- Use short-lived access tokens (15 min) with refresh token rotation.
+- Use `[Authorize]` attribute globally. Use `[AllowAnonymous]` selectively.
+- Use HTTPS redirection: `app.UseHttpsRedirection()`.
+
+## Authorization
+- Use policy-based authorization: `[Authorize(Policy = "AdminOnly")]`.
+- Use `IAuthorizationHandler` for custom authorization logic.
+- Use resource-based authorization for object-level access control.
+- Default deny: apply `[Authorize]` at controller/app level, opt out per endpoint.
+- Check ownership in service layer, not just role membership.
+
+## CSRF and XSS
+- Use anti-forgery tokens for form-based submissions.
+- Razor/Blazor auto-encodes output. Never use `@Html.Raw()` with user data.
+- Set `Content-Security-Policy` headers to restrict script sources.
+- Use `SameSite=Strict` on cookies for CSRF mitigation.
+- Enable CORS only for specific origins. Never use `AllowAnyOrigin()` with credentials.
+
+## Data Protection
+- Use `IDataProtectionProvider` for symmetric encryption of sensitive data.
+- Use `SecureString` or `ProtectedData` for in-memory sensitive data (limited use).
+- Use ASP.NET Core Data Protection API for token and cookie encryption.
+- Hash passwords with `PasswordHasher<T>` (PBKDF2 with salt).
+
+## Secrets Management
+- Use `dotnet user-secrets` for local development. Use Azure Key Vault for production.
+- Use `IConfiguration` with environment variable providers. Never hardcode secrets.
+- Use `[SensitiveData]` attributes to exclude fields from logging and serialization.
+- Never log request headers containing Authorization or cookie values.
+
+## Dependency Security
+- Run `dotnet list package --vulnerable` to check for known CVEs.
+- Use Dependabot or NuGetAudit for automated vulnerability scanning.
+- Pin package versions explicitly. Avoid floating version ranges.
+- Update `Microsoft.AspNetCore.*` packages promptly for security patches.
+
+# C# Testing
+
+## Framework
+- Use xUnit as the primary test framework (modern, extensible).
+- Use NSubstitute for mocking (clean syntax, no setup boilerplate).
+- Use FluentAssertions for readable, expressive assertions.
+- Use Testcontainers for integration tests with databases and services.
+
+## File Naming
+- Test files: `FooTests.cs` in a separate `*.Tests` project.
+- Mirror source project namespace structure in test project.
+- Integration tests: separate `*.IntegrationTests` project.
+- Use `[Collection("Database")]` for shared fixtures across test classes.
+
+## Structure
+- Use `[Fact]` for single test cases. Use `[Theory]` for parameterized tests.
+- Use `[InlineData]` or `[MemberData]` for test data in theories.
+- Use constructor injection for per-test setup. Use `IClassFixture<T>` for shared setup.
+- Name tests: `MethodName_Scenario_ExpectedResult`.
+
+## Assertions (FluentAssertions)
+- Use `result.Should().Be(expected)` for value assertions.
+- Use `action.Should().Throw<InvalidOperationException>()` for exception testing.
+- Use `collection.Should().ContainSingle(x => x.Id == 1)` for collection assertions.
+- Use `result.Should().BeEquivalentTo(expected)` for deep object comparison.
+- Use `execution.Should().CompleteWithinAsync(5.Seconds())` for timeout assertions.
+
+## Mocking (NSubstitute)
+- Create mocks: `var repo = Substitute.For<IUserRepository>()`.
+- Stub returns: `repo.GetAsync(1).Returns(user)`.
+- Verify calls: `repo.Received(1).SaveAsync(Arg.Any<User>())`.
+- Use `Arg.Is<T>(predicate)` for argument matching.
+- Use `ReturnsForAnyArgs()` for lenient stubs in arrangement-focused tests.
+
+## Integration Testing
+- Use `WebApplicationFactory<Program>` for ASP.NET Core integration tests.
+- Override services with `WithWebHostBuilder(b => b.ConfigureServices(...))`.
+- Use `HttpClient` from factory for endpoint testing.
+- Use `Respawn` for database cleanup between tests.
+- Use `[Collection]` attribute to prevent parallel execution of shared-resource tests.
+
+## Test Data
+- Use Builder pattern for complex test data: `new UserBuilder().WithName("Ada").Build()`.
+- Use `AutoFixture` for auto-generated test data.
+- Use `Bogus` library for realistic fake data generation.
+- Keep test data creation close to the test, not in distant shared files.
+
+## Best Practices
+- Test behavior, not implementation. Avoid testing private methods.
+- Keep tests independent. No shared mutable state between tests.
+- Use `CancellationToken.None` explicitly in async test calls.
+- Run tests in CI with `dotnet test --blame-hang-timeout 60s`.

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

@@ -0,0 +1,299 @@
+---
+name: dart-rules
+description: "Dart/Flutter coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget. Load when writing, reviewing, or editing Dart/Flutter code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Dart/Flutter Rules
+
+These rules come from `app/rules/dart/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Dart/Flutter. Apply them when writing or
+reviewing Dart/Flutter code.
+
+# Dart Coding Style
+
+## Naming
+- PascalCase: classes, enums, typedefs, extensions, mixins.
+- camelCase: variables, functions, methods, parameters, named constants.
+- snake_case: libraries, packages, directories, source files.
+- UPPER_SNAKE: not used in Dart. Use camelCase for constants.
+- Prefix private members with `_`: `_internalState`, `_helper()`.
+
+## Null Safety
+- Enable sound null safety (default since Dart 2.12).
+- Use `?` types only when null is semantically meaningful.
+- Use `!` operator sparingly. Prefer null checks or `??` fallback.
+- Use `late` keyword only when initialization is guaranteed before access.
+- Use `required` keyword for mandatory named parameters.
+
+## Classes
+- Use `const` constructors for immutable classes.
+- Use factory constructors for caching, subtype selection, or validation.
+- Use named constructors for clarity: `Point.fromJson(json)`.
+- Use `final` fields for immutable properties.
+- Use `@immutable` annotation on classes that should be immutable.
+
+## Functions
+- Use named parameters for functions with >2 parameters.
+- Use `required` for mandatory named parameters.
+- Use default values for optional parameters.
+- Use fat arrow (`=>`) for single-expression functions.
+- Always specify return types for public functions.
+
+## Collections
+- Use collection literals: `[]`, `{}`, `<String, int>{}`.
+- Use `if` and `for` inside collection literals for conditional/iterative building.
+- Use spread operator: `[...list1, ...list2]`.
+- Use `whereType<T>()` for type-safe filtering.
+- Prefer `const` collections when values are known at compile time.
+
+## Async
+- Use `async`/`await` for all asynchronous operations.
+- Return `Future<T>` from async functions. Never return `void`.
+- Use `Stream<T>` for continuous data (events, real-time updates).
+- Use `Future.wait()` for concurrent independent operations.
+- Use `Completer<T>` only when wrapping callback-based APIs.
+
+## Imports
+- Order: `dart:` SDK, `package:` external, relative project imports.
+- Use `show`/`hide` to limit import scope when names conflict.
+- Use `as` prefix for namespace conflicts: `import 'package:foo/foo.dart' as foo`.
+- Prefer relative imports within the same package.
+
+## Formatting
+- Use `dart format` (line length 80) for consistent formatting.
+- Use `dart analyze` for static analysis with default lint rules.
+- Use `analysis_options.yaml` with recommended lints: `flutter_lints` or `lints`.
+- Use trailing commas in multi-line argument lists for cleaner diffs.
+
+# Dart Frameworks
+
+## Flutter
+- Use `StatelessWidget` by default. Use `StatefulWidget` only for local state.
+- Use `const` constructors and `const` widgets for build optimization.
+- Use `Key` parameters for widgets in lists for correct diffing.
+- Extract large `build()` methods into smaller widget classes (not methods).
+- Use `Theme.of(context)` and `TextTheme` for consistent styling.
+
+## Navigation
+- Use `GoRouter` for declarative, type-safe routing.
+- Define routes as constants: `static const String home = '/home'`.
+- Use `ShellRoute` for persistent navigation bars across routes.
+- Use `context.go()` for navigation, `context.push()` for stacking.
+- Pass arguments via path parameters or `extra` for complex objects.
+
+## Networking
+- Use `dio` for HTTP with interceptors, retry, and cancellation.
+- Use `retrofit` (code gen) for type-safe REST client definitions.
+- Use interceptors for auth token injection and refresh logic.
+- Set timeouts on every request: `connectTimeout`, `receiveTimeout`.
+- Use `CancelToken` for cancelling in-flight requests on navigation.
+
+## JSON Serialization
+- Use `json_serializable` (+ `build_runner`) for generated `fromJson`/`toJson`. Default `fieldRename: FieldRename.none` uses Dart property names as-is — combined with Effective Dart `lowerCamelCase`, this produces `camelCase` JSON keys with zero configuration.
+- Flutter docs recommend: *"best if both server and client follow the same naming strategy"* ([Flutter — JSON and serialization](https://docs.flutter.dev/data-and-backend/serialization/json)). When they do, no mapping is needed.
+- When server uses a different convention, prefer `@JsonSerializable(fieldRename: FieldRename.snake)` at the class level (or globally in `build.yaml`) over sprinkling `@JsonKey(name:)` on every field. Community recommendation from the `json_serializable` docs and pub.dev guides.
+- Use individual `@JsonKey(name: '...')` only for exceptional cases: external API with mixed conventions, reserved Dart keyword collision (`class`, `is`, `new`), or legacy field rename during deprecation window. Document the reason in a comment.
+- For enum / status / permission values on the wire: `UPPER_SNAKE_CASE` is the cross-language community consensus (see `common/coding-style.md` — JSON Wire Format Conventions). Dart enum case names themselves stay `lowerCamelCase` per Effective Dart; map them to uppercase strings in `fromJson`/`toJson` (`value.toUpperCase()` + `switch`).
+- Write unit tests asserting both directions (`fromJson` + `toJson`) with explicit expected keys. Catches contract drift at CI time.
+
+## Local Storage
+- Use `shared_preferences` for simple key-value persistence.
+- Use `drift` (formerly Moor) for type-safe SQLite with reactive queries.
+- Use `hive` for fast, lightweight NoSQL local storage.
+- Use `flutter_secure_storage` for sensitive data (tokens, passwords).
+- Never store secrets in `shared_preferences` (not encrypted).
+
+## Dependency Injection
+- Use `get_it` for service locator pattern. Register at app startup.
+- Use `injectable` (code gen) for automatic registration from annotations.
+- Use Riverpod providers as DI containers for testable architecture.
+- Register singletons for services, factories for per-use instances.
+
+## Platform Channels
+- Use `MethodChannel` for invoking native (iOS/Android) code.
+- Use `EventChannel` for streaming data from native to Dart.
+- Use `Pigeon` (code gen) for type-safe platform channel definitions.
+- Handle `MissingPluginException` gracefully on unsupported platforms.
+
+## Testing Frameworks
+- Use `flutter_test` for widget tests with `WidgetTester`.
+- Use `integration_test` package for full app integration tests.
+- Use `patrol` for native-aware integration testing (permissions, notifications).
+- Use `golden_toolkit` for advanced visual regression testing.
+
+## Build and CI
+- Use `flutter build` with `--release` and `--dart-define` for env configuration.
+- Use flavors (`--flavor`) for dev/staging/prod build variants.
+- Use `flutter analyze` in CI for static analysis enforcement.
+- Use `flutter test --coverage` with `lcov` for coverage reporting.
+
+# Dart Patterns
+
+## Error Handling
+- Use typed exceptions for domain errors: `class UserNotFoundException implements Exception`.
+- Use `try-catch` with specific exception types. Avoid bare `catch (e)`.
+- Use `rethrow` to preserve stack trace when re-raising exceptions.
+- Use `Result<T, E>` pattern (e.g., `dartz` Either) for expected failures.
+- Use `Future.catchError()` only when `async/await` is not applicable.
+
+## State Management (Flutter)
+- Use Riverpod for compile-safe, testable state management.
+- Use BLoC pattern for event-driven state with clear input/output.
+- Use `ChangeNotifier` / `ValueNotifier` for simple local state.
+- Use `StateNotifier` (Riverpod) for immutable state transitions.
+- Keep state classes immutable. Use `copyWith()` for updates.
+
+## Riverpod
+- Use `@riverpod` annotation (code gen) for provider definitions.
+- Use `ref.watch()` for reactive dependencies. Use `ref.read()` for one-time access.
+- Use `AsyncNotifier` for async state management.
+- Use `autoDispose` for providers that should clean up when unused.
+- Use `family` modifier for parameterized providers.
+
+## BLoC Pattern
+- Separate events (input), states (output), and logic (bloc).
+- Use `sealed class` for events and states (exhaustive `switch`).
+- Use `Emitter<State>` for emitting state transitions.
+- Use `transformEvents()` for debouncing search inputs.
+- Use `BlocObserver` for global logging and error tracking.
+
+## Repository Pattern
+- Abstract data sources behind repository interfaces.
+- Repositories return domain models, not DTOs or raw data.
+- Use `Future<T>` for single values, `Stream<T>` for real-time updates.
+- Cache data in repository layer when appropriate.
+- Inject repositories via constructor. Use Riverpod/GetIt for DI.
+
+## Freezed (Code Generation)
+- Use `@freezed` for immutable data classes with `copyWith`, equality, `toString`.
+- Use `@freezed` sealed unions for state modeling: `factory State.loading()`.
+- Use `when()` / `map()` for exhaustive pattern matching on freezed unions.
+- Run `dart run build_runner build` after modifying freezed classes.
+
+## Async Patterns
+- Use `Stream.asyncMap()` for transforming streams with async operations.
+- Use `StreamController<T>` for custom streams. Close in `dispose()`.
+- Use `Completer<T>` to bridge callback APIs to Future-based APIs.
+- Use `Timer.periodic()` for polling. Cancel in `dispose()`.
+- Use `compute()` (Flutter) for CPU-intensive work on isolates.
+
+## Anti-Patterns
+- Using `dynamic` type: defeats type safety. Use `Object?` or generics.
+- Not disposing controllers/subscriptions: causes memory leaks.
+- Putting business logic in widgets: extract to services/blocs.
+- Using `setState()` for global state: use proper state management.
+- Deep widget nesting: extract sub-widgets as separate classes.
+
+# Dart Security
+
+## Input Validation
+- Validate all user input in form fields with `TextFormField` validators.
+- Use `RegExp` for pattern validation (email, phone, URL).
+- Sanitize HTML content before rendering. Never use `Html` widget with raw user input.
+- Validate deep link parameters before navigation or data loading.
+- Limit text input length with `maxLength` on `TextFormField`.
+
+## Network Security
+- Use HTTPS exclusively. Configure `SecurityContext` for certificate pinning.
+- Use `dio` interceptors for consistent auth header injection.
+- Validate SSL certificates in production. Do not disable certificate checks.
+- Set connection and read timeouts on all HTTP requests.
+- Use `CancelToken` to abort requests when the user navigates away.
+
+## Data Storage
+- Use `flutter_secure_storage` for tokens, passwords, and API keys.
+- Never store sensitive data in `shared_preferences` (stored in plaintext).
+- Encrypt local databases (`drift` with `sqlcipher`, or `hive` with encryption).
+- Clear secure storage on user logout.
+- Use `kIsWeb` checks to handle web platform storage limitations.
+
+## Authentication
+- Use OAuth 2.0 / OIDC with PKCE flow for mobile authentication.
+- Store refresh tokens in secure storage. Store access tokens in memory.
+- Use `flutter_appauth` for standards-compliant OAuth flows.
+- Implement biometric authentication with `local_auth` package.
+- Never store credentials in Dart source code or asset files.
+
+## Platform Channel Security
+- Validate all data received from native code via platform channels.
+- Do not pass sensitive data through `MethodChannel` logging-enabled calls.
+- Use `Pigeon` for type-safe channel communication (prevents mismatched types).
+- Handle `PlatformException` gracefully for missing native implementations.
+
+## Obfuscation and Hardening
+- Use `--obfuscate --split-debug-info=<dir>` for release builds.
+- Use `--dart-define` for environment-specific configuration (not secrets).
+- Do not embed API keys in the Dart source. Use server-side proxying.
+- Use ProGuard rules (Android) and symbol stripping (iOS) for native code.
+
+## WebView Security
+- Use `webview_flutter` with JavaScript disabled unless explicitly needed.
+- Restrict navigation to allowlisted domains with `NavigationDelegate`.
+- Sanitize any data passed from WebView to Dart via JavaScript channels.
+- Do not load untrusted URLs in WebViews.
+
+## Dependency Security
+- Run `dart pub outdated` regularly. Update dependencies promptly.
+- Audit `pubspec.lock` for unexpected transitive dependencies.
+- Use `dart pub audit` (when available) for vulnerability scanning.
+- Prefer well-maintained packages with high pub.dev scores.
+- Pin exact versions in `pubspec.yaml` for production apps.
+
+# Dart Testing
+
+## Framework
+- Use `package:test` for pure Dart unit tests.
+- Use `package:flutter_test` for Flutter widget and integration tests.
+- Use `package:mockito` with `@GenerateMocks` for mock generation.
+- Use `package:mocktail` as a simpler alternative (no code generation).
+
+## File Naming
+- Test files: `foo_test.dart` in `test/` mirroring `lib/` structure.
+- Widget tests: `test/widgets/` for Flutter widget tests.
+- Integration tests: `integration_test/` directory (Flutter convention).
+- Golden tests: `test/goldens/` for visual regression snapshots.
+
+## Structure
+- Use `group()` for organizing related tests.
+- Use `setUp()` / `tearDown()` for per-test setup and cleanup.
+- Use `setUpAll()` / `tearDownAll()` for expensive one-time setup.
+- Name tests descriptively: `test('returns null when user is not found', ...)`.
+
+## Assertions
+- Use `expect(actual, matcher)` with built-in matchers.
+- Use `equals()`, `isNull`, `isNotNull`, `isA<T>()` for type/value checks.
+- Use `throwsA(isA<FormatException>())` for exception testing.
+- Use `completion(expected)` for Future assertions.
+- Use `emitsInOrder([...])` for Stream emission testing.
+
+## Mocking (Mockito)
+- Annotate: `@GenerateMocks([UserRepository])`. Run `build_runner`.
+- Stub: `when(mock.getUser(any)).thenAnswer((_) async => user)`.
+- Verify: `verify(mock.saveUser(captureAny)).called(1)`.
+- Use `verifyNever()` to assert a method was not called.
+- Use `throwOnMissingStub()` to catch unstubbed method calls.
+
+## Widget Testing (Flutter)
+- Use `testWidgets('description', (tester) async { ... })`.
+- Use `tester.pumpWidget(MaterialApp(home: MyWidget()))` to render.
+- Use `tester.pump()` to trigger rebuilds after state changes.
+- Use `tester.pumpAndSettle()` to wait for animations to complete.
+- Use `find.byType()`, `find.text()`, `find.byKey()` for widget lookups.
+- Use `tester.tap()`, `tester.enterText()` for interaction simulation.
+
+## Golden Tests
+- Use `matchesGoldenFile('goldens/my_widget.png')` for visual comparison.
+- Run `flutter test --update-goldens` to regenerate baseline images.
+- Use golden tests for complex UI components, not simple widgets.
+- Keep golden tests platform-specific (render output varies by OS).
+
+## Best Practices
+- Test public API behavior, not implementation details.
+- Use `fake` classes (implementing interfaces) for simple test doubles.
+- Use `addTearDown()` to register cleanup in the test body.
+- Run `flutter test --coverage` and check `coverage/lcov.info`.
+- Use `blocTest()` from `bloc_test` package for BLoC testing.