@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/flutter-code-reviewer/POWER.md

@@ -0,0 +1,185 @@
+---
+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: `steering/testing_expectations.md`
+
+---
+
+## Steering Files
+
+| File                       | Load When                              |
+| -------------------------- | -------------------------------------- |
+| `review_checklist.md`      | Starting a review, categories          |
+| `testing_expectations.md`  | Checking test requirements             |
+| `common-issues.md`         | N+1 queries, magic numbers, patterns   |
+| `feedback-examples.md`     | Writing good feedback                  |
+| `strict-rules.md`          | Enforcing strict review standards      |
+
+## Templates
+
+- `review_response.md` - Code review response template

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

@@ -0,0 +1,185 @@
+---
+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: `steering/testing_expectations.md`
+
+---
+
+## Steering Files
+
+| File                       | Load When                              |
+| -------------------------- | -------------------------------------- |
+| `review_checklist.md`      | Starting a review, categories          |
+| `testing_expectations.md`  | Checking test requirements             |
+| `common-issues.md`         | N+1 queries, magic numbers, patterns   |
+| `feedback-examples.md`     | Writing good feedback                  |
+| `strict-rules.md`          | Enforcing strict review standards      |
+
+## Templates
+
+- `review_response.md` - Code review response template

package/workflows/workflows/agent-environment-setup/platforms/copilot/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/copilot/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       |