@bdayadev/flutter-ultra-mcp 1.5.8 → 1.7.0

package/skills/scaffold/SKILL.md

@@ -1,167 +1,173 @@
 ---
 name: flutter-scaffold
-description: Scaffolding new Flutter projects or features following the conventions detected in the existing codebase. Use when starting a fresh app, adding a feature module, or generating boilerplate that should match an existing project's structure.
+description: Scaffolds new Flutter projects or features following conventions detected in the existing codebase. Use when starting a fresh app, adding a feature module, generating boilerplate that should match the project's structure, setting up state management, or configuring localization.
 disable-model-invocation: true
 ---
 
-# flutter-scaffold — Project and Feature Scaffolding
+# Project and Feature Scaffolding
 
-## When to use
-
-User must explicitly trigger this skill with `/flutter:scaffold`. It is not auto-invoked because it creates files. Use when the user asks to create a new Flutter project, add a feature module, scaffold a new screen, set up state management, or add boilerplate that must match the project's existing conventions.
-
-## Prerequisites
-
-- For **project mode**: a target directory must be specified or agreed upon. Flutter SDK must be on PATH.
-- For **feature mode**: a Flutter project must already exist and be identifiable by `list_projects`.
-- The user must confirm the scaffolding plan before any files are written.
+User must explicitly trigger this skill with `/flutter:scaffold`. It creates files and is not auto-invoked.
 
 ## Mode detection
 
-Determine which mode to use from the user's request:
-
-| User asks                                                 | Mode                                 |
-| --------------------------------------------------------- | ------------------------------------ |
-| "create a new Flutter app", "new project"                 | Project mode                         |
-| "add a feature", "new screen", "scaffold [X] page/module" | Feature mode                         |
-| "set up BLoC / Riverpod / Provider"                       | State management mode                |
-| "add a new route / page"                                  | Screen mode (subset of feature mode) |
+| User asks | Mode |
+|-----------|------|
+| "create a new Flutter app" | Project mode |
+| "add a feature", "new screen" | Feature mode |
+| "set up BLoC / Riverpod" | State management mode |
+| "add localization" | L10n mode |
 
----
-
-## Project mode — new Flutter app
+## Project mode
 
-1. Confirm with the user: project name, org (reverse domain), target directory, and Flutter channel (stable/beta).
-2. Run via shell (Bash tool):
-   ```bash
-   flutter create --org com.example --project-name my_app ./my_app
-   ```
-3. Call `mcp__plugin_flutter_flutter-ultra-build__pub_get` on the new project to fetch dependencies.
-4. Call `mcp__plugin_flutter_flutter-ultra-build__analyze` to confirm a clean baseline.
-5. Ask the user if they want state management, routing, or localization scaffolded next — then proceed to the relevant feature mode sections below.
-
----
+1. Confirm: project name, org, target directory, Flutter channel.
+2. Create via shell: `flutter create --org com.example --project-name my_app ./my_app`.
+3. `mcp__plugin_flutter_flutter-ultra-build__pub_get` to fetch dependencies.
+4. `mcp__plugin_flutter_flutter-ultra-build__analyze` to confirm clean baseline.
+5. `mcp__plugin_flutter_flutter-ultra-build__flutter_doctor` to verify the environment.
+6. Ask if state management, routing, or l10n scaffolding is needed.
 
-## Feature mode — detect existing conventions first
+## Feature mode — detect conventions first
 
-Before creating any files, call `mcp__plugin_flutter_flutter-ultra-build__project_info` on the target project to read:
+Call `mcp__plugin_flutter_flutter-ultra-build__project_info` to read project structure and dependencies.
 
-- Project root and `lib/` structure
-- Existing dependencies (from `pubspec.yaml`)
+Detect the project's state management from `pubspec.yaml`:
 
-Then detect the project's conventions by reading `pubspec.yaml` dependencies:
+| Dependency | Pattern |
+|-----------|---------|
+| `flutter_bloc` / `bloc` | BLoC |
+| `riverpod` / `flutter_riverpod` | Riverpod |
+| `provider` | Provider |
+| None | Ask the user |
 
-| Detected dep                    | State management pattern  |
-| ------------------------------- | ------------------------- |
-| `flutter_bloc` / `bloc`         | BLoC pattern              |
-| `riverpod` / `flutter_riverpod` | Riverpod                  |
-| `provider`                      | Provider                  |
-| None of the above               | Ask the user which to use |
+Detect routing: `go_router` = GoRouter, `auto_route` = AutoRoute, none = Navigator 1.0.
 
-| Detected dep | Routing pattern          |
-| ------------ | ------------------------ |
-| `go_router`  | GoRouter                 |
-| `auto_route` | AutoRoute                |
-| None         | Navigator 1.0 (push/pop) |
+Announce detected conventions before scaffolding.
 
-Announce detected conventions to the user before scaffolding.
-
----
-
-## Screen scaffolding (new route/page)
-
-For each new screen, create the following files following the detected pattern:
-
-### File structure (BLoC + GoRouter example for `InvoiceList`):
+### Screen scaffolding (BLoC + GoRouter example)
 
 ```
-lib/
-  features/
-    invoice_list/
-      bloc/
-        invoice_list_bloc.dart      # BLoC class
-        invoice_list_event.dart     # events sealed class
-        invoice_list_state.dart     # states sealed class
-      view/
-        invoice_list_page.dart      # BlocProvider wrapper
-        invoice_list_view.dart      # stateless widget body
-      invoice_list.dart             # barrel export
-test/
-  features/
-    invoice_list/
-      bloc/
-        invoice_list_bloc_test.dart
+lib/features/invoice_list/
+  bloc/
+    invoice_list_bloc.dart
+    invoice_list_event.dart
+    invoice_list_state.dart
+  view/
+    invoice_list_page.dart
+    invoice_list_view.dart
+  invoice_list.dart           # barrel export
+test/features/invoice_list/
+  bloc/
+    invoice_list_bloc_test.dart
 ```
 
-For **Riverpod**: replace `bloc/` with `provider/` containing a `StateNotifier` or `AsyncNotifier`.
-For **Provider**: replace `bloc/` with `provider/` containing a `ChangeNotifier`.
-
-### Route registration (GoRouter):
+### After creating files
 
-Add the new route to the router config file (detect by searching for `GoRouter(` in `lib/`):
+1. `mcp__plugin_flutter_flutter-ultra-build__format` to normalize formatting.
+2. `mcp__plugin_flutter_flutter-ultra-build__analyze` to confirm clean compilation.
+3. If codegen is needed (Riverpod generators, freezed): `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build` -> `mcp__plugin_flutter_flutter-ultra-build__poll_build_runner_job` -> `mcp__plugin_flutter_flutter-ultra-build__get_build_runner_result`.
 
-```dart
-GoRoute(
-  path: '/invoice-list',
-  name: 'invoiceList',
-  builder: (context, state) => const InvoiceListPage(),
-),
-```
-
-### After creating files:
-
-1. Call `mcp__plugin_flutter_flutter-ultra-build__format` on the new files to normalize formatting.
-2. Call `mcp__plugin_flutter_flutter-ultra-build__analyze` — fix any errors before reporting done.
-3. Do **not** call `pub_get` unless new packages were added.
-
----
-
-## State management setup (first-time)
-
-When the project has no state management and the user wants to add one:
+## State management setup
 
 **BLoC:**
 
-1. Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `flutter_bloc bloc equatable`.
-2. Call `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
-3. Scaffold the first BLoC as described in the screen section above.
+1. `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `flutter_bloc bloc equatable`.
+2. `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
 
 **Riverpod:**
 
-1. Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `flutter_riverpod riverpod_annotation` and dev deps `riverpod_generator build_runner`.
-2. Call `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
-3. Wrap `main.dart`'s `runApp` with `ProviderScope`.
-4. Call `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build` → `poll_build_runner_job` → `get_build_runner_result` to generate initial code.
+1. `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `flutter_riverpod riverpod_annotation` + dev deps `riverpod_generator build_runner`.
+2. `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
+3. Run build_runner to generate initial code.
 
 **Provider:**
 
-1. Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `provider`.
-2. Call `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
-
----
-
-## Localization scaffolding
+1. `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `provider`.
+2. `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
 
-When the user asks to add l10n:
+## Localization setup
 
-1. Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `flutter_localizations` (SDK package).
+1. `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `flutter_localizations` (SDK package).
 2. Create `lib/l10n/app_en.arb` with a minimal key set.
 3. Add `generate: true` to `pubspec.yaml` under `flutter:`.
-4. Call `mcp__plugin_flutter_flutter-ultra-build__flutter_gen_l10n` to generate the `AppLocalizations` class.
-5. Add `localizationsDelegates` and `supportedLocales` to the `MaterialApp`.
-
----
+4. `mcp__plugin_flutter_flutter-ultra-build__flutter_gen_l10n` to generate the `AppLocalizations` class.
+5. Add `localizationsDelegates` and `supportedLocales` to `MaterialApp`.
+6. Verify: `mcp__plugin_flutter_flutter-ultra-build__list_missing_translations` to check all locales have translations.
+
+## Asset management
+
+When the scaffold includes images or other assets:
+
+1. `mcp__plugin_flutter_flutter-ultra-build__add_asset` to register assets in `pubspec.yaml`.
+2. `mcp__plugin_flutter_flutter-ultra-build__validate_assets` to confirm all referenced assets exist on disk.
+3. `mcp__plugin_flutter_flutter-ultra-build__list_orphan_assets` to find assets on disk not referenced in code.
+
+## Web configuration
+
+For web-targeted projects:
+
+1. `mcp__plugin_flutter_flutter-ultra-build__validate_web_redirect` to check `web/index.html` base href and redirect handling.
+2. `mcp__plugin_flutter_flutter-ultra-build__validate_canvaskit_vs_html_consistency` to verify renderer consistency.
+3. `mcp__plugin_flutter_flutter-ultra-build__flush_service_worker` when changing web config during development.
+
+## Signing verification
+
+After scaffolding a release-ready project:
+
+1. `mcp__plugin_flutter_flutter-ultra-build__verify_android_signing` to check keystore and signing config.
+2. `mcp__plugin_flutter_flutter-ultra-build__verify_ios_signing` to check provisioning profiles.
+3. `mcp__plugin_flutter_flutter-ultra-build__set_bundle_id` to configure the app's bundle identifier.
+
+## Safety rules
+
+- Always announce the file list before writing. Wait for user confirmation if more than 3 files.
+- Never overwrite existing files without explicit confirmation.
+- Match the existing naming convention (`snake_case` vs `camelCase`).
+- Run `analyze` and surface any errors before reporting done.
+
+## Tool reference
+
+| Action | Tool |
+|--------|------|
+| Project info | `mcp__plugin_flutter_flutter-ultra-build__project_info` |
+| List projects | `mcp__plugin_flutter_flutter-ultra-build__list_projects` |
+| Add dependency | `mcp__plugin_flutter_flutter-ultra-build__pub_add` |
+| Remove dependency | `mcp__plugin_flutter_flutter-ultra-build__pub_remove` |
+| Resolve deps | `mcp__plugin_flutter_flutter-ultra-build__pub_get` |
+| Search pub.dev | `mcp__plugin_flutter_flutter-ultra-build__pub_dev_search` |
+| Format code | `mcp__plugin_flutter_flutter-ultra-build__format` |
+| Analyze | `mcp__plugin_flutter_flutter-ultra-build__analyze` |
+| Auto-fix | `mcp__plugin_flutter_flutter-ultra-build__fix` |
+| Preview fixes | `mcp__plugin_flutter_flutter-ultra-build__fix_preview` |
+| Build runner | `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build` |
+| Gen l10n | `mcp__plugin_flutter_flutter-ultra-build__flutter_gen_l10n` |
+| Add asset | `mcp__plugin_flutter_flutter-ultra-build__add_asset` |
+| Validate assets | `mcp__plugin_flutter_flutter-ultra-build__validate_assets` |
+| Orphan assets | `mcp__plugin_flutter_flutter-ultra-build__list_orphan_assets` |
+| Web redirect | `mcp__plugin_flutter_flutter-ultra-build__validate_web_redirect` |
+| CanvasKit check | `mcp__plugin_flutter_flutter-ultra-build__validate_canvaskit_vs_html_consistency` |
+| Flush SW | `mcp__plugin_flutter_flutter-ultra-build__flush_service_worker` |
+| Android signing | `mcp__plugin_flutter_flutter-ultra-build__verify_android_signing` |
+| iOS signing | `mcp__plugin_flutter_flutter-ultra-build__verify_ios_signing` |
+| Set bundle ID | `mcp__plugin_flutter_flutter-ultra-build__set_bundle_id` |
+| Flutter doctor | `mcp__plugin_flutter_flutter-ultra-build__flutter_doctor` |
+| Missing translations | `mcp__plugin_flutter_flutter-ultra-build__list_missing_translations` |
+
+## Example
 
-## Confirmation and safety rules
-
-- **Always announce the file list** that will be created before writing. Wait for user confirmation if the list is more than 3 files.
-- **Never overwrite existing files** without explicit user confirmation.
-- **Match the existing naming convention**: if existing files use `snake_case` feature directories, continue that pattern; if they use `camelCase`, match it.
-- After scaffolding, run `analyze` and surface any errors — do not report done if there are errors.
+```
+User: "/flutter:scaffold add an InvoiceList feature to the Invora app"
+
+1. project_info -> detected: BLoC + GoRouter
+2. Announce plan: 7 files to create (bloc, events, state, page, view, barrel, test)
+3. [User confirms]
+4. Create files following BLoC + GoRouter pattern
+5. Add GoRoute entry to router config
+6. format -> normalized
+7. analyze -> 0 errors
+-> "InvoiceList feature scaffolded: 7 files created, 1 file modified."
+```
 
 ## See also
 
-- Sibling skill: `flutter-test` for writing tests after scaffolding
-- Sibling skill: `flutter-debug` for inspecting live state in scaffolded features
-- `mcp__plugin_flutter_flutter-ultra-build__project_info` — reads project structure and dependencies
-- `mcp__plugin_flutter_flutter-ultra-build__analyze` — validates scaffolded code compiles clean
+- `flutter-test` — write and run tests for scaffolded features
+- `flutter-setup` — initial flutter-ultra plugin setup

package/skills/setup/SKILL.md

@@ -1,45 +1,30 @@
 ---
 name: flutter-setup
-description: One-command setup of the flutter-ultra-mcp plugin in an existing Flutter codebase. Use when the user wants to enable flutter-ultra for the first time, or when re-running after a clean install. Idempotent — safe to run again if a previous attempt was partial.
+description: One-command setup of the flutter-ultra-mcp plugin in an existing Flutter codebase. Use when the user wants to enable flutter-ultra for the first time, re-run after a clean install, or verify an existing setup is complete and working. Idempotent and safe to re-run.
 ---
 
-# flutter-setup — One-Command Plugin Setup
+# Plugin Setup
 
-## When to use
-
-Use this skill when the user wants to wire up the flutter-ultra-mcp plugin into a Flutter project for the first time, or when verifying that a previously attempted setup is complete and working. The expected end state is: `UltraFlutterBinding` initialized in the app entry point, `ultra_flutter` in `dev_dependencies`, patrol fork overridden in `pubspec_overrides.yaml`, and a smoke launch confirming the VM Service attaches correctly.
-
-## Prerequisites
-
-- Flutter SDK installed and on PATH (`flutter --version` must succeed).
-- Node.js ≥ 18 installed (required for the MCP servers).
-- The target project has a `pubspec.yaml` (i.e., it is a Flutter app, not a pure Dart package).
-- The user is working from the project root (or has provided an absolute path to it).
+Expected end state: `UltraFlutterBinding` initialized in the app entry point, `ultra_flutter` in `dev_dependencies`, patrol fork overridden if needed, and a smoke launch confirming the VM Service attaches correctly.
 
 ## Workflow
 
 ### 1. Verify the environment
 
-- Call `mcp__plugin_flutter_flutter-ultra-build__flutter_doctor` with the project root.
-  - If any `[✗]` entries appear for Flutter SDK, connected devices, or Dart, stop and surface the doctor output to the user. Do not continue until the environment is healthy.
-- Call `mcp__plugin_flutter_flutter-ultra-build__project_info` with the project root.
-  - Note: `entryPoints` (usually `lib/main.dart` or `lib/bootstrap.dart`), `hasSentry` (affects binding pattern), `hasPatrol` (determines whether to configure the patrol fork override).
+- `mcp__plugin_flutter_flutter-ultra-build__flutter_doctor` — stop if Flutter SDK, devices, or Dart show `[x]`.
+- `mcp__plugin_flutter_flutter-ultra-build__project_info` — note entry points, `hasSentry`, `hasPatrol`, `hasUltraBinding`.
+- `mcp__plugin_flutter_flutter-ultra-runtime__list_devices` — verify at least one target device is available.
+- `mcp__plugin_flutter_flutter-ultra-build__list_dart_defines` — discover required dart-defines for launch.
+- `mcp__plugin_flutter_flutter-ultra-build__list_flavors` — check for flavor configuration.
 
 ### 2. Add `ultra_flutter` to dev_dependencies
 
-- Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with:
-  - `package`: `ultra_flutter`
-  - `dev`: `true`
-- If `pub_add` fails because `ultra_flutter` is not on pub.dev (it is a local plugin bundled with the MCP server), use `pubspec_overrides_set` to point to the bundled path instead:
-  - Call `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` with `package: ultra_flutter` and `path` set to the absolute path of the bundled package (ask the user or read from plugin config if available).
-  - Then add the dependency manually by editing `pubspec.yaml`: add `ultra_flutter: any` under `dev_dependencies`.
-  - Call `mcp__plugin_flutter_flutter-ultra-build__pub_get` to resolve.
+- `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `package: ultra_flutter`, `dev: true`.
+- If it fails (not on pub.dev), use `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` to point to the bundled path, add `ultra_flutter: any` under `dev_dependencies` manually, then `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
 
 ### 3. Patch the app entry point
 
-Read the primary entry point file identified in step 1. Apply the following pattern:
-
-**Without Sentry** — wrap the existing `runApp` call:
+**Without Sentry:**
 
 ```dart
 import 'package:flutter/foundation.dart';
@@ -53,98 +38,110 @@ void main() {
 }
 ```
 
-**With Sentry** (when `hasSentry: true`) — Sentry installs its own binding; use the direct mixin pattern:
+**With Sentry** (custom binding mixin):
 
 ```dart
-import 'package:flutter/foundation.dart';
 import 'package:ultra_flutter/ultra_flutter.dart';
 
-// In your custom binding class:
 class AppBinding extends WidgetsFlutterBinding with UltraFlutterBindingMixin {
   static AppBinding ensureInitialized() =>
       WidgetsFlutterBinding.ensureInitialized() as AppBinding;
 }
-
-void main() {
-  AppBinding.ensureInitialized();
-  // ... Sentry.init wrapping runApp as before
-}
 ```
 
-Edit the file with the appropriate pattern. Only add the import and the `ensureInitialized` call — do not reorganize the existing code.
-
-### 4. Configure the patrol fork override (if patrol detected)
+Skip if `project_info` reported `hasUltraBinding: true`.
 
-When `project_info` reported `hasPatrol: true`:
+### 4. Configure patrol fork override (if patrol detected)
 
-- Call `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_list` to check if a `patrol` override already exists.
-- If not present, call `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` with:
-  - `package`: `patrol`
-  - `path`: the vendored patrol fork path bundled with flutter-ultra-mcp (located at `<plugin-root>/packages/flutter-ultra-patrol/vendor/patrol` — ask the user for `<plugin-root>` if not available in context).
-- Call `mcp__plugin_flutter_flutter-ultra-build__pub_get` to resolve the override.
+- `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_list` — check if `patrol` override exists.
+- If not: `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` with `package: patrol` and the vendored fork path.
+- `mcp__plugin_flutter_flutter-ultra-build__pub_get` to resolve.
 
-### 5. Run static analysis to verify the setup
+### 5. Static analysis
 
-- Call `mcp__plugin_flutter_flutter-ultra-build__pub_get` (ensure lock file is current after all edits).
-- Call `mcp__plugin_flutter_flutter-ultra-build__analyze` with the project root.
-  - If any errors reference `ultra_flutter` or `UltraFlutterBinding`, the import or mixin was not applied correctly — re-read the entry point and fix.
-  - Warnings about `// ignore: implementation_imports` on the Sentry path are expected; surface them to the user as informational only.
+- `mcp__plugin_flutter_flutter-ultra-build__pub_get` — ensure lock file is current.
+- `mcp__plugin_flutter_flutter-ultra-build__analyze` — fix any errors referencing `ultra_flutter` or `UltraFlutterBinding`.
+- If analysis finds other pre-existing issues: `mcp__plugin_flutter_flutter-ultra-build__fix` to auto-apply safe lint fixes.
 
 ### 6. Smoke test: launch, attach, screenshot
 
-- Call `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` with the project root and target device (default: `chrome` for web projects, `linux`/`macos`/`windows` for desktop, first connected device for mobile).
-  - Poll `mcp__plugin_flutter_flutter-ultra-runtime__poll_launch_app` until status is `ready` or `error`.
-  - If `error`, surface the launch log to the user and stop.
-- Call `mcp__plugin_flutter_flutter-ultra-runtime__attach` with the returned `sessionId`.
-- Call `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — save to `.omc/research/setup-smoke-<YYYY-MM-DD>.png`.
-- Call `mcp__plugin_flutter_flutter-ultra-runtime__detach`.
-- Call `mcp__plugin_flutter_flutter-ultra-runtime__stop_app` with the `sessionId`.
-
-If screenshot succeeds and the image is not blank, the setup is confirmed working.
-
-## Handling edge cases
-
-- **`UltraFlutterBinding.ensureInitialized()` already present**: `project_info` reports `hasUltraBinding: true`. Skip step 3 but still run steps 5–6 to confirm working state.
-- **Multiple entry points** (e.g. `main_dev.dart`, `main_prod.dart`): patch all of them with the same binding initialization. Confirm with the user if the list is longer than 3 files before editing.
-- **Monorepo / workspace**: `pubspec_overrides.yaml` must exist in each app package that needs ultra. Run steps 2–6 for each app package separately.
-- **pub_get fails after overrides**: common cause is a mismatched `patrol` version in `pubspec.yaml` vs. the fork. Call `mcp__plugin_flutter_flutter-ultra-build__pub_outdated` to inspect version constraints, then relax the constraint in `pubspec.yaml` to `any` for the overridden package.
-- **analyze reports `ultra_flutter` not found**: the `pubspec_overrides.yaml` path is wrong. Call `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_list` to verify the resolved path, then correct it.
-- **launch_app times out**: the app may require dart-defines (e.g. OIDC client IDs). Call `mcp__plugin_flutter_flutter-ultra-build__list_dart_defines` to discover required defines, then relaunch with them.
+- `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` with the project root and target device (default: `chrome` for web, platform default for desktop, first connected device for mobile).
+  - Pass `importLaunchJsonConfig` if `.vscode/launch.json` has dart-defines.
+- `mcp__plugin_flutter_flutter-ultra-runtime__poll_launch_app` until status is `attached` or `failed`.
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` to capture the running app.
+- `mcp__plugin_flutter_flutter-ultra-runtime__detach`.
+- `mcp__plugin_flutter_flutter-ultra-runtime__stop_app`.
+
+If screenshot succeeds and is not blank, setup is confirmed working.
+
+### 7. Build verification (optional, when requested)
+
+Verify the app builds for all target platforms using the build server's platform-specific start/poll/get/cancel tool sets. Each platform follows the same pattern: `start_build_{platform}` -> `poll_build_{platform}_job` -> `get_build_{platform}_result`. Supported platforms: apk, appbundle, ipa (macOS only), web, windows, macos, linux.
+
+## Edge cases
+
+- **`UltraFlutterBinding.ensureInitialized()` already present**: skip step 3, run steps 5-6 to confirm.
+- **Multiple entry points** (`main_dev.dart`, `main_prod.dart`): patch all of them. Confirm with the user if more than 3 files.
+- **Monorepo / workspace**: run steps 2-6 for each app package separately.
+- **pub_get fails after overrides**: `mcp__plugin_flutter_flutter-ultra-build__pub_outdated` to inspect version constraints, then relax to `any`.
+- **analyze reports `ultra_flutter` not found**: `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_list` to verify the resolved path.
+- **launch_app times out**: check `mcp__plugin_flutter_flutter-ultra-build__list_dart_defines` for required defines, relaunch with them.
+- **Pub cache corruption**: `mcp__plugin_flutter_flutter-ultra-build__pub_cache_repair` to rebuild the cache, then retry pub_get.
+- **Stale build artifacts**: `mcp__plugin_flutter_flutter-ultra-build__flutter_clean` to clear, then rebuild.
+
+## Tool reference
+
+| Action | Tool |
+|--------|------|
+| Flutter doctor | `mcp__plugin_flutter_flutter-ultra-build__flutter_doctor` |
+| Project info | `mcp__plugin_flutter_flutter-ultra-build__project_info` |
+| List devices | `mcp__plugin_flutter_flutter-ultra-runtime__list_devices` |
+| List dart defines | `mcp__plugin_flutter_flutter-ultra-build__list_dart_defines` |
+| List flavors | `mcp__plugin_flutter_flutter-ultra-build__list_flavors` |
+| Add dependency | `mcp__plugin_flutter_flutter-ultra-build__pub_add` |
+| Resolve deps | `mcp__plugin_flutter_flutter-ultra-build__pub_get` |
+| Overrides set | `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` |
+| Overrides list | `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_list` |
+| Analyze | `mcp__plugin_flutter_flutter-ultra-build__analyze` |
+| Auto-fix | `mcp__plugin_flutter_flutter-ultra-build__fix` |
+| Flutter clean | `mcp__plugin_flutter_flutter-ultra-build__flutter_clean` |
+| Pub cache repair | `mcp__plugin_flutter_flutter-ultra-build__pub_cache_repair` |
+| Pub outdated | `mcp__plugin_flutter_flutter-ultra-build__pub_outdated` |
+| Launch app | `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` |
+| Poll launch | `mcp__plugin_flutter_flutter-ultra-runtime__poll_launch_app` |
+| Attach | `mcp__plugin_flutter_flutter-ultra-runtime__attach` |
+| Screenshot | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` |
+| Detach | `mcp__plugin_flutter_flutter-ultra-runtime__detach` |
+| Stop app | `mcp__plugin_flutter_flutter-ultra-runtime__stop_app` |
+| Build (any platform) | `start_build_{platform}` via the build server |
 
 ## Output format
 
-After the workflow completes, produce:
-
 1. **Status**: `setup complete` or `setup failed at step N`.
-2. **Changes made**: bullet list of files edited (entry points, `pubspec.yaml`, `pubspec_overrides.yaml`).
-3. **Smoke test result**: path to the saved screenshot, or the error message if launch failed.
-4. **Next steps**: suggest running `/flutter-tour` to capture a visual baseline, or `/flutter-debug` if the smoke test revealed a runtime error.
+2. **Changes made**: bullet list of files edited.
+3. **Smoke test result**: screenshot path or error message.
+4. **Next steps**: suggest `/flutter:tour` for a visual baseline or `/flutter:debug` if the smoke test failed.
 
 ## Example
 
 ```
-User: "Set up flutter-ultra on the Invora Flutter app."
-
-1. flutter_doctor → all checks pass
-2. project_info → entryPoints: ["lib/bootstrap.dart"], hasSentry: true, hasPatrol: true
-3. pub_add ultra_flutter dev:true → added to pubspec.yaml
-4. Edit lib/bootstrap.dart — add UltraFlutterBindingMixin to AppBinding class
-5. pubspec_overrides_set patrol → path: /home/user/.claude/plugins/flutter-ultra-mcp/vendor/patrol
-6. pub_get → resolved
-7. analyze → 0 errors, 1 warning (ignore: implementation_imports — expected)
-8. launch_app device:chrome → sessionId: "flutter-1"
-9. attach(sessionId: "flutter-1")
-10. screenshot → .omc/research/setup-smoke-2026-05-19.png (dashboard visible)
-11. detach + stop_app
-
-Setup complete. 3 files changed. Smoke screenshot saved.
-Next: run /flutter-tour to capture a full visual baseline.
+User: "Set up flutter-ultra on my app."
+
+1. flutter_doctor -> all checks pass
+2. project_info -> entryPoints: ["lib/main.dart"], hasSentry: false, hasPatrol: false
+3. list_devices -> chrome, windows
+4. pub_add ultra_flutter dev:true -> added
+5. Edit lib/main.dart -> add UltraFlutterBinding.ensureInitialized()
+6. pub_get -> resolved
+7. analyze -> 0 errors
+8. launch_app(device: "chrome") -> poll -> attached
+9. screenshot -> app visible
+10. detach + stop_app
+-> "Setup complete. 2 files changed. Smoke screenshot saved."
 ```
 
 ## See also
 
-- Sibling skill: `flutter-tour` — visual screenshot tour after setup
-- Sibling skill: `flutter-debug` — triage if the smoke launch reveals a runtime error
-- `mcp__plugin_flutter_flutter-ultra-build__project_info` — entry point and feature detection
-- `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` — launch app for smoke test
-- `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` — configure patrol fork override
+- `flutter-tour` — visual screenshot tour after setup
+- `flutter-debug` — triage if the smoke launch reveals a runtime error
+- `flutter-devtools` — wire up the DevTools panel for live inspection