@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/agents-file-coverage-gate/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agents-file-coverage-gate
+description: 在一个仓库跑「AGENTS.md 契约覆盖」gate——扫出根目录和每个源码目录是否都有 AGENTS.md,可一键补 stub 并接 CI 卡关。确定性脚本运行器,不做交付分类。触发:"查/跑 AGENTS 覆盖"、"查/跑/补 agent 覆盖地图"、"agent 契约覆盖"、"扫一下哪些目录缺 AGENTS.md"、"每个目录都有 agent 契约了吗"、"补缺失的 AGENTS.md"、"契约覆盖 gate"、"给这个仓初始化契约覆盖"、"装 AGENTS 的 pre-commit / CI 卡关"、"check AGENTS.md coverage"、"agents coverage"、"scaffold missing AGENTS.md"、"bootstrap agents coverage"、"do all dirs have an agent contract"。Skip:问「何时/是否」该更新契约或分层策略本身 → `product-rd-workflow` 的 spec/repo-contract sync gate;只是写某一个 AGENTS.md 的内容 → 直接编辑该文件;定义 agent 工具调用/函数的输入输出 schema 或调用契约(不是 AGENTS.md 文件覆盖)→ `llm-inference-integration`。
+---
+
+# AGENTS.md File Coverage Gate
+
+On-demand runner for the agent-contract coverage gate: it verifies (and can scaffold) that a repo's **root and every source-code directory** carry an `AGENTS.md`. This skill RUNS the gate; the *policy* — when a delivery must update a contract, and the layering rules contracts encode — lives in `product-rd-workflow`'s spec / repo-contract sync gate. Do not re-decide policy here.
+
+In a project health-check system, this is a deterministic check provider for repo-local contract coverage. It reports the coverage states implemented by this gate, and it becomes CI-enforceable only when the project wires the vendored script with `--enforce`; agent review still owns whether each contract's content correctly captures the directory boundary.
+
+Contracts are **nearest-file-wins** (the closest `AGENTS.md` to the edited file applies; there is no root index). Scope is **every directory that contains a source file picked up by the scan** (tracked, or untracked-but-not-gitignored; outside a git work tree it falls back to a plain file scan), detected by extension — so Go packages like `dal`/`service`/`handler` with no manifest are covered.
+
+The gate checks **one repository**. Before running, confirm `--repo` points at a single repo, not a **GitLab group / parent-of-repos** checkout (sibling repos cloned side by side under a parent folder, where the parent is not itself a git repo). Running it on a group parent would conflate sibling repos and report a spurious "missing root contract" — so the script now detects that case (target is not a git repo root yet contains nested repos) and **refuses with exit 2, listing the sub-repos to run per-repo**. For a group, loop the gate over each member repo.
+
+## Run
+
+The gate ships in this package at `product-rd-workflow/scripts/check-agent-contract-coverage.sh`. Resolve that script inside the installed ccl-skills plugin (the newest match under the plugin cache) and run it against the target repo (default `--repo .`). Never copy it into the repo just to run it; copying is only for CI.
+
+1. **Scan** — `bash <script> --repo <dir> --check`. Lists every source directory missing a non-empty `AGENTS.md`. Exit 0 (guidance) — never blocks, safe on legacy repos.
+2. **Scaffold** — when the user wants to close gaps: `--fix` writes a stub `AGENTS.md` in each missing directory. Additive only: it never edits or overwrites an existing file, and never follows a symlink.
+3. **Fill** — replace each stub with the directory's real contract: role/responsibility; allowed and forbidden dependencies and layering rules (e.g. a logic layer must not access the database directly — go through the data-access layer); invariants; build/test commands; a link to the nearest parent contract. An empty stub still counts as a gap. **Edit only `AGENTS.md` files.** Keep every contract SHORT: Codex consumers (per current documented behavior — `project_doc_max_bytes`, default 32 KiB, version/config-dependent; primary source: the official Codex AGENTS.md guide at developers.openai.com/codex/guides/agents-md — verify against the installed version) build ONE instruction chain at session start from repo root down to cwd and stop appending on overflow (the guide documents the cap and the stop-adding behavior; no overflow warning is documented) — an oversized root/parent contract can therefore evict deeper overrides, and contracts outside the root→cwd path are not auto-loaded there at all (hosts implementing the agents.md convention apply nearest-file-wins per edited file — per the agents.md spec FAQ; the short-contract discipline serves both semantics).
+4. **Enforce** — `--enforce` exits 1 on any missing / empty / symlinked contract. Wire it into `make lint`/CI once the repo is clean.
+
+Tune scope per project/language: `--source-ext ".tf .razor"`, `--exclude "migrations gen"`, `--name <filename>`. See `bash <script> --help`.
+
+**A clean result only covers the languages the scan recognizes.** Source dirs are detected *by file extension*; a directory whose source is a language outside the active `--source-ext` set is silently unscanned and contributes no gap — so a green `--enforce` on a repo whose source is in an unrecognized extension (e.g. `.tf` / `.razor` / `.zig`, or `Dockerfile` / `Makefile`) can be a false-negative for those dirs. (`--source-ext` *appends to* the built-in default set rather than replacing it, so common mainstream languages are already covered; the blind spot is the extensions neither in the defaults nor added.) Before trusting a clean result (or wiring `--enforce` as a blocking gate), confirm the active extension set covers every in-scope source language whose directories should count toward AGENTS coverage; widen it, or record the unscanned languages as a known coverage gap — do not read a green from a partial extension set as full contract coverage.
+
+## Bootstrap a repo (one-time adoption)
+
+To make coverage self-sustaining — enforced on every commit with no agent and no prompt — set a repo up once:
+
+1. **Vendor the script** into the repo. This is the ONLY case where copying is correct: a git hook or CI runner cannot reach the plugin cache. Copy `check-agent-contract-coverage.sh` to e.g. `tools/`.
+2. **Scaffold + fill** the current gaps — `--fix`, then fill each stub (Run step 3).
+3. **Install the gate** as a git hook or CI step that runs `--enforce`:
+   - pre-commit / pre-push: `bash tools/check-agent-contract-coverage.sh --enforce`. To share across the team, commit a `hooks/` dir AND have a setup/init script run `git config core.hooksPath hooks` (that config is local per clone, so it must be installed, not just committed).
+   - or CI / `make lint`: the same command.
+   During rollout run `--check` (warn-only, exit 0); flip to `--enforce` once the repo is clean so it blocks.
+
+After bootstrap, every commit/CI run enforces coverage automatically; the on-demand path above is then only for ad-hoc checks. This skill can drive the bootstrap (vendor + scaffold + install hook); the running afterwards needs neither agent nor skill — just the vendored script.
+
+## Boundary
+
+- This skill is the **on-demand** path (a short ask → run the gate) plus **one-time bootstrap** (vendor + hook/CI). The steady-state automatic enforcement is the vendored script in a hook/CI, not this skill.
+- It does not decide *when* contracts must change or what layering rules to impose — route those to `product-rd-workflow`'s sync gate.

package/dist/assets/marketplace/plugins/ccl-skills/skills/agents-file-coverage-gate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AGENTS.md File Coverage Gate"
+  short_description: "Scaffold, verify, and enforce AGENTS.md across a repo's source directories"
+  default_prompt: "Use $agents-file-coverage-gate to check, scaffold, or enforce that the repo root and every source-code directory carry an AGENTS.md; it runs product-rd-workflow's check-agent-contract-coverage.sh (--check/--fix/--enforce) and can bootstrap a pre-commit/CI gate."

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: app-cross-platform-dev
+description: Use when designing, implementing, reviewing, debugging, testing, or shipping mobile app client features across Flutter, React Native, native Android, and native iOS, including navigation, state, API integration, offline/cache, platform capabilities, accessibility, performance, app build/release, and rendered device verification. Product-agnostic; use miniapp-product-dev for mini-programs, web-react-dev for React web, product-ui-ux-design for UI/UX, backend skills for services, and testing-strategy for test planning. Triggers include "移动端怎么做", "Flutter / React Native / iOS / Android App 端怎么写", "RN 端", "原生 iOS / Android 页面怎么写", "重构这个 App 页面/组件(局部)", "refactor an app screen/widget".
+---
+
+# App Cross-Platform Dev
+
+Use this skill for mobile app and cross-platform client engineering. It covers Flutter, React Native, native Android, and native iOS. It does not own mini-programs, React web, backend service design, product requirements, or visual design rules.
+
+## Routing
+
+- Use `product-rd-workflow` first when the work spans product intent, architecture, design, implementation, testing, and release.
+- Use `product-ui-ux-design` before or alongside coding for user-facing surfaces, interaction model, visual hierarchy, density, motion, empty/error states, and accessibility acceptance.
+- Use `miniapp-product-dev` for WeChat/Alipay/Douyin/Baidu mini-program pages, host-platform APIs, developer tools, real-device preview, review submission, and miniapp release.
+- Use `web-react-dev` for React web and browser-specific client work.
+- Use Go or Python backend skills for server contracts, persistence, queues, auth services, and API ownership.
+- Use `testing-strategy` to choose the test layer; return here for Flutter, React Native, Android, or iOS implementation details.
+- Use `test-artifact-management` when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
+- Use `defect-diagnosis` first for bugs, failed tests, flaky behavior, crashes, rendering regressions, build failures, or store/release symptoms.
+- For money, quota, permission, tenant/user data, high-impact AI, repeated submit, async finality, or support-traceable incidents, apply `product-rd-workflow` high-risk resilience gates before treating the app flow as complete.
+
+## Core Workflow
+
+Before editing app code, native project files, platform configs, styles, assets, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-screen change can use a short inline plan; multi-platform, user-visible, API-visible, native-capability, release/store, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, design checkpoint, target-device matrix, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to design, testing, backend, release, or diagnosis skills before edits.
+
+Repo-local agent contracts (`AGENTS.md` at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per `product-rd-workflow`'s spec / repo-contract sync gate.
+
+When checking a cross-platform app against team standards, split conformance into deterministic and agent review evidence. Deterministic checks cover build flavors/schemes, package locks, generated API/IDL client usage, environment/lane config, unit/widget/instrumented/E2E commands, CI gates, signing/release config, and request/trace identifiers in central clients. Agent review checks cover screen/module boundaries, platform abstraction leakage, native bridge contracts, finite-value mapping, device evidence quality, and whether tests prove the shipped runtime paths rather than only mocked widgets. For the per-substack deterministic executor list (each analyzer is its own toolchain with thin defaults — `dart analyze`+`flutter_lints` with `analyzer>errors:` severity escalation, detekt `coroutines`/`exceptions` inactive rules, SwiftLint opt-in safety rules, RN typed-ESLint) and the shipped client conformance checkers, see `testing-strategy/references/fitness-functions.md` §4.1.3 (client language-basics; spec 006). Layering/dependency-direction has no out-of-box rule on any substack — express it as import-ban config (Konsist/ArchUnit/custom_lint/dep-cruiser).
+
+1. Resolve the target app shape.
+   - Flutter shared app, React Native app, native Android, native iOS, or mixed native plus shared module.
+   - Target devices, OS versions, form factors, app-store constraints, and native capability needs.
+   - Whether the feature is shared across platforms or intentionally platform-specific.
+
+2. Analyze the existing client surface.
+   - Locate the owning feature/module, route entry, state owner, API client, local storage, platform adapter, and tests before editing.
+   - Identify shared behavior versus platform-specific behavior; list which platforms must be changed and verified.
+   - Read local wrappers first: Flutter/Gradle/Xcode scripts, package managers, CI jobs, test targets, flavors/schemes, and generated files.
+   - If a design exists, map each visible state and interaction to code ownership before implementing.
+   - For any visible UI change, map the design checkpoint to code ownership: aesthetic hierarchy/density, interaction flow, behavioral feedback, user psychology, safe-area/keyboard/orientation adaptation, and device screenshot acceptance. Also record `product-ui-ux-design`'s implementation-owner checkpoint before the first edit — its field list (design/stack/test owners, entry-rule evidence, rendered/device evidence status) and copy-only path are authoritative there; load the named owner skills rather than only naming them, and treat a completion claim without `captured/verified` rendered evidence as incomplete — an explicitly accepted gap closes the slice only as `pre-runtime-test ready` / handoff, never as complete/done.
+   - For UI/UX redesign slices meeting `product-ui-ux-design`'s page-slice trigger conditions — that gate's trigger list is authoritative and must be checked, not paraphrased, whenever a screen/surface change could be a redesign, restyle, new-style declaration, structural/visual-system change, continuation, or redesigned-surface reference — apply its cross-stack page-slice gate before framework mechanics: RED-first focused assertion, IA regrouping by user intent/consequence, behavior-contract preservation, state matrix, rendered evidence, and the design verdict (`accepted` / `rejected` / `pending`; missing = `pending`, and `design-rejected` blocks complete/MR-ready/normal/draft MR per the **Rejected-surface rule**). Translate examples from other stacks into the target app runtime instead of copying Flutter-, Android-, iOS-, or Web-specific commands as the method itself.
+
+3. Define the client boundary before coding.
+   - Screens, routes, tabs, navigation stack, deep links, and back behavior.
+   - UI state owner, domain/data state owner, and source of truth.
+   - API client contract, request cancellation, retry, auth/session behavior, and error mapping.
+   - API observability: central clients should attach or preserve request/trace/operation identifiers, measure duration, distinguish cancel from failure, classify upload or long-running requests, and map backend envelopes into typed user-facing errors.
+   - Finite-value boundary: generated API enums, backend string codes, deep-link params, local cache values, analytics dimensions, and native bridge payload codes should flow through one typed client/domain mapping module. Screens/widgets should use mapped symbols and label tables instead of scattering raw values such as `"US"`, `"CN"`, `"active"`, or `"default"` across render, storage, routing, or tracking code. If shared client-domain ownership is unclear, keep a local mapper for the slice, mark temporary duplicate/raw uses with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, and record the consolidation owner. Architecture owns the cross-stack semantic decision when the same value must align across app, web, mini-program, backend, storage, and analytics.
+   - Local persistence, offline/cache policy, invalidation, conflict handling, and sync triggers.
+   - Platform capabilities such as camera, files, notifications, background tasks, payments, share sheet, sensors, biometrics, and permissions.
+   - Observability: crash reporting, analytics events, logs, performance traces, and feature flags.
+   - High-risk submit/finality behavior: duplicate tap protection, request cancellation semantics, offline/foreground recovery, durable pending/final states, retry rules, and a visible tracking identifier when support or reconciliation may be needed.
+
+4. Keep architecture boring and inspectable.
+   - Keep view/widget code thin; move data loading, validation, command handling, and mapping out of render code.
+   - Use unidirectional data flow where practical: user action -> intent/command -> state update -> render.
+   - Separate transient UI state from durable domain/data state.
+   - Keep typed API clients and explicit error envelopes; do not let raw transport errors leak into UI copy.
+   - Isolate platform-specific code behind adapters, plugins, protocols, or modules.
+   - Treat route/deep-link behavior as a public contract with tests or smoke verification.
+
+5. Implement by platform.
+   - Codegen regeneration discipline (cross-stack — Flutter `build_runner`/`freezed`/`pigeon`, Android KSP/Hilt/Room/Moshi, iOS `Sourcery` and other accessor/mock generators): never hand-edit pure generator-owned files (mark them `// DO NOT EDIT`; they regenerate freely *only when their working copy is clean/committed* — a dirty or untracked generated file may hold local edits a regen would silently restore over, so it gets the same preimage snapshot/diff/approval as below) — put customization in extension points / handwritten files beside the generated code. A file that is generated once and then hand-maintained is a *different* class: mark it explicitly `FROZEN` / `HAND-MAINTAINED` (not `DO NOT EDIT`, which a reader treats as regenerate-freely), exclude it from normal regeneration, and overwrite it only on explicit request through the preimage gate below. Edit the source of truth (annotations / IDL / `.proto` / templates) first, then regenerate. Do not overwrite a hand-maintained or user-edited file on regeneration without an explicit request, and gate that overwrite on the *pre-overwrite* preimage — generate to a temp/backup path, diff against the current file, and only replace after that diff is reviewed and approved (deleting the backup only once generation succeeds). Reviewing the git diff *after* an in-place overwrite is too late, and silently loses edits in dirty/untracked files. After a generator or toolchain *upgrade* (not just an input change) the emitted shape can change, so a cache key built only on input source can silently serve stale output — force a fresh, no-cache full regeneration and review the resulting diff against expected drift (clean/no-op is a valid outcome when the upgrade is semantically neutral; the point is that the regen actually ran rather than being skipped by a stale cache). Record the regeneration evidence (the command, that it ran fresh/no-cache, and the generated diff or an explicit no-op note) when the source-of-truth or generator/toolchain changed; when a shape change is expected *or* appears in the regenerated diff, also confirm the runtime/consumer reflects the new schema and, for a generated artifact carrying a version/schema stamp, that the stamp advanced — a clean `build` alone is not proof the regeneration ran. A shape change that appears unexpectedly in the diff is a stop-for-approval signal, not something to wave through because it was not anticipated. A parallel codegen-regeneration discipline exists for backend protobuf/IDL/DI codegen — load that skill for backend work, since this app-skill bullet does not gate backend codegen: `go-microservice-dev` owns the fuller set (never hand-edit generated, edit-source-then-regenerate, guarded-backup before overwrite, fresh-regen smoke for generator-shape changes, regenerate-and-verify); `python-service-dev` owns the core (never hand-edit generated clients/protobuf, update source contract then regenerate, verify generated output is clean or intentionally reviewed).
+   - Flutter: use feature-first modules when the repo allows it; keep widgets declarative; choose state management from the existing repo pattern; isolate platform channels and plugins; test with unit, widget, golden/screenshot when available, and integration tests for critical flows.
+   - React Native: keep navigation, storage, native modules, permissions, image/media pickers, and platform branches behind repo-owned adapters. Verify both JS behavior and native module availability on the affected iOS/Android target; do not treat a Metro bundle running as proof that the native capability works.
+   - Flutter platform scaffolds: after `flutter create` or adding a new target platform, inspect generated noise before committing. Preserve existing `.metadata` platform entries, align bundle/package identifiers and display names across platforms, and keep generated/local files such as IDE module files, Flutter generated configs, ephemeral debugger files, and generated plugin registrants ignored unless the repo explicitly tracks them.
+   - Android: follow UI/data layer separation; use ViewModel or state holders for screen state; hoist Compose state; collect lifecycle-aware state; keep repositories as data boundaries; use WorkManager or platform APIs for background work when needed.
+   - iOS: use SwiftUI for new UI unless the repo is UIKit-first; keep views data-driven; use State/Binding/Observable-style ownership deliberately; isolate URLSession/client code; use async/await where it matches the repo; bridge UIKit only behind clear boundaries.
+   - iOS simulator setup: do not treat a successful platform download as proof that Xcode can build. Verify runtime registration and destination discovery with `xcrun simctl list runtimes -j`, `xcrun simctl runtime list`, `xcodebuild -showBuildSettings -destination ...`, and, when storyboard or asset compilation fails, a minimal `xcrun ibtool` reproduction. If Xcode reports that the iOS platform is not installed while `simctl runtime list` shows duplicate or unusable runtime images, remove only the unusable duplicates with `xcrun simctl runtime delete`, then run `xcrun simctl runtime scan-and-mount` and recheck before changing app code.
+   - H5/WebView or hybrid app surfaces: initialize bridge capability explicitly, gate debug tooling to development builds, model auth/session cleanup across native and web storage, and verify gestures, safe area, keyboard, orientation, image preview, and floating toolbars on the target devices.
+   - Native WebView shells need a written shell contract: initial route and launch/consent gate, injected app info, JS bridge handler names and callback semantics, native/web storage sync, permission flows, loading/error/retry surfaces, back/edge-swipe behavior, orientation lock/unlock, network-state recovery, and update/download/install states.
+   - JS bridge handlers are API contracts. Validate input payloads, keep callback ids scoped and cleaned up, return terminal success/cancel/failure states, avoid exposing broad native capabilities, and make handler availability detectable from the web side.
+   - App-hosted web surfaces need lifecycle state rules: foreground/background save and restore, TTL or expiry, sensitive-field handling, session invalidation, public/guest access modes, and recovery when the native bridge or injected app info is missing.
+   - App-hosted web surfaces should use full-screen containers by default and add max-width/device frames only for intentional preview modes. Bottom tabs, sticky actions, overlays, and toasts must respect safe-area insets from the native host when available and fall back predictably in browser or iframe contexts.
+   - App startup/auth shells need an explicit sequence: native splash or fake launch screen, first-run privacy/terms gate, web content load, login/account-opening or session restore, and deterministic handoff to the first tab. Do not initialize optional background listeners or broad native capabilities before consent and shell readiness; do not enable debug overlays or debug menus in production builds.
+   - Foundational app shells need a written app-state contract across native and web: splash timeout, consent persistence, initial route, bottom-tab ownership, guest/authenticated session, verification restore, web/native cache keys, logout/delete cleanup, privacy/legal document routes, about/version/update state, network/load retry, and production debug gating.
+   - The native shell should treat login, home, profile, privacy, and about as one launch-to-account system. It owns splash or fake-launch timing, first-run privacy gate persistence, WebView/WKWebView readiness, app-info injection before web layout depends on it, native storage get/set/remove/clear, network-error retry, back/edge-swipe behavior, update handoff, and debug/diagnostic gating; the hosted web owns auth modes, verification, home modules, profile routes, and legal document rendering.
+   - When logout, guest exit, account deletion, or identity reset succeeds, clear both hosted-web state and native shell state where present. Verify that the next launch cannot reuse stale WebView storage, stale injected account metadata, or an old first-tab route.
+   - Account-opening or binding in an app-hosted flow is conditional on the product contract. When present, the web layer owns validation, consent, verification, first-login password setup, and user-visible copy; the native shell owns app info, storage sync, privacy gate, and post-auth cache/session handoff. New-user account creation must not hide required setup or recovery states behind server side effects.
+   - Verification and password setup flows need native-container resilience: masked destination, resend countdown, paste/autofill support, focus and Backspace behavior, foreground/background restore with sensitive-field handling, expired restore cleanup, and a deterministic route after success or failure.
+   - Keyboard avoidance must distinguish visual-viewport resize, overlay mode, Android legacy behavior, and iOS native behavior. Keep the active input and submit/retry action visible; reset padding/translation on blur, orientation changes, and route exit.
+   - Orientation changes are platform capability flows, not CSS toggles. Model enter, exit, failed bridge call, iframe/postMessage fallback, browser-only instruction, state sync, cleanup on unmount, and route-level return-to-portrait behavior.
+   - Async content shells need stable loading, error, retry, empty, and children geometry. Put retry inside the failed content region, not only in a toast, so users can recover without losing route or scroll context.
+   - Mobile UI must treat safe area, keyboard, orientation, foreground/background, weak network, and app restart as first-class UX states, not late bug fixes.
+   - Mobile forms running in WebView need platform-aware input handling: paste, deletion, cursor restoration, old Android WebView fallback, iOS WebKit duplicate or delayed input behavior, focus/blur reformatting, and keyboard-safe submit reachability.
+   - Media, upload, scan, review, or annotation flows: cover permission prompts, selected asset state, upload/progress/failure, preview/zoom/pan/reset, retry/cancel, foreground/background recovery, and final status rather than only a success toast.
+   - Microphone or speech-capture flows need a native capability lifecycle, not only an input widget.
+     - Lazy-load native audio modules so app startup does not freeze or prompt for permission before intent; probe by actually opening a capture path rather than checking that a binary, bridge, or permission string exists, discard probe bytes, keep probes out of transcription/model-visible paths, and stop the probe recorder even after partial initialization failure.
+     - Distinguish unsupported remote/headless environments, no device, permission denied, silent input, connection failure, unsupported language, and speech-not-detected states.
+     - Cross-platform fallback chains must match the real start path, consume subprocess/native error streams to avoid backpressure, stop every active recorder on release, blur, cancel, retry, or unmount, and fence callbacks by session generation so stale audio or transcripts cannot update a newer input.
+   - AI media-extraction flows need a staged client state machine: capture/import, crop/preview, upload, analyze, render generated content, classify/tag, save/publish, retake, and retry. Keep final commit disabled until required generated content and metadata are valid, and isolate rich-content renderer failure from the rest of the screen.
+   - Camera/media capture launched from WebView must not assume success just because the native picker opened; model native capability, returned object key/URL, and web callback recovery as a contract.
+   - Native capture launched from hosted web should be a two-phase finality contract: native success means an asset key or URL was produced; the hosted destination route still owns metadata validation, save/publish, page-ready acknowledgement, and final user feedback.
+   - Native camera capture for document/image extraction needs preview-final parity. If the user sees a processed crop, the uploaded bytes should use the same crop coordinates, orientation correction, color-space normalization, binarization/enhancement class, and size budget. Do not show a clean preview and upload a materially different image.
+   - Media processing pipelines need guardrails, not only filters: EXIF/upright normalization, crop rect clamping in normalized coordinates, aspect-ratio alignment between preview and final output, all-black/all-white detection, output-size backoff, and logs that expose ratios/bytes/timing without leaking credentials.
+   - WebView-launched native capture should keep old and new bridge contracts isolated. Use versioned handler names or explicit capability detection, scoped callback ids, terminal `success/cancel/failure` states, parseable JSON payloads, and page-ready or transition-cover cleanup so the web layer never depends on a hidden native screen finishing silently.
+   - Capture overlays should be owned by the native shell until the hosted page confirms readiness. Add an automatic timeout as a recovery guard, but treat the page-ready callback as the normal completion path.
+   - Native camera screens need stable full-screen geometry: safe-area back, dominant preview/crop area, bottom bar reserved for secondary import, centered shutter/confirm, and device tool such as torch or rotate. Do not resize the primary image area when loading, focusing, or toggling tools.
+   - Upload configuration and token selection should be runtime-configurable behind a coordinator or adapter with a conservative fallback. Log chosen config, object key, byte size, and token shape only in redacted form; do not require an app restart for bucket, endpoint, or signing-version changes when the product expects remote switching.
+   - Camera UX must cover real device craft: tap-to-focus or focus pulse where supported, torch availability and unsupported feedback, album fallback, visible taking/uploading overlays, retake path, permission temporary versus permanent denial, unavailable hardware, settings handoff, upload/token failure, and disabled controls while capture or upload is in flight.
+   - iOS and Android may need different media hardening, but the product contract should stay aligned: upright orientation, color-space normalization where needed, crop bounds clamping, preview/final parity, size budget/backoff, redacted diagnostics, and terminal callback cleanup on both platforms.
+   - Native app update flows need visible download progress, failed-token/download/install states, install-permission handling, cancel/retry, and platform-appropriate update path. Treat "open store" and "download APK then install" as different contracts.
+   - Mobile home, list, and insight surfaces need independent state ownership per module: initial skeleton, section-level error/retry, search debounce, pull-to-refresh, infinite scroll, no-more state, pending-versus-committed filters, and keyboard-safe bottom sheets.
+   - App-hosted mobile insight/report surfaces need separate owners for report context, metadata cache, data cache, filter state, advanced settings, card state, native-shell state, and scroll state. Do not let a global store or stale cache silently override an explicit route scope.
+   - When the same insight/report is reachable from a home summary and a bottom-tab list, define one entry contract: home shortcut, tab list, detail page, drilldown, and back behavior must share the same report id, scope, filter precedence, and stale-cache rules.
+   - For report filters, merge route, stored state, metadata defaults, and permissions in that order unless the product defines a stricter source of truth. Preserve explicit all-scope sentinels; never collapse them into `undefined`.
+   - For module data refresh, merge by affected module. A shorter or permission-limited response should not overwrite fuller cached context unless the scope genuinely changed. Setting changes should show card-level loading instead of full-page reload where feasible.
+   - Dense app-hosted tables need fixed headers or context columns, dynamic grouped columns, visible sort state, horizontal scroll affordance, load-more throttling, and in-table loading/error/empty overlays.
+   - Analytics scroll restoration should wait for stable layout height, clamp to current scroll bounds, abort on user wheel/touch, handle storage failure, and clear on filter, route, or context changes.
+   - Native shells that host mobile reports need a first-class contract for launch/consent, injected app info, status-bar and safe-area values, bridge capability detection, native storage get/set/remove/clear, network/load failure retry, back-stack behavior, orientation lock/unlock, update handoff, and shell overlay return to the originating page.
+   - For app-hosted report/detail pages, H5/Flutter owns context, metadata, filters, card state, chart/table rendering, drilldown routes, and module refresh; the native shell owns WebView/load retry, safe area/status injection, native storage, back gesture, orientation lock/unlock, and overlay page-ready cleanup.
+   - For app-hosted resource or asset-library entries, distinguish the shell from the library. The native shell owns WebView load/error/retry, injected app info, safe area/status values, native storage, bridge capability detection, update/download handoff, orientation/back behavior, and page-ready overlay cleanup. The hosted web or H5 route owns resource metadata, save/share/download/preview state, and final user feedback.
+   - Do not infer a native resource manager from a hosted save-to-library or upload entry. Add native file/download/share capabilities only when the target platform code exposes a scoped handler, permission flow, callback semantics, and recovery state.
+   - Do not initialize broad listeners, background recovery, debug WebView inspection, or optional native capabilities before consent and shell readiness. Production builds must gate inspectability, verbose logs, and bridge debug output.
+   - Bridge callbacks must be terminal and scoped: validate payloads, store callback ids per handler or request, return success/cancel/failure where relevant, remove callbacks after completion, and expose a page-ready acknowledgement for native overlays that wait for web route mount.
+   - Mobile precision workspaces need explicit runtime state for retryable media, zoom/pan, selected item, task switcher, progress counters, custom numeric/keypad input, invalid value feedback, handedness or control placement, persisted settings, and portrait/landscape composition differences.
+   - Mobile precision workspaces need a written state contract before implementation: route/context ids, task-source state, selected item or selected batch, cached task batch, cached media, persisted user preferences, context preferences, item-scoped geometry/scale, timer or quality gates, shell orientation state, and exit/unlock behavior.
+   - Precision media should avoid blank swaps: prioritize current-screen preloads, limit background preload concurrency, wait for image decode or readiness before replacing the displayed artifact, keep the previous artifact visible during load, provide in-region retry after automatic retry, and remove committed artifacts from memory/cache.
+   - Pan/zoom surfaces should use refs or imperative transforms for high-frequency pointer updates when the WebView would jank under render-loop state updates. Coordinate pinch, wheel, pan, tap, and page-swipe blocking explicitly, and persist only normalized scale values that can be cleared safely on item or orientation changes.
+   - Precision submission must be idempotent and explainable: block duplicate taps, submit only changed or still-pending items when possible, handle unprocessed-item defaults through an explicit confirmation policy, validate minimum time or quality gates before commit, clean cache after success, and recover from locked, completed, expired, permission, or no-work responses without losing route context.
+   - App-hosted precision workspaces need a native-plus-H5 route contract: the H5 route owns selected item, selected batch, task-source state, cached work, media readiness, scoring/input state, settings scope, final submit, and exception dialogs; the native shell owns orientation, WebView loading/error/retry, injected app info, storage bridge, back gesture, and page-ready or overlay cleanup.
+   - Orientation for precision work is a shell contract. H5 should request orientation through capability-detected bridge calls, skip no-op iOS rotation calls when they would hang, fall back to iframe or browser guidance where needed, clear measured geometry on rotation, and return to the expected portrait/default orientation on exit after the route has saved or unlocked state.
+   - Precision work must survive slow networks and repeated entry: distinguish cache hit, loading, stale, expired, retrying, and final states; keep user-visible context while refreshing; and map transport, permission, lock, expiry, and invalid-input failures to local copy and recovery controls.
+   - Accessibility is part of the implementation contract. Verify touch target size, focus order, programmatic names for icon-only controls, screen-reader labels for compact toolbars, text scaling, contrast, reduced-motion behavior, and keyboard/safe-area reachability for primary and recovery actions. Visible icon labels are not enough when compact modes hide text.
+   - App-hosted flows that can be interrupted need foreground/background restoration rules: storage scope, TTL, sensitive-field handling, route/context validation after restore, pagehide/pageshow/focus/blur coverage, and a visible stale-or-expired recovery path.
+   - Repeated-use mobile tools should separate local device state, user-scoped preferences, context-scoped preferences, and item-scoped preferences. Restore each layer independently, validate it against current permissions and available items, and reset only the invalid layer.
+   - Dense mobile data surfaces need deliberate landscape support: orientation request and failure guidance, dynamic table/canvas scroll bounds, fixed context columns when needed, search/filter/sort ownership, load-more thresholds, and cleanup back to the prior orientation on exit.
+   - Account deletion, logout-all, identity reset, or other high-consequence account actions need explicit disclosure loading, acknowledgement or cool-down gating, second confirmation, failure feedback, session/native-cache cleanup, and deterministic return to login or onboarding.
+   - Profile/settings shells need account/security, privacy, about/version, logout, and delete-account flows to coordinate native and web storage. A successful logout or account deletion should clear both web cache and native cache where present, then return to login/onboarding without leaving a stale WebView session.
+
+6. Debug systematically when behavior is wrong.
+   - Reproduce on the smallest affected target: device, emulator, simulator, preview, or focused test.
+   - Treat repeated device, emulator, simulator, Gradle, Xcode, CocoaPods, adb, or NDK blockers as app infrastructure defects, not fresh one-off environment gaps. If the same blocker appears again, fix or harden the setup script, readiness check, or toolchain pin before reporting the app test layer as unavailable.
+   - Classify the failure by layer: route/deep link, render/layout, state transition, API/client contract, cache/offline, platform permission/capability, build/signing, or release config.
+   - Inspect logs, crash traces, network payloads, lifecycle events, permission state, local storage, and feature flags before changing code.
+   - Prove the cause on each affected platform; do not assume a Flutter/shared fix covers native host behavior or store/runtime configuration.
+   - Add regression evidence at the lowest sufficient layer, then run broader device/build smoke based on risk.
+
+7. Verify on rendered surfaces.
+   - Run the repo's formatter, analyzer/linter, typecheck/build, and focused tests.
+   - **TC traceability**: Flutter/Dart tests link via `tcTest(['TC-XX-NNN'], 'desc', () { ... })` wrapper (registers at registration time, so `skip:` / `skipIf:` etc. still register correctly). Helper from `test-artifact-management/references/tc_helpers/tc.dart`, installed under `test/tc.dart`. Native Android/iOS use the language-appropriate wrapper convention (write a small helper that appends to `test/results/tc-map.jsonl`). See `test-artifact-management/references/tc-marker-conventions.md`. Before adding tests, `grep -rn 'tcTest.*"TC-[A-Z]' test/` plus the sidecar to check for existing coverage — extend rather than duplicate. When a TC is marked 废弃, grep both source and sidecar for that TC ID; follow deprecation cascade in `testing-strategy`. Tests without any `tcTest(...)` / equivalent helper call: prompt user only when the underlying code is also removed.
+   - **废弃级联：业务代码是否仍在用** — 每端原生 + 跨端各有套路：
+     1. Flutter / Dart：`grep -rEn "import ['\"]package:<pkg>/<file>|import ['\"]\.+/<file>" lib/`；运行 `dart analyze` 看 unused-import warning；路由表 `MaterialApp.routes` / GoRouter 配置内未注册的页面可删
+     2. Android（Kotlin/Java）：`grep -rn "import .*<class>" app/src` + `./gradlew lintDebug` 看 UnusedResource / UnusedSymbol；AndroidManifest.xml 内未注册的 Activity/Service 实际不会被启动
+     3. iOS（Swift/ObjC）：`grep -rn "import <module>\|<ClassName>" ios/`；Xcode 的 dead-code-stripping 报告；Storyboard / XIB 引用 grep `.storyboard` 与 `.xib`
+     4. 边界：跨端项目（KMM / 桥接代码）每层独立判，删一层不代表另一层也死；反射 / runtime 注解（Android）/ Objective-C runtime（iOS）grep 抓不到，需运行时验证
+   - Inspect the screen in a real device, emulator, simulator, preview, or captured screenshot for any visible UI change.
+   - For UI/UX redesign evidence, include the target device/form factor, safe-area, keyboard, orientation, dynamic type/text scale, loading/empty/error/final states, and a screenshot or equivalent rendered artifact; mark each dimension covered or `N/A` with a one-line reason. `N/A` is valid only when the reason names a verifiable structural fact, explains why that fact makes the dimension unreachable or unchanged for this slice, and includes a checkable pointer such as a file path, config key, or commit that resolves at review time. Also record the design verdict (`accepted` / `rejected` / `pending`) from a user or named independent design-owner review per `product-ui-ux-design`'s page-slice gate; a missing or absent verdict counts as `pending` and blocks complete/MR-ready exactly like a missing dimension — the screenshot alone is never acceptance. Persist evidence artifacts where reviewers can access them using sanitized/test accounts and redacting tokens, PII, credentials, private paths, and raw personal data; remove temporary smoke files or scripts before commit unless the repo intentionally owns them.
+   - In approval-sensitive runtimes, do not create a new one-off smoke file for every screenshot or slice. Prefer a repo-owned smoke harness, existing integration test, debug route, fixture flag, deep link, or already-created slice harness; if a temporary harness is genuinely unavoidable, reuse one stable harness for the whole batch, mutate it minimally, and explicitly delete it before commit (a throwaway harness is evidence scaffolding, not shippable code; verify it is gone in the pre-commit diff) unless the repo intentionally owns it. Repeated edit-approval prompts from throwaway helper files are an execution defect, not normal evidence collection.
+   - Capture Android evidence as approval-friendly single commands. In environments where command-prefix approval is used, do not combine `adb` with shell pipes, `>`, `>>`, command substitution, `&&`, or local filtering in the same command; those forms are split or de-scoped by the approval layer and can re-trigger prompts even when `adb` itself is approved. Use sanitized/test fixture screens, then run three standalone commands: `adb -s <serial> shell screencap -p "/sdcard/<artifact>.png"`, `adb -s <serial> pull "/sdcard/<artifact>.png" "<repo-evidence-path>/"`, and `adb -s <serial> shell rm "/sdcard/<artifact>.png"` in cleanup even when pull fails or the run aborts. Generate `<artifact>` from a safe basename alphabet (no spaces, globs, or path separators) and quote the `/sdcard` path in every command so `rm` targets exactly the file you created, and create the destination with `mkdir -p <repo-evidence-path>` before pulling. Never write credential, PII, account, or otherwise sensitive real-user screens to `/sdcard`; redact or fixture first. If the environment explicitly pre-approves shell redirection for `adb`, `adb -s <serial> exec-out screencap -p > <repo-evidence-path>/<artifact>.png` is acceptable and avoids device-side storage, but the transcript must record that redirection is approved for that command shape. Either way, validate the captured file is a non-empty valid PNG before relying on it: a failed pull, or an empty/zero-byte `exec-out` stream, means there is no host artifact — retry rather than counting it as evidence.
+   - A mobile screenshot that proves the app rendered is not automatically design acceptance evidence. If the design owner or page-slice review rejects the captured surface for weak hierarchy, blank-feeling composition, generic patched layout, clipped safe-area/keyboard behavior, or mismatch with the design checkpoint, route back to `product-ui-ux-design`'s **Rejected-surface rule** and re-capture after redesign; the app implementation waits on that design verdict instead of self-adjudicating taste. A technically successful but visually failed smoke leaves the slice `design-rejected` — blocking complete, MR-ready, and any normal or draft MR until the re-rendered surface is accepted, not only the completion claim.
+   - For platform enablement, verify each newly added platform with a real platform build and an install/run smoke on the relevant emulator or simulator. Adding the host project or passing one platform does not complete the slice; record the platform targets, commands, and screenshot or runtime evidence.
+   - For mobile runtime changes, device/emulator/simulator smoke is a completion gate when lower layers cannot prove the behavior. This includes changes to native capabilities, WebView/native bridge callbacks, foreground/background recovery, orientation/safe-area/keyboard behavior, storage/session restore, route/deep-link behavior, upload/media flows, permissions, and rendered loading/error/final states. If the runner is missing, first attempt normal setup; if still unavailable, stop at `pre-runtime-test ready` or `blocked` and name the owner, attempted commands, residual risk, and next unblock action. `pre-runtime-test ready` is handoff-only, not merge-ready, release-ready, or complete.
+   - For emulator readiness scripts, do not trust process launch or boot log text alone. Confirm the runner sees the target device, then verify direct device state such as `adb devices -l`, `adb -s <serial> get-state`, and platform boot readiness before calling Android ready; keep the serial in the output so later E2E commands target the same device.
+   - If the app or app-hosted H5 CI only builds or deploys packages, treat that as structural release evidence, not functional proof. Interaction, permission, lifecycle, upload/media, and recovery changes still need focused assertions plus rendered device or host-container smoke.
+   - Check accessibility labels, dynamic type/text scale, focus order, screen reader reachability, contrast, and touch targets.
+   - Check startup impact, scroll/frame stability, image loading, memory, app size, and network failure behavior when relevant.
+   - For release work, verify signing/flavors/schemes, environment config, store metadata implications, crash reporting, rollback/feature flag path, and smoke path on installable builds.
+
+## Non-Negotiable Rules
+
+- Do not treat one platform passing as proof that all platforms pass.
+- Do not let reorderable, insertable, or filterable lists fall back to array-index identity. React Native `FlatList`/`SectionList` derive the key from `item.key` then `item.id` and only then the array index — so provide an explicit `keyExtractor` (or a stable `item.key`/`item.id`) whenever items lack a stable id; Flutter list children need a `ValueKey`/`ObjectKey` on stable item identity. Without a stable key a reorder/insert/delete makes the framework reuse element state on the wrong row (scroll offset, `TextField`/`TextEditingController` contents, animation progress, and selection/checkbox state bleed across rows, and inline `dispose` can hit the wrong element). Same reconciliation class as the web index-key rule.
+- Do not call a Flutter platform scaffold complete until generated/local files have been reviewed, platform identifiers are aligned, and the target platform has fresh build plus runtime evidence.
+- Do not hide a platform-specific failure by weakening shared behavior unless product explicitly accepts the difference.
+- Do not add live network, credentials, or store-only dependencies to default fast tests.
+- Do not ship UI changes without rendered inspection when the change affects layout, hierarchy, interaction, or visual state.
+- Do not manufacture rendered evidence through repeated one-off temporary smoke files when an existing route, test, debug entry, fixture, or reusable harness can reach the same screen. Batch or reuse the harness and keep evidence collection inside the least-noisy approved command path.
+- Do not add platform permission prompts, background work, biometric/payment flows, or push/deep-link behavior without explicit user-facing state and failure handling.
+- Do not ship app-hosted H5/WebView UI with production-visible debug consoles, unbounded keyboard/layout fallbacks, or untested safe-area/orientation behavior on the target container.
+- Do not ship debug-only instrumentation — debug bridges, in-app state/inspection servers, dev overlays/menus, network inspectors, verbose-token/remote-debug hooks, or mock-auth/bypass surfaces — in any build that can reach real users, real auth, or real PII (App Store/Play production AND TestFlight, enterprise, dogfood, internal/closed testing, staged rollout — scope by channel + data sensitivity, not an `isProduction` enum). Exclude it from the release dependency/target (not a runtime flag), and verify on the exact signed artifact per channel/variant with a release-blocking evidence row (digest + variant matrix + check output); a symbol grep alone or a manual pre-release removal is not the guard. See `references/mobile-quality-release.md` Release Readiness.
+- Do not rely on CSS safe-area variables alone when the host app can inject physical status-bar or bottom-inset values; normalize them by device pixel ratio and verify iOS, Android, iframe, and browser fallbacks where applicable.
+- Do not ship high-risk app actions with only optimistic UI or generic toast/error surfaces; users must be able to tell whether the operation is pending, succeeded, failed, retryable, blocked, or needs support after weak network, app restart, or foreground recovery.
+- Do not treat a mobile API client as done until empty response, invalid JSON, non-2xx envelope, auth expiry, network failure, cancellation, and backend error message extraction are covered at the client or screen boundary when relevant.
+- Do not scatter backend enum/string literals through app screens, deep links, native bridge payload handling, storage, analytics, or tests. Centralize finite-value parsing, display labels, defaults, and unknown-value behavior at the API/client-domain boundary, and keep raw literals only in clearly named boundary conversion tests that cover every known external value plus unknown/default behavior. Migrate existing non-boundary test raw literals for that value in the same pull request or mark each remaining use with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, even when the current slice does not introduce a new mapper.
+- Do not debug app failures from code inspection alone when a runnable reproduction, trace, screenshot, or device log can be collected.
+- Do not claim a mobile client fix is complete without naming the platform targets that were verified. If required device/emulator/simulator smoke is unavailable after remediation, the status is `pre-runtime-test ready` or `blocked`, not complete.
+
+## Reference Loading
+
+- For source provenance, current extraction boundary, and keep/merge/discard decisions, read `references/source-evidence-map.md` when auditing or re-extracting this skill.
+- For joint extraction from Figma design source AND the mobile app workspace (with package class mapping, design-token cross-validation, deprecation-marker detection), read `../skill-extraction-workflow/references/two-source-extraction-pattern.md`. Use when both sources are available; produces aligned design + implementation rules with cross-source token validation.
+- For platform selection, shared-vs-native tradeoffs, and client boundaries, read `references/mobile-platform-boundaries.md`.
+- For Flutter architecture, state, navigation, platform channels, testing, performance, and release checks, read `references/flutter-dev.md`.
+- For native Android architecture, Compose, lifecycle, testing, quality, and release checks, read `references/android-dev.md`.
+- For native iOS architecture, SwiftUI/UIKit boundaries, state, accessibility, testing, performance, and release checks, read `references/ios-dev.md`.
+- For Kotlin Multiplatform (KMP) + Compose Multiplatform — adoption decision matrix, source-set hierarchy + expect/actual, iOS framework integration (direct / CocoaPods / SPM), Kotlin/Native runtime, Compose MP iOS Stable scope, code-reuse tiering, build/test matrix, platform-stability table — read `references/kotlin-multiplatform.md`. Required when evaluating shared logic across Android + iOS, or considering Compose Multiplatform iOS adoption.
+- For mobile testing, accessibility, performance, observability, and release readiness across platforms, read `references/mobile-quality-release.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "App Cross-Platform Dev"
+  short_description: "Build Flutter, React Native, Android, and iOS app client features"
+  default_prompt: "Use $app-cross-platform-dev to design, implement, test, or release a mobile app feature across Flutter, React Native, native Android, or native iOS."

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/android-dev.md

@@ -0,0 +1,92 @@
+# Android Dev
+
+## Architecture
+
+- Follow Android's common layer split: UI layer for rendering and user events, data layer for repositories/data sources, optional domain layer when use cases are reused or complex.
+- Keep screen state in ViewModel or a repo-approved state holder. Compose functions should render state and emit events rather than own durable business state.
+- Hoist Compose state to the lowest common owner that needs to read or write it.
+- Collect flows lifecycle-aware. Avoid leaking work across stopped screens.
+- Keep repositories as data boundaries for network, database, cache, and sync decisions.
+- **MVVM / MVI naming is rebrand, not contract** — the audit looks at: single source of truth (ViewModel / state holder owns durable state, no shadow copies), unidirectional flow (UI emits Intent / event → ViewModel produces new State → UI renders), side effects (navigation, toast, snackbar) routed through a one-shot event channel rather than re-emitted state. A repo that says "MVI" but mutates state directly from `@Composable` callbacks is closer to "scattered state with extra ceremony".
+- **Modularization is a tool, not a goal**: split into feature / API / platform-adapter Gradle modules when build-time / team-ownership / variant-isolation evidence justifies it. Module boundary's job is to prevent cross-feature direct dependency, duplicated network clients, and duplicated state holders — not to maximize module count. A monolithic `:app` is fine for small teams; a 40-module graph with two engineers is overhead.
+- **Coroutines + Flow are the default async substrate**: scope work to `viewModelScope` / `lifecycleScope` / `repositoryScope` (custom + `SupervisorJob`) — never `GlobalScope` in app code; expose state as cold `Flow` and convert to `StateFlow` / `SharedFlow` at the boundary that needs replay / sticky value; collect with `flowWithLifecycle(...)` / `collectAsStateWithLifecycle()` in UI so collection cancels off-screen. `LiveData` remains valid for older Java/Kotlin codebases but new code defaults to `StateFlow`. RxJava is acceptable in projects with deep Rx investment, not for new code.
+- **Compose strong skipping mode**: introduced experimental in Compose Compiler 1.5.4; non-experimental in 1.5.13; **enabled by default starting Kotlin 2.0.20**. When enabled, all restartable composables become skippable regardless of parameter stability, and lambdas are auto-`remember`-wrapped — the optimization "greatly increases the number of composables that the runtime skips during recomposition" per Android docs (docs do NOT publish a specific recomposition % win; APK size impact is +4kB on the Now In Android sample). For projects on Kotlin <2.0.20, opt in via `composeCompiler { enableStrongSkippingMode = true }`; for projects on 2.0.20+, verify lambda capture semantics did not change before assuming default-on is safe.
+
+## Platform Capabilities
+
+- Use platform components for background work, notifications, permissions, camera/media/files, and app links when the feature needs OS-level behavior.
+- Model permission denied, permanently denied, unavailable hardware, interrupted background work, and app restore as explicit states.
+- Keep build variants, flavors, signing, min/target SDK, ProGuard/R8, and manifest changes reviewable.
+- **Android 14+ Foreground Service strictness**: every started foreground service MUST declare a `foregroundServiceType` in the manifest (missing → `MissingForegroundServiceTypeException`) AND declare the matching FGS permission in the manifest (`FOREGROUND_SERVICE_LOCATION` / `_CAMERA` / `_MICROPHONE` / `_DATA_SYNC` etc — these are NORMAL manifest permissions, auto-granted, not runtime-revocable). Per-type runtime prerequisites must ALSO be satisfied (e.g., `camera` FGS requires `CAMERA` runtime permission already granted; `location` requires `ACCESS_FINE_LOCATION` / `_COARSE`; `microphone` requires `RECORD_AUDIO`; `dataSync` has no extra runtime prerequisite). Missing prerequisites → `SecurityException`, not deprecation warning. Audit FGS start sites whenever permission, media, or sync code is touched.
+- **Android 15 (targetSdk 35) edge-to-edge default**: apps targeting API 35 render edge-to-edge by default; insets handling (system bar / nav bar / IME) becomes mandatory for every screen — windows no longer auto-pad. Run edge-to-edge / insets visual check on every screen with status-bar / nav-bar overlap before bumping targetSdk to 35.
+- **Baseline Profile + Macrobenchmark for startup-critical surfaces**: generate a Baseline Profile (Android Studio / `androidx.benchmark.macro` library) for launch + first-interaction paths; install it with the AAB so the included code paths are AOT-compiled at install time and avoid interpretation / JIT on first launch. Verify startup gains via Macrobenchmark, not by stopwatch.
+- **Splash Screen API (Android 12+, `androidx.core:core-splashscreen` backport to API 23+)**: stop hand-rolling a `SplashActivity` — the system splash is constructed from the app launcher icon + `windowBackground`. Migrate any custom splash to `SplashScreen` API; the compat library provides a consistent look across all supported Android versions. Use `setKeepOnScreenCondition` for the "wait for first data" pattern instead of an extra screen.
+- **Predictive Back enforcement timeline**: Android 14 (API 34) introduced predictive back as opt-in via manifest `android:enableOnBackInvokedCallback="true"`. Android 15 (API 35) removed the developer option — opt-in apps see system back-to-home / cross-task / cross-activity animations, but opting in remains required. **Android 16 (API 36): predictive back is default and enforced** for apps targeting API 36 — `onBackPressed()` is no longer called and `KeyEvent.KEYCODE_BACK` is no longer dispatched; migrate to `OnBackPressedDispatcher` / `OnBackPressedCallback` (View system) or `BackHandler` / `PredictiveBackHandler` (Compose). Temporary opt-out via `android:enableOnBackInvokedCallback="false"` exists but is announced to stop working at targetSdk 37.
+
+## Data Persistence
+
+- **DataStore (Preferences DataStore for key-value, Proto DataStore for typed schema) replaces SharedPreferences for new code**. SharedPreferences has a sync API that's unsafe to call on the UI thread, no error signal, no transactional API; DataStore is async (Coroutines + Flow), handles migration / corruption explicitly. Preferences DataStore is the SharedPreferences shape without the bugs; Proto DataStore adds schema + type safety via protobuf. For complex data with partial updates or referential integrity, use Room — DataStore is for small / simple datasets only.
+- **Sensitive credentials use the Android Keystore directly (or existing platform crypto APIs)** — Keystore manages keys in hardware-backed secure storage when available; never store raw tokens in regular SharedPreferences / files. The Jetpack wrapper `androidx.security:security-crypto` (`EncryptedSharedPreferences` / `EncryptedFile` / `MasterKey`) deprecated all APIs in 1.1.0-beta01 on 2025-06-04 (stable 1.1.0 on 2025-07-30); official direction is platform APIs + direct Android Keystore use — no Jetpack-wrapper successor. Existing projects on `security-crypto` migrate to direct Keystore + a project-owned crypto wrapper.
+
+## Dependencies And Toolchain
+
+- **KSP (Kotlin Symbol Processing) over KAPT**: Kapt is in maintenance mode and incompatible with the built-in Kotlin compiler plugin; the recommendation is to migrate. KSP is up to 2x faster on Kotlin-aware processors (no Java-stub generation step); for most libraries the migration is just renaming `kapt(...)` to `ksp(...)` in dependency declarations because the processor ships in the same artifact. Hilt, Room, Moshi, and most modern Android codegen libs support KSP. Stay on KAPT only for processors that have not shipped a KSP variant.
+- **`libs.versions.toml` (Gradle Version Catalog) for dependency declarations**: single source of truth for versions across multi-module builds; type-safe accessor generated by Gradle; dependency-update tooling reads the catalog directly. New modules should consume from the catalog, not declare versions inline.
+- **`androidx.startup` (App Startup library) for SDK initializer order**: replace ad-hoc `Application.onCreate` blocks with explicit `Initializer<T>` classes; declare dependencies between initializers so order is explicit; CI / build can verify the graph. Critical when multiple SDKs (analytics, crash, push, feature-flag) need init order.
+
+## Theme And Brand Color
+
+The shared design discipline (token sourcing, multi-platform alignment, source-vs-export rules, three-layer evidence) is owned by `product-ui-ux-design/references/multi-project-token-consistency.md` and `design-system-source-of-truth.md` — consult those before writing or auditing this section's implementation rules.
+
+Android-specific anti-patterns observed across native Compose subprojects:
+
+- **IDE / Material You scaffold colors left as dead-code declarations in `Color.kt` / `Theme.kt`**: new Compose modules generated by Android Studio ship with `Purple40 / Purple80 / PurpleGrey40 / PurpleGrey80 / Pink40 / Pink80` plus matching `lightColorScheme(primary = Purple40, ...)` / `darkColorScheme(primary = Purple80, ...)` blocks. When the team adds a brand `primaryColor = Color(0xFF<brand>)` and routes it through a separate `generateColorScheme(primaryColor, ...)` builder, the original Purple/Pink declarations and the scaffold `ColorScheme` vals usually stay in the file unreferenced. They are inert at runtime, BUT they confuse onboarding ("which is the real brand color?") and make later regex / search-and-replace refreshes ambiguous. Delete the unreferenced scaffold declarations once the brand color is wired; do not keep them "for reference".
+- **`AppTheme(dynamicColor: Boolean = true, ...)`-style dead parameter**: scaffold `@Composable` themes accept a `dynamicColor` flag intended to switch to `dynamicLightColorScheme(LocalContext.current)` on Android 12+. When the team overrides the body to call its own `generateColorScheme(brandColor, ...)` unconditionally and never reads the flag, the parameter becomes a footgun — callers think Material You is opt-in. Either honor the flag (branch on `Build.VERSION.SDK_INT >= S` and dispatch dynamic vs brand scheme) or remove the parameter; do not ship a no-op flag.
+- **Vendor-default literal leak in custom theme**: a brand theme that still contains literals identifiable as Google Material defaults — `Color(0xFFD93025)` (Google red), `Color(0xFF6750A4)` (Material You purple), `Color(0xFF03DAC5)` (Material teal), `Color(0xFF1976D2)` (MUI blue), `Color(0xFFBB86FC)` (Material light purple), etc — inside `errorColor`, `secondaryColor`, fallback values, or per-component overrides. Same pattern as the cross-stack rule in `multi-project-token-consistency.md` "Vendor-default literal leaked into a custom theme": the value looks deliberate because someone typed it, so generic literal-detection passes; but brand refresh skips it. Detection: grep the theme module for the per-version Material / MUI default palette values. A hit resolves to one of three classes per the shared rule: **leak** (replace with brand token), **deliberate documented reuse** (keep with rationale comment), or **legitimate convergence** (brand role independently resolves to the same hex — keep but reference the brand token, not the literal).
+- **Algorithmic secondary / tertiary derived from primary without designer sign-off** — applies to **custom** algorithmic derivation, NOT to standards-based Material You: patterns like `secondaryColor = Color.hsv(hue = (primaryColor.hue + 30) % 360, saturation = 0.8f, value = 0.9f)` or `SecondaryColor = primary.copy(alpha = 0.2f)` are custom derivations that skip the designer for every derived state. See the shared rule in `multi-project-token-consistency.md` Anti-Patterns. Acceptable IF the file carries a one-line provenance comment naming the algorithm and the designer sign-off date, AND brand-refresh QA includes a derived-color visual check. **Material You carve-out**: `dynamicLightColorScheme(LocalContext.current)` / `dynamicDarkColorScheme(...)` (Android 12+ wallpaper-derived) and standards-based `ColorScheme.fromSeed(seedColor = brandColor)` are acceptable as the design policy when documented with library/version, `DynamicSchemeVariant` if set, accessibility/contrast checks against the brand seed, and visual QA on canonical screens. Designer sign-off applies to the policy adoption + the seed/canonical-screen pass, NOT to every runtime-generated secondary/tertiary value (incoherent for wallpaper-derived schemes).
+- **Per-app duplicated brand literal vs shared design-token module**: when N native Android apps in one product each declare `val PrimaryColor = Color(0xFF<brand>)` in their own `Color.kt`, a brand refresh becomes an N-place edit and apps silently fall out of sync. The fix is a shared design-token Gradle module (or published artifact) consumed by every app — same pattern as the shared theme-package rule on the web side.
+
+### WebView-wrapper Android shells
+
+A native Android app whose main product flows are hosted in a `WebView` plus a thin shell of native helper screens (network error, photo upload, auth bridge, splash, settings) is a **hybrid WebView shell**. The audit verdict is per-surface, not per-app: WebView-hosted product flows route their brand audit to the loaded web app; native-owned shell screens (splash, login, settings, offline / network-error fallback, permission prompts, native modal flows, status-bar / safe-area chrome, deep-link landing) are audited as native surfaces with normal three-layer evidence.
+
+- Detection signals: small native source count relative to the app's apparent feature surface, `WebView` / `WKWebView` plus a JS bridge as the primary UI component, no Compose / View-system screens for the main product flows, vendor pods or AARs for JS bridging (`WebViewJavascriptBridge` and equivalents).
+- Reporting rule: the verdict is **per-surface, not per-app**. WebView-hosted product flows → `native-theme: not-applicable (webview-hosted, brand audited via loaded URL)`; native-owned surfaces in the SAME app (splash, login, settings, offline / network-error fallback, permission prompts, native modal flows, status bar / safe-area chrome, deep-link landing, updater dialogs) → `audit native brand tokens normally`. A whole-app `not-applicable` verdict is wrong whenever the app ships ANY native screen with brand-relevant chrome; that wording lets auditors skip visible surfaces blindly. Confirm the loaded web URL's brand alignment separately for the WebView portion.
+- Wrapper-specific risks that DO belong to native: WebView JS-bridge auth, file-upload / camera permissions plumbed through the WebView, status-bar / safe-area / system-back integration, deep-link handoff into the WebView URL, offline / network-error native fallback screen branding. Those still need native attention even when the visual brand lives in the web app.
+
+## Vendor AIDL Hardware Service Binding
+
+When the app runs on a dedicated / kiosk / vendor-supplied Android device and needs hardware capabilities exposed by a vendor-installed system service (printer driver, scanner, payment terminal, scale, RFID reader, OEM firmware control like timed power-on/off, silent install, status-bar display), the integration is via AIDL service binding to the vendor's service — not via root, not via `Runtime.exec`, not via fragile reflection on hidden APIs:
+
+- **AIDL interface is a contract artifact owned by the vendor, copied into the app under a documented license**: the vendor publishes the `.aidl` files (or an SDK that includes them); the app copies them into `app/src/main/aidl/<vendor-package>/` preserving the vendor's package path. Before the copy lands, confirm the vendor SDK's license permits source redistribution / inclusion (some vendor SDKs ship `.aidl` under a license that allows binary linking only; copying source into the app repo can be a license violation). Record per-binding: vendor name, SDK / AIDL source version, license, the vendor doc URL that authoritatively describes the methods. Vendor SDK updates rev the AIDL file; the contract version is a per-vendor track, not the app's version.
+- **One `ServiceConnection` per vendor service, with explicit handlers for ALL Binder lifecycle callbacks AND a circuit-breaker terminal state**: `<Iface>.Stub.asInterface(service)` runs on `onServiceConnected`. All four Binder lifecycle callbacks must be handled, each for a distinct failure mode: `onServiceDisconnected` (process killed by framework / OOM / firmware reboot) → reconnect; `onBindingDied` (the binding itself died, typical for vendor-service package update / OTA replace) → unbind + rebind, NOT just reconnect, because the dead binding never recovers without re-binding; `onNullBinding` (`bindService` returned non-null but the service returned `null` from `onBind` — the service is installed but refuses our identity, typical for signature-protected services) → fail-closed terminal "vendor service refused binding" state; explicit `false` return from `bindService` (component not present at all) → fail-closed terminal "vendor service not installed" state. Reconnect uses bounded exponential backoff AND a maximum-attempts / maximum-window circuit breaker (typical: stop after N attempts over T minutes); when the circuit opens, the binding enters a stable "vendor service unavailable" state until a package-replace broadcast (`ACTION_PACKAGE_ADDED` / `_REPLACED` for the vendor package) or explicit user action retries — silent infinite reconnect spams logs and battery without ever recovering.
+- **Wrap every AIDL call in `RemoteException` handling**: AIDL calls cross a Binder boundary and can throw `RemoteException` (vendor service died, transaction failed, parcel too large). Bubble these as typed errors with the vendor + capability name in the message (`<vendor>.<method> failed: <cause>`) so logs identify which vendor service was unreachable. Returning `null` silently from a vendor-service wrapper is the bug class that lets the hardware feature degrade unnoticed for weeks.
+- **Capability detection happens at binding time, not at call time**: when the binding succeeds, probe the vendor service's `getManufacturer()` / `getVersion()` / capability-discovery method once, cache the result, and expose `isAvailable(capability)` to callers. Callers gate UI affordances on `isAvailable`; they do not catch `RemoteException` per call as the availability check. Vendor services with no version probe are wrapped in a per-method capability map updated on each known-vendor revision.
+- **AIDL service binding is a `<service>` declaration in the vendor app, not in our app**: the binding target is a `ComponentName(<vendor-package>, <vendor-service-class>)` — verify the package + class in vendor docs before shipping. A `bindService` to a non-existent component returns `false` silently; check the return value and fail closed with a "vendor service not installed" state, NOT a generic "hardware unavailable" toast.
+- **USB-attached peripherals (printer, scanner) go through `UsbManager` + permission broadcast, not AIDL**: AIDL-bound vendor services are for OEM-firmware capabilities (timed boot, status bar, silent install). Plug-in USB hardware uses `UsbManager.requestPermission()` + a `BroadcastReceiver` for `ACTION_USB_PERMISSION` / `ACTION_USB_DEVICE_ATTACHED` / `ACTION_USB_DEVICE_DETACHED`. Mixing the two paths in one class is acceptable; conflating them in the rule is not — the auth model and the failure mode are different.
+- **Privileged AIDL methods (silent install, reboot, shutdown) require the device's vendor signature or platform permission**: confirm the privilege model with the vendor before the feature ships; an app distributed via Play Store generally cannot exercise `installPackage` / `reboot` against vendor services from third-party APKs. Ship the privileged path only when the device is vendor-flashed with the app pre-installed under the vendor's signature.
+
+## Shared-Device Inactivity (Compose)
+
+When the Android app runs on a shared device (kiosk terminal, counter staff terminal, intake tablet) and needs inactivity-driven session handoff: the **full cross-platform shared-device contract** lives in `web-react-dev/references/web-ui-quality.md` (Shared Device And Inactivity Session) — full input event set, throttled reset, durable shared timestamp, cross-tab/window coordination, terminal-to-neutral, deployment-context timeout split, server-side independent session expiry. A Compose implementation MUST satisfy the full contract, not only the local-timer subset; a `LaunchedEffect` + `remember` timer that ignores the durable-timestamp / cross-process coordination rules is the source-observed shorthand, NOT the rule. Compose-specific implementation guidance for satisfying the full contract:
+
+- The inactivity handler is a top-level `@Composable` that wraps the route content and exposes a `resetTimeout: () -> Unit` slot to children that need to register additional activity sources.
+- The countdown loop runs inside a `LaunchedEffect` keyed on the dialog-visible state; on dialog dismissal the effect cancels via standard coroutine cancellation — no manual cleanup needed.
+- Input event observation: pointer/touch events are observed via `Modifier.pointerInput` on the wrapping `Box`. Key events (hardware keyboard, DPAD, barcode scanner that emulates keypresses, remote control) need a focus-bearing root — `Modifier.onKeyEvent` only fires when the node or a focused descendant is focused, so the root must be `Modifier.focusRequester(focusRequester).focusable()` with a `LaunchedEffect { focusRequester.requestFocus() }` AND/OR the activity-level `dispatchKeyEvent` override forwards keys into the inactivity handler. The modifier order is significant: `focusRequester` must be applied BEFORE `focusable` in the chain — `.focusable().focusRequester(...)` reverses the wiring and `requestFocus()` silently no-ops, leaving the key-event capture broken. Without one of these, key-only activity (a user paging via DPAD on a kiosk remote) does NOT reset the timer and the app misfires the terminal action.
+- The shared-monotonic-timestamp cross-tab rule from the web side translates on Android to a durable shared store (`DataStore` / `SharedPreferences` / Room with `lastActivityAt` / `expiresAt`), updated by activity and re-read immediately before the terminal action. `BroadcastChannel` on web maps to a `BroadcastReceiver` (cross-process) or a process-level `Flow` (in-process multi-Activity / multi-Fragment). The durable store is authoritative; broadcasts are notification only — process restart, framework recreation, or backgrounded-Activity resumption all rely on re-reading the durable store, never on in-memory state.
+- Compose composition lifecycle differs from React unmount: a `LaunchedEffect` cancels on key change OR on the composition leaving — but Activity / Fragment lifecycle (foreground/background) and process death are separate dimensions. The terminal-to-neutral rule applies on process-resume (read durable `expiresAt`, terminate if exceeded), not only on composition recomposition.
+
+## Tests And Verification
+
+- Unit test state holders, use cases, repositories with fakes, mappers, validators, and error translation.
+- Compose/UI tests should assert visible states and interactions, not just launch screens.
+- Instrumented tests belong to flows requiring real Android framework behavior.
+- Verify app links, notification opens, permission prompts, process death/state restore, and offline/cache behavior when touched.
+- **Test tooling stack**: JUnit 5 (`useJUnitPlatform()` in Gradle) for new **local JVM** unit tests; instrumented (`androidTest`) tests still run on the JUnit 4 runner by default unless extra setup is added (e.g., `de.mannodermaus.junit5`). MockK for mocking (Kotlin-native, supports coroutines + extension functions / final classes that Mockito needs special config for); Robolectric for JVM-side Android-context tests (faster than instrumented but not a substitute when real Android framework behavior matters); Turbine for `Flow` / `SharedFlow` testing (manages collection lifecycle + assertion-on-emission). Screenshot regression goes through Roborazzi (JVM-based, Robolectric-style) or Paparazzi (LayoutLib-based, no emulator) — scope to design-system primitives and visually-risky surfaces, not every screen.
+
+## Quality
+
+- Check startup time, frame stability, list performance, memory, image loading, network failures, accessibility labels, touch targets, contrast, and font scaling.
+- Prefer existing Gradle wrappers and CI tasks over raw commands.
+- **StrictMode + LeakCanary as dev/staging guardrails**: enable `StrictMode.setThreadPolicy` (detect disk / network on main thread) and `setVmPolicy` (leaked closables / cursors / activities) in debug builds — Strict findings are violation-class evidence of bugs that ship unnoticed. Add LeakCanary to debug / staging variants; activity / fragment leaks surface immediately in dev rather than via support tickets in production. Both stay out of release builds.
+- **WorkManager / CoroutineWorker for deferrable background work**: any task that should survive process death / app close / device reboot (sync, upload, scheduled refresh, deferred notification) goes through WorkManager, not raw `JobScheduler` / `AlarmManager` — WorkManager handles backoff, constraints (network / charging / idle), chained work, and Doze-mode compatibility. Use `CoroutineWorker` for Kotlin code; `RxWorker` for Rx codebases. Foreground services (per Android 14+ FGS rule above) are for actively-running visible work, not deferrable.

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/flutter-dev.md

@@ -0,0 +1,80 @@
+# Flutter Dev
+
+## Architecture
+
+- Start from the existing repo pattern. If no pattern exists, use feature-first structure with presentation/widgets, state/controller/view model, data/repository, API client, models, and platform adapters.
+- Keep widgets declarative and thin. Heavy mapping, validation, side effects, and command handling belong outside `build`.
+- Pick state management deliberately. Riverpod, Bloc, Provider/ChangeNotifier, ValueNotifier, or built-in state can all be valid; do not introduce a new framework when the repo already has a consistent one.
+- Separate ephemeral widget state from app/domain state. Durable state needs a clear owner and lifecycle.
+- Use explicit navigation and deep-link handling. Treat route params as typed contracts and verify back behavior.
+- **Widget mental model**: `StatelessWidget` for pure render-from-props; `StatefulWidget` only when the widget itself owns ephemeral interaction state that does not belong in a state container. For dependency injection across the tree, prefer `InheritedWidget` (broadcast change) / `InheritedModel` (selective subtree rebuild by aspect) over global singletons. App / domain state lives in the chosen state container (Riverpod / Bloc / etc.), not in `StatefulWidget`.
+- **Hooks and DI carve-outs**: `flutter_hooks` is a legitimate alternative composition style — adopt project-wide if the team chose it, not as a sprinkle. `get_it` / `GetIt` is acceptable as a service locator at app composition root, but treat it as a controlled trade-off — global mutable locators erode testability and hide dependency graphs; prefer constructor injection or Riverpod providers for new code. Both default to "not introduced if absent" per the existing state-management rule.
+- **Riverpod 3 migration breaks several API shapes**: automatic retry of failing providers is on by default; provider failures rethrow as `ProviderException` (not the original error); `StateProvider` / `StateNotifierProvider` / `ChangeNotifierProvider` are LEGACY and moved to `package:riverpod/legacy.dart` (new code uses `NotifierProvider` / `AsyncNotifierProvider`); `AsyncValue` is now `sealed` (enables exhaustive `switch` pattern matching); `valueOrNull` renamed to `value`. Offline persistence and mutation support are experimental. Verify before upgrading existing Riverpod 2 projects.
+- **App lifecycle observation**: `AppLifecycleListener` (`flutter/widgets`) is the newer, preferred API over `WidgetsBindingObserver` for observing app lifecycle state — callback-based, no class inheritance required, supports `onExitRequested` for desktop close-window negotiation. `AppLifecycleState.hidden` (added Flutter 3.13) is part of the standard state set across both APIs. `WidgetsBindingObserver` remains valid for existing code and for combined observation needs (metrics + accessibility + focus + lifecycle in one observer).
+
+## Codegen And Toolchain
+
+- **Codegen stack**: `freezed` (immutable data classes + unions/sealed classes) + `json_serializable` (typed JSON) + `build_runner` (build orchestrator) is the canonical pattern for typed models and serialization. Generated files (`*.g.dart`, `*.freezed.dart`) are checked into the repo or regenerated in CI; do not depend on developers running `build_runner` ad-hoc. When using Riverpod, `riverpod_generator` + `riverpod_annotation` is the canonical codegen path — only adopt if the project already uses Riverpod.
+- **Flutter SDK version pinning**: pin the Flutter SDK version per repo via FVM (`.fvmrc` / `.fvm/`) or the equivalent toolchain manager; CI uses the same pinned version. An unpinned project drifts across developer machines; build-vs-runtime mismatch is a class of bugs unique to cross-platform SDKs.
+- **Dart Macros are indefinitely paused (Dart team Jan 2025)** — do NOT bet on macros for production code generation. The Dart team paused implementation work to focus on improving `build_runner` and shipping **augmentations** (one feature prototyped as part of macros) as a standalone language feature. `build_runner` + `freezed` + `json_serializable` remains the canonical codegen path; `freezed 3.0` and successor codegen tools target the post-macros world.
+
+## Platform Integration
+
+- Keep platform channels, plugins, and native SDK calls behind adapters.
+- Represent permission and capability failures in UI state, not only logs.
+- For add-to-app, define ownership of the host app, Flutter module, build pipeline, route handoff, and lifecycle events.
+- **Pigeon vs MethodChannel vs FFI** — pick by surface, not preference: **Pigeon** (codegen) for typed, evolving, multi-platform contracts where long-term type safety across Flutter / Android / iOS / future targets matters — prefer Pigeon when the contract will change over time or carries structured types. **MethodChannel** (manual) for small, stable, one-off capabilities, dynamic payloads, or bridge debugging where the codegen overhead is not worth it. **FFI** for C-ABI native libraries and measured perf paths (image / crypto / parsing) — NOT for routine Kotlin/Swift business APIs (FFI does not target Kotlin/Swift directly and does not cover Web).
+
+## Cross-Platform Target Matrix
+
+- **Cross-platform is not "one UI fits everywhere"**: each target (mobile iOS / mobile Android / web / desktop macOS / desktop Windows / desktop Linux) has its own input model (touch / pointer + keyboard / mouse + keyboard), window model, navigation conventions, accessibility APIs, plugin support matrix, and performance profile. Maintain a platform capability matrix per project: which targets are in scope, which plugins are verified on each, which screens have target-specific layout overrides, which capabilities are stubbed / disabled on each.
+- **Material / Cupertino / Adaptive**: Material for explicit Material-system apps; Cupertino for explicit iOS-native look; **adaptive widgets** (e.g. `Switch.adaptive`, `Slider.adaptive`, `CircularProgressIndicator.adaptive`) when the surface should follow platform conventions automatically. Mixing without a portfolio rule produces inconsistent feel; record the choice in the project's design contract.
+- **Flutter Web renderers**: per current Flutter docs, only two renderers exist: **CanvasKit** (default for normal builds — Skia compiled to WebAssembly, ~1.5MB) and **skwasm** (selected when building with `--wasm` if the browser supports WasmGC, falls back to CanvasKit otherwise — more compact ~1.1MB, multi-threaded rendering). The **HTML renderer is no longer documented in current Flutter docs** — projects pinned to old SDK versions using HTML renderer need an explicit migration plan to CanvasKit (default) or `--wasm` / skwasm before SDK upgrade. Web targets also need SEO / document-heavy considerations Flutter does not natively address — for content-dominant pages, a static / SSR-rendered web surface alongside the Flutter app is usually the right architecture.
+- **Web interop migration**: `dart:js_interop` (released with Dart 3.3, Feb 2024) replaces `package:js` / `dart:js`; `package:web` replaces `dart:html` and the other browser libraries. Legacy JS interop is deprecated as of Dart 3.7 (Feb 2025). New Web code uses `dart:js_interop` + `package:web`; existing Web code on `dart:html` has migration debt — required for Wasm compilation (Wasm only works with the new interop). Migration guide is at `dart.dev/interop/js-interop/package-web`.
+- **Federated plugin architecture** for multi-platform plugins: split into platform-interface package (`<plugin>_platform_interface`) + per-platform implementation packages (`<plugin>_android`, `<plugin>_ios`, `<plugin>_web`, etc.) + app-facing package (`<plugin>`). Per Flutter docs, federated is **optional** — recommended / expected for shared multi-platform plugins where independent platform implementations or endorsed third-party additions matter, optional for single-package plugins. The structure makes per-platform contribution and version skew explicit; adopt when those concerns are real, not as ceremony.
+- **Multi-package Flutter repo**: when a Flutter project grows into multiple packages (app + shared libs + plugins), Melos / Dart workspaces is a common monorepo orchestration choice. Deep monorepo governance routes to the team's repo / tooling owner; Flutter-side responsibility is keeping per-package `pubspec.yaml` resolvable and CI building each package.
+
+## Theme And Brand Color
+
+Shared design discipline lives in `product-ui-ux-design/references/multi-project-token-consistency.md`; consult it before applying the Flutter-specific implementation rules below.
+
+- **`MaterialApp(theme: ThemeData(...))` must reference a brand theme, not the default**: an app whose entry is `MaterialApp(theme: ThemeData())` / `MaterialApp(theme: ThemeData.light())` / `MaterialApp()` with no `theme` arg renders the Material default palette. This is the Flutter equivalent of the empty framework-wrapper anti-pattern in `multi-project-token-consistency.md`. Audit signal: `MaterialApp.theme` must reach a brand `ThemeData` built from the project's design tokens (not the framework default); `CupertinoApp.theme` must reach a brand `CupertinoThemeData` (NOT `ThemeData`); a `MaterialApp` wrapping `CupertinoApp`-style screens still needs `MaterialApp.theme` populated since Material widgets read from it.
+- **Flutter scaffold colors left as dead-code declarations**: `flutter create` ships sample colors (`Colors.blue`, `Colors.deepPurple` as the seed in `MaterialApp.theme: ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple))`). When the team replaces the seed with a brand value but leaves the original scaffold-color constants declared elsewhere in `theme.dart` / `colors.dart`, those become onboarding noise — same shape as the Android Compose `Purple40/Pink40` dead-code anti-pattern in `android-dev.md`. Delete unreferenced scaffold colors once the brand value is wired.
+- **Vendor-default literal leak in custom theme** (cross-stack rule): `Color(0xFFD93025)` / `Color(0xFF6750A4)` / `Colors.deepPurple` / Material 3 default tonal palette values typed into the brand layer fall under the shared anti-pattern in `multi-project-token-consistency.md`. Detection: grep `theme.dart` / `colors.dart` / `ThemeData` builder for known Material default literals. A hit resolves to one of three classes per the shared rule: **leak** (replace with brand token), **deliberate documented reuse** (keep with rationale comment), or **legitimate convergence** (brand role independently resolves to the same hex — keep but reference the brand token, not the literal).
+- **Algorithmic secondary / tertiary derived without designer sign-off** — applies to **custom** derivation patterns; standards-based Material You has a carve-out: Flutter's `ColorScheme.fromSeed(seedColor: brandColor)` algorithmically derives the entire tonal palette from one seed. This IS the Material You design intent. Acceptable as the design policy when the project records (a) the Material You variant in use (M3 default vs `DynamicSchemeVariant.tonalSpot` / `vibrant` / `expressive` / etc.), (b) accessibility/contrast checks against the brand seed, (c) visual QA on canonical screens at the seed value. Designer sign-off applies to the policy adoption + the seed/canonical-screen pass, NOT to every runtime-generated secondary/tertiary value. Silent reliance on `fromSeed` without ANY of (a)/(b)/(c) is the failure mode. Custom HSV-shift / alpha-tint / complementary derivations have stricter sign-off requirements per the shared anti-pattern in `multi-project-token-consistency.md`.
+- **`ThemeExtension<T>` for brand-specific additions beyond `ThemeData`'s fixed fields**: subclass `ThemeExtension<T>`, define brand-specific fields (extra colors, spacing tokens, custom typography roles), implement `copyWith` + `lerp` for smooth transitions; register via `ThemeData(extensions: [<MyExtension>(...)])`; read via `Theme.of(context).extension<MyExtension>()`. This is the official path for "Material doesn't cover this brand-specific token". Do not create a parallel `BrandTheme` `InheritedWidget` SOLELY to host Material / brand tokens that `ThemeExtension` would carry — that path breaks `Theme.of(context).extension` lookups and animation interpolation. A separate app-domain `InheritedWidget` for non-theme runtime config (feature flags, user role, environment) is still valid.
+- **Material 3 Expressive (Google I/O 2025): watch, do not adopt as Flutter default yet**. Material 3 Expressive is currently shipping for Wear OS via dedicated Jetpack libraries (Wear Compose Material 3 + Wear ProtoLayout Material 3) and Android handheld surfaces; Flutter Material widget set has not yet adopted Expressive as a production-ready default. Track Flutter docs `docs.flutter.dev/ui/design/material` and Flutter release notes for adoption; until then, current `ColorScheme.fromSeed` + Material 3 remains the production guidance.
+
+## Tests And Verification
+
+- Unit test pure mapping, validators, state reducers/controllers, repository behavior, error translation, cache policy, and retry decisions.
+- Widget test loading/empty/error/success states, gestures, forms, validation, route entry, and permission-denied UI.
+- Use golden or screenshot tests when the repo already supports them or when the UI surface is visually risky.
+- Integration test critical device flows, plugin paths, deep links, auth/session behavior, and offline/retry flows.
+- Run analyzer/format/build for the changed target and inspect a rendered screen before delivery.
+- **Mocking**: prefer `mocktail` for Flutter (null-safety friendly, no codegen / `build_runner` dependency, simpler stub API). `mockito` remains valid for projects already using it, but new code in the codegen + null-safety era leans `mocktail`.
+- **Golden / screenshot testing** (`golden_toolkit` / `alchemist`): apply when the surface is visually high-risk (design-system primitives, financial / data-dense forms, complex layouts the design team reviews). Do NOT golden every screen — golden suites are maintenance debt, baselines drift across font / OS / renderer, and per-developer flakiness is real. Scope per-project to the screens whose visual regression cost is high.
+
+## Errors And Diagnostics
+
+- **Three-layer error capture for public / staged-rollout / high-risk shipping apps**: (1) `FlutterError.onError` catches errors thrown during widget build / framework callbacks; (2) `PlatformDispatcher.instance.onError` (or `runZonedGuarded` in older patterns) catches errors outside the Flutter framework — uncaught async, isolate errors, native bridge errors propagating up; (3) the `ErrorWidget.builder` controls what users see when build itself fails (default red error screen is for debug, never for production). Wire all three to the crash backend (per `mobile-quality-release.md` symbolication gate); missing any layer drops a real class of crashes from the dashboard. Internal / closed-test builds may downgrade by risk acceptance.
+- **DevTools is non-optional for debugging non-trivial behavior**: per Flutter docs, the top-level views are Flutter Inspector (widget tree + layout boundaries) for rebuild / overflow / constraint debugging; Performance view (with Timeline Events tab inside) for jank / frame-rate investigation; CPU Profiler view for CPU-bound work analysis; Memory view (heap + leak detection) for image / cache / list memory issues; Network view for HTTP / WebSocket inspection; plus Debugger, Logging view, Debug console, App size tool. Reaching for `print` instead of DevTools is the recurring habit that masks the actual cause.
+- **Hot reload vs hot restart**: `hot reload` re-runs `build` and preserves widget state — fast iteration on UI / business logic. `hot restart` resets the app state and re-runs `main()` — required after changing `main()`, top-level state, `const` constructors, `enum` / generic type signatures, or DI graph; reload silently keeping stale state from these classes is the recurring "but it worked locally" cause. When in doubt, hot restart.
+- **DevTools extensions** (`package:devtools_extensions`): for products where repeated domain-debugging cost exceeds extension maintenance, ship a DevTools extension as a custom panel embedded in DevTools (iframe-based, Flutter web app). Extension consumes shared DevTools APIs (VM service connection, theming, shared widgets); user enables by adding the providing package as a `dev_dependency`. Recent integration with the Dart Tooling Daemon allows access to IDE-registered methods and a minimal file-system API. Not for every in-house framework — the threshold is "we keep instrumenting print-debugging for the same domain over and over"; if it's one-off debugging, scattered `print` + DevTools' built-in panels still win.
+
+## Internationalization
+
+- **`gen_l10n + intl` (official) is the default** for any Flutter app that might ship in more than one language. Configure via `l10n.yaml` + `.arb` files; `flutter gen-l10n` (or the build runner) emits typed `AppLocalizations` accessed via `BuildContext`. Hard-coded user-facing strings in `Text(...)` are migration debt the day a second language is added.
+- Alternatives (`easy_localization`, `slang`) are acceptable if the project already uses them; do not introduce them in greenfield work without a specific reason to skip the official path. Plural / gender / select forms, locale-aware date / number formatting, RTL layout, and font fallback for non-Latin scripts are part of i18n acceptance — not a string-replace exercise.
+
+## Performance
+
+- Watch startup work, large rebuilds, image decoding, long lists, jank during animation/scroll, synchronous parsing, and app size.
+- Move CPU-heavy parsing or transforms off the UI path when needed. On **native** targets, `compute()` (or `Isolate.run()`, Flutter 3.7+) runs the callback in a separate isolate so it does not block the UI isolate. On **Web**, `compute()` runs the callback on the current event loop — there is no isolate to offload to, so it does NOT prevent UI jank for CPU-bound work; Web CPU-bound work needs Web Workers via JS interop or algorithmic chunking, not `compute()`.
+- **Repaint boundary discipline**: wrap subtrees that repaint frequently (animations, scrollable lists with their own animation, custom-painted overlays) in `RepaintBoundary` so their repaints don't invalidate the parent's raster. `CustomPainter` is the right primitive for one-off visuals that don't compose from existing widgets — pair with `shouldRepaint` returning `false` when inputs are unchanged. For long scrollable lists / grids, use `Sliver*` widgets (`SliverList`, `SliverGrid`, `CustomScrollView`) instead of nesting fixed-extent widgets in a `ListView` — Slivers participate in the scroll geometry directly, avoid forced relayouts, and support sticky / collapsing headers naturally.
+- Prefer measured profiling for suspected performance issues; do not tune blindly.
+- **Impeller renderer is default on iOS (since 3.10) and on Android API 29+ (since 3.27)**. Two separate verification surfaces: **iOS** — Flutter docs current state is Impeller-only on iOS, no Skia switch; verify first-frame and animation smoothness on supported iPhone floor. **Android** — Impeller is default on API 29+; the `--no-enable-impeller` debug flag still toggles to Skia for diagnosis. Verify on real low-end Android devices the project supports, watch for shader-compile-on-demand jank on rare surfaces, and confirm Skia fallback still ships acceptably for the targeted Android API floor before treating Impeller as the only path.
+
+## Release Patterns
+
+- **OTA / code push (Shorebird) is the production path for Flutter** when the team needs faster-than-app-store-review updates. Shorebird is in active production at scale (hundreds of millions of patches deployed in 2025 across Android / iOS / macOS / Windows / Linux per the vendor's year-in-review). **Platform constraint discipline**: Apple's App Review Guideline **2.5.2** (executable code) plus Apple Developer Program License Agreement **3.3.1(b)** (which Shorebird itself cites) constrain what can be patched without re-review — interpreter compliance, no deceptive primary-purpose change, and major / native-surface changes continue through normal store releases. Document the patch policy with legal/release-engineering before adopting, not after a patch is rejected. Android has fewer constraints but still subject to Play Store policy. OTA is niche-but-recommendable for products with: (a) high cost of waiting for review, (b) critical bug-fix windows, or (c) feature-flag governance the team will actually use; not a substitute for normal release discipline.