agy-superpowers 5.0.7 → 5.0.9

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-matcher-best-practices.md

@@ -0,0 +1,106 @@
+---
+name: dart-matcher-best-practices
+description: |-
+  Best practices for using `expect` and `package:matcher`.
+  Focuses on readable assertions, proper matcher selection, and avoiding common pitfalls.
+license: Apache-2.0
+---
+
+# Dart Matcher Best Practices
+
+## When to use this skill
+Use this skill when:
+- Writing assertions using `expect` and `package:matcher`.
+- Migrating legacy manual checks to cleaner matchers.
+- Debugging confusing test failures.
+
+## Core Matchers
+
+### 1. Collections (`hasLength`, `contains`, `isEmpty`)
+
+- **`hasLength(n)`**:
+  - Prefer `expect(list, hasLength(n))` over `expect(list.length, n)`.
+  - Gives better error messages on failure (shows actual list content).
+
+- **`isEmpty` / `isNotEmpty`**:
+  - Prefer `expect(list, isEmpty)` over `expect(list.isEmpty, true)`.
+  - Prefer `expect(list, isNotEmpty)` over `expect(list.isNotEmpty, true)`.
+
+- **`contains(item)`**:
+  - Verify existence without manual iteration.
+
+- **`unorderedEquals(items)`**:
+  - Verify contents regardless of order.
+
+### 2. Type Checks (`isA<T>` and `TypeMatcher<T>`)
+
+- **`isA<T>()`**:
+  - Prefer for inline assertions: `expect(obj, isA<Type>())`.
+  - More concise and readable than `TypeMatcher<Type>()`.
+  - Allows chaining constraints using `.having()`.
+
+- **`TypeMatcher<T>`**:
+  - Prefer when defining top-level reusable matchers.
+  - **Use `const`**: `const isMyType = TypeMatcher<MyType>();`
+  - Chaining `.having()` works here too, but the resulting matcher is not `const`.
+
+### 3. Object Properties (`having`)
+
+Use `.having()` on `isA<T>()` or other TypeMatchers to check properties.
+
+- **Descriptive Names**: Use meaningful parameter names in the closure (e.g.,
+  `(e) => e.message`) instead of generic ones like `p0` to improve readability.
+
+```dart
+expect(person, isA<Person>()
+    .having((p) => p.name, 'name', 'Alice')
+    .having((p) => p.age, 'age', greaterThan(18)));
+```
+
+This provides detailed failure messages indicating exactly which property
+failed.
+
+### 4. Async Assertions
+
+- **`completion(matcher)`**:
+  - Wait for a future to complete and check its value.
+  - **Prefer `await expectLater(...)`** to ensure the future completes before
+    the test continues.
+  - `await expectLater(future, completion(equals(42)))`.
+
+- **`throwsA(matcher)`**:
+  - Check that a future or function throws an exception.
+  - `await expectLater(future, throwsA(isA<StateError>()))`.
+  - `expect(() => function(), throwsA(isA<ArgumentError>()))` (synchronous
+    function throwing is fine with `expect`).
+
+### 5. Using `expectLater`
+
+Use `await expectLater(...)` when testing async behavior to ensure proper
+sequencing.
+
+```dart
+// GOOD: Waits for future to complete before checking side effects
+await expectLater(future, completion(equals(42)));
+expect(sideEffectState, equals('done'));
+
+// BAD: Side effect check might run before future completes
+expect(future, completion(equals(42)));
+expect(sideEffectState, equals('done')); // Race condition!
+```
+
+## Principles
+
+1.  **Readable Failures**: Choose matchers that produce clear error messages.
+2.  **Avoid Manual Logic**: Don't use `if` statements or `for` loops for
+    assertions; let matchers handle it.
+3.  **Specific Matchers**: Use the most specific matcher available (e.g.,
+    `containsPair` for maps instead of checking keys manually).
+
+## Related Skills
+
+- **[`dart-test-fundamentals`](../dart-test-fundamentals/SKILL.md)**: Core
+  concepts for structuring tests, lifecycles, and configuration.
+- **[`dart-checks-migration`](../dart-checks-migration/SKILL.md)**: Use this
+  skill if you are migrating tests from `package:matcher` to modern
+  `package:checks`.

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-modern-features.md

@@ -0,0 +1,241 @@
+---
+name: dart-modern-features
+description: |-
+  Guidelines for using modern Dart features (v3.0 - v3.10) such as Records, 
+  Pattern Matching, Switch Expressions, Extension Types, Class Modifiers, 
+  Wildcards, Null-Aware Elements, and Dot Shorthands.
+---
+
+# Dart Modern Features
+
+## 1. When to use this skill
+Use this skill when:
+- Writing or reviewing Dart code targeting Dart 3.0 or later.
+- Refactoring legacy Dart code to use modern, concise, and safe features.
+- Looking for idiomatic ways to handle multiple return values, deep data
+  extraction, or exhaustive checking.
+
+## 2. Features
+
+### Records
+Use records as anonymous, immutable, aggregate structures to bundle multiple
+objects without defining a custom class. Prefer them for returning multiple
+values from a function or grouping related data temporarily.
+
+**Avoid:**
+Creating a dedicated class for simple multiple-value returns.
+```dart
+class UserResult {
+  final String name;
+  final int age;
+  UserResult(this.name, this.age);
+}
+
+UserResult fetchUser() {
+  return UserResult('Alice', 42);
+}
+```
+
+**Prefer:**
+Using records to bundle types seamlessly on the fly.
+```dart
+(String, int) fetchUser() {
+  return ('Alice', 42);
+}
+
+void main() {
+  var user = fetchUser();
+  print(user.$1); // Alice
+}
+```
+
+### Patterns and Pattern Matching
+Use patterns to destructure complex data into local variables and match against
+specific shapes or values. Use them in `switch`, `if-case`, or variable
+declarations to unpack data directly.
+
+**Avoid:**
+Manually checking types, nulls, and keys for data extraction.
+```dart
+void processJson(Map<String, dynamic> json) {
+  if (json.containsKey('name') && json['name'] is String &&
+      json.containsKey('age') && json['age'] is int) {
+    String name = json['name'];
+    int age = json['age'];
+    print('$name is $age years old.');
+  }
+}
+```
+
+**Prefer:**
+Combining type-checking, validation, and assignment into a single statement.
+```dart
+void processJson(Map<String, dynamic> json) {
+  if (json case {'name': String name, 'age': int age}) {
+    print('$name is $age years old.');
+  }
+}
+```
+
+### Switch Expressions
+Use switch expressions to return a value directly, eliminating bulky `case` and
+`break` statements.
+
+**Avoid:**
+Using switch statements where every branch simply returns or assigns a value.
+```dart
+String describeStatus(int code) {
+  switch (code) {
+    case 200:
+      return 'Success';
+    case 404:
+      return 'Not Found';
+    default:
+      return 'Unknown';
+  }
+}
+```
+
+**Prefer:**
+Returning the evaluated expression directly using the `=>` syntax.
+```dart
+String describeStatus(int code) => switch (code) {
+  200 => 'Success',
+  404 => 'Not Found',
+  _ => 'Unknown',
+};
+```
+
+### Class Modifiers
+Use class modifiers (`sealed`, `final`, `base`, `interface`) to restrict how
+classes can be used outside their defines library. Prefer `sealed` for defining
+closed families of subtypes to enable exhaustive checking.
+
+**Avoid:**
+Using open `abstract` classes when the set of subclasses is known and fixed.
+```dart
+abstract class Result {}
+
+class Success extends Result {}
+class Failure extends Result {}
+
+String handle(Result r) {
+  if (r is Success) return 'OK';
+  if (r is Failure) return 'Error';
+  return 'Unknown';
+}
+```
+
+**Prefer:**
+Using `sealed` to guarantee to the compiler that all cases are covered.
+```dart
+sealed class Result {}
+
+class Success extends Result {}
+class Failure extends Result {}
+
+String handle(Result r) => switch(r) {
+  Success() => 'OK',
+  Failure() => 'Error',
+};
+```
+
+### Extension Types
+Use extension types for a zero-cost wrapper around an existing type. Use them to
+restrict operations or add custom behavior without runtime overhead.
+
+**Avoid:**
+Allocating new wrapper objects just for domain-specific logic or type safety.
+```dart
+class Id {
+  final int value;
+  Id(this.value);
+  bool get isValid => value > 0;
+}
+```
+
+**Prefer:**
+Using extension types which compile down to the underlying type at runtime.
+```dart
+extension type Id(int value) {
+  bool get isValid => value > 0;
+}
+```
+
+### Digit Separators
+Use underscores (`_`) in number literals strictly to improve visual readability
+of large numeric values.
+
+**Avoid:**
+Long number literals that are difficult to read at a glance.
+```dart
+const int oneMillion = 1000000;
+```
+
+**Prefer:**
+Using underscores to separate thousands or other groupings.
+```dart
+const int oneMillion = 1_000_000;
+```
+
+### Wildcard Variables
+Use wildcards (`_`) as non-binding variables or parameters to explicitly signal
+that a value is intentionally unused.
+
+**Avoid:**
+Inventing clunky, distinct variable names to avoid "unused variable" warnings.
+```dart
+void handleEvent(String ignoredName, int status) {
+  print('Status: $status');
+}
+```
+
+**Prefer:**
+Explicitly dropping the binding with an underscore.
+```dart
+void handleEvent(String _, int status) {
+  print('Status: $status');
+}
+```
+
+### Null-Aware Elements
+Use null-aware elements (`?`) inside collection literals to conditionally
+include items only if they evaluate to a non-null value.
+
+**Avoid:**
+Using collection `if` statements for simple null checks.
+```dart
+var names = [
+  'Alice',
+  if (optionalName != null) optionalName,
+  'Charlie'
+];
+```
+
+**Prefer:**
+Using the `?` prefix inline.
+```dart
+var names = ['Alice', ?optionalName, 'Charlie'];
+```
+
+### Dot Shorthands
+Use dot shorthands to omit the explicit type name when it can be confidently
+inferred from context, such as with enums or static fields.
+
+**Avoid:**
+Fully qualifying type names when the type is obvious from the context.
+```dart
+LogLevel currentLevel = LogLevel.info;
+```
+
+**Prefer:**
+Reducing visual noise with inferred shorthand.
+```dart
+LogLevel currentLevel = .info;
+```
+
+## Related Skills
+
+- **[`dart-best-practices`](../dart-best-practices/SKILL.md)**: General code
+  style and foundational Dart idioms that predate or complement the modern
+  syntax features.

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-package-maintenance.md

@@ -0,0 +1,75 @@
+---
+name: dart-package-maintenance
+description: |-
+  Guidelines for maintaining external Dart packages, covering versioning,
+  publishing workflows, and pull request management. Use when updating Dart
+  packages, preparing for a release, or managing collaborative changes in a
+  repository.
+---
+
+# Dart Package Maintenance
+
+Guidelines for maintaining Dart packages in alignment with Dart team best
+practices.
+
+## Versioning
+
+### Semantic Versioning
+- **Major**: Breaking changes.
+- **Minor**: New features (non-breaking API changes).
+- **Patch**: Bug fixes, documentation, or non-impacting changes.
+- **Unstable packages**: Use `0.major.minor+patch`.
+- **Recommendation**: Aim for `1.0.0` as soon as the package is stable.
+
+### Pre-Edit Verification
+- **Check Published Versions**: Before modifying `CHANGELOG.md` or
+  `pubspec.yaml`, ALWAYS check the currently released version (e.g., via
+  `git tag` or `pub.dev`).
+- **Do Not Amend Released Versions**: Never add new entries to a version header
+  that corresponds to a released tag.
+- **Increment for New Changes**: If the current version in `pubspec.yaml`
+  matches a released tag, increment the version (e.g., usually to `-wip`) and
+  create a new section in `CHANGELOG.md`.
+
+  - **Consistency**: The `CHANGELOG.md` header must match the new
+    `pubspec.yaml` version.
+
+  - **SemVer Guidelines**:
+    - **Breaking Changes**: Bump Major, reset Minor/Patch
+      (e.g., `2.0.0-wip`, `0.5.0-wip`).
+    - **New Features**: Bump Minor, reset Patch
+      (e.g., `1.1.0-wip`, `0.4.5-wip`).
+    - **Bug Fixes**: Bump Patch (e.g., `1.0.1-wip`).
+
+### Work-in-Progress (WIP) Versions
+- Immediately after a publish, or on the first change after a publish, update
+  `pubspec.yaml` and `CHANGELOG.md` with a `-wip` suffix (e.g., `1.1.0-wip`).
+- This indicates the current state is not yet published.
+
+### Breaking Changes
+- Evaluate the impact on dependent packages and internal projects.
+- Consider running changes through internal presubmits if possible.
+- Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize
+  downstream breakage.
+
+## Publishing Process
+
+1. **Preparation**: Remove the `-wip` suffix from `pubspec.yaml` and
+   `CHANGELOG.md` in a dedicated pull request.
+2. **Execution**: Run `dart pub publish` (or `flutter pub publish`) and resolve
+   all warnings and errors.
+3. **Tagging**: Create and push a git tag for the published version:
+   - For single-package repos: `v1.2.3`
+   - For monorepos: `package_name-v1.2.3`
+   - Example: `git tag v1.2.3 && git push --tags`
+
+## Pull Request Management
+
+- **Commits**: Each PR should generally correspond to a single squashed commit
+  upon merging.
+- **Shared History**: Once a PR is open, avoid force pushing to the branch.
+- **Conflict Resolution**: Prefer merging `main` into the PR branch rather than
+  rebasing to resolve conflicts. This preserves the review history and comments.
+- **Reviewing**: Add comments from the "Files changed" view to batch them.
+- **Local Inspection**: Use `gh pr checkout <number>` to inspect changes
+  locally in your IDE.

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-test-fundamentals.md

@@ -0,0 +1,124 @@
+---
+name: dart-test-fundamentals
+description: |-
+  Core concepts and best practices for `package:test`.
+  Covers `test`, `group`, lifecycle methods (`setUp`, `tearDown`), and configuration (`dart_test.yaml`).
+license: Apache-2.0
+---
+
+# Dart Test Fundamentals
+
+## When to use this skill
+Use this skill when:
+- Writing new test files.
+- structuring test suites with `group`.
+- Configuring test execution via `dart_test.yaml`.
+- Understanding test lifecycle methods.
+
+## Core Concepts
+
+### 1. Test Structure (`test` and `group`)
+
+- **`test`**: The fundamental unit of testing.
+  ```dart
+  test('description', () {
+    // assertions
+  });
+  ```
+- **`group`**: Used to organize tests into logical blocks.
+  - Groups can be nested.
+  - Descriptions are concatenated (e.g., "Group Description Test Description").
+  - Helps scope `setUp` and `tearDown` calls.
+  - **Naming**: Use `PascalCase` for groups that correspond to a class name
+    (e.g., `group('MyClient', ...)`).
+  - **Avoid Single Groups**: Do not wrap all tests in a file with a single
+    `group` call if it's the only one.
+
+- **Naming Tests**:
+  - Avoid redundant "test" prefixes.
+  - Include the expected behavior or outcome in the description (e.g.,
+    `'throws StateError'` or `'adds API key to URL'`).
+  - Descriptions should read well when concatenated with their group name.
+
+- **Named Parameters Placement**:
+  - For `test` and `group` calls, place named parameters (e.g., `testOn`,
+    `timeout`, `skip`) immediately after the description string, before the
+    callback closure. This improves readability by keeping the test logic last.
+    ```dart
+    test('description', testOn: 'vm', () {
+      // assertions
+    });
+    ```
+
+### 2. Lifecycle Methods (`setUp`, `tearDown`)
+
+- **`setUp`**: Runs *before* every `test` in the current `group` (and nested
+  groups).
+- **`tearDown`**: Runs *after* every `test` in the current `group`.
+- **`setUpAll`**: Runs *once* before any test in the group.
+- **`tearDownAll`**: Runs *once* after all tests in the group.
+
+**Best Practice:**
+- Use `setUp` for resetting state to ensure test isolation.
+- Avoid sharing mutable state between tests without resetting it.
+
+### 3. Configuration (`dart_test.yaml`)
+
+The `dart_test.yaml` file configures the test runner. Common configurations
+include:
+
+#### Platforms
+Define where tests run (vm, chrome, node).
+
+```yaml
+platforms:
+  - vm
+  - chrome
+```
+
+#### Tags
+Categorize tests to run specific subsets.
+
+```yaml
+tags:
+  integration:
+    timeout: 2x
+```
+
+Usage in code:
+```dart
+@Tags(['integration'])
+import 'package:test/test.dart';
+```
+
+Running tags:
+`dart test --tags integration`
+
+#### Timeouts
+Set default timeouts for tests.
+
+```yaml
+timeouts:
+  2x # Double the default timeout
+```
+
+### 4. File Naming
+- Test files **must** end in `_test.dart` to be picked up by the test runner.
+- Place tests in the `test/` directory.
+
+## Common commands
+
+- `dart test`: Run all tests.
+- `dart test test/path/to/file_test.dart`: Run a specific file.
+- `dart test --name "substring"`: Run tests matching a description.
+
+## Related Skills
+
+`dart-test-fundamentals` is the core skill for structuring and configuring
+tests. For writing assertions within those tests, refer to:
+
+- **[`dart-matcher-best-practices`](../dart-matcher-best-practices/SKILL.md)**:
+  Use this if the project sticks with the traditional
+  `package:matcher` (`expect` calls).
+- **[`dart-checks-migration`](../dart-checks-migration/SKILL.md)**: Use this
+  if the project is migrating to the modern `package:checks` (`check` calls).