@softspark/ai-toolkit 1.2.0 → 1.3.0

package/app/rules/csharp/frameworks.md

@@ -0,0 +1,60 @@
+---
+language: csharp
+category: frameworks
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/csharp/patterns.md

@@ -0,0 +1,61 @@
+---
+language: csharp
+category: patterns
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/csharp/security.md

@@ -0,0 +1,60 @@
+---
+language: csharp
+category: security
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/csharp/testing.md

@@ -0,0 +1,58 @@
+---
+language: csharp
+category: testing
+version: "1.0.0"
+---
+
+# 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/rules/dart/coding-style.md

@@ -0,0 +1,61 @@
+---
+language: dart
+category: coding-style
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/dart/frameworks.md

@@ -0,0 +1,59 @@
+---
+language: dart
+category: frameworks
+version: "1.0.0"
+---
+
+# 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.
+
+## 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.

package/app/rules/dart/patterns.md

@@ -0,0 +1,62 @@
+---
+language: dart
+category: patterns
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/dart/security.md

@@ -0,0 +1,60 @@
+---
+language: dart
+category: security
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/dart/testing.md

@@ -0,0 +1,60 @@
+---
+language: dart
+category: testing
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/golang/coding-style.md

@@ -0,0 +1,50 @@
+---
+language: golang
+category: coding-style
+version: "1.0.0"
+---
+
+# Go Coding Style
+
+## Naming
+- MixedCaps/mixedCaps only. No underscores in Go names (except test functions).
+- Exported: `PascalCase`. Unexported: `camelCase`. Acronyms: `HTTPClient`, `userID`.
+- Short variable names in small scopes: `i`, `r`, `w`, `ctx`, `err`.
+- Descriptive names in larger scopes: `userRepository`, `requestTimeout`.
+- Package names: short, lowercase, singular (`auth`, `user`, not `utils`, `helpers`).
+
+## Packages
+- One package per directory. Package name = directory name.
+- Avoid `util`, `common`, `helpers` packages. Name by what it provides.
+- Keep package APIs small. Export only what consumers need.
+- Use `internal/` directory for packages not meant for external consumption.
+
+## Functions
+- Accept interfaces, return structs.
+- First parameter `ctx context.Context` if the function does I/O or may be cancelled.
+- Return `(result, error)` tuple. Error is always last return value.
+- Use named return values only for documentation, not for naked returns.
+- Keep functions short. If >40 lines, consider splitting.
+
+## Error Handling
+- Always check errors. Never use `_` to discard errors silently.
+- Wrap errors with context: `fmt.Errorf("fetching user %s: %w", id, err)`.
+- Use sentinel errors (`var ErrNotFound = errors.New(...)`) for expected conditions.
+- Use `errors.Is()` and `errors.As()` for error checking, not type assertions.
+
+## Formatting
+- Use `gofmt` / `goimports`. No formatting debates in Go.
+- Use `golangci-lint` with a `.golangci.yml` config in CI.
+- Use `go vet` as minimum static analysis.
+
+## Struct Design
+- Use struct embedding for composition, not inheritance.
+- Prefer value receivers for small structs, pointer receivers for large or mutable.
+- Be consistent: all methods on a type use the same receiver type.
+- Use struct literals with field names: `User{Name: "Ada", Age: 30}`.
+
+## Concurrency
+- Do not start goroutines without a plan to stop them.
+- Use `sync.WaitGroup` or `errgroup.Group` to coordinate goroutines.
+- Use channels for communication, mutexes for state protection.
+- Prefer `context.Context` for cancellation and timeouts over manual signaling.

package/app/rules/golang/frameworks.md

@@ -0,0 +1,56 @@
+---
+language: golang
+category: frameworks
+version: "1.0.0"
+---
+
+# Go Frameworks
+
+## Standard Library HTTP
+- Use `http.NewServeMux()` (Go 1.22+ with method patterns) for simple APIs.
+- Use `http.HandlerFunc` for handlers. Compose with middleware pattern.
+- Use `context.Context` from `r.Context()` in all handlers.
+- Use `http.TimeoutHandler` to prevent slow handlers from hanging.
+
+## Chi / Gorilla Mux
+- Use Chi for routing with middleware chains and URL params.
+- Use `chi.URLParam(r, "id")` to extract path parameters.
+- Use middleware groups: `r.Group(func(r chi.Router) { r.Use(authMiddleware) })`.
+- Prefer Chi over Gorilla Mux (Gorilla was archived, Chi actively maintained).
+
+## Gin / Echo
+- Use Gin for high-performance APIs with built-in validation.
+- Use binding tags: `binding:"required,email"` on struct fields.
+- Use middleware for cross-cutting: logging, recovery, CORS, auth.
+- Use `c.ShouldBindJSON()` over `c.BindJSON()` to handle errors yourself.
+
+## GORM / sqlx / pgx
+- Use `sqlx` for SQL-first with struct scanning (lightweight).
+- Use `pgx` directly for PostgreSQL-specific features and performance.
+- Use GORM only when rapid prototyping outweighs SQL control.
+- Always use prepared statements or parameterized queries.
+- Use `sqlx.In()` for dynamic IN clauses safely.
+
+## gRPC
+- Define services in `.proto` files. Generate Go code with `protoc`.
+- Use interceptors for auth, logging, and tracing (equivalent to middleware).
+- Use deadlines (context timeout) on every RPC call.
+- Use streaming RPCs for real-time data, unary for request-response.
+
+## Configuration
+- Use `envconfig` or `viper` for configuration from env/files.
+- Use struct tags for env mapping: `envconfig:"DATABASE_URL"`.
+- Validate config at startup. Fail fast on invalid configuration.
+- Use `flag` package for CLI arguments in tools and utilities.
+
+## Observability
+- Use `slog` (Go 1.21+) for structured logging. Replace `log` package.
+- Use OpenTelemetry for distributed tracing and metrics.
+- Export metrics via Prometheus endpoint.
+- Use `pprof` for CPU and memory profiling in development.
+
+## Project Layout
+- Follow Standard Go Project Layout: `cmd/`, `internal/`, `pkg/`.
+- Entry points in `cmd/appname/main.go`.
+- Business logic in `internal/`. Shared libraries in `pkg/`.
+- Use `Makefile` for common tasks: build, test, lint, run.