opencode-agent-kit 1.0.0

package/template/.opencode/skills/dart-generate-test-mocks/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: dart-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.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:13:58 GMT
+---
+# Testing and Mocking Dart Applications
+
+## Contents
+- [Structuring Code for Testability](#structuring-code-for-testability)
+- [Managing Dependencies](#managing-dependencies)
+- [Generating Mocks](#generating-mocks)
+- [Implementing Unit Tests](#implementing-unit-tests)
+- [Workflow: Creating and Running Mocked Tests](#workflow-creating-and-running-mocked-tests)
+- [Examples](#examples)
+
+## Structuring Code for Testability
+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
+Configure the `pubspec.yaml` file with the necessary testing and code generation packages.
+
+- 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 to avoid namespace collisions: `import 'package:http/http.dart' as http;`.
+
+## Generating Mocks
+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` 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. Use `package:test` to structure the test suite.
+
+- **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 (e.g., `http.Client`).
+- [ ] 2. Inject the dependency into the target class constructor.
+- [ ] 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()`.
+- [ ] 8. Execute the target method.
+- [ ] 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
+
+**1. System Under Test (`lib/api_service.dart`)**
+```dart
+import 'dart:convert';
+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 {
+      throw Exception('Failed to load data');
+    }
+  }
+}
+```
+
+**2. Test Implementation (`test/api_service_test.dart`)**
+```dart
+import 'package:test/test.dart';
+import 'package:mockito/annotations.dart';
+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';
+
+void main() {
+  group('ApiService', () {
+    late ApiService apiService;
+    late MockClient mockHttpClient;
+
+    setUp(() {
+      mockHttpClient = MockClient();
+      apiService = ApiService(mockHttpClient);
+    });
+
+    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/template/.opencode/skills/dart-migrate-to-checks-package/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: dart-migrate-to-checks-package
+description: Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:15:22 GMT
+---
+# Migrating Dart Tests to Package Checks
+
+## Contents
+- [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.
+
+## Syntax Migration Guidelines
+Transition test assertions from the `package:matcher` syntax to the literate API provided by `package:checks`.
+
+- **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, 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
+
+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 `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 the analyzer returns zero issues.
+
+### Feedback Loop: Test Validation
+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
+
+### Basic Assertions
+**Input (`matcher`):**
+```dart
+expect(someList.length, 1);
+expect(someString, startsWith('a'));
+expect(someObject, isA<Map>());
+```
+
+**Output (`checks`):**
+```dart
+check(someList).length.equals(1);
+check(someString).startsWith('a');
+check(someObject).isA<Map>();
+```
+
+### Composed Expectations
+**Input (`matcher`):**
+```dart
+expect('foo,bar,baz', allOf([
+  contains('foo'),
+  isNot(startsWith('bar')),
+  endsWith('baz')
+]));
+```
+
+**Output (`checks`):**
+```dart
+check('foo,bar,baz')
+  ..contains('foo')
+  ..not((s) => s.startsWith('bar'))
+  ..endsWith('baz');
+```
+
+### Asynchronous Futures
+**Input (`matcher`):**
+```dart
+expect(Future.value(10), completion(equals(10)));
+expect(Future.error('oh no'), throwsA(equals('oh no')));
+```
+
+**Output (`checks`):**
+```dart
+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'));
+```

package/template/.opencode/skills/dart-resolve-package-conflicts/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: dart-resolve-package-conflicts
+description: Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:11:14 GMT
+---
+# Managing Dart Dependencies
+
+## Contents
+- [Core Concepts](#core-concepts)
+- [Version Constraints](#version-constraints)
+- [Workflow: Auditing Dependencies](#workflow-auditing-dependencies)
+- [Workflow: Upgrading Dependencies](#workflow-upgrading-dependencies)
+- [Workflow: Resolving Version Conflicts](#workflow-resolving-version-conflicts)
+- [Examples](#examples)
+
+## Core Concepts
+
+Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package. This prevents runtime type mismatches but introduces the risk of "version lock."
+
+To mitigate version lock, Dart relies on version constraints rather than pinned versions in the `pubspec.yaml`. The `pubspec.lock` file maintains the exact resolved versions for reproducible builds.
+
+Understand the output columns of `dart pub outdated`:
+*   **Current:** The version currently recorded in `pubspec.lock`.
+*   **Upgradable:** The latest version allowed by the constraints in `pubspec.yaml`. `dart pub upgrade` resolves to this.
+*   **Resolvable:** The absolute latest version that can be resolved when factoring in all other dependencies in the project.
+*   **Latest:** The latest published version of the package (excluding prereleases).
+
+## Version Constraints
+
+*   **Use Caret Syntax:** Always use caret syntax (e.g., `^1.2.3`) for dependencies in `pubspec.yaml`. This allows `pub` to select newer, non-breaking versions (up to, but not including, the next major version) during resolution.
+*   **Tighten Dev Dependencies:** Set the lower bound of `dev_dependencies` to the exact version currently used. This reduces resolution complexity and prevents older, incompatible dev tools from being selected.
+*   **Enforce Lockfiles in CI:** Use `dart pub get --enforce-lockfile` in CI/CD pipelines to ensure the exact versions tested locally are used in production.
+
+## Workflow: Auditing Dependencies
+
+Run this workflow periodically to identify stale packages that may impact stability or performance.
+
+**Task Progress:**
+- [ ] Run `dart pub outdated`.
+- [ ] Review the **Upgradable** column to identify packages that can be updated without modifying `pubspec.yaml`.
+- [ ] Review the **Resolvable** column to identify packages that require constraint modifications in `pubspec.yaml` to update.
+- [ ] Identify any packages marked as retracted or discontinued.
+
+## Workflow: Upgrading Dependencies
+
+Use conditional logic based on the audit results to upgrade dependencies.
+
+**Task Progress:**
+- [ ] **If updating to "Upgradable" versions:**
+  - [ ] Run `dart pub upgrade`.
+  - [ ] Run `dart pub upgrade --tighten` to automatically update the lower bounds in `pubspec.yaml` to match the newly resolved versions.
+- [ ] **If updating to "Resolvable" versions (Major updates):**
+  - [ ] Manually edit `pubspec.yaml` to bump the version constraint to match the "Resolvable" column (e.g., change `^0.11.0` to `^0.12.1`).
+  - [ ] Run `dart pub upgrade` to resolve the new constraints and update `pubspec.lock`.
+- [ ] **Feedback Loop:**
+  - [ ] Run `dart analyze` -> review errors -> fix breaking API changes.
+  - [ ] Run `dart test` -> review failures -> fix regressions.
+
+## Workflow: Resolving Version Conflicts
+
+When `pub` cannot find a set of concrete versions that satisfy all constraints, or when dealing with a retracted package version, manipulate the lockfile surgically.
+
+**NEVER** delete the entire `pubspec.lock` file and run `dart pub get`. This causes uncontrolled upgrades across the entire dependency graph.
+
+**Task Progress:**
+- [ ] Open `pubspec.lock`.
+- [ ] Locate the specific YAML block for the conflicting or retracted package.
+- [ ] Delete ONLY that package's entry from the lockfile.
+- [ ] Run `dart pub get` to fetch the newest compatible, non-retracted version for that specific package.
+- [ ] **Feedback Loop:**
+  - [ ] Run `dart pub deps` -> verify the dependency graph resolves correctly.
+  - [ ] If resolution fails, identify the transitive dependency causing the lock, update its constraint in `pubspec.yaml`, and retry.
+
+## Examples
+
+### Tightening Constraints
+When `dart pub outdated` shows a package is resolvable to a higher minor/patch version, use the `--tighten` flag to update the `pubspec.yaml` automatically.
+
+**Input (`pubspec.yaml`):**
+```yaml
+dependencies:
+  http: ^0.13.0
+```
+
+**Command:**
+```bash
+dart pub upgrade --tighten http
+```
+
+**Output (`pubspec.yaml`):**
+```yaml
+dependencies:
+  http: ^0.13.5
+```
+
+### Surgical Lockfile Removal
+If `package_a` is retracted or locked in a conflict, remove only its block from `pubspec.lock`.
+
+**Before (`pubspec.lock`):**
+```yaml
+packages:
+  package_a:
+    dependency: "direct main"
+    description:
+      name: package_a
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.0" # Retracted version
+  package_b:
+    dependency: "direct main"
+    # ...
+```
+
+**Action:** Delete the `package_a` block entirely. Leave `package_b` untouched. Run `dart pub get`.

package/template/.opencode/skills/dart-run-static-analysis/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: dart-run-static-analysis
+description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:09:34 GMT
+---
+# Analyzing and Fixing Dart Code
+
+## Contents
+- [Analysis Configuration](#analysis-configuration)
+- [Diagnostic Suppression](#diagnostic-suppression)
+- [Workflow: Executing Static Analysis](#workflow-executing-static-analysis)
+- [Workflow: Applying Automated Fixes](#workflow-applying-automated-fixes)
+- [Examples](#examples)
+
+## Analysis Configuration
+
+Configure the Dart analyzer using the `analysis_options.yaml` file located at the package root.
+
+- **Base Configuration:** Always include a standard rule set (e.g., `package:lints/recommended.yaml` or `package:flutter_lints/flutter.yaml`) using the `include:` directive.
+- **Strict Type Checks:** Enable strict type checks under the `analyzer: language:` node to prevent implicit downcasts and dynamic inferences. Set `strict-casts: true`, `strict-inference: true`, and `strict-raw-types: true`.
+- **Linter Rules:** Explicitly enable or disable specific rules under the `linter: rules:` node. Use a key-value map (`rule_name: true/false`) when overriding included rules, or a list (`- rule_name`) when defining a fresh set. Do not mix list and map syntax in the same `rules` block.
+- **Formatter Configuration:** Configure `dart format` behavior under the `formatter:` node. Set `page_width` (default 80) and `trailing_commas` (`automate` or `preserve`).
+- **Analyzer Plugins:** Enable custom diagnostics by adding plugins under the `analyzer: plugins:` node. Ensure the plugin package is added as a `dev_dependency` in `pubspec.yaml`.
+
+## Diagnostic Suppression
+
+When a diagnostic (lint or warning) yields a false positive or applies to generated code, suppress it explicitly.
+
+- **File-level Exclusion:** Use the `analyzer: exclude:` node in `analysis_options.yaml` to exclude entire files or directories (e.g., `**/*.g.dart`) using glob patterns.
+- **File-level Suppression:** Add `// ignore_for_file: <diagnostic_code>` at the top of a Dart file to suppress specific diagnostics for the entire file. Use `// ignore_for_file: type=lint` to suppress all linter rules.
+- **Line-level Suppression:** Add `// ignore: <diagnostic_code>` on the line directly above the offending code, or appended to the end of the offending line.
+- **Pubspec Suppression:** Add `# ignore: <diagnostic_code>` above the offending line in `pubspec.yaml` files (e.g., `# ignore: sort_pub_dependencies`).
+- **Plugin Diagnostics:** Prefix the diagnostic code with the plugin name when suppressing plugin-specific issues (e.g., `// ignore: some_plugin/some_code`).
+
+## Workflow: Executing Static Analysis
+
+Use this workflow to identify type-related bugs, style violations, and potential runtime errors.
+
+**Task Progress:**
+- [ ] 1. Verify `analysis_options.yaml` exists at the project root.
+- [ ] 2. Run the analyzer using the `analyze_files` MCP tool (if available) or the CLI command `dart analyze <target_directory>`.
+- [ ] 3. Review the diagnostic output.
+- [ ] 4. If info-level issues must be treated as failures, append the `--fatal-infos` flag.
+- [ ] 5. Resolve reported errors manually or proceed to the Automated Fixes workflow.
+
+## Workflow: Applying Automated Fixes
+
+Use this workflow to resolve outdated API usages, apply quick fixes, and migrate code (e.g., Dart 3 migrations).
+
+**Task Progress:**
+- [ ] 1. Execute a dry run to preview proposed changes using the `dart_fix` MCP tool or CLI command `dart fix --dry-run`.
+- [ ] 2. Review the proposed fixes to ensure they align with the intended architecture.
+- [ ] 3. If additional fixes are required, verify that the corresponding linter rules are enabled in `analysis_options.yaml`.
+- [ ] 4. Apply the fixes using the `dart_fix` MCP tool or CLI command `dart fix --apply`.
+- [ ] 5. Format the modified code using the `dart_format` MCP tool or CLI command `dart format .`.
+- [ ] 6. Run the static analysis workflow to verify all diagnostics are resolved.
+
+## Examples
+
+### Comprehensive `analysis_options.yaml`
+
+```yaml
+include: package:flutter_lints/recommended.yaml
+
+analyzer:
+  exclude:
+    - "**/*.g.dart"
+    - "lib/generated/**"
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+  errors:
+    todo: ignore
+    invalid_assignment: warning
+    missing_return: error
+
+linter:
+  rules:
+    avoid_shadowing_type_parameters: false
+    await_only_futures: true
+    use_super_parameters: true
+
+formatter:
+  page_width: 100
+  trailing_commas: preserve
+```
+
+### Inline Diagnostic Suppression
+
+```dart
+// Suppress for the entire file
+// ignore_for_file: unused_local_variable, dead_code
+
+void processData() {
+  // Suppress for a specific line
+  // ignore: invalid_assignment
+  int x = '';
+  
+  const y = 10; // ignore: constant_identifier_names
+}
+```

package/template/.opencode/skills/dart-use-pattern-matching/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: dart-use-pattern-matching
+description: Use switch expressions and pattern matching where appropriate
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:08:55 GMT
+---
+# Implementing Dart Patterns
+
+## Contents
+- [Pattern Selection Strategy](#pattern-selection-strategy)
+- [Switch Statements vs. Expressions](#switch-statements-vs-expressions)
+- [Core Pattern Implementations](#core-pattern-implementations)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Pattern Selection Strategy
+
+Apply specific pattern types based on the data structure and desired outcome. Follow these conditional guidelines:
+
+*   **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns to simultaneously check structure and destructure key-value pairs.
+*   **If handling multiple return values:** Use Record patterns to destructure fields directly into local variables.
+*   **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns combined with `sealed` classes to ensure exhaustiveness.
+*   **If matching numeric ranges or conditions:** Use Relational (`>=`, `<=`) and Logical-and (`&&`) patterns.
+*   **If multiple cases share logic:** Use Logical-or (`||`) patterns to share a single case body or guard clause.
+*   **If ignoring specific values:** Use the Wildcard pattern (`_`) or a non-matching Rest element (`...`) in collections.
+
+## Switch Statements vs. Expressions
+
+Select the appropriate switch construct based on the execution context:
+
+*   **If producing a value:** Use a **switch expression**.
+    *   Syntax: `switch (value) { pattern => expression, }`
+    *   Rule: Each case must be a single expression. No implicit fallthrough. Must be exhaustive.
+*   **If executing statements or side effects:** Use a **switch statement**.
+    *   Syntax: `switch (value) { case pattern: statements; }`
+    *   Rule: Empty cases fall through to the next case. Non-empty cases implicitly break (no `break` keyword required).
+
+## Core Pattern Implementations
+
+Implement patterns using the following syntax and rules:
+
+*   **Logical-or (`||`):** `pattern1 || pattern2`. Both branches must define the exact same set of variables.
+*   **Logical-and (`&&`):** `pattern1 && pattern2`. Branches must *not* define overlapping variables.
+*   **Relational:** `==`, `!=`, `<`, `>`, `<=`, `>=` followed by a constant expression.
+*   **Cast (`as`):** `pattern as Type`. Throws if the value does not match the type. Use to forcibly assert types during destructuring.
+*   **Null-check (`?`):** `pattern?`. Fails the match if the value is null. Binds the variable to the non-nullable base type.
+*   **Null-assert (`!`):** `pattern!`. Throws if the value is null.
+*   **Variable:** `var name` or `Type name`. Binds the matched value to a new local variable.
+*   **Wildcard (`_`):** Matches any value and discards it.
+*   **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...` or `...var rest`) is used.
+*   **Map:** `{"key": pattern}`. Matches maps containing the specified keys. Ignores unmatched keys.
+*   **Record:** `(pattern1, named: pattern2)`. Matches records of the exact shape. Use `:var name` to infer the getter name.
+*   **Object:** `ClassName(field: pattern)`. Matches instances of `ClassName`. Use `:var field` to infer the getter name.
+
+## Workflows
+
+### Task Progress: Implementing Pattern Matching
+Copy this checklist to track progress when implementing complex pattern matching logic:
+
+- [ ] Identify the data structure being evaluated (JSON, Record, Class, Enum).
+- [ ] Select the appropriate switch construct (Expression for values, Statement for side-effects).
+- [ ] Define the required patterns (Object, Map, List, Record).
+- [ ] Extract required data using Variable patterns (`var x`, `:var y`).
+- [ ] Apply Guard clauses (`when condition`) for logic that cannot be expressed via patterns.
+- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class).
+- [ ] Run exhaustiveness validator.
+
+### Feedback Loop: Exhaustiveness Checking
+When switching over `sealed` classes or enums, you must ensure all subtypes are handled.
+
+1. **Run validator:** Execute `dart analyze`.
+2. **Review errors:** Look for "The type 'X' is not exhaustively matched by the switch cases" errors.
+3. **Fix:** Add the missing Object patterns for the unhandled subtypes, or add a Wildcard (`_`) case if a default fallback is acceptable.
+
+## Examples
+
+### JSON Validation and Destructuring
+Use Map and List patterns to validate structure and extract data in a single step.
+
+**Input:**
+```dart
+var data = {
+  'user': ['Lily', 13],
+};
+```
+
+**Implementation:**
+```dart
+if (data case {'user': [String name, int age]}) {
+  print('User $name is $age years old.');
+} else {
+  print('Invalid JSON structure.');
+}
+```
+
+### Algebraic Data Types (Sealed Classes)
+Use Object patterns with switch expressions to handle family types exhaustively.
+
+**Implementation:**
+```dart
+sealed class Shape {}
+
+class Square implements Shape {
+  final double length;
+  Square(this.length);
+}
+
+class Circle implements Shape {
+  final double radius;
+  Circle(this.radius);
+}
+
+// Switch expression guarantees exhaustiveness due to `sealed` modifier.
+double calculateArea(Shape shape) => switch (shape) {
+  Square(length: var l) => l * l,
+  Circle(:var radius)   => math.pi * radius * radius,
+};
+```
+
+### Variable Swapping and Destructuring
+Use variable assignment patterns to swap values or extract record fields without temporary variables.
+
+**Implementation:**
+```dart
+var (a, b) = ('left', 'right');
+(b, a) = (a, b); // Swap values
+
+// Destructuring a function return
+var (name, age) = getUserInfo();
+```
+
+### Guard Clauses and Logical-or
+Use `when` to evaluate arbitrary conditions after a pattern matches.
+
+**Implementation:**
+```dart
+switch (shape) {
+  case Square(size: var s) || Circle(size: var s) when s > 0:
+    print('Valid symmetric shape with size $s');
+  case Square() || Circle():
+    print('Invalid or empty shape');
+  default:
+    print('Unknown shape');
+}
+```