@bdayadev/flutter-ultra-mcp 1.12.0 → 1.13.0

package/skills/fix-runtime-errors/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fix-runtime-errors
 description: Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload.
+  last_modified: Fri, 24 Apr 2026 15:13:22 GMT
 ---
 
 # Resolving Dart Static Analysis Errors
@@ -8,7 +9,11 @@ description: Uses get_runtime_errors and lsp to fetch an active stack trace, loc
 ## Contents
 
 - [Core Concepts & Guidelines](#core-concepts--guidelines)
+  - [Type System & Soundness](#type-system--soundness)
+  - [Null Safety](#null-safety)
+  - [Error Handling](#error-handling)
 - [Workflows](#workflows)
+  - [Workflow: Static Analysis Resolution](#workflow-static-analysis-resolution)
 - [Examples](#examples)
 
 ## Core Concepts & Guidelines
@@ -18,30 +23,32 @@ description: Uses get_runtime_errors and lsp to fetch an active stack trace, loc
 Enforce Dart's sound type system to prevent runtime invalid states.
 
 - **Method Overrides:** Maintain sound return types (covariant) and parameter types (contravariant). Never tighten a parameter type in a subclass unless explicitly marked with the `covariant` keyword.
-- **Generics & Collections:** Add explicit type annotations to generic classes (e.g., `List<T>`, `Map<K, V>`). Never assign a `List<dynamic>` to a typed list.
+- **Generics & Collections:** Add explicit type annotations to generic classes (e.g., `List<T>`, `Map<K, V>`). Never assign a `List<dynamic>` to a typed list (e.g., `List<Cat>`).
 - **Downcasting:** Avoid implicit downcasts from `dynamic`. Use explicit casts (e.g., `as List<Cat>`) when necessary, but ensure the underlying runtime type matches to prevent `TypeError` exceptions.
-- **Strict Casts:** Enable `strict-casts: true` in `analysis_options.yaml` under `analyzer: language:` to force explicit casting.
+- **Strict Casts:** Enable `strict-casts: true` in `analysis_options.yaml` under `analyzer: language:` to force explicit casting and catch implicit downcast errors at compile time.
 
 ### Null Safety
 
 Eliminate static errors related to null safety by correctly managing variable initialization and nullability.
 
 - **Modifiers:** Apply `?` for nullable types, `!` for null assertions, and `required` for named parameters that cannot be null.
-- **Late Initialization:** Use the `late` keyword for non-nullable variables guaranteed to be initialized before use.
-- **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters.
+- **Late Initialization:** Use the `late` keyword for non-nullable variables guaranteed to be initialized before use. Apply this specifically to top-level or instance variables where Dart's control flow analysis cannot definitively prove initialization.
+- **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters to avoid unused variable warnings.
 
 ### Error Handling
 
 Distinguish between recoverable exceptions and unrecoverable errors.
 
 - **Catching:** Catch `Exception` subtypes for recoverable failures.
-- **Errors:** Never explicitly catch `Error` or its subtypes (e.g., `TypeError`, `ArgumentError`). Errors indicate programming bugs that must be fixed, not caught.
+- **Errors:** Never explicitly catch `Error` or its subtypes (e.g., `TypeError`, `ArgumentError`). Errors indicate programming bugs that must be fixed, not caught. Enforce this by enabling the `avoid_catching_errors` linter rule.
 - **Rethrowing:** Use `rethrow` inside a `catch` block to propagate an exception while preserving its original stack trace.
 
 ## Workflows
 
 ### Workflow: Static Analysis Resolution
 
+Use this sequential workflow to identify, fix, and verify static analysis errors in a Dart project. Copy the checklist to track your progress.
+
 **Task Progress:**
 
 - [ ] 1. Run static analyzer.
@@ -50,36 +57,52 @@ Distinguish between recoverable exceptions and unrecoverable errors.
 - [ ] 4. Verify fixes (Feedback Loop).
 
 **1. Run static analyzer**
+Execute the Dart analyzer to identify all static errors in the target directory or file.
 
 ```bash
 dart analyze . --fatal-infos
 ```
 
 **2. Apply automated fixes**
+Use the `dart fix` tool to automatically resolve standard linting and analysis issues.
 
 ```bash
+# Preview changes
 dart fix --dry-run
+# Apply changes
 dart fix --apply
 ```
 
 **3. Resolve remaining errors manually**
-
-- **If Null Safety issue:** Verify if the variable can logically be null. Use `?.` or `??` if yes, `late` if initialization is guaranteed elsewhere.
-- **If Type Mismatch:** Add explicit generic type annotations to the instantiation.
-- **If Invalid Override:** Widen the parameter type or add `covariant`.
+Review the remaining analyzer output and apply conditional logic based on the error type:
+
+- **If the error is a Null Safety issue (e.g., "Property cannot be accessed on a nullable receiver"):**
+  - Verify if the variable can logically be null.
+  - If yes, use optional chaining (`?.`) or provide a fallback (`??`).
+  - If no, and initialization is guaranteed elsewhere, mark the declaration with `late`.
+- **If the error is a Type Mismatch (e.g., "The argument type 'List<dynamic>' can't be assigned..."):**
+  - Trace the variable's initialization.
+  - Add explicit generic type annotations to the instantiation (e.g., `<int>[]` instead of `[]`).
+- **If the error is an Invalid Override (e.g., "The parameter type doesn't match the overridden method"):**
+  - Widen the parameter type to match the superclass, OR
+  - Add the `covariant` keyword to the parameter if tightening the type is intentionally required by the domain logic.
 
 **4. Verify fixes (Feedback Loop)**
+Run the validator. Review errors. Fix.
 
 ```bash
 dart analyze .
 dart test
 ```
 
+- **If `dart analyze` reports errors:** Return to Step 3.
+- **If `dart test` fails with a `TypeError`:** You have introduced an invalid explicit cast (`as T`) or accessed an uninitialized `late` variable. Locate the runtime failure and correct the type hierarchy or initialization order.
+
 ## Examples
 
-### Fixing Dynamic List Assignments
+### Example: Fixing Dynamic List Assignments
 
-**Input (Fails):**
+**Input (Fails Static Analysis):**
 
 ```dart
 void printInts(List<int> a) => print(a);
@@ -87,11 +110,12 @@ void printInts(List<int> a) => print(a);
 void main() {
   final list = []; // Inferred as List<dynamic>
   list.add(1);
-  printInts(list); // Error
+  list.add(2);
+  printInts(list); // Error: List<dynamic> can't be assigned to List<int>
 }
 ```
 
-**Output (Passes):**
+**Output (Passes Static Analysis):**
 
 ```dart
 void printInts(List<int> a) => print(a);
@@ -99,27 +123,62 @@ void printInts(List<int> a) => print(a);
 void main() {
   final list = <int>[]; // Explicitly typed
   list.add(1);
+  list.add(2);
   printInts(list);
 }
 ```
 
-### Fixing Null Safety with `late`
+### Example: Fixing Method Overrides (Contravariance)
+
+**Input (Fails Static Analysis):**
+
+```dart
+class Animal {
+  void chase(Animal a) {}
+}
+
+class Cat extends Animal {
+  @override
+  void chase(Mouse a) {} // Error: Tightening parameter type
+}
+```
+
+**Output (Passes Static Analysis):**
+
+```dart
+class Animal {
+  void chase(Animal a) {}
+}
+
+class Cat extends Animal {
+  @override
+  void chase(covariant Mouse a) {} // Explicitly marked covariant
+}
+```
+
+### Example: Fixing Null Safety with `late`
 
-**Input (Fails):**
+**Input (Fails Static Analysis):**
 
 ```dart
 class Thermometer {
-  String temperature; // Error: Non-nullable must be initialized
-  void read() { temperature = '20C'; }
+  String temperature; // Error: Non-nullable instance field must be initialized
+
+  void read() {
+    temperature = '20C';
+  }
 }
 ```
 
-**Output (Passes):**
+**Output (Passes Static Analysis):**
 
 ```dart
 class Thermometer {
-  late String temperature;
-  void read() { temperature = '20C'; }
+  late String temperature; // Defers initialization check to runtime
+
+  void read() {
+    temperature = '20C';
+  }
 }
 ```
 

package/skills/generate-test-mocks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: generate-test-mocks
 description: Define and generate mock objects for external dependencies using `package:mockito` and `build_runner`. Use when unit testing classes that depend on complex external services like APIs or databases.
+  last_modified: Fri, 24 Apr 2026 15:13:58 GMT
 ---
 
 # Testing and Mocking Dart Applications
@@ -16,10 +17,11 @@ description: Define and generate mock objects for external dependencies using `p
 
 ## Structuring Code for Testability
 
-Design Dart classes to support dependency injection. Isolate complex external dependencies so they can be replaced with mock objects during testing.
+Design Dart classes to support dependency injection. Isolate complex external dependencies (like API clients or databases) so they can be replaced with mock objects during testing.
 
 - Inject external services (e.g., `http.Client`) through class constructors.
 - Represent URLs strictly as `Uri` objects using `Uri.parse(string)`.
+- Utilize Dart's object-oriented features (classes, mixins) to define clear interfaces for external interactions.
 
 ## Managing Dependencies
 
@@ -27,33 +29,38 @@ Configure the `pubspec.yaml` file with the necessary testing and code generation
 
 - Add runtime dependencies (e.g., `package:http`) using `dart pub add http`.
 - Add testing dependencies using `dart pub add dev:test dev:mockito dev:build_runner`.
-- Import HTTP libraries with a prefix: `import 'package:http/http.dart' as http;`.
+- Import HTTP libraries with a prefix to avoid namespace collisions: `import 'package:http/http.dart' as http;`.
 
 ## Generating Mocks
 
-Use `package:mockito` and `build_runner` to automatically generate mock classes.
+Use `package:mockito` and `build_runner` to automatically generate mock classes for fixed scenarios and behavior verification.
 
-- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks`).
+- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks` to avoid missing stub exceptions).
 - Place the annotation in the test file, passing a list of `MockSpec<Type>()` objects.
 - Import the generated file using the `.mocks.dart` extension.
 - Execute `build_runner` to generate the mock files: `dart run build_runner build`.
 
 ## Implementing Unit Tests
 
-Isolate the system under test using the generated mock objects.
+Isolate the system under test using the generated mock objects. Use `package:test` to structure the test suite.
 
-- **Stubbing:** Use `when(mock.method()).thenReturn(value)` for synchronous methods.
-- **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns.
-- **Verification:** Use `verify(mock.method()).called(1)` to check exact invocation counts.
+- **Stubbing:** Configure mock behavior before interacting with the system under test.
+  - Use `when(mock.method()).thenReturn(value)` for synchronous methods.
+  - **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns.
+- **Verification:** Assert that the system under test interacted with the mock object correctly.
+  - Use `verify(mock.method()).called(1)` to check exact invocation counts.
+  - Use argument matchers like `any`, `anyNamed`, or `captureAny` for flexible verification.
 
 ## Workflow: Creating and Running Mocked Tests
 
+Use the following checklist to implement and verify mocked unit tests.
+
 ### Task Progress
 
-- [ ] 1. Identify the external dependency to mock.
+- [ ] 1. Identify the external dependency to mock (e.g., `http.Client`).
 - [ ] 2. Inject the dependency into the target class constructor.
-- [ ] 3. Create a test file and add `@GenerateNiceMocks([MockSpec<Dependency>()])`.
-- [ ] 4. Add the import directive for the generated `.mocks.dart` file.
+- [ ] 3. Create a test file (e.g., `target_test.dart`) and add `@GenerateNiceMocks([MockSpec<Dependency>()])`.
+- [ ] 4. Add the `part` or `import` directive for the generated `.mocks.dart` file.
 - [ ] 5. Run `dart run build_runner build` to generate the mock classes.
 - [ ] 6. Write the test cases using `group()` and `test()`.
 - [ ] 7. Stub required behaviors using `when()`.
@@ -61,11 +68,23 @@ Isolate the system under test using the generated mock objects.
 - [ ] 9. Verify interactions using `verify()` and assert outcomes using `expect()`.
 - [ ] 10. Run the test suite using `dart test`.
 
+### Feedback Loop: Test Failures
+
+If tests fail or `build_runner` encounters errors:
+
+1. **Run validator:** Execute `dart test` or `dart run build_runner build`.
+2. **Review errors:** Check for missing stubs, mismatched argument matchers, or syntax errors in the generated files.
+3. **Fix:**
+   - If a mock method throws an unexpected null error, ensure you used `@GenerateNiceMocks`.
+   - If an async stub throws an `ArgumentError`, change `thenReturn` to `thenAnswer`.
+   - If `build_runner` fails, ensure the `.mocks.dart` import matches the file name exactly.
+4. Repeat until all tests pass.
+
 ## Examples
 
 ### High-Fidelity Mocking and Testing Example
 
-**System Under Test (`lib/api_service.dart`):**
+**1. System Under Test (`lib/api_service.dart`)**
 
 ```dart
 import 'dart:convert';
@@ -73,11 +92,13 @@ import 'package:http/http.dart' as http;
 
 class ApiService {
   final http.Client client;
+
   ApiService(this.client);
 
   Future<String> fetchData(String urlString) async {
     final uri = Uri.parse(urlString);
     final response = await client.get(uri);
+
     if (response.statusCode == 200) {
       return jsonDecode(response.body)['data'];
     } else {
@@ -87,7 +108,7 @@ class ApiService {
 }
 ```
 
-**Test Implementation (`test/api_service_test.dart`):**
+**2. Test Implementation (`test/api_service_test.dart`)**
 
 ```dart
 import 'package:test/test.dart';
@@ -96,6 +117,7 @@ import 'package:mockito/mockito.dart';
 import 'package:http/http.dart' as http;
 import 'package:my_app/api_service.dart';
 
+// Generate the mock class for http.Client
 @GenerateNiceMocks([MockSpec<http.Client>()])
 import 'api_service_test.mocks.dart';
 
@@ -110,20 +132,28 @@ void main() {
     });
 
     test('returns data if the http call completes successfully', () async {
+      // Arrange: Stub the async HTTP GET request using thenAnswer
       when(mockHttpClient.get(any)).thenAnswer(
         (_) async => http.Response('{"data": "Success"}', 200),
       );
 
+      // Act
       final result = await apiService.fetchData('https://api.example.com/data');
+
+      // Assert
       expect(result, 'Success');
+
+      // Verify the mock was called with the correct Uri
       verify(mockHttpClient.get(Uri.parse('https://api.example.com/data'))).called(1);
     });
 
     test('throws an exception if the http call completes with an error', () {
+      // Arrange
       when(mockHttpClient.get(any)).thenAnswer(
         (_) async => http.Response('Not Found', 404),
       );
 
+      // Act & Assert
       expect(
         apiService.fetchData('https://api.example.com/data'),
         throwsException,

package/skills/implement-json-serialization/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: implement-json-serialization
 description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
+  last_modified: Tue, 21 Apr 2026 21:44:50 GMT
 ---
 
 # Serializing JSON Manually in Flutter
@@ -14,36 +15,52 @@ description: Create model classes with `fromJson` and `toJson` methods using `da
 
 ## Core Guidelines
 
-- **Import `dart:convert`**: Use `jsonEncode` and `jsonDecode`.
-- **Enforce Type Safety**: Cast `jsonDecode()` result to `Map<String, dynamic>` or `List<dynamic>`.
-- **Encapsulate Logic**: Define `fromJson` factory constructor and `toJson` method in model classes.
-- **Handle Background Parsing**: If parsing takes >16ms, use `compute()` to prevent UI jank.
-- **Throw on Failure**: Throw an exception on non-success HTTP status codes. Do not return `null`.
+- **Import `dart:convert`**: Utilize Flutter's built-in `dart:convert` library for manual JSON encoding (`jsonEncode`) and decoding (`jsonDecode`).
+- **Enforce Type Safety**: Always cast the `dynamic` result of `jsonDecode()` to the expected type, typically `Map<String, dynamic>` for objects or `List<dynamic>` for arrays.
+- **Encapsulate Serialization Logic**: Define plain model classes containing properties corresponding to the JSON structure. Implement a `fromJson` factory constructor and a `toJson` method within the model.
+- **Handle Background Parsing**: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's `compute()` function to prevent UI jank.
+- **Throw Exceptions on Failure**: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return `null`.
 
 ## Workflow: Implementing a Serializable Model
 
+Use this checklist to implement manual JSON serialization for a data model.
+
 **Task Progress:**
 
 - [ ] Define the plain model class with `final` properties.
-- [ ] Implement `factory Model.fromJson(Map<String, dynamic> json)`.
-- [ ] Implement `Map<String, dynamic> toJson()`.
-- [ ] Write unit tests for both methods.
+- [ ] Implement the `factory Model.fromJson(Map<String, dynamic> json)` constructor.
+- [ ] Implement the `Map<String, dynamic> toJson()` method.
+- [ ] Write unit tests for both serialization methods.
 - [ ] Run validator -> review type mismatch errors -> fix casting logic.
 
+1. **Define the Model**: Create a class with properties matching the JSON keys.
+2. **Implement `fromJson`**: Extract values from the `Map` and cast them to the appropriate Dart types. Use pattern matching or explicit casting.
+3. **Implement `toJson`**: Return a `Map<String, dynamic>` mapping the class properties back to their JSON string keys.
+4. **Validate**: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly.
+
 ## Workflow: Fetching and Parsing JSON
 
+Use this conditional workflow when retrieving and parsing JSON from a network request.
+
 **Task Progress:**
 
 - [ ] Execute the HTTP request.
 - [ ] Validate the response status code.
-- [ ] Determine parsing strategy:
-  - **Small payload**: Parse synchronously on the main thread.
-  - **Large payload**: Use `compute(parseFunction, response.body)`.
+- [ ] Determine parsing strategy (Synchronous vs. Isolate).
 - [ ] Decode and map the JSON to the model.
 
+1. **Execute Request**: Use the `http` package to perform the network call.
+2. **Validate Response**:
+   - If `response.statusCode == 200` (or 201 for POST), proceed to parsing.
+   - If the status code indicates failure, throw an `Exception`.
+3. **Determine Parsing Strategy**:
+   - If parsing a **small payload** (e.g., a single object), parse synchronously on the main thread.
+   - If parsing a **large payload** (e.g., an array of thousands of objects), use `compute(parseFunction, response.body)` to parse in a background isolate.
+4. **Decode and Map**: Pass the decoded JSON to your model's `fromJson` constructor.
+
 ## Examples
 
-### Model Implementation
+### High-Fidelity Model Implementation
 
 ```dart
 import 'dart:convert';
@@ -53,17 +70,59 @@ class User {
   final String name;
   final String email;
 
-  const User({required this.id, required this.name, required this.email});
+  const User({
+    required this.id,
+    required this.name,
+    required this.email,
+  });
 
+  // Factory constructor for deserialization
   factory User.fromJson(Map<String, dynamic> json) {
     return switch (json) {
-      {'id': int id, 'name': String name, 'email': String email} =>
-        User(id: id, name: name, email: email),
+      {
+        'id': int id,
+        'name': String name,
+        'email': String email,
+      } =>
+        User(
+          id: id,
+          name: name,
+          email: email,
+        ),
       _ => throw const FormatException('Failed to load User.'),
     };
   }
 
-  Map<String, dynamic> toJson() => {'id': id, 'name': name, 'email': email};
+  // Method for serialization
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'name': name,
+      'email': email,
+    };
+  }
+}
+```
+
+### Synchronous Parsing (Small Payload)
+
+```dart
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+
+Future<User> fetchUser(http.Client client, int userId) async {
+  final response = await client.get(
+    Uri.parse('https://api.example.com/users/$userId'),
+    headers: {'Accept': 'application/json'},
+  );
+
+  if (response.statusCode == 200) {
+    // Decode returns dynamic, cast to Map<String, dynamic>
+    final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
+    return User.fromJson(jsonMap);
+  } else {
+    throw Exception('Failed to load user');
+  }
 }
 ```
 
@@ -74,14 +133,20 @@ import 'dart:convert';
 import 'package:flutter/foundation.dart';
 import 'package:http/http.dart' as http;
 
+// Top-level function required for compute()
 List<User> parseUsers(String responseBody) {
   final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
   return parsed.map<User>((json) => User.fromJson(json)).toList();
 }
 
 Future<List<User>> fetchUsers(http.Client client) async {
-  final response = await client.get(Uri.parse('https://api.example.com/users'));
+  final response = await client.get(
+    Uri.parse('https://api.example.com/users'),
+    headers: {'Accept': 'application/json'},
+  );
+
   if (response.statusCode == 200) {
+    // Offload expensive parsing to a background isolate
     return compute(parseUsers, response.body);
   } else {
     throw Exception('Failed to load users');

package/skills/migrate-to-checks-package/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: migrate-to-checks-package
 description: Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.
+  last_modified: Fri, 24 Apr 2026 15:15:22 GMT
 ---
 
 # Migrating Dart Tests to Package Checks
@@ -9,11 +10,14 @@ description: Replace the usage of `expect` and similar functions from `package:m
 
 - [Dependency Management](#dependency-management)
 - [Syntax Migration Guidelines](#syntax-migration-guidelines)
+- [Utilizing Dart MCP Tools](#utilizing-dart-mcp-tools)
 - [Migration Workflow](#migration-workflow)
 - [Examples](#examples)
 
 ## Dependency Management
 
+Manage dependencies using the Dart Tooling MCP Server `pub` tool or standard CLI commands.
+
 - Add `package:checks` as a `dev_dependency` using `dart pub add dev:checks`.
 - Remove `package:matcher` if it is explicitly listed in the `pubspec.yaml` (note: it is often transitively included by `package:test`, which is fine).
 - Import `package:checks/checks.dart` in all test files undergoing migration.
@@ -22,35 +26,47 @@ description: Replace the usage of `expect` and similar functions from `package:m
 
 Transition test assertions from the `package:matcher` syntax to the literate API provided by `package:checks`.
 
-- **Basic Equality:** Replace `expect(actual, equals(expected))` with `check(actual).equals(expected)`.
+- **Basic Equality:** Replace `expect(actual, equals(expected))` or `expect(actual, expected)` with `check(actual).equals(expected)`.
 - **Type Checking:** Replace `expect(actual, isA<Type>())` with `check(actual).isA<Type>()`.
 - **Property Extraction:** Replace `expect(actual.property, expected)` with `check(actual).has((a) => a.property, 'property name').equals(expected)`.
 - **Cascades for Multiple Checks:** Use Dart's cascade operator (`..`) to chain multiple expectations on a single subject.
 - **Asynchronous Expectations:**
   - If checking a `Future`, `await` the `check` call: `await check(someFuture).completes((r) => r.equals(expected));`.
-  - If checking a `Stream`, wrap it in a `StreamQueue` for multiple checks.
+  - If checking a `Stream`, wrap it in a `StreamQueue` for multiple checks, or use `.withQueue` for single/broadcast checks.
+
+## Utilizing Dart MCP Tools
+
+Leverage the Dart MCP Server tools to automate and validate the migration process.
+
+- Use `pub` to run `dart pub get` or `dart pub add`.
+- Use `analyze_files` to run static analysis on the project or specific paths.
+- Use `run_tests` to execute Dart or Flutter tests with an agent-centric UX. ALWAYS use this instead of shell commands like `dart test`.
+- Use `dart_fix` to apply automated fixes if applicable.
 
 ## Migration Workflow
 
-- [ ] Add `package:checks` as a dev dependency.
-- [ ] Identify all test files using `package:matcher` (`expect` calls).
-- [ ] Import `package:checks/checks.dart` in target test files.
-- [ ] Rewrite all `expect(...)` statements to `check(...)` statements.
-- [ ] Run static analyzer.
-- [ ] Run tests.
+Copy and use the following checklist to track progress when migrating a test suite:
+
+- [ ] **Task Progress**
+  - [ ] Add `package:checks` as a dev dependency.
+  - [ ] Identify all test files using `package:matcher` (`expect` calls).
+  - [ ] Import `package:checks/checks.dart` in target test files.
+  - [ ] Rewrite all `expect(...)` statements to `check(...)` statements.
+  - [ ] Run static analyzer (`analyze_files`).
+  - [ ] Run tests (`run_tests`).
 
 ### Feedback Loop: Static Analysis
 
-1. Run the analyzer on the modified test directories.
-2. Review any static analysis warnings or errors.
+1. Run the `analyze_files` tool on the modified test directories.
+2. Review any static analysis warnings or errors (e.g., missing imports, incorrect generic types on `isA`, unawaited futures).
 3. Fix the warnings.
-4. Repeat until zero issues.
+4. Repeat until the analyzer returns zero issues.
 
 ### Feedback Loop: Test Validation
 
-1. Run the tests.
-2. If tests fail, review the failure output. `package:checks` provides detailed context.
-3. Adjust the `check()` expectations or the underlying code.
+1. Run the `run_tests` tool.
+2. If tests fail, review the failure output. `package:checks` provides detailed context (e.g., `Which: has length of <2>`).
+3. Adjust the `check()` expectations or the underlying code to resolve the failure.
 4. Repeat until all tests pass.
 
 ## Examples
@@ -110,6 +126,22 @@ await check(Future.value(10)).completes((it) => it.equals(10));
 await check(Future.error('oh no')).throws<String>().equals('oh no');
 ```
 
+### Asynchronous Streams
+
+**Input (`matcher`):**
+
+```dart
+var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
+await expectLater(stdout, emitsThrough('Ready'));
+```
+
+**Output (`checks`):**
+
+```dart
+var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
+await check(stdout).emitsThrough((it) => it.equals('Ready'));
+```
+
 ## Flutter Ultra Integration
 
 Validate the migration with static analysis and tests: