# Freemansoft Flutter Adaptivecards Code Review > Code Review Protocol - Skill: `tomevault-io/freemansoft-flutter-adaptivecards-code-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/freemansoft-flutter-adaptivecards-code-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/freemansoft-flutter-adaptivecards-code-review/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/freemansoft-flutter-adaptivecards-code-review --- # Code Review Protocol Use this skill as a "Final Gate" for any PR or significant change. Cross-reference with specialized skills (`adaptive-cards-spec-compliance`, `adaptive-cards-element-registry`, `dart-public-api-docs`, `flutter-adaptive-cards-testing`) as needed. --- ## 1. Monorepo Hygiene & Consistency - [ ] **FVM usage**: Are all commands (`flutter`, `dart`) executed via `fvm`? - [ ] **Analysis**: Does the code pass `fvm flutter analyze`? (Compliance with `very_good_analysis`). - [ ] **Changelog**: Has `CHANGELOG.md` been updated in the affected packages following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)? - [ ] **Release / post-publish** (if applicable): Follow `release-engineer` — all **six** `version:` fields match, **six** changelogs have matching top `## []` sections, and `flutter_adaptive_charts_fs` and `flutter_adaptive_cards_host_fs` use `flutter_adaptive_cards_fs: ^`. - [ ] **Formatting**: Has `dart_format` been run on all modified files? - [ ] **Public `///` docs**: Do exported API changes in library packages explain why and how to use the API (not implementation steps)? See **`dart-public-api-docs`**. --- ## 2. `flutter_adaptive_cards_fs` Checklist ### Registration & Pattern Compliance - [ ] **Registry**: Is the new element/action added to `CardTypeRegistry` or `ActionTypeRegistry`? - [ ] **Mixins**: Does the element correctly implement `AdaptiveElementWidgetMixin` (Widget) and `AdaptiveElementMixin` + `AdaptiveVisibilityMixin` (State)? - [ ] **Inputs**: Does the input use `AdaptiveInputMixin`? On user change, does it call `setDocumentInputValue(...)`? Does it sync controllers in `onDocumentValueChanged` when overlays change (reset)? - [ ] **Visibility**: If visibility can change at runtime, does the element use `AdaptiveVisibilityMixin` and write via `setIsVisible` / document notifier (not local-only `setState`)? - [ ] **TextBlock text**: If runtime text can change, does `AdaptiveTextBlock` read display copy from `resolvedElementProvider(id)` (not only stale `adaptiveMap['text']`)? - [ ] **Actions**: Do action buttons respect `isEnabled` via `AdaptiveActionStateMixin` / `resolvedActionProvider` when host-driven enable/disable matters? - [ ] **Overlays**: Are host/runtime patches written through the document notifier (`setInputValue`, `setText`, `setInputError`, …) rather than mutating the host JSON map? - [ ] **Extension boundary**: Does `flutter_adaptive_cards_fs` avoid chart-specific (or other optional-package) types, imports, and overlay fields? Optional behavior belongs in extension packages via `addedElements` / `overlayExtensions`, not in core. ### Theming & Styling - [ ] **ReferenceResolver**: Does the element use `styleResolver` (via `ProviderScopeMixin`) or `ProviderScope.containerOf(context).read(styleReferenceResolverProvider)` for all colors, font sizes, and spacing? - [ ] **Registries**: Does the element use `cardTypeRegistry` / `actionTypeRegistry` from `ProviderScopeMixin` (not from `ReferenceResolver`)? - [ ] **Theme Awareness**: Has it been verified in both **Light** and **Dark** modes? - [ ] **HostConfig**: Does it respect spacing, separator, and padding properties from JSON via `SeparatorElement`? ### Keys & Identity - [ ] **Deterministic Keys**: Is the outer widget key generated via `generateAdaptiveWidgetKey(adaptiveMap)`? - [ ] **Internal Keys**: For inputs or sub-elements, are keys generated using the `id` (e.g., `ValueKey(id)` or `ValueKey('${id}_suffix')`)? _Crucial for testing stability._ ### Accessibility - [ ] **Semantics**: Does the widget use `Semantics` or `semanticLabel` where appropriate? - [ ] **Alt-text**: For images or icons, is the `altText` (if provided in JSON) used as a semantic label? ### Exports - [ ] **Public API**: Is the new class/widget exported in `lib/flutter_adaptive_cards_fs.dart`? - [ ] **Extension API**: Is it exported in `lib/flutter_adaptive_cards_extend.dart` if intended for customization by consumers? - [ ] **Public `///` docs**: Do new or changed exported members explain **why** the API exists and **how** callers use it — not implementation steps? See **`dart-public-api-docs`**. --- ## 3. `flutter_adaptive_template_fs` Checklist - [ ] **Expression Evaluation**: Are new AST nodes or functions implemented in both the parser and the evaluator? - [ ] **Reserved Keywords**: Are `$data`, `$root`, `$index`, and `$when` handled correctly during expansion? - [ ] **Scope Integrity**: Does nesting `$data` correctly shift the resolution context? --- ## 4. `flutter_adaptive_cards_host_fs` Checklist - [ ] **Handlers**: `AdaptiveCardBackendHandlers` shares the same `GlobalKey` as `RawAdaptiveCard` when `onSubmit` / `onExecute` / `onRefresh` need card state. - [ ] **Adapters**: PlainJson vs Teams invoke shapes match the backend contract; response effects applied via `AdaptiveCardInvokeResponse.applyTo`. - [ ] **Dependencies**: `pubspec.yaml` declares `flutter_adaptive_cards_fs: ^` (sync on release bump). - [ ] **Tests**: Unit tests under `packages/flutter_adaptive_cards_host_fs/test/` (no goldens); run `fvm flutter test` from that package directory. - [ ] **Docs**: Public API changes reflected in `docs/backend-host-integration.md` and package `README.md`; exported `///` comments follow **`dart-public-api-docs`**. See **`adaptive-cards-backend-host`** skill for file paths and invoke round-trip patterns. --- ## 5. Testing Protocol - [ ] **Key-First Searching**: All `find.text()` or `find.byType()` calls in tests should be replaced with `find.byKey()` whenever a key is available. - [ ] **JSON Samples**: Is there a new file in `test/samples/` demonstrating the feature/fix? - [ ] **Golden Tests**: - Have golden tests been added/updated for UI changes? - **New goldens:** generate with `--update-goldens` on macOS, then **copy each new PNG from `test/gold_files/macos/` to `test/gold_files/linux/`** so CI has a baseline (see `adaptive-cards-testing` skill and `test/gold_files/README.md`). - **CI pixel failures:** replace `linux/` files from CI artifact zips for canonical Linux images. ### `widgetbook` changes (sample app) - [ ] **Asset registration**: New folders under `widgetbook/lib/samples/` are listed in `widgetbook/pubspec.yaml` under `flutter: assets:` (required for `AdaptiveCardsCanvas.asset`). - [ ] **Use case / codegen**: `@widgetbook.UseCase` added or updated in `adaptive_cards_use_cases.dart`; `fvm dart run build_runner build` run when use cases change. - [ ] **Changelog**: `widgetbook/CHANGELOG.md` updated when the demo app changes. - [ ] **Docs**: Overlay knob pages → registry row in [`docs/widgetbook-overlay-demos.md`](../../docs/widgetbook-overlay-demos.md); package behavior docs tag widgetbook as **Example (widgetbook sample)** per [`documentation-scope.md`](../../docs/documentation-scope.md). --- ## Review Output Template When performing a review, summarize findings using this format: ```markdown ### Code Review Summary - **Package**: [e.g. flutter_adaptive_cards_fs] - **Hygiene**: [PASS/FAIL] (Analysis, Changelog, Formatting) - **Compliance**: [PASS/FAIL] (Registry, Spec, Theming) - **Testing**: [PASS/FAIL] (Keys, Samples, Goldens) #### Details - [Specific feedback regarding keys, accessibility, etc.] ``` --- > Source: [freemansoft/Flutter-AdaptiveCards](https://github.com/freemansoft/Flutter-AdaptiveCards) — distributed by [TomeVault](https://tomevault.io).