@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/workflows/flutter-build.md

@@ -1,164 +1,164 @@
----
-description: Fix Dart analyzer errors and Flutter build failures incrementally. Invokes the dart-build-resolver agent for minimal, surgical fixes.
----
-
-# Flutter Build and Fix
-
-This command invokes the **dart-build-resolver** agent to incrementally fix Dart/Flutter build errors with minimal changes.
-
-## What This Command Does
-
-1. **Run Diagnostics**: Execute `flutter analyze`, `flutter pub get`
-2. **Parse Errors**: Group by file and sort by severity
-3. **Fix Incrementally**: One error at a time
-4. **Verify Each Fix**: Re-run analysis after each change
-5. **Report Summary**: Show what was fixed and what remains
-
-## When to Use
-
-Use `/flutter-build` when:
-- `flutter analyze` reports errors
-- `flutter build` fails for any platform
-- `dart pub get` / `flutter pub get` fails with version conflicts
-- `build_runner` fails to generate code
-- After pulling changes that break the build
-
-## Diagnostic Commands Run
-
-```bash
-# Analysis
-flutter analyze 2>&1
-
-# Dependencies
-flutter pub get 2>&1
-
-# Code generation (if project uses build_runner)
-dart run build_runner build --delete-conflicting-outputs 2>&1
-
-# Platform builds
-flutter build apk 2>&1
-flutter build web 2>&1
-```
-
-## Example Session
-
-````text
-User: /flutter-build
-
-Agent:
-# Flutter Build Resolution
-
-## Initial Diagnostics
-
-```
-$ flutter analyze
-Analyzing project...
-
-  error • lib/features/user/data/user_repository_impl.dart:34:16 •
-    A value of type 'String?' can't be assigned to a variable of type 'String'. •
-    invalid_assignment
-
-  error • lib/features/cart/presentation/cart_page.dart:58:5 •
-    The method 'add' isn't defined for the type 'List<Item>'.
-    Try correcting the name to the name of an existing method, or defining a method named 'add'. •
-    undefined_method
-
-2 errors found.
-```
-
-## Fix 1: Null Safety
-
-File: lib/features/user/data/user_repository_impl.dart:34
-Error: A value of type 'String?' can't be assigned to type 'String'
-
-Changed:
-```dart
-final id = response.id;
-```
-To:
-```dart
-final id = response.id ?? '';
-```
-
-```
-$ flutter analyze
-1 error found.
-```
-
-## Fix 2: Immutable List
-
-File: lib/features/cart/presentation/cart_page.dart:58
-Error: The method 'add' isn't defined for the type 'List<Item>'
-Cause: State holds an unmodifiable list; mutation goes through Cubit
-
-Changed:
-```dart
-state.items.add(item);
-```
-To:
-```dart
-context.read<CartCubit>().addItem(item);
-// Note: Cubit exposes named methods (addItem, removeItem);
-// .add(event) is the BLoC event API — don't mix them.
-```
-
-```
-$ flutter analyze
-No issues found!
-```
-
-## Final Verification
-
-```
-$ flutter test
-All tests passed.
-```
-
-## Summary
-
-| Metric | Count |
-|--------|-------|
-| Analysis errors fixed | 2 |
-| Files modified | 2 |
-| Remaining issues | 0 |
-
-Build Status: PASS ✓
-````
-
-## Common Errors Fixed
-
-| Error | Typical Fix |
-|-------|-------------|
-| `A value of type 'X?' can't be assigned to 'X'` | Add `?? default` or null guard |
-| `The name 'X' isn't defined` | Add import or fix typo |
-| `Non-nullable instance field must be initialized` | Add initializer or `late` |
-| `Version solving failed` | Adjust version constraints in pubspec.yaml |
-| `Missing concrete implementation of 'X'` | Implement missing interface method |
-| `build_runner: Part of X expected` | Delete stale `.g.dart` and rebuild |
-
-## Fix Strategy
-
-1. **Analysis errors first** — code must be error-free
-2. **Warning triage second** — fix warnings that could cause runtime bugs
-3. **pub conflicts third** — fix dependency resolution
-4. **One fix at a time** — verify each change
-5. **Minimal changes** — don't refactor, just fix
-
-## Stop Conditions
-
-The agent will stop and report if:
-- Same error persists after 3 attempts
-- Fix introduces more errors
-- Requires architectural changes
-- Package upgrade conflicts need user decision
-
-## Related Commands
-
-- `/flutter-test` — Run tests after build succeeds
-- `/flutter-review` — Review code quality
-- `/verify` — Full verification loop
-
-## Related
-
-- Agent: `agents/dart-build-resolver.md`
-- Skill: `skills/flutter-dart-code-review/`
+---
+description: Fix Dart analyzer errors and Flutter build failures incrementally. Invokes the dart-build-resolver agent for minimal, surgical fixes.
+---
+
+# Flutter Build and Fix
+
+This command invokes the **dart-build-resolver** agent to incrementally fix Dart/Flutter build errors with minimal changes.
+
+## What This Command Does
+
+1. **Run Diagnostics**: Execute `flutter analyze`, `flutter pub get`
+2. **Parse Errors**: Group by file and sort by severity
+3. **Fix Incrementally**: One error at a time
+4. **Verify Each Fix**: Re-run analysis after each change
+5. **Report Summary**: Show what was fixed and what remains
+
+## When to Use
+
+Use `/flutter-build` when:
+- `flutter analyze` reports errors
+- `flutter build` fails for any platform
+- `dart pub get` / `flutter pub get` fails with version conflicts
+- `build_runner` fails to generate code
+- After pulling changes that break the build
+
+## Diagnostic Commands Run
+
+```bash
+# Analysis
+flutter analyze 2>&1
+
+# Dependencies
+flutter pub get 2>&1
+
+# Code generation (if project uses build_runner)
+dart run build_runner build --delete-conflicting-outputs 2>&1
+
+# Platform builds
+flutter build apk 2>&1
+flutter build web 2>&1
+```
+
+## Example Session
+
+````text
+User: /flutter-build
+
+Agent:
+# Flutter Build Resolution
+
+## Initial Diagnostics
+
+```
+$ flutter analyze
+Analyzing project...
+
+  error • lib/features/user/data/user_repository_impl.dart:34:16 •
+    A value of type 'String?' can't be assigned to a variable of type 'String'. •
+    invalid_assignment
+
+  error • lib/features/cart/presentation/cart_page.dart:58:5 •
+    The method 'add' isn't defined for the type 'List<Item>'.
+    Try correcting the name to the name of an existing method, or defining a method named 'add'. •
+    undefined_method
+
+2 errors found.
+```
+
+## Fix 1: Null Safety
+
+File: lib/features/user/data/user_repository_impl.dart:34
+Error: A value of type 'String?' can't be assigned to type 'String'
+
+Changed:
+```dart
+final id = response.id;
+```
+To:
+```dart
+final id = response.id ?? '';
+```
+
+```
+$ flutter analyze
+1 error found.
+```
+
+## Fix 2: Immutable List
+
+File: lib/features/cart/presentation/cart_page.dart:58
+Error: The method 'add' isn't defined for the type 'List<Item>'
+Cause: State holds an unmodifiable list; mutation goes through Cubit
+
+Changed:
+```dart
+state.items.add(item);
+```
+To:
+```dart
+context.read<CartCubit>().addItem(item);
+// Note: Cubit exposes named methods (addItem, removeItem);
+// .add(event) is the BLoC event API — don't mix them.
+```
+
+```
+$ flutter analyze
+No issues found!
+```
+
+## Final Verification
+
+```
+$ flutter test
+All tests passed.
+```
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Analysis errors fixed | 2 |
+| Files modified | 2 |
+| Remaining issues | 0 |
+
+Build Status: PASS ✓
+````
+
+## Common Errors Fixed
+
+| Error | Typical Fix |
+|-------|-------------|
+| `A value of type 'X?' can't be assigned to 'X'` | Add `?? default` or null guard |
+| `The name 'X' isn't defined` | Add import or fix typo |
+| `Non-nullable instance field must be initialized` | Add initializer or `late` |
+| `Version solving failed` | Adjust version constraints in pubspec.yaml |
+| `Missing concrete implementation of 'X'` | Implement missing interface method |
+| `build_runner: Part of X expected` | Delete stale `.g.dart` and rebuild |
+
+## Fix Strategy
+
+1. **Analysis errors first** — code must be error-free
+2. **Warning triage second** — fix warnings that could cause runtime bugs
+3. **pub conflicts third** — fix dependency resolution
+4. **One fix at a time** — verify each change
+5. **Minimal changes** — don't refactor, just fix
+
+## Stop Conditions
+
+The agent will stop and report if:
+- Same error persists after 3 attempts
+- Fix introduces more errors
+- Requires architectural changes
+- Package upgrade conflicts need user decision
+
+## Related Commands
+
+- `/flutter-test` — Run tests after build succeeds
+- `/flutter-review` — Review code quality
+- `/verify` — Full verification loop
+
+## Related
+
+- Agent: `agents/dart-build-resolver.md`
+- Skill: `skills/flutter-dart-code-review/`

package/.agent/workflows/flutter-review.md

@@ -1,116 +1,116 @@
----
-description: Review Flutter/Dart code for idiomatic patterns, widget best practices, state management, performance, accessibility, and security. Invokes the flutter-reviewer agent.
----
-
-# Flutter Code Review
-
-This command invokes the **flutter-reviewer** agent to review Flutter/Dart code changes.
-
-## What This Command Does
-
-1. **Gather Context**: Review `git diff --staged` and `git diff`
-2. **Inspect Project**: Check `pubspec.yaml`, `analysis_options.yaml`, state management solution
-3. **Security Pre-scan**: Check for hardcoded secrets and critical security issues
-4. **Full Review**: Apply the complete review checklist
-5. **Report Findings**: Output issues grouped by severity with fix guidance
-
-## Prerequisites
-
-Before running `/flutter-review`, ensure:
-1. **Build passes** — run `/flutter-build` first; a review on broken code is incomplete
-2. **Tests pass** — run `/flutter-test` to confirm no regressions
-3. **No merge conflicts** — resolve all conflicts so the diff reflects only intentional changes
-4. **`flutter analyze` is clean** — fix analyzer warnings before review
-
-## When to Use
-
-Use `/flutter-review` when:
-- Before submitting a PR with Flutter/Dart changes (after build and tests pass)
-- After implementing a new feature to catch issues early
-- When reviewing someone else's Flutter code
-- To audit a widget, state management component, or service class
-- Before a production release
-
-## Review Areas
-
-| Area | Severity |
-|------|----------|
-| Hardcoded secrets, cleartext HTTP | CRITICAL |
-| Architecture violations, state management anti-patterns | CRITICAL |
-| Widget rebuild issues, resource leaks | HIGH |
-| Missing `dispose()`, `BuildContext` after await | HIGH |
-| Dart null safety, missing error/loading states | HIGH |
-| Const propagation, widget composition | HIGH |
-| Performance: expensive work in `build()` | HIGH |
-| Accessibility, semantic labels | MEDIUM |
-| Missing tests for state transitions | HIGH |
-| Hardcoded strings (l10n) | MEDIUM |
-| Pub dependency hygiene | LOW |
-
-## Example Session
-
-````text
-User: /flutter-review
-
-Agent:
-# Flutter Code Review
-
-## Context
-
-Changed files:
-- lib/features/auth/presentation/login_page.dart
-- lib/features/auth/data/auth_repository_impl.dart
-
-State management: Riverpod (detected from pubspec.yaml)
-Architecture: feature-first
-
-## Security Pre-scan
-
-✓ No hardcoded secrets detected
-✓ No cleartext HTTP calls
-
-## Review Findings
-
-[HIGH] BuildContext used after async gap without mounted check
-File: lib/features/auth/presentation/login_page.dart:67
-Issue: `context.go('/home')` called after `await auth.login(...)` with no `mounted` check.
-Fix: Add `if (!context.mounted) return;` before any navigation after awaits (Flutter 3.7+).
-
-[HIGH] AsyncValue error state not handled
-File: lib/features/auth/presentation/login_page.dart:42
-Issue: `ref.watch(authProvider)` switches on loading/data but has no `error` branch.
-Fix: Add error case to the switch expression or `when()` call to show a user-facing error message.
-
-[MEDIUM] Hardcoded string not localized
-File: lib/features/auth/presentation/login_page.dart:89
-Issue: `Text('Login')` — user-visible string not using localization system.
-Fix: Use the project's l10n accessor: `Text(context.l10n.loginButton)`.
-
-## Review Summary
-
-| Severity | Count | Status |
-|----------|-------|--------|
-| CRITICAL | 0     | pass   |
-| HIGH     | 2     | block  |
-| MEDIUM   | 1     | info   |
-| LOW      | 0     | note   |
-
-Verdict: BLOCK — HIGH issues must be fixed before merge.
-````
-
-## Approval Criteria
-
-- **Approve**: No CRITICAL or HIGH issues
-- **Block**: Any CRITICAL or HIGH issues must be fixed before merge
-
-## Related Commands
-
-- `/flutter-build` — Fix build errors first
-- `/flutter-test` — Run tests before reviewing
-- `/code-review` — General code review (language-agnostic)
-
-## Related
-
-- Agent: `agents/flutter-reviewer.md`
-- Skill: `skills/flutter-dart-code-review/`
-- Rules: `rules/dart/`
+---
+description: Review Flutter/Dart code for idiomatic patterns, widget best practices, state management, performance, accessibility, and security. Invokes the flutter-reviewer agent.
+---
+
+# Flutter Code Review
+
+This command invokes the **flutter-reviewer** agent to review Flutter/Dart code changes.
+
+## What This Command Does
+
+1. **Gather Context**: Review `git diff --staged` and `git diff`
+2. **Inspect Project**: Check `pubspec.yaml`, `analysis_options.yaml`, state management solution
+3. **Security Pre-scan**: Check for hardcoded secrets and critical security issues
+4. **Full Review**: Apply the complete review checklist
+5. **Report Findings**: Output issues grouped by severity with fix guidance
+
+## Prerequisites
+
+Before running `/flutter-review`, ensure:
+1. **Build passes** — run `/flutter-build` first; a review on broken code is incomplete
+2. **Tests pass** — run `/flutter-test` to confirm no regressions
+3. **No merge conflicts** — resolve all conflicts so the diff reflects only intentional changes
+4. **`flutter analyze` is clean** — fix analyzer warnings before review
+
+## When to Use
+
+Use `/flutter-review` when:
+- Before submitting a PR with Flutter/Dart changes (after build and tests pass)
+- After implementing a new feature to catch issues early
+- When reviewing someone else's Flutter code
+- To audit a widget, state management component, or service class
+- Before a production release
+
+## Review Areas
+
+| Area | Severity |
+|------|----------|
+| Hardcoded secrets, cleartext HTTP | CRITICAL |
+| Architecture violations, state management anti-patterns | CRITICAL |
+| Widget rebuild issues, resource leaks | HIGH |
+| Missing `dispose()`, `BuildContext` after await | HIGH |
+| Dart null safety, missing error/loading states | HIGH |
+| Const propagation, widget composition | HIGH |
+| Performance: expensive work in `build()` | HIGH |
+| Accessibility, semantic labels | MEDIUM |
+| Missing tests for state transitions | HIGH |
+| Hardcoded strings (l10n) | MEDIUM |
+| Pub dependency hygiene | LOW |
+
+## Example Session
+
+````text
+User: /flutter-review
+
+Agent:
+# Flutter Code Review
+
+## Context
+
+Changed files:
+- lib/features/auth/presentation/login_page.dart
+- lib/features/auth/data/auth_repository_impl.dart
+
+State management: Riverpod (detected from pubspec.yaml)
+Architecture: feature-first
+
+## Security Pre-scan
+
+✓ No hardcoded secrets detected
+✓ No cleartext HTTP calls
+
+## Review Findings
+
+[HIGH] BuildContext used after async gap without mounted check
+File: lib/features/auth/presentation/login_page.dart:67
+Issue: `context.go('/home')` called after `await auth.login(...)` with no `mounted` check.
+Fix: Add `if (!context.mounted) return;` before any navigation after awaits (Flutter 3.7+).
+
+[HIGH] AsyncValue error state not handled
+File: lib/features/auth/presentation/login_page.dart:42
+Issue: `ref.watch(authProvider)` switches on loading/data but has no `error` branch.
+Fix: Add error case to the switch expression or `when()` call to show a user-facing error message.
+
+[MEDIUM] Hardcoded string not localized
+File: lib/features/auth/presentation/login_page.dart:89
+Issue: `Text('Login')` — user-visible string not using localization system.
+Fix: Use the project's l10n accessor: `Text(context.l10n.loginButton)`.
+
+## Review Summary
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| CRITICAL | 0     | pass   |
+| HIGH     | 2     | block  |
+| MEDIUM   | 1     | info   |
+| LOW      | 0     | note   |
+
+Verdict: BLOCK — HIGH issues must be fixed before merge.
+````
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Block**: Any CRITICAL or HIGH issues must be fixed before merge
+
+## Related Commands
+
+- `/flutter-build` — Fix build errors first
+- `/flutter-test` — Run tests before reviewing
+- `/code-review` — General code review (language-agnostic)
+
+## Related
+
+- Agent: `agents/flutter-reviewer.md`
+- Skill: `skills/flutter-dart-code-review/`
+- Rules: `rules/dart/`