@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-code-reviewer/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: "flutter-code-reviewer"
+displayName: "Flutter/Dart Code Reviewer"
+description: "Perform strict, actionable code reviews for Flutter/Dart projects enforcing architecture boundaries, Riverpod patterns, testing, and performance"
+keywords:
+  [
+    "code review",
+    "pr review",
+    "flutter review",
+    "dart review",
+    "riverpod review",
+    "architecture",
+    "clean code",
+    "testing",
+    "performance",
+  ]
+---
+
+# Flutter/Dart Code Reviewer
+
+## Overview
+
+This power performs comprehensive code reviews enforcing Clean Architecture boundaries, state management patterns (Riverpod/GetX/Bloc), testing requirements, and performance standards. It adapts to your project's specific tech stack and design system.
+
+## Review Goals
+
+- Keep the codebase **consistent** with your architecture
+- Catch bugs early (loops, rebuild storms, race conditions)
+- Enforce **clean boundaries** (presentation ↔ domain ↔ data)
+- Ensure changes are **testable** and include the right tests
+- Prevent long-term maintenance pain (naming, duplication, tight coupling)
+
+## When to Use
+
+- Reviewing pull requests
+- Conducting code quality audits
+- Checking for architectural violations
+- Validating state management patterns
+- Ensuring test coverage
+
+## Review Severity Levels
+
+- **BLOCKER**: Must fix before merge (crashes, security, data loss, infinite loops, architectural violations)
+- **MAJOR**: Should fix before merge (performance issues, missing tests, incorrect patterns)
+- **MINOR**: Fix soon (style, small refactors)
+- **NIT**: Optional (readability, formatting)
+
+## Review Output Format
+
+When reviewing, output exactly:
+
+1. **Summary** (2-5 lines)
+2. **BLOCKERS** (bulleted, each with "Why" + "Fix")
+3. **MAJORS**
+4. **MINORS / NITS**
+5. **Suggested patch** (optional: small code snippets only)
+6. **Tests to add/update** (concrete list)
+7. **Architecture & performance notes** (select/watch boundaries, DI, caching)
+
+---
+
+## Architecture Compliance (Pragmatic Clean Architecture)
+
+### Presentation Layer
+- Views contain **no business logic**, no repository calls
+- Controllers (AsyncNotifier) own all state + operations for a feature
+- One controller per feature — reads AND writes (no separate mutation unless 5+ write ops)
+- UI uses design system components and tokens
+
+### Data Layer
+- Repository is the "conductor" — coordinates API + cache, returns domain types
+- Repository handles error mapping (DioException → Failure)
+- No Riverpod imports in data layer
+- DI provider for repository lives inline in the repository file
+
+### Models
+- ONE Freezed class per entity (no separate entity + model)
+- Add mapper only when API response shape ≠ domain shape
+
+**BLOCKER if:**
+- UI calls repository/data source directly
+- Data layer imports Riverpod/Flutter
+- Controller imports data-layer classes (Dio, jsonEncode/Decode)
+- Duplicate entity + model classes when they're the same shape
+- Pass-through use cases that just call `repository.method()`
+
+---
+
+## State Management Review
+
+### Riverpod Watch/Read Discipline
+- `ref.watch` only in widget build / provider build
+- `ref.read` in callbacks + controller methods
+- `ref.listen` for side effects (snackbar/nav/dialog)
+
+### Loop & Rebuild Storm Red Flags
+
+**BLOCKER:**
+- Calling controller methods inside widget `build()`
+- Updating providers during build in a way that affects watched dependencies
+- Mutating lists/maps in-place and re-emitting same object reference
+
+### Families / Parameters
+- Params must be stable and comparable (`==`/`hashCode`) if object-based
+- Avoid passing mutable lists/maps as family params
+
+### Async State Handling
+- For "load more", keep flags inside state (don't abuse AsyncLoading and lose data)
+- Guard parallel calls (`isLoadingMore`)
+
+---
+
+## Naming & File Structure
+
+### File Naming
+- `lowercase_with_underscores.dart` for files and folders
+- 1 file = 1 main public type (or a tight group)
+
+### Type/Function Naming
+- Types: UpperCamelCase
+- Methods: lowerCamelCase; verb-first for commands (`refresh`, `submit`, `approve`)
+- Avoid `getX()` for remote calls; use `fetchX()`
+
+**BLOCKER if:**
+- Inconsistent naming causes confusion across features
+- Cross-feature imports instead of shared/core modules
+
+---
+
+## Clean Code Principles (Pragmatic)
+
+Apply these *practically*:
+- **SRP**: one controller per screen/aggregate; repositories only data concerns
+- **DIP**: domain depends on abstractions; data provides implementations
+- **KISS**: avoid over-abstraction; prefer the simplest working design
+- **DRY**: avoid copy/paste, but do not create "god utils" or premature frameworks
+- **YAGNI**: don't add complexity "just in case"
+
+Use as review guidance, not dogma.
+
+---
+
+## Performance Checklist
+
+**BLOCKER:**
+- Expensive computation in build (parsing, sorting large lists) without memoization
+- Whole-screen watching large provider states without `select`
+- Rebuilding entire lists for small changes
+
+**MAJOR:**
+- Missing `const` where easy
+- No stable keys on list items where state should persist
+
+---
+
+## Testing Requirements
+
+Required when:
+- New controller/provider logic is added
+- Bug fixes for regressions
+- Paging/refresh/caching logic changes
+- Error mapping changes
+
+Minimum:
+- 1 unit/provider test for controller happy path
+- 1 unit test for failure path
+- Widget test for loading/error/data (or override repo)
+
+See: `references/testing_expectations.md`
+
+---
+
+## References
+
+Load detailed guidance only when needed.
+
+| File | Load when |
+| --- | --- |
+| `references/review_checklist.md` | Starting a review and needing the full category-by-category checklist |
+| `references/testing_expectations.md` | Checking whether controller, widget, or regression tests are sufficient |
+| `references/common-issues.md` | Looking for recurring Flutter/Riverpod review smells and anti-patterns |
+| `references/feedback-examples.md` | Writing concise, high-signal review feedback with clear fixes |
+| `references/strict-rules.md` | Applying stricter merge-blocking review standards |
+
+## Templates
+
+- `templates/review_response.md` - Code review response template

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-code-reviewer/references/common-issues.md

@@ -0,0 +1,173 @@
+# Common Issues
+
+> Reference for: Code Reviewer
+> Load when: Identifying code problems
+
+## N+1 Query Problem
+
+```dart
+// N+1 queries - BAD
+final posts = await postRepository.findAll();
+for (final post in posts) {
+  post.author = await userRepository.findById(post.authorId); // N queries!
+}
+
+// Single query with join - GOOD
+final posts = await postRepository.findAllWithAuthors();
+
+// Or batch load
+final posts = await postRepository.findAll();
+final authorIds = posts.map((p) => p.authorId).toList();
+final authors = await userRepository.findByIds(authorIds);
+```
+
+## Missing Error Handling
+
+```dart
+// Unhandled error - BAD
+final data = await api.fetchData();
+
+// Proper error handling - GOOD
+try {
+  final response = await api.fetchData();
+  return Result.success(response);
+} on DioException catch (e) {
+  logger.error('Failed to fetch data', error: e);
+  return Result.failure(NetworkFailure(e.message));
+} catch (e, st) {
+  logger.error('Unexpected error', error: e, stackTrace: st);
+  return Result.failure(UnknownFailure(e.toString()));
+}
+```
+
+## Magic Numbers/Strings
+
+```dart
+// Magic number - BAD
+if (user.age >= 18) { ... }
+Future.delayed(Duration(milliseconds: 86400000));
+
+// Named constant - GOOD
+const minimumAge = 18;
+const oneDay = Duration(days: 1);
+
+if (user.age >= minimumAge) { ... }
+Future.delayed(oneDay);
+```
+
+## Deep Nesting
+
+```dart
+// Deep nesting - BAD
+if (user != null) {
+  if (user.isActive) {
+    if (user.hasPermission) {
+      doSomething();
+    }
+  }
+}
+
+// Early returns - GOOD
+if (user == null || !user.isActive || !user.hasPermission) {
+  return;
+}
+doSomething();
+```
+
+## God Functions
+
+```dart
+// Does too much - BAD
+Future<void> processOrder(Order order) async {
+  // validate
+  // check inventory
+  // process payment
+  // send email
+  // update database
+  // log analytics
+}
+
+// Single responsibility - GOOD
+Future<void> processOrder(Order order) async {
+  await validateOrder(order);
+  await reserveInventory(order);
+  await chargePayment(order);
+  await sendConfirmation(order);
+}
+```
+
+## Mutable Shared State
+
+```dart
+// Shared mutable - BAD
+final config = {'debug': false};
+void enableDebug() {
+  config['debug'] = true;
+}
+
+// Immutable pattern - GOOD (Freezed)
+@freezed
+class Config with _$Config {
+  const factory Config({@Default(false) bool debug}) = _Config;
+}
+```
+
+## Missing Null Checks
+
+```dart
+// Unsafe access - BAD
+final name = user.profile.name;
+
+// Safe access - GOOD
+final name = user?.profile?.name ?? 'Unknown';
+```
+
+## Riverpod-Specific Issues
+
+```dart
+// ref.read in build - BAD
+Widget build(BuildContext context, WidgetRef ref) {
+  final data = ref.read(dataProvider); // WRONG!
+}
+
+// ref.watch in build - GOOD
+Widget build(BuildContext context, WidgetRef ref) {
+  final data = ref.watch(dataProvider);
+}
+
+// Calling methods in build - BAD (infinite loop)
+Widget build(BuildContext context, WidgetRef ref) {
+  ref.read(controllerProvider.notifier).loadMore(); // INFINITE LOOP!
+}
+
+// In-place mutation - BAD
+state = state..items.add(newItem); // Same reference!
+
+// Immutable update - GOOD
+state = state.copyWith(items: [...state.items, newItem]);
+```
+
+## Design Principles Checklist
+
+- **SRP** (Single Responsibility): one reason to change
+- **OCP** (Open/Closed): extend behavior without modifying core
+- **LSP** (Liskov): subtypes remain substitutable
+- **ISP** (Interface Segregation): small, focused interfaces
+- **DIP** (Dependency Inversion): depend on abstractions
+- **KISS**: simplest solution that works
+- **DRY**: avoid duplicated logic; extract shared code
+- **YAGNI**: avoid speculative features
+
+## Quick Reference
+
+| Issue                  | Impact          | Fix                       |
+| ---------------------- | --------------- | ------------------------- |
+| N+1 queries            | Performance     | Eager load or batch       |
+| Missing error handling | Reliability     | Try/catch + Result type   |
+| Magic numbers          | Maintainability | Named constants           |
+| Deep nesting           | Readability     | Early returns             |
+| God functions          | Testability     | Single responsibility     |
+| Mutable shared state   | Bugs            | Immutable patterns        |
+| Missing null checks    | Crashes         | Null-aware operators      |
+| ref.read in build      | Bugs            | Use ref.watch             |
+| In-place mutation      | State bugs      | copyWith / spread         |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-code-reviewer/references/feedback-examples.md

@@ -0,0 +1,163 @@
+# Feedback Examples
+
+> Reference for: Code Reviewer
+> Load when: Writing review feedback
+
+## Good vs Bad Feedback
+
+### Be Specific, Not Vague
+
+```markdown
+BAD: "This is confusing"
+
+GOOD: "This function handles both validation and persistence. Consider
+      splitting into `validateUser()` and `saveUser()` for single
+      responsibility and easier testing."
+```
+
+### Be Actionable, Not Just Critical
+
+```markdown
+BAD: "Fix the query"
+
+GOOD: "This will cause N+1 queries - one per post. Use eager loading
+      or batch fetch authors in a single query."
+```
+
+### Be Constructive, Not Demanding
+
+```markdown
+BAD: "Add tests"
+
+GOOD: "Missing test for the case when `email` is already taken. Add a test
+      that verifies the error state is returned with appropriate message."
+```
+
+### Ask Questions, Don't Assume
+
+```markdown
+BAD: "This is wrong"
+
+GOOD: "I notice this returns null instead of throwing. Is that intentional?
+      The other methods throw on not-found. Should this be consistent?"
+```
+
+## Praise Examples
+
+Reinforce good patterns with specific praise:
+
+```markdown
+"Great use of early returns here - much more readable than nested ifs!"
+
+"Nice extraction of this validation logic into a reusable function."
+
+"Excellent error messages - they'll help debugging in production."
+
+"Good choice using Freezed here instead of mutable state."
+
+"Appreciate the comprehensive test coverage, especially the edge cases."
+
+"Clean use of ref.watch vs ref.read - exactly right!"
+```
+
+## Feedback by Category
+
+### Critical (Must Fix)
+
+```markdown
+**[CRITICAL] Rebuild Loop**
+Location: `lib/features/home/views/home_view.dart:45`
+
+Calling controller method in build causes infinite loop:
+```dart
+Widget build(context, ref) {
+  ref.read(homeControllerProvider.notifier).loadData(); // INFINITE LOOP!
+}
+```
+
+Fix: Move to useEffect or call from user action:
+```dart
+useEffect(() {
+  ref.read(homeControllerProvider.notifier).loadData();
+  return null;
+}, []);
+```
+```
+
+### Major (Should Fix)
+
+```markdown
+**[MAJOR] Performance: N+1 Query**
+Location: `lib/features/posts/data/post_repository.dart:23`
+
+Current code fetches users in a loop (N+1 problem):
+```dart
+for (final post in posts) {
+  post.author = await userRepository.findById(post.authorId);
+}
+```
+
+Suggestion: Batch load users:
+```dart
+final authorIds = posts.map((p) => p.authorId).toSet().toList();
+final authors = await userRepository.findByIds(authorIds);
+final authorMap = {for (var a in authors) a.id: a};
+for (final post in posts) {
+  post.author = authorMap[post.authorId];
+}
+```
+
+Impact: ~100 extra DB queries per request with current approach.
+```
+
+### Minor (Nice to Have)
+
+```markdown
+**[MINOR] Naming: Unclear variable**
+Location: `lib/core/utils/date_utils.dart:12`
+
+`d` is unclear. Consider `createdDate` or `timestamp` for better readability.
+
+**[MINOR] Style: Prefer const**
+Location: `lib/core/config/app_config.dart:8`
+
+`var config` is never reassigned. Use `final` for immutability.
+```
+
+## Question Format
+
+```markdown
+**[QUESTION]**
+Location: `lib/features/orders/data/order_repository.dart:67`
+
+What's the expected behavior when the user has an existing pending order?
+Should this:
+- Return the existing order?
+- Create a new one anyway?
+- Return an error?
+```
+
+## Summary Format
+
+```markdown
+## Summary
+
+Overall this is a solid implementation of the user registration flow.
+The validation logic is clean and the error handling is comprehensive.
+
+**Blocking Issues**: 1 critical (rebuild loop)
+**Suggestions**: 2 major, 3 minor
+
+Once the rebuild loop is fixed, this is ready to merge. The major
+suggestions are performance improvements worth considering.
+```
+
+## Quick Reference
+
+| Feedback Type | Tone          | Required Action       |
+| ------------- | ------------- | --------------------- |
+| Critical      | Firm, clear   | Must fix before merge |
+| Major         | Suggestive    | Should fix            |
+| Minor         | Optional      | Nice to have          |
+| Praise        | Positive      | None - reinforcement  |
+| Question      | Curious       | Response needed       |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-code-reviewer/references/review_checklist.md

@@ -0,0 +1,68 @@
+# PR Review Checklist (copy/paste)
+
+## Architecture
+- [ ] Presentation does not call repository/data sources directly
+- [ ] Domain has no framework-specific imports (Flutter/Riverpod/Dio/Isar/GetX)
+- [ ] Data implements repository interface; errors mapped to Failure/Result
+- [ ] Dependency injection used correctly (no hardcoded dependencies)
+- [ ] Single responsibility principle followed
+
+## State Management
+
+### Riverpod Projects
+- [ ] No side effects in build
+- [ ] `ref.watch` in build, `ref.read` in callbacks, `ref.listen` for side effects
+- [ ] `build()` is pure, mutations in methods
+- [ ] Family params stable (==/hashCode)
+- [ ] No in-place mutation of emitted state
+- [ ] `ref.mounted` checked after async operations
+
+### GetX Projects
+- [ ] Controllers properly disposed
+- [ ] Observables used correctly (.obs, Rx types)
+- [ ] No memory leaks from subscriptions
+- [ ] GetBuilder/Obx used appropriately
+
+### Bloc/Cubit Projects
+- [ ] Events/states are immutable
+- [ ] No side effects in mapEventToState
+- [ ] Bloc properly closed
+- [ ] BlocProvider scope is correct
+
+## UI
+
+### Design System Compliance (if project has design system)
+- [ ] Uses project's design tokens (colors, spacing, typography)
+- [ ] Uses project's component library (not raw Flutter widgets)
+- [ ] No hardcoded colors (`Color(0xFF...)`, `Colors.white`)
+- [ ] No hardcoded spacing (`SizedBox(height: 16)`)
+- [ ] Theme-aware colors used where appropriate
+
+### General UI Best Practices
+- [ ] `select()` or equivalent used to minimize rebuilds
+- [ ] Large lists use `ListView.builder` or equivalent
+- [ ] List items have stable keys when needed
+- [ ] `const` widgets used where possible
+- [ ] No expensive computation in build methods
+
+## Networking/Errors
+- [ ] No secrets in logs
+- [ ] Errors mapped to typed Failure/Error classes
+- [ ] Timeouts configured appropriately
+- [ ] Cancellation behavior reasonable
+- [ ] Retry logic doesn't expose sensitive data
+
+## Tests
+- [ ] Controller/provider/bloc unit tests added
+- [ ] Failure/error paths tested
+- [ ] Widget test covers loading/error/data states
+- [ ] Mocks used appropriately (no real network calls)
+- [ ] Edge cases covered
+
+## Code Quality
+- [ ] Files use lowercase_with_underscores naming
+- [ ] Types use UpperCamelCase
+- [ ] Methods use verb-first naming (fetchUser, submitForm)
+- [ ] One main type per file
+- [ ] No commented-out code
+- [ ] No TODO without issue reference

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-code-reviewer/references/strict-rules.md

@@ -0,0 +1,84 @@
+# Strict Code Review Rules
+
+> Reference for: Code Reviewer
+> Load when: Enforcing strict review standards
+
+## Core Standard (Non-Negotiable)
+
+- **Correctness first**: reject changes that introduce incorrect behavior, regressions, or incomplete edge cases
+- **Readability is a feature**: if code is hard to understand, request changes
+- **Consistency over preference**: match existing style and patterns within the codebase
+
+## Change Size & Scope
+
+- **Small, focused changes**: large or multi-purpose changes must be split
+- **No scope creep**: remove unrequested features and speculative abstractions
+- **Spec first**: if requirements are ambiguous, request clarification before approval
+
+## Naming & File Organization
+
+- **Intention-revealing names**: names must convey responsibility and behavior
+- **One primary concern per file**: avoid "utility dump" files
+- **Consistent file naming**: `lowercase_with_underscores.dart`
+- **Type naming**: `UpperCamelCase` for classes, enums, typedefs
+
+## Error Handling & Reliability
+
+- **No empty catch blocks**: handle or rethrow with context
+- **Avoid catch-all**: don't catch overly broad exceptions unless at top-level boundary
+- **Fail fast with clear errors**: avoid silent failures and partial updates
+- **Use Result/Either types**: prefer typed error handling over exceptions
+
+## Concurrency & Race Conditions
+
+- **Atomicity required**: read-modify-write must be transactional or atomic
+- **Shared state must be protected**: use proper state management patterns
+- **Idempotency for retries**: requests and jobs should be safe to retry
+- **Check ref.mounted**: always check after async operations in Riverpod
+
+## Design Principles (Strict)
+
+- **SRP**: split large classes/functions by responsibility
+- **KISS**: prefer the simplest solution that meets requirements
+- **DRY**: remove duplicated logic or clearly justify it
+- **YAGNI**: no speculative features or "just in case" hooks
+- **Composition over inheritance**: avoid deep inheritance chains
+
+## State Management (Riverpod)
+
+- **ref.watch in build**: never use ref.read in build methods
+- **ref.read in callbacks**: never use ref.watch in callbacks
+- **No side effects in build**: never call controller methods in build
+- **Immutable state updates**: never mutate state in-place
+- **Family params must be stable**: implement == and hashCode
+
+## Testing Requirements
+
+- **Critical paths covered**: happy path + failure path + edge cases
+- **Concurrency tests**: required when shared state or ordering is involved
+- **No flaky tests**: reject non-deterministic tests
+- **Mock external dependencies**: no real network calls in tests
+
+## Logging & Observability
+
+- **No sensitive data in logs**: redact secrets and PII
+- **Log sparingly**: avoid noisy logs and repeated errors
+- **Actionable logs**: include enough context to debug without leaking data
+
+## Security Baseline
+
+- **Input validation** everywhere input crosses trust boundaries
+- **Least privilege** for services, DB access, and API scopes
+- **No unsafe defaults**: defaults must be secure, explicit opt-in for risky behavior
+
+## Architecture Boundaries
+
+- **Presentation → Domain → Data**: never skip layers
+- **No Flutter in domain**: domain layer must be framework-agnostic
+- **Repository interfaces in domain**: implementations in data layer
+- **No Riverpod in data/domain**: only in presentation layer
+
+## References
+
+- Google Engineering Practices – Code Review: https://google.github.io/eng-practices/review/reviewer/
+- Effective Dart: https://dart.dev/effective-dart

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-code-reviewer/references/testing_expectations.md

@@ -0,0 +1,21 @@
+# Testing expectations for reviews
+
+When a PR adds or modifies provider/controller logic, require tests:
+
+## Controllers (AsyncNotifier/Notifier)
+- Happy path returns expected state
+- Failure path maps to UI state (message/code)
+- refresh() re-runs build (invalidateSelf)
+- paging: loadMore merges immutably & stops when no more
+
+## Repositories
+- cache hit/miss behavior
+- TTL expiry (if implemented)
+- mapping errors into Failure types
+
+## Widgets
+- verifies loading/error/data renders
+- verifies actions call notifier methods (button taps)
+
+If tests are missing:
+- mark as MAJOR (or BLOCKER if change is risky: auth/session, payment, data deletion).