@bdayadev/flutter-ultra-mcp 1.3.1 → 1.4.0

package/skills/devtools/SKILL.md

@@ -1,21 +1,131 @@
 ---
-name: devtools
-description: Wiring up the Flutter DevTools panel for this plugin so the user can see live MCP activity inside their IDE. Use when the user wants to inspect the plugin's recent tool calls, attached sessions, or activity timeline.
-disable-model-invocation: true
+name: flutter-devtools
+description: Wiring up and using the flutter-ultra DevTools panel to inspect live MCP activity, attached sessions, and agent tool calls from inside the IDE. Use when the user wants to see the plugin's activity timeline, pause/resume agent flows from the panel, or stream screenshots to the DevTools view.
 ---
 
-# DevTools (stub)
+# flutter-devtools — Wire Up the DevTools Panel
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.6, §12).
+## When to use
 
-User-triggered only — installing a dev dependency and editing pubspec is opinionated.
+Use this skill when the user wants to:
+
+- See live MCP tool call activity inside Flutter DevTools while the agent is running.
+- Pause or resume an automated agent flow from a panel button (human-in-the-loop).
+- Stream screenshots or session events to the DevTools view during a tour or drive flow.
+- Verify that the DevTools extension is correctly wired to the running MCP server.
+
+## Prerequisites
+
+- The flutter-ultra-mcp plugin is already set up in the project (run `/flutter-setup` first if not).
+- Flutter DevTools is open in the IDE (VS Code: `Dart: Open DevTools` from the command palette; Android Studio: via the Flutter Inspector toolbar).
+- The DevTools extension tab labeled **flutter-ultra** must be visible. If it is not, the `ultra_flutter_devtools` package may not be in `dev_dependencies` — step 1 covers this.
 
 ## Workflow
 
-- Detect `ultra_flutter_devtools` in `dev_dependencies`; add via `mcp__flutter-ultra-build__pub_add` if missing.
-- Start the panel WebSocket via `mcp__flutter-ultra-devtools__start_panel_server`.
-- Print the DevTools URL with the `flutter-ultra` tab anchor.
+### 1. Ensure `ultra_flutter_devtools` is in dev_dependencies
+
+- Call `mcp__plugin_flutter_flutter-ultra-build__project_info` to read existing dependencies.
+- If `ultra_flutter_devtools` is NOT listed under `dev_dependencies`:
+  - Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `package: ultra_flutter_devtools`, `dev: true`.
+  - Call `mcp__plugin_flutter_flutter-ultra-build__pub_get` to resolve.
+- If `pub_add` fails (package not on pub.dev — it is bundled with the MCP plugin):
+  - Call `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` with the bundled package path.
+  - Add `ultra_flutter_devtools: any` manually under `dev_dependencies` in `pubspec.yaml`.
+  - Call `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
+
+### 2. Start the panel WebSocket server
+
+- Call `mcp__plugin_flutter_flutter-ultra-devtools__start_panel_server` with `port: 9170` (default).
+  - Returns: `{ url: "ws://127.0.0.1:9170", port: 9170, status: "listening" }`.
+  - If the port is already in use, retry with `port: 9171` (or any free port above 9170).
+- Note the returned `url` — this is what the DevTools extension iframe connects to.
+
+### 3. Connect the DevTools extension
+
+- Open Flutter DevTools in the IDE and navigate to the **flutter-ultra** tab.
+- The extension panel auto-connects to `ws://127.0.0.1:9170` when the tab loads (default port).
+- Verify connection by calling `mcp__plugin_flutter_flutter-ultra-devtools__panel_status`:
+  - Expect: `{ running: true, viewers: 1, url: "ws://127.0.0.1:9170" }`.
+  - If `viewers: 0` after 10 seconds, the extension has not connected — see edge cases below.
+
+### 4. Push a test event to confirm the pipeline
+
+- Call `mcp__plugin_flutter_flutter-ultra-devtools__push_event` with:
+  - `type: "custom"`
+  - `server: "flutter-ultra-devtools"`
+  - `payload: { message: "flutter-ultra panel connected" }`
+- If `delivered: 1` is returned, the panel is receiving events. The user should see the notification in the DevTools flutter-ultra tab.
+
+### 5. Stream activity during automated flows (optional)
+
+During long operations (tour, drive, patrol test runs), push events to keep the panel updated:
+
+- After each screenshot: call `push_event` with `type: "screenshot"` and `payload: { path: "<screenshot-path>", route: "<current-route>" }`.
+- After each tool call completes: call `push_event` with `type: "tool_result"` and `payload: { tool: "<tool-name>", status: "ok" }`.
+- On error: call `push_event` with `type: "error"` and `payload: { message: "<error>" }`.
+
+This is especially useful when running `/flutter-tour` or `/flutter-drive` so the user can follow progress without reading the raw agent output.
+
+### 6. Wait for human-in-the-loop panel commands (optional)
+
+To pause an automated flow and wait for the panel user to click a button:
+
+- Call `mcp__plugin_flutter_flutter-ultra-devtools__panel_command` with:
+  - `timeoutMs: 300000` (5 minutes — adjust to the expected review window)
+  - `prompt: "Review the current state and click Resume when ready."`
+- The tool blocks until the panel user sends a command or the timeout expires.
+- Returns: `{ type: "resume" | "pause" | <custom>, payload: {...}, viewerId: "...", timestamp: "..." }`.
+- Use `type === "pause"` to abort the current flow; `type === "resume"` to continue.
+
+### 7. Stop the server when done
+
+- Call `mcp__plugin_flutter_flutter-ultra-devtools__stop_panel_server` when the session ends.
+  - This disconnects all panel viewers and frees the port.
+  - Safe to call even if no viewers are connected.
+
+## Handling edge cases
+
+- **`viewers: 0` after tab load**: the DevTools extension connects to port 9170 by default. If `start_panel_server` used a different port, the extension won't find it. Either restart with port 9170, or check if the extension allows a custom port in its settings panel.
+- **Port already in use**: `start_panel_server` will throw. Call `panel_status` first — if `running: true` and the port matches, the server is already up from a previous session; skip to step 3.
+- **`pub_add ultra_flutter_devtools` fails**: the package is bundled inside the MCP plugin distribution. Ask the user for the plugin root path and use `pubspec_overrides_set` to point to `<plugin-root>/packages/flutter-ultra-devtools/dart/`.
+- **DevTools tab not visible**: the `ultra_flutter_devtools` package must be imported somewhere in the app (it self-registers its DevTools extension on import). Add `import 'package:ultra_flutter_devtools/ultra_flutter_devtools.dart';` to the entry point or a debug-only file.
+- **`panel_command` times out**: the panel user did not interact within `timeoutMs`. Treat the timeout as a "continue" signal and proceed with the automated flow. Notify the user in your response that the timeout elapsed.
+- **Multiple IDEs / DevTools windows**: each opened DevTools flutter-ultra tab creates a separate viewer. `push_event` broadcasts to all of them. `panel_command` dequeues from the first one that sends a response — subsequent responses from other viewers are discarded.
+
+## Output format
+
+After completing setup, report:
+
+1. **Panel URL**: the WebSocket URL the extension connects to.
+2. **Viewer count**: how many DevTools windows are connected.
+3. **Test event delivered**: yes/no.
+4. **Next steps**: suggest running `/flutter-tour` or `/flutter-drive` with the panel open to see live event streaming.
+
+## Example
+
+```
+User: "Wire up the DevTools panel so I can see what the agent is doing."
+
+1. project_info → ultra_flutter_devtools not in dev_dependencies
+2. pub_add ultra_flutter_devtools dev:true → added
+3. pub_get → resolved
+4. start_panel_server port:9170 → url: ws://127.0.0.1:9170
+5. [User opens DevTools → flutter-ultra tab]
+6. panel_status → { running: true, viewers: 1 }
+7. push_event type:custom payload:{ message: "flutter-ultra panel connected" }
+   → delivered: 1
+8. Panel confirmed working.
+
+Panel URL: ws://127.0.0.1:9170 — 1 viewer connected.
+Test event delivered: yes.
+Next: run /flutter-tour with the panel open to see screenshots streaming live.
+```
 
 ## See also
 
-- Plan §8.6, §6.2
+- Sibling skill: `flutter-tour` — route screenshot tour; push screenshot events during the tour
+- Sibling skill: `flutter-drive` — multi-step flows; use `panel_command` for human review gates
+- `mcp__plugin_flutter_flutter-ultra-devtools__start_panel_server` — start the WS server
+- `mcp__plugin_flutter_flutter-ultra-devtools__panel_status` — check viewer count
+- `mcp__plugin_flutter_flutter-ultra-devtools__push_event` — stream events to the panel
+- `mcp__plugin_flutter_flutter-ultra-devtools__panel_command` — wait for human-in-the-loop input

package/skills/drive/SKILL.md

@@ -1,20 +1,143 @@
 ---
-name: drive
+name: flutter-drive
 description: Driving multi-step user flows in a running Flutter app via gestures and assertions. Use when reproducing a bug across several screens, validating an onboarding flow, or running an ad-hoc end-to-end scenario without writing a patrol test.
 ---
 
-# Drive (stub)
+# flutter-drive — Multi-Step User Flow Automation
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.2, §12).
+## When to use
+
+Use this skill when the user wants to walk through a specific interactive flow — login sequences, checkout funnels, onboarding wizards, form submissions — and wants the agent to drive the app step by step, verifying state and capturing screenshots between major steps. This is ad-hoc flow automation; for repeatable E2E test suites use the `flutter-test` skill instead.
+
+## Prerequisites
+
+- A Flutter app is running in debug mode with the `ultra_flutter` binding initialized (or the app can be launched via `mcp__plugin_flutter_flutter-ultra-runtime__launch_app`).
+- The user has described the flow to execute (e.g. "log in as user@example.com, navigate to invoices, open the first one").
+- For web OAuth flows: a browser context must be available via `mcp__plugin_flutter_flutter-ultra-browser__launch_browser`.
 
 ## Workflow
 
-- Enumerate interactive elements via `mcp__flutter-ultra-gesture__interactive_elements`.
-- Tap or enter text using key-based finders.
-- Verify intermediate state via `mcp__flutter-ultra-runtime__get_widget_tree`.
-- For OAuth/popups: delegate to `mcp__flutter-ultra-browser__*` (web) or `mcp__flutter-ultra-native-mobile__*` (mobile).
+### 1. Attach to the running session
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` — pick the session matching the target app.
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__attach` with `sessionId`.
+- Take an initial screenshot with `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` to confirm starting state.
+
+### 2. Plan the flow steps
+
+Break the user's request into discrete, verifiable steps:
+
+```
+Step 1: Navigate to /login
+Step 2: Enter email "user@example.com" in field key='email-field'
+Step 3: Enter password in field key='password-field'
+Step 4: Tap button key='sign-in-button'
+Step 5: Verify dashboard loaded (widget key='dashboard-root' present)
+Step 6: Screenshot
+```
+
+Announce the plan before executing if it involves more than 3 steps.
+
+### 3. For each step — inspect → act → verify → screenshot
+
+**Inspect the current UI:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` with `key` or `text` to confirm the target element exists before acting.
+- If `find_widget` returns nothing, call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` to understand the current widget hierarchy and adjust the finder.
+
+**Perform the action** (choose appropriate tool):
+
+- **Tap by key**: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `find.byKey(ValueKey('btn')).first.tap()` via the gesture VM extension, or use marionette's `mcp__marionette__tap` if connected.
+- **Enter text**: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to set controller value, or `mcp__marionette__enter_text` for native keyboard input.
+- **Scroll**: `mcp__marionette__scroll_to` with the target key.
+- **Navigate programmatically**: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `context.go('/route')`.
+
+**Verify the result:**
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` for an expected element on the next screen.
+- Or call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to read state: `MyBloc.of(context).state.runtimeType.toString()`.
+- If verification fails: call `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` and `mcp__plugin_flutter_flutter-ultra-runtime__get_logs` before reporting failure.
+
+**Screenshot after major transitions** (not every micro-step):
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` → save to `.omc/research/drive-<date>/<step-N>-<label>.png`.
+
+### 4. Web OAuth / external popups (web target)
+
+When a flow involves an external OAuth consent screen:
+
+1. Call `mcp__plugin_flutter_flutter-ultra-browser__intercept_redirect` to capture the redirect URL.
+2. Call `mcp__plugin_flutter_flutter-ultra-browser__navigate` to drive the external auth page.
+3. Call `mcp__plugin_flutter_flutter-ultra-browser__fill` for username/password fields.
+4. Call `mcp__plugin_flutter_flutter-ultra-browser__click` on the submit button.
+5. Call `mcp__plugin_flutter_flutter-ultra-browser__wait_for_url` matching the app's redirect URI.
+6. Re-attach to the Flutter runtime after the redirect completes.
+
+### 5. Native mobile system dialogs (mobile target)
+
+When the flow triggers OS-level permission dialogs or system sheets:
+
+- Call `mcp__plugin_flutter_flutter-ultra-native-mobile__wait_for_native_element` to detect the dialog.
+- Call `mcp__plugin_flutter_flutter-ultra-native-mobile__native_permission_grant` or `native_permission_deny`.
+- Call `mcp__plugin_flutter_flutter-ultra-native-mobile__native_tap` for other system buttons.
+
+### 6. Report the flow result
+
+After all steps complete, produce:
+
+- A numbered summary of steps taken, each with pass/fail status and the screenshot path if captured.
+- Any errors encountered (with stack traces from `get_runtime_errors`).
+- Final state description (current route, visible widget).
+
+## Handling edge cases
+
+- **Element not found**: call `get_widget_tree` from the root to find where the element actually is; the app may still be loading or may have navigated differently than expected. Wait up to 3 seconds in 500 ms increments by calling `evaluate` with `SchedulerBinding.instance.endOfFrame`.
+- **App is on wrong route**: call `evaluate` with `GoRouter.of(context).routerDelegate.currentConfiguration.fullPath` to read current route, then navigate to the expected starting point.
+- **Text field requires focus first**: tap the field before entering text; use `find_widget` to confirm it has focus via `hasFocus` property.
+- **Async operations in progress**: check for loading indicators via `find_widget` with type `CircularProgressIndicator`; wait and retry.
+- **Hot-reload after code change**: call `mcp__plugin_flutter_flutter-ultra-runtime__hot_reload` after any code edit, then re-verify the widget tree before continuing.
+
+## Key tool reference
+
+| Action                        | Tool                                                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Find element by key/text      | `mcp__plugin_flutter_flutter-ultra-runtime__find_widget`                                              |
+| Inspect widget hierarchy      | `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree`                                          |
+| Run arbitrary Dart in-app     | `mcp__plugin_flutter_flutter-ultra-runtime__evaluate`                                                 |
+| Tap / enter text (marionette) | `mcp__marionette__tap`, `mcp__marionette__enter_text`                                                 |
+| Scroll to element             | `mcp__marionette__scroll_to`                                                                          |
+| Read runtime errors           | `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`                                       |
+| Read app logs                 | `mcp__plugin_flutter_flutter-ultra-runtime__get_logs`                                                 |
+| Screenshot                    | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot`                                               |
+| Web fill / click              | `mcp__plugin_flutter_flutter-ultra-browser__fill`, `mcp__plugin_flutter_flutter-ultra-browser__click` |
+| Wait for URL (OAuth)          | `mcp__plugin_flutter_flutter-ultra-browser__wait_for_url`                                             |
+| Native permission grant       | `mcp__plugin_flutter_flutter-ultra-native-mobile__native_permission_grant`                            |
+
+## Example
+
+```
+User: "Drive the login flow for user@invora.app with password hunter2, then open the first invoice."
+
+1. discover_sessions → attach(sessionId: "flutter-1")
+2. screenshot → step-0-start.png (confirm login screen)
+3. find_widget(key: "email-field") → found
+4. evaluate: set email controller value to "user@invora.app"
+5. find_widget(key: "password-field") → found
+6. evaluate: set password controller value to "hunter2"
+7. find_widget(key: "sign-in-button") → found; marionette tap(key: "sign-in-button")
+8. evaluate: await SchedulerBinding.instance.endOfFrame (wait for navigation)
+9. find_widget(key: "dashboard-root") → found (login succeeded)
+10. screenshot → step-1-dashboard.png
+11. evaluate: context.go('/invoices')
+12. find_widget(text: "Invoice #1") → found; marionette tap(text: "Invoice #1")
+13. find_widget(key: "invoice-detail-root") → found
+14. screenshot → step-2-invoice-detail.png
+
+Summary: 3 major steps completed, all passed. Final route: /invoices/1.
+```
 
 ## See also
 
-- Plan §8.2
-- Sibling skill: `test` for orchestrated patrol runs
+- Sibling skill: `flutter-tour` for passive route screenshot sweeps (no interaction)
+- Sibling skill: `flutter-test` for orchestrated patrol E2E test runs
+- `mcp__marionette__*` — native gesture and text tools via VM service extensions

package/skills/scaffold/SKILL.md

@@ -1,21 +1,167 @@
 ---
-name: scaffold
+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.
 disable-model-invocation: true
 ---
 
-# Scaffold (stub)
+# flutter-scaffold — Project and Feature Scaffolding
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.4, §12).
+## When to use
 
-This skill is opinionated and destructive (creates files), so it is **not** auto-invocable. The user must trigger it explicitly with `/flutter:scaffold`.
+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.
 
-## Workflow
+## Prerequisites
 
-- Project mode: `flutter create` via shell with detected channel + org.
-- Feature mode: read the existing structure via `mcp__flutter-ultra-build__project_info`, then create files that match.
+- 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.
+
+## 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) |
+
+---
+
+## Project mode — new Flutter app
+
+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.
+
+---
+
+## Feature mode — detect existing conventions first
+
+Before creating any files, call `mcp__plugin_flutter_flutter-ultra-build__project_info` on the target project to read:
+
+- Project root and `lib/` structure
+- Existing dependencies (from `pubspec.yaml`)
+
+Then detect the project's conventions by reading `pubspec.yaml` dependencies:
+
+| 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 |
+
+| Detected dep | Routing pattern          |
+| ------------ | ------------------------ |
+| `go_router`  | GoRouter                 |
+| `auto_route` | AutoRoute                |
+| None         | Navigator 1.0 (push/pop) |
+
+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`):
+
+```
+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
+```
+
+For **Riverpod**: replace `bloc/` with `provider/` containing a `StateNotifier` or `AsyncNotifier`.
+For **Provider**: replace `bloc/` with `provider/` containing a `ChangeNotifier`.
+
+### Route registration (GoRouter):
+
+Add the new route to the router config file (detect by searching for `GoRouter(` in `lib/`):
+
+```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:
+
+**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.
+
+**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.
+
+**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
+
+When the user asks to add l10n:
+
+1. Call `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`.
+
+---
+
+## 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.
 
 ## See also
 
-- Plan §8.4
-- Sibling skill: `setup` for plugging the plugin into an existing codebase
+- 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

package/skills/setup/SKILL.md

@@ -1,26 +1,150 @@
 ---
-name: setup
-description: Bootstrapping flutter-ultra-mcp into an existing Flutter codebase end-to-end. Use when the user wants the plugin enabled for the first time on a project, or when re-running after a clean install. Idempotent.
-disable-model-invocation: true
+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.
 ---
 
-# Setup (stub)
+# flutter-setup — One-Command Plugin Setup
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.7, §12).
+## When to use
 
-User-triggered only — patches pubspec, entry points, and `.vscode/launch.json`.
+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.
 
-## Workflow (target)
+## Prerequisites
 
-1. Detect project layout via `mcp__flutter-ultra-build__project_info` (entry points, existing bindings, Sentry usage, patrol).
-2. Add `ultra_flutter` to `dev_dependencies`; if Sentry detected, show the direct `// ignore: implementation_imports` binding pattern.
-3. Patch entry point(s) with AST-aware edits to mix in `UltraFlutterBinding` under `kDebugMode`.
-4. Optional: add a launch.json profile pre-applying dart-defines for session discovery.
-5. Detect existing patrol setup and offer the `run_patrol_web` wrapper.
-6. Generate per-project `.flutter-ultra.config.yaml`.
-7. Run a smoke launch + screenshot + detach.
-8. Emit `SETUP-REPORT.md` at project root.
+- 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).
+
+## 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).
+
+### 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.
+
+### 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:
+
+```dart
+import 'package:flutter/foundation.dart';
+import 'package:ultra_flutter/ultra_flutter.dart';
+
+void main() {
+  if (kDebugMode) {
+    UltraFlutterBinding.ensureInitialized();
+  }
+  runApp(const MyApp());
+}
+```
+
+**With Sentry** (when `hasSentry: true`) — Sentry installs its own binding; use the direct mixin pattern:
+
+```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)
+
+When `project_info` reported `hasPatrol: true`:
+
+- 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.
+
+### 5. Run static analysis to verify the setup
+
+- 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.
+
+### 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.
+
+## 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.
+
+## 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.
+```
 
 ## See also
 
-- Plan §8.7
+- 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