@heyai-rules/pilo-masterkit 1.2.2 → 2.2.0

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

@@ -0,0 +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/`

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

@@ -0,0 +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/`

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

@@ -0,0 +1,144 @@
+---
+description: Run Flutter/Dart tests, report failures, and incrementally fix test issues. Covers unit, widget, golden, and integration tests.
+---
+
+# Flutter Test
+
+This command runs the Flutter test suite and reports results. When failures occur, it diagnoses and fixes issues incrementally.
+
+## What This Command Does
+
+1. **Run Tests**: Execute `flutter test` (or scope to changed files)
+2. **Parse Failures**: Identify failing tests by type and cause
+3. **Fix Incrementally**: One failure at a time where possible
+4. **Verify**: Re-run after each fix
+5. **Report**: Show coverage summary and remaining failures
+
+## When to Use
+
+Use `/flutter-test` when:
+- After implementing a feature to verify nothing broke
+- After running `/flutter-build` to ensure tests pass
+- To check test coverage on new code
+- When a specific test file is failing
+- Before submitting a PR
+
+## Commands Run
+
+```bash
+# Run all tests
+flutter test 2>&1
+
+# Run with coverage
+flutter test --coverage 2>&1
+
+# Run specific test file
+flutter test test/unit/domain/usecases/get_user_test.dart 2>&1
+
+# Run tests matching a name pattern
+flutter test --name "CartBloc" 2>&1
+
+# Run integration tests (requires device/emulator)
+flutter test integration_test/ 2>&1
+
+# Update golden files when intentional visual changes are made
+flutter test --update-goldens 2>&1
+```
+
+## Example Session
+
+````text
+User: /flutter-test
+
+Agent:
+# Flutter Test Run
+
+## Test Execution
+
+```
+$ flutter test
+00:05 +42 -2: Some tests failed.
+
+FAILED: test/unit/data/user_repository_test.dart
+  UserRepository getById
+    returns null when user not found
+    Expected: null
+    Actual: User(id: 'test-id', name: 'Test User')
+
+FAILED: test/widget/cart_page_test.dart
+  CartPage
+    shows empty state when cart is empty
+    Expected: exactly one widget with text 'Your cart is empty'
+    Found: no widget with text 'Your cart is empty'
+```
+
+## Fix 1: Repository Test
+
+File: test/unit/data/user_repository_test.dart
+Failure: `getById` returns a user when it should return null for missing ID
+
+Root cause: Test setup adds a user with ID 'test-id' but queries with 'missing-id'.
+Fix: Updated test to query with 'missing-id' — setup was correct, query was wrong.
+
+```
+$ flutter test test/unit/data/user_repository_test.dart
+1 test passed.
+```
+
+## Fix 2: Widget Test
+
+File: test/widget/cart_page_test.dart
+Failure: Empty state text widget not found
+
+Root cause: Empty state message was renamed from 'Your cart is empty' to 'Cart is empty' in the widget.
+Fix: Updated test string to match current widget copy.
+
+```
+$ flutter test test/widget/cart_page_test.dart
+1 test passed.
+```
+
+## Final Run
+
+```
+$ flutter test --coverage
+All 44 tests passed.
+Coverage: 84.2% (target: 80%)
+```
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total tests | 44 |
+| Passed | 44 |
+| Failed | 0 |
+| Coverage | 84.2% |
+
+Test Status: PASS ✓
+````
+
+## Common Test Failures
+
+| Failure | Typical Fix |
+|---------|-------------|
+| `Expected: <X> Actual: <Y>` | Update assertion or fix implementation |
+| `Widget not found` | Fix finder selector or update test after widget rename |
+| `Golden file not found` | Run `flutter test --update-goldens` to generate |
+| `Golden mismatch` | Inspect diff; run `--update-goldens` if change was intentional |
+| `MissingPluginException` | Mock platform channel in test setup |
+| `LateInitializationError` | Initialize `late` fields in `setUp()` |
+| `pumpAndSettle timed out` | Replace with explicit `pump(Duration)` calls |
+
+## Related Commands
+
+- `/flutter-build` — Fix build errors before running tests
+- `/flutter-review` — Review code after tests pass
+- `/tdd` — Test-driven development workflow
+
+## Related
+
+- Agent: `agents/flutter-reviewer.md`
+- Agent: `agents/dart-build-resolver.md`
+- Skill: `skills/flutter-dart-code-review/`
+- Rules: `rules/dart/testing.md`

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

@@ -0,0 +1,99 @@
+Parse the following from $ARGUMENTS:
+1. `brief` — the user's one-line description of what to build
+2. `--max-iterations N` — (optional, default 15) maximum generator-evaluator cycles
+3. `--pass-threshold N` — (optional, default 7.0) weighted score to pass
+4. `--skip-planner` — (optional) skip planner, assume spec.md already exists
+5. `--eval-mode MODE` — (optional, default "playwright") one of: playwright, screenshot, code-only
+
+## GAN-Style Harness Build
+
+This command orchestrates a three-agent build loop inspired by Anthropic's March 2026 harness design paper.
+
+### Phase 0: Setup
+1. Create `gan-harness/` directory in project root
+2. Create subdirectories: `gan-harness/feedback/`, `gan-harness/screenshots/`
+3. Initialize git if not already initialized
+4. Log start time and configuration
+
+### Phase 1: Planning (Planner Agent)
+Unless `--skip-planner` is set:
+1. Launch the `gan-planner` agent via Task tool with the user's brief
+2. Wait for it to produce `gan-harness/spec.md` and `gan-harness/eval-rubric.md`
+3. Display the spec summary to the user
+4. Proceed to Phase 2
+
+### Phase 2: Generator-Evaluator Loop
+```
+iteration = 1
+while iteration <= max_iterations:
+
+    # GENERATE
+    Launch gan-generator agent via Task tool:
+    - Read spec.md
+    - If iteration > 1: read feedback/feedback-{iteration-1}.md
+    - Build/improve the application
+    - Ensure dev server is running
+    - Commit changes
+
+    # Wait for generator to finish
+
+    # EVALUATE
+    Launch gan-evaluator agent via Task tool:
+    - Read eval-rubric.md and spec.md
+    - Test the live application (mode: playwright/screenshot/code-only)
+    - Score against rubric
+    - Write feedback to feedback/feedback-{iteration}.md
+
+    # Wait for evaluator to finish
+
+    # CHECK SCORE
+    Read feedback/feedback-{iteration}.md
+    Extract weighted total score
+
+    if score >= pass_threshold:
+        Log "PASSED at iteration {iteration} with score {score}"
+        Break
+
+    if iteration >= 3 and score has not improved in last 2 iterations:
+        Log "PLATEAU detected — stopping early"
+        Break
+
+    iteration += 1
+```
+
+### Phase 3: Summary
+1. Read all feedback files
+2. Display final scores and iteration history
+3. Show score progression: `iteration 1: 4.2 → iteration 2: 5.8 → ... → iteration N: 7.5`
+4. List any remaining issues from the final evaluation
+5. Report total time and estimated cost
+
+### Output
+
+```markdown
+## GAN Harness Build Report
+
+**Brief:** [original prompt]
+**Result:** PASS/FAIL
+**Iterations:** N / max
+**Final Score:** X.X / 10
+
+### Score Progression
+| Iter | Design | Originality | Craft | Functionality | Total |
+|------|--------|-------------|-------|---------------|-------|
+| 1 | ... | ... | ... | ... | X.X |
+| 2 | ... | ... | ... | ... | X.X |
+| N | ... | ... | ... | ... | X.X |
+
+### Remaining Issues
+- [Any issues from final evaluation]
+
+### Files Created
+- gan-harness/spec.md
+- gan-harness/eval-rubric.md
+- gan-harness/feedback/feedback-001.md through feedback-NNN.md
+- gan-harness/generator-state.md
+- gan-harness/build-report.md
+```
+
+Write the full report to `gan-harness/build-report.md`.

package/.agent/workflows/gan-design.md

@@ -0,0 +1,35 @@
+Parse the following from $ARGUMENTS:
+1. `brief` — the user's description of the design to create
+2. `--max-iterations N` — (optional, default 10) maximum design-evaluate cycles
+3. `--pass-threshold N` — (optional, default 7.5) weighted score to pass (higher default for design)
+
+## GAN-Style Design Harness
+
+A two-agent loop (Generator + Evaluator) focused on frontend design quality. No planner — the brief IS the spec.
+
+This is the same mode Anthropic used for their frontend design experiments, where they saw creative breakthroughs like the 3D Dutch art museum with CSS perspective and doorway navigation.
+
+### Setup
+1. Create `gan-harness/` directory
+2. Write the brief directly as `gan-harness/spec.md`
+3. Write a design-focused `gan-harness/eval-rubric.md` with extra weight on Design Quality and Originality
+
+### Design-Specific Eval Rubric
+```markdown
+### Design Quality (weight: 0.35)
+### Originality (weight: 0.30)
+### Craft (weight: 0.25)
+### Functionality (weight: 0.10)
+```
+
+Note: Originality weight is higher (0.30 vs 0.20) to push for creative breakthroughs. Functionality weight is lower since design mode focuses on visual quality.
+
+### Loop
+Same as `/project:gan-build` Phase 2, but:
+- Skip the planner
+- Use the design-focused rubric
+- Generator prompt emphasizes visual quality over feature completeness
+- Evaluator prompt emphasizes "would this win a design award?" over "do all features work?"
+
+### Key Difference from gan-build
+The Generator is told: "Your PRIMARY goal is visual excellence. A stunning half-finished app beats a functional ugly one. Push for creative leaps — unusual layouts, custom animations, distinctive color work."

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

@@ -140,7 +140,7 @@ ok      project/internal/handler   0.023s
 | Files modified | 2 |
 | Remaining issues | 0 |
 
-Build Status: ✅ SUCCESS
+Build Status: PASS: SUCCESS
 ```
 
 ## Common Errors Fixed

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

@@ -124,16 +124,16 @@ return fmt.Errorf("get user %s: %w", userID, err)
 - HIGH: 1
 - MEDIUM: 0
 
-Recommendation: ❌ Block merge until CRITICAL issue is fixed
+Recommendation: FAIL: Block merge until CRITICAL issue is fixed
 ```
 
 ## Approval Criteria
 
 | Status | Condition |
 |--------|-----------|
-| ✅ Approve | No CRITICAL or HIGH issues |
-| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
-| ❌ Block | CRITICAL or HIGH issues found |
+| PASS: Approve | No CRITICAL or HIGH issues |
+| WARNING: Warning | Only MEDIUM issues (merge with caution) |
+| FAIL: Block | CRITICAL or HIGH issues found |
 
 ## Integration with Other Commands
 

package/.agent/workflows/harness-audit.md

@@ -4,22 +4,23 @@ Run a deterministic repository harness audit and return a prioritized scorecard.
 
 ## Usage
 
-`/harness-audit [scope] [--format text|json]`
+`/harness-audit [scope] [--format text|json] [--root path]`
 
 - `scope` (optional): `repo` (default), `hooks`, `skills`, `commands`, `agents`
 - `--format`: output style (`text` default, `json` for automation)
+- `--root`: audit a specific path instead of the current working directory
 
 ## Deterministic Engine
 
 Always run:
 
 ```bash
-node scripts/harness-audit.js <scope> --format <text|json>
+node scripts/harness-audit.js <scope> --format <text|json> [--root <path>]
 ```
 
 This script is the source of truth for scoring and checks. Do not invent additional dimensions or ad-hoc points.
 
-Rubric version: `2026-03-16`.
+Rubric version: `2026-03-30`.
 
 The script computes 7 fixed categories (`0-10` normalized each):
 
@@ -32,6 +33,7 @@ The script computes 7 fixed categories (`0-10` normalized each):
 7. Cost Efficiency
 
 Scores are derived from explicit file/rule checks and are reproducible for the same commit.
+The script audits the current working directory by default and auto-detects whether the target is the ECC repo itself or a consumer project using ECC.
 
 ## Output Contract