mindsystem-cc 3.3.3 → 3.6.0

package/skills/flutter-code-quality/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: flutter-code-quality
+description: Flutter/Dart code quality, widget organization, and folder structure guidelines. Use when reviewing, refactoring, or cleaning up Flutter code after implementation.
+license: MIT
+metadata:
+  author: forgeblast
+  version: "1.0.0"
+  date: January 2026
+  argument-hint: <file-or-pattern>
+---
+
+# Flutter Code Quality
+
+Comprehensive guidelines for Flutter/Dart code quality, widget organization, and folder structure. Combines pattern-level rules (anti-patterns, idioms) with structural guidance (build method organization, folder conventions).
+
+## How It Works
+
+1. Fetch flutter-code-quality-guidelines.md from the gist URL below (always fresh)
+2. Apply embedded widget organization and folder structure rules
+3. Check files against all guidelines
+4. Output findings in terse `file:line` format
+
+## Code Quality Guidelines (Remote)
+
+Fetch fresh guidelines before each review:
+
+```
+https://gist.githubusercontent.com/rolandtolnay/edf9ea7d5adf218f45accb3411f0627c/raw/flutter-code-quality-guidelines.md
+```
+
+Use WebFetch to retrieve. Contains: anti-patterns, widget patterns, state management, collections, hooks, theme/styling, etc.
+
+## Widget Organization Guidelines (Embedded)
+
+### Build Method Structure
+
+Order inside `build()`:
+1. Providers (reads/watches)
+2. Hooks (if using flutter_hooks)
+3. Derived variables needed for rendering
+4. Widget variables (in render order)
+
+### When to Use What
+
+| Scenario | Pattern |
+|----------|---------|
+| Widget always shown, no conditions | Local variable: `final header = Container(...);` |
+| Widget depends on condition/null check | Builder function: `Widget? _buildContent() { if (data == null) return null; ... }` |
+| Subtree is large, reusable, or has own state | Extract to standalone widget in own file |
+| Function needs 3 or fewer params | Define outside `build()` as class method |
+| Function needs 4+ params (esp. hooks) | Define inside `build()` to capture scope |
+
+### Rules
+
+- **No file-private widgets** - If big enough to be a widget, it gets its own file
+- **Define local variables in render order** - Top-to-bottom matches screen layout
+- **Extract non-trivial conditions** - `final canSubmit = isValid && !isLoading && selectedId != null;`
+- **Pass `WidgetRef` only** when function needs both ref and context - Use `ref.context` inside
+
+### Async UX Conventions
+
+- **Button loading** - Watch provider state, not separate `useState<bool>`
+- **Retriable errors** - Listen to provider, show toast on error, user retries by tapping again
+- **First-load errors** - Render error view with retry button that invalidates provider
+
+### Sorting/Filtering
+
+- Simple options: Use enum with computed properties
+- Options with behavior: Use sealed class
+- Complex multi-field filtering: Dedicated `Filter` class
+
+## Folder Structure Guidelines (Embedded)
+
+### Core Rules
+
+1. **Organize by feature** - Each feature gets its own folder
+2. **Screens at feature root** - `account_screen.dart`, `edit_account_screen.dart`
+3. **Create subfolders only when justified:**
+   - `widgets/` when 2+ reusable widgets exist
+   - `providers/` when 2+ provider files exist
+   - `domain/` usually always (models, repositories)
+4. **Split large features into subfeatures** - Each subfeature follows same rules
+
+### Example
+
+```
+lib/features/
+  account/
+    account_screen.dart
+    edit_account_screen.dart
+    widgets/
+      account_avatar.dart
+      account_form.dart
+    providers/
+      account_provider.dart
+    domain/
+      account.dart
+      account_repository.dart
+```
+
+## Application Priority
+
+When reviewing code, apply in this order:
+
+1. **Code Quality Patterns** (from fetched gist) - Anti-patterns, idioms, provider patterns
+2. **Widget Organization** (above) - Build structure, extraction rules, async UX
+3. **Folder Structure** (above) - File placement, feature boundaries
+
+## Anti-Patterns Quick Reference
+
+Flag these patterns (details in fetched guidelines):
+
+- `useState<bool>` for loading states
+- Manual try-catch in provider actions
+- `.toList()..sort()` instead of `.sorted()`
+- `_handleAction(ref, controller, user, state)` with 4+ params
+- Hardcoded hex colors
+- Deep `lib/features/x/presentation/` directories
+- Barrel files that only re-export
+- Boolean flags instead of sealed classes
+- Magic numbers scattered across widgets
+- `where((e) => e.status == Status.active)` instead of computed property
+- Generic provider names like `expansionVisibilityProvider`
+- `.asData?.value` instead of `.value`
+
+## Output Format
+
+Group by file. Use `file:line` format. Terse findings.
+
+```text
+## lib/home/home_screen.dart
+
+lib/home/home_screen.dart:42 - useState for loading state -> use provider
+lib/home/home_screen.dart:67 - .toList()..sort() -> .sorted()
+lib/home/home_screen.dart:89 - hardcoded Color(0xFF...) -> context.color.*
+
+## lib/models/user.dart
+
+pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.

package/skills/flutter-code-simplification/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: flutter-code-simplification
+description: Flutter/Dart code simplification principles. Use when simplifying, refactoring, or cleaning up Flutter code for clarity and maintainability.
+license: MIT
+metadata:
+  author: forgeblast
+  version: "1.0.0"
+  date: January 2026
+  argument-hint: <file-or-pattern>
+---
+
+# Flutter Code Simplification
+
+Principles and patterns for simplifying Flutter/Dart code. Simplification means making code easier to reason about — not making it shorter at the cost of clarity.
+
+## Core Philosophy
+
+**Clarity over brevity.** Explicit code is often better than compact code. The goal is code that's easy to read, understand, and maintain without changing what it does.
+
+## Principles
+
+### 1. Preserve Functionality
+
+Never change what the code does — only how it does it. All original features, outputs, and behaviors must remain intact.
+
+### 2. Enhance Clarity
+
+- Reduce unnecessary complexity and nesting
+- Eliminate redundant code and abstractions
+- Improve readability through clear naming
+- Consolidate related logic and duplicates (DRY)
+- Choose clarity over brevity — explicit code is often better than compact code
+
+### 3. Maintain Balance
+
+Avoid over-simplification that could:
+- Create overly clever solutions that are hard to understand
+- Combine too many concerns into single functions/components
+- Remove helpful abstractions that improve code organization
+- Prioritize "fewer lines" over readability
+- Make code harder to debug or extend
+
+### 4. Apply Judgment
+
+Use expertise to determine what improves the code. These principles guide decisions — they are not a checklist. If a change doesn't clearly improve clarity while preserving behavior, don't make it.
+
+## Flutter Patterns
+
+Common opportunities in Flutter/Dart code. Apply when they genuinely improve clarity.
+
+### State & Data
+
+| Pattern | Simplification |
+|---------|----------------|
+| Scattered boolean flags | Sealed class variants with switch expressions (when it consolidates and clarifies) |
+| Same parameters repeated across functions | Records or typed classes |
+| Manual try-catch in providers | `AsyncValue.guard()` with centralized error handling |
+| Async operations without mount check | Check `ref.mounted` after async operations |
+
+### Widget Structure
+
+| Pattern | Simplification |
+|---------|----------------|
+| Large `build()` methods | Extract into local variables or builder methods |
+| Widgets with many boolean parameters | Consider composition or typed mode objects |
+| Unordered build() | Keep order: providers → hooks → derived values → widget tree |
+
+### Collections
+
+| Pattern | Simplification |
+|---------|----------------|
+| Mutation patterns | Immutable methods (`.sorted()`, `.where()`, etc.) |
+| Null-unsafe access | `firstWhereOrNull` with fallbacks |
+| Repeated enum switches | Computed properties on the enum itself |
+
+### Code Organization
+
+| Pattern | Simplification |
+|---------|----------------|
+| Duplicated logic across files | Extract to shared location |
+| Related methods scattered in class | Group by concern |
+| Unnecessary indirection (factories creating one type, wrappers adding no behavior) | Use concrete types directly |
+
+**Exception:** API layer interfaces with implementation in same file are intentional — interface provides at-a-glance documentation.
+
+## Output Format
+
+Group by file. Use `file:line` format. Terse findings.
+
+```text
+## lib/home/home_screen.dart
+
+lib/home/home_screen.dart:42 - scattered booleans -> sealed class
+lib/home/home_screen.dart:67 - .toList()..sort() -> .sorted()
+lib/home/home_screen.dart:120 - large build() -> extract builder methods
+
+## lib/models/user.dart
+
+pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.