@bdayadev/flutter-ultra-mcp 1.6.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/package.json +1 -1
  4. package/skills/bisect/SKILL.md +91 -121
  5. package/skills/debug/SKILL.md +98 -99
  6. package/skills/devtools/SKILL.md +93 -91
  7. package/skills/drive/SKILL.md +90 -98
  8. package/skills/scaffold/SKILL.md +132 -126
  9. package/skills/setup/SKILL.md +89 -92
  10. package/skills/test/SKILL.md +112 -104
  11. package/skills/tour/SKILL.md +94 -82
package/skills/devtools/SKILL.md CHANGED
@@ -1,131 +1,133 @@
1
1
  ---
2
2
  name: flutter-devtools
3
- 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.
3
+ description: Wires up and uses the flutter-ultra DevTools panel to inspect live MCP activity, pause/resume agent flows, and stream screenshots to the DevTools view. Use when the user wants to see plugin activity in DevTools, set up human-in-the-loop review gates, or stream live progress from tours and drive flows.
4
4
  ---
5
5
 
6
- # flutter-devtools — Wire Up the DevTools Panel
6
+ # DevTools Panel Integration
7
7
 
8
- ## When to use
8
+ ## Workflow
9
9
 
10
- Use this skill when the user wants to:
10
+ ### 1. Ensure `ultra_flutter_devtools` is in dev_dependencies
11
11
 
12
- - See live MCP tool call activity inside Flutter DevTools while the agent is running.
13
- - Pause or resume an automated agent flow from a panel button (human-in-the-loop).
14
- - Stream screenshots or session events to the DevTools view during a tour or drive flow.
15
- - Verify that the DevTools extension is correctly wired to the running MCP server.
12
+ - `mcp__plugin_flutter_flutter-ultra-build__project_info` to check existing dependencies.
13
+ - If missing: `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `ultra_flutter_devtools`, `dev: true`.
14
+ - If `pub_add` fails (bundled package): `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` with the bundled path, then `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
16
15
 
17
- ## Prerequisites
16
+ ### 2. Start the panel server
18
17
 
19
- - The flutter-ultra-mcp plugin is already set up in the project (run `/flutter-setup` first if not).
20
- - Flutter DevTools is open in the IDE (VS Code: `Dart: Open DevTools` from the command palette; Android Studio: via the Flutter Inspector toolbar).
21
- - 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.
18
+ - `mcp__plugin_flutter_flutter-ultra-devtools__start_panel_server` with `port: 9170`.
19
+ - Returns `{ url, port, status }`.
20
+ - If port is in use, call `mcp__plugin_flutter_flutter-ultra-devtools__panel_status` first — if already running, skip to step 3.
22
21
 
23
- ## Workflow
22
+ ### 3. Verify connection
24
23
 
25
- ### 1. Ensure `ultra_flutter_devtools` is in dev_dependencies
24
+ - Open Flutter DevTools in the IDE, navigate to the **flutter-ultra** tab.
25
+ - `mcp__plugin_flutter_flutter-ultra-devtools__panel_status` — expect `{ running: true, viewers: 1 }`.
26
26
 
27
- - Call `mcp__plugin_flutter_flutter-ultra-build__project_info` to read existing dependencies.
28
- - If `ultra_flutter_devtools` is NOT listed under `dev_dependencies`:
29
- - Call `mcp__plugin_flutter_flutter-ultra-build__pub_add` with `package: ultra_flutter_devtools`, `dev: true`.
30
- - Call `mcp__plugin_flutter_flutter-ultra-build__pub_get` to resolve.
31
- - If `pub_add` fails (package not on pub.dev — it is bundled with the MCP plugin):
32
- - Call `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` with the bundled package path.
33
- - Add `ultra_flutter_devtools: any` manually under `dev_dependencies` in `pubspec.yaml`.
34
- - Call `mcp__plugin_flutter_flutter-ultra-build__pub_get`.
27
+ ### 4. Test the pipeline
35
28
 
36
- ### 2. Start the panel WebSocket server
29
+ - `mcp__plugin_flutter_flutter-ultra-devtools__push_event` with:
30
+ - `type: "custom"`, `server: "flutter-ultra-devtools"`, `payload: { message: "panel connected" }`.
31
+ - If `delivered: 1`, the panel is receiving events.
37
32
 
38
- - Call `mcp__plugin_flutter_flutter-ultra-devtools__start_panel_server` with `port: 9170` (default).
39
- - Returns: `{ url: "ws://127.0.0.1:9170", port: 9170, status: "listening" }`.
40
- - If the port is already in use, retry with `port: 9171` (or any free port above 9170).
41
- - Note the returned `url` — this is what the DevTools extension iframe connects to.
33
+ ### 5. Stream activity during automated flows
42
34
 
43
- ### 3. Connect the DevTools extension
35
+ Push events to keep the panel updated during `/flutter:tour` or `/flutter:drive`:
44
36
 
45
- - Open Flutter DevTools in the IDE and navigate to the **flutter-ultra** tab.
46
- - The extension panel auto-connects to `ws://127.0.0.1:9170` when the tab loads (default port).
47
- - Verify connection by calling `mcp__plugin_flutter_flutter-ultra-devtools__panel_status`:
48
- - Expect: `{ running: true, viewers: 1, url: "ws://127.0.0.1:9170" }`.
49
- - If `viewers: 0` after 10 seconds, the extension has not connected — see edge cases below.
37
+ **Screenshot events:**
38
+ ```
39
+ push_event(type: "screenshot", payload: { path: "tour/login.png", route: "/login" })
40
+ ```
50
41
 
51
- ### 4. Push a test event to confirm the pipeline
42
+ **Tool result events:**
43
+ ```
44
+ push_event(type: "tool_result", payload: { tool: "tap", status: "ok" })
45
+ ```
46
+
47
+ **Error events:**
48
+ ```
49
+ push_event(type: "error", payload: { message: "Widget not found" })
50
+ ```
52
51
 
53
- - Call `mcp__plugin_flutter_flutter-ultra-devtools__push_event` with:
54
- - `type: "custom"`
55
- - `server: "flutter-ultra-devtools"`
56
- - `payload: { message: "flutter-ultra panel connected" }`
57
- - If `delivered: 1` is returned, the panel is receiving events. The user should see the notification in the DevTools flutter-ultra tab.
52
+ Combine with tools from other servers for rich context:
58
53
 
59
- ### 5. Stream activity during automated flows (optional)
54
+ - After `mcp__plugin_flutter_flutter-ultra-runtime__screenshot`, push the path as a screenshot event.
55
+ - After `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`, push errors as error events.
56
+ - After `mcp__plugin_flutter_flutter-ultra-gesture__tap`, push the result as a tool_result event.
57
+ - After `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result`, push test results.
60
58
 
61
- During long operations (tour, drive, patrol test runs), push events to keep the panel updated:
59
+ ### 6. Human-in-the-loop review gates
62
60
 
63
- - After each screenshot: call `push_event` with `type: "screenshot"` and `payload: { path: "<screenshot-path>", route: "<current-route>" }`.
64
- - After each tool call completes: call `push_event` with `type: "tool_result"` and `payload: { tool: "<tool-name>", status: "ok" }`.
65
- - On error: call `push_event` with `type: "error"` and `payload: { message: "<error>" }`.
61
+ To pause and wait for the panel user to click Resume:
66
62
 
67
- This is especially useful when running `/flutter-tour` or `/flutter-drive` so the user can follow progress without reading the raw agent output.
63
+ - `mcp__plugin_flutter_flutter-ultra-devtools__panel_command` with `timeoutMs` and `prompt`.
64
+ - Returns `{ type: "resume" | "pause" | <custom>, payload, viewerId, timestamp }`.
65
+ - `type === "pause"` means abort; `type === "resume"` means continue.
68
66
 
69
- ### 6. Wait for human-in-the-loop panel commands (optional)
67
+ Useful during:
70
68
 
71
- To pause an automated flow and wait for the panel user to click a button:
69
+ - Long `flutter-tour` runs — let the user review each route before continuing.
70
+ - `flutter-drive` validation flows — gate critical steps behind human approval.
71
+ - `flutter-test` patrol runs — pause after failures for manual inspection.
72
72
 
73
- - Call `mcp__plugin_flutter_flutter-ultra-devtools__panel_command` with:
74
- - `timeoutMs: 300000` (5 minutes — adjust to the expected review window)
75
- - `prompt: "Review the current state and click Resume when ready."`
76
- - The tool blocks until the panel user sends a command or the timeout expires.
77
- - Returns: `{ type: "resume" | "pause" | <custom>, payload: {...}, viewerId: "...", timestamp: "..." }`.
78
- - Use `type === "pause"` to abort the current flow; `type === "resume"` to continue.
73
+ ### 7. Stop the server
79
74
 
80
- ### 7. Stop the server when done
75
+ - `mcp__plugin_flutter_flutter-ultra-devtools__stop_panel_server` when the session ends.
81
76
 
82
- - Call `mcp__plugin_flutter_flutter-ultra-devtools__stop_panel_server` when the session ends.
83
- - This disconnects all panel viewers and frees the port.
84
- - Safe to call even if no viewers are connected.
77
+ ## Edge cases
85
78
 
86
- ## Handling edge cases
79
+ - **`viewers: 0` after tab load**: the DevTools extension connects to port 9170 by default. If a different port was used, restart with 9170.
80
+ - **Port already in use**: `mcp__plugin_flutter_flutter-ultra-devtools__panel_status` first — if running, reuse it.
81
+ - **DevTools tab not visible**: `ultra_flutter_devtools` must be imported somewhere in the app (self-registers on import).
82
+ - **`panel_command` times out**: treat as "continue" and proceed. Notify the user.
83
+ - **Multiple DevTools windows**: `push_event` broadcasts to all. `panel_command` dequeues from the first responder.
87
84
 
88
- - **`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.
89
- - **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.
90
- - **`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/`.
91
- - **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.
92
- - **`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.
93
- - **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.
85
+ ## Tool reference
94
86
 
95
- ## Output format
87
+ | Action | Tool |
88
+ |--------|------|
89
+ | Start server | `mcp__plugin_flutter_flutter-ultra-devtools__start_panel_server` |
90
+ | Stop server | `mcp__plugin_flutter_flutter-ultra-devtools__stop_panel_server` |
91
+ | Check status | `mcp__plugin_flutter_flutter-ultra-devtools__panel_status` |
92
+ | Push event | `mcp__plugin_flutter_flutter-ultra-devtools__push_event` |
93
+ | Wait for command | `mcp__plugin_flutter_flutter-ultra-devtools__panel_command` |
94
+ | Project info | `mcp__plugin_flutter_flutter-ultra-build__project_info` |
95
+ | Add dependency | `mcp__plugin_flutter_flutter-ultra-build__pub_add` |
96
+ | Resolve deps | `mcp__plugin_flutter_flutter-ultra-build__pub_get` |
97
+ | Overrides set | `mcp__plugin_flutter_flutter-ultra-build__pubspec_overrides_set` |
98
+ | VM screenshot | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` |
99
+ | Runtime errors | `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` |
100
+ | Gesture tap | `mcp__plugin_flutter_flutter-ultra-gesture__tap` |
101
+ | Patrol result | `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result` |
96
102
 
97
- After completing setup, report:
103
+ ## Event types reference
98
104
 
99
- 1. **Panel URL**: the WebSocket URL the extension connects to.
100
- 2. **Viewer count**: how many DevTools windows are connected.
101
- 3. **Test event delivered**: yes/no.
102
- 4. **Next steps**: suggest running `/flutter-tour` or `/flutter-drive` with the panel open to see live event streaming.
105
+ | Type | Payload | When to use |
106
+ |------|---------|-------------|
107
+ | `custom` | `{ message: string }` | General notifications |
108
+ | `screenshot` | `{ path: string, route?: string }` | After capturing a screenshot |
109
+ | `tool_result` | `{ tool: string, status: string }` | After any tool call completes |
110
+ | `error` | `{ message: string, stack?: string }` | On runtime errors or tool failures |
111
+ | `progress` | `{ step: number, total: number, label: string }` | During multi-step flows |
112
+ | `test_result` | `{ name: string, passed: boolean }` | After each test completes |
103
113
 
104
114
  ## Example
105
115
 
106
116
  ```
107
- User: "Wire up the DevTools panel so I can see what the agent is doing."
108
-
109
- 1. project_info → ultra_flutter_devtools not in dev_dependencies
110
- 2. pub_add ultra_flutter_devtools dev:true → added
111
- 3. pub_get → resolved
112
- 4. start_panel_server port:9170 → url: ws://127.0.0.1:9170
113
- 5. [User opens DevTools → flutter-ultra tab]
114
- 6. panel_status → { running: true, viewers: 1 }
115
- 7. push_event type:custom payload:{ message: "flutter-ultra panel connected" }
116
- → delivered: 1
117
- 8. Panel confirmed working.
118
-
119
- Panel URL: ws://127.0.0.1:9170 — 1 viewer connected.
120
- Test event delivered: yes.
121
- Next: run /flutter-tour with the panel open to see screenshots streaming live.
117
+ User: "Wire up the DevTools panel."
118
+
119
+ 1. project_info -> ultra_flutter_devtools not in dev_dependencies
120
+ 2. pub_add ultra_flutter_devtools dev:true
121
+ 3. pub_get
122
+ 4. start_panel_server(port: 9170) -> ws://127.0.0.1:9170
123
+ 5. [User opens DevTools -> flutter-ultra tab]
124
+ 6. panel_status -> { running: true, viewers: 1 }
125
+ 7. push_event(type: "custom", payload: { message: "panel connected" }) -> delivered: 1
126
+ -> "Panel at ws://127.0.0.1:9170, 1 viewer connected."
122
127
  ```
123
128
 
124
129
  ## See also
125
130
 
126
- - Sibling skill: `flutter-tour` — route screenshot tour; push screenshot events during the tour
127
- - Sibling skill: `flutter-drive` — multi-step flows; use `panel_command` for human review gates
128
- - `mcp__plugin_flutter_flutter-ultra-devtools__start_panel_server` — start the WS server
129
- - `mcp__plugin_flutter_flutter-ultra-devtools__panel_status` — check viewer count
130
- - `mcp__plugin_flutter_flutter-ultra-devtools__push_event` — stream events to the panel
131
- - `mcp__plugin_flutter_flutter-ultra-devtools__panel_command` — wait for human-in-the-loop input
131
+ - `flutter-tour` — route screenshot tour; push screenshot events during the tour
132
+ - `flutter-drive` — multi-step flows; use `panel_command` for human review gates
133
+ - `flutter-test` — test orchestration; push test results to the panel
package/skills/drive/SKILL.md CHANGED
@@ -1,143 +1,135 @@
1
1
  ---
2
2
  name: flutter-drive
3
- 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.
3
+ description: Drives 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, running an ad-hoc end-to-end scenario without writing a patrol test, or automating login/checkout/form-submission sequences.
4
4
  ---
5
5
 
6
- # flutter-drive — Multi-Step User Flow Automation
6
+ # Multi-Step User Flow Automation
7
7
 
8
- ## When to use
9
-
10
- 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.
11
-
12
- ## Prerequisites
13
-
14
- - 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`).
15
- - The user has described the flow to execute (e.g. "log in as user@example.com, navigate to invoices, open the first one").
16
- - For web OAuth flows: a browser context must be available via `mcp__plugin_flutter_flutter-ultra-browser__launch_browser`.
8
+ Drive interactive flows step by step — login sequences, checkout funnels, onboarding wizards, form submissions — verifying state and capturing screenshots between major steps. For repeatable E2E test suites, use `flutter-test` instead.
17
9
 
18
10
  ## Workflow
19
11
 
20
12
  ### 1. Attach to the running session
21
13
 
22
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` — pick the session matching the target app.
23
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__attach` with `sessionId`.
24
- - Take an initial screenshot with `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` to confirm starting state.
14
+ - `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` to find active sessions.
15
+ - If none, `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` + `mcp__plugin_flutter_flutter-ultra-runtime__poll_launch_app`.
16
+ - `mcp__plugin_flutter_flutter-ultra-runtime__attach` with the chosen session.
17
+ - `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` to confirm starting state.
25
18
 
26
- ### 2. Plan the flow steps
19
+ ### 2. Plan the flow
27
20
 
28
- Break the user's request into discrete, verifiable steps:
21
+ Break the user's request into discrete, verifiable steps. Announce the plan before executing if more than 3 steps.
29
22
 
30
- ```
31
- Step 1: Navigate to /login
32
- Step 2: Enter email "user@example.com" in field key='email-field'
33
- Step 3: Enter password in field key='password-field'
34
- Step 4: Tap button key='sign-in-button'
35
- Step 5: Verify dashboard loaded (widget key='dashboard-root' present)
36
- Step 6: Screenshot
37
- ```
23
+ ### 3. For each step: inspect, act, verify, screenshot
38
24
 
39
- Announce the plan before executing if it involves more than 3 steps.
25
+ **Inspect the current UI:**
40
26
 
41
- ### 3. For each step — inspect → act → verify → screenshot
27
+ - `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` to confirm the target element exists.
28
+ - `mcp__plugin_flutter_flutter-ultra-gesture__interactive_elements` to discover all tappable/editable elements on screen.
29
+ - If not found, `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` to understand the hierarchy.
42
30
 
43
- **Inspect the current UI:**
31
+ **Perform the action:**
44
32
 
45
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` with `key` or `text` to confirm the target element exists before acting.
46
- - 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.
33
+ | Action | Tool |
34
+ |--------|------|
35
+ | Tap by key/text/coords | `mcp__plugin_flutter_flutter-ultra-gesture__tap` |
36
+ | Double tap | `mcp__plugin_flutter_flutter-ultra-gesture__double_tap` |
37
+ | Long press | `mcp__plugin_flutter_flutter-ultra-gesture__long_press` |
38
+ | Enter text | `mcp__plugin_flutter_flutter-ultra-gesture__enter_text` |
39
+ | Clear text field | `mcp__plugin_flutter_flutter-ultra-gesture__clear_text` |
40
+ | Scroll to element | `mcp__plugin_flutter_flutter-ultra-gesture__scroll_to` |
41
+ | Scroll until visible | `mcp__plugin_flutter_flutter-ultra-gesture__scroll_until_visible` |
42
+ | Swipe gesture | `mcp__plugin_flutter_flutter-ultra-gesture__swipe` |
43
+ | Pinch zoom | `mcp__plugin_flutter_flutter-ultra-gesture__pinch_zoom` |
44
+ | Navigate programmatically | `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` |
47
45
 
48
- **Perform the action** (choose appropriate tool):
46
+ **Wait for the UI to settle:**
49
47
 
50
- - **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.
51
- - **Enter text**: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to set controller value, or `mcp__marionette__enter_text` for native keyboard input.
52
- - **Scroll**: `mcp__marionette__scroll_to` with the target key.
53
- - **Navigate programmatically**: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `context.go('/route')`.
48
+ - `mcp__plugin_flutter_flutter-ultra-gesture__wait_for` to wait for a widget to appear/disappear after an action.
49
+ - Or `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `SchedulerBinding.instance.endOfFrame`.
54
50
 
55
51
  **Verify the result:**
56
52
 
57
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` for an expected element on the next screen.
58
- - Or call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to read state: `MyBloc.of(context).state.runtimeType.toString()`.
59
- - 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.
53
+ - `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` for an expected element on the next screen.
54
+ - `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists` for quick existence checks.
55
+ - `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to read state: `MyBloc.of(context).state.runtimeType`.
56
+ - On failure: `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` and `mcp__plugin_flutter_flutter-ultra-runtime__get_logs`.
57
+
58
+ **Screenshot after major transitions:**
59
+
60
+ - `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` for VM-level capture.
61
+
62
+ ### 4. HTTP/gRPC verification (optional)
60
63
 
61
- **Screenshot after major transitions** (not every micro-step):
64
+ Capture network traffic during the flow to verify API calls:
62
65
 
63
- - `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` → save to `.omc/research/drive-<date>/<step-N>-<label>.png`.
66
+ - `mcp__plugin_flutter_flutter-ultra-runtime__start_http_capture` before starting the flow.
67
+ - `mcp__plugin_flutter_flutter-ultra-runtime__get_http_events` at checkpoints to verify expected API calls were made.
68
+ - `mcp__plugin_flutter_flutter-ultra-runtime__decode_grpc_message` to inspect gRPC request/response payloads.
69
+ - `mcp__plugin_flutter_flutter-ultra-runtime__stop_http_capture` when done.
64
70
 
65
- ### 4. Web OAuth / external popups (web target)
71
+ ### 5. Web OAuth / external popups (web targets)
66
72
 
67
73
  When a flow involves an external OAuth consent screen:
68
74
 
69
- 1. Call `mcp__plugin_flutter_flutter-ultra-browser__intercept_redirect` to capture the redirect URL.
70
- 2. Call `mcp__plugin_flutter_flutter-ultra-browser__navigate` to drive the external auth page.
71
- 3. Call `mcp__plugin_flutter_flutter-ultra-browser__fill` for username/password fields.
72
- 4. Call `mcp__plugin_flutter_flutter-ultra-browser__click` on the submit button.
73
- 5. Call `mcp__plugin_flutter_flutter-ultra-browser__wait_for_url` matching the app's redirect URI.
74
- 6. Re-attach to the Flutter runtime after the redirect completes.
75
+ 1. `mcp__plugin_flutter_flutter-ultra-browser__intercept_redirect` to capture the redirect URL.
76
+ 2. `mcp__plugin_flutter_flutter-ultra-browser__navigate` to drive the external auth page.
77
+ 3. `mcp__plugin_flutter_flutter-ultra-browser__fill` for username/password fields.
78
+ 4. `mcp__plugin_flutter_flutter-ultra-browser__click` on the submit button.
79
+ 5. `mcp__plugin_flutter_flutter-ultra-browser__wait_for_url` matching the app's redirect URI.
75
80
 
76
- ### 5. Native mobile system dialogs (mobile target)
81
+ ### 6. Native mobile system dialogs (mobile targets)
77
82
 
78
- When the flow triggers OS-level permission dialogs or system sheets:
83
+ - `mcp__plugin_flutter_flutter-ultra-native-mobile__wait_for_native_element` to detect OS dialogs.
84
+ - `mcp__plugin_flutter_flutter-ultra-native-mobile__native_permission_grant` or `mcp__plugin_flutter_flutter-ultra-native-mobile__native_permission_deny`.
85
+ - `mcp__plugin_flutter_flutter-ultra-native-mobile__native_tap` for other system UI elements.
86
+ - `mcp__plugin_flutter_flutter-ultra-native-mobile__native_back` for Android back navigation.
87
+ - `mcp__plugin_flutter_flutter-ultra-native-mobile__native_home` to press Home.
88
+ - `mcp__plugin_flutter_flutter-ultra-native-mobile__solve_oauth_cct` for Chrome Custom Tab OAuth flows.
79
89
 
80
- - Call `mcp__plugin_flutter_flutter-ultra-native-mobile__wait_for_native_element` to detect the dialog.
81
- - Call `mcp__plugin_flutter_flutter-ultra-native-mobile__native_permission_grant` or `native_permission_deny`.
82
- - Call `mcp__plugin_flutter_flutter-ultra-native-mobile__native_tap` for other system buttons.
90
+ ### 7. Native desktop dialogs (desktop targets)
83
91
 
84
- ### 6. Report the flow result
92
+ - `mcp__plugin_flutter_flutter-ultra-native-desktop__wait_for_window` to detect native dialogs.
93
+ - `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_click` to interact with dialog buttons.
94
+ - `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_type` for text input in native fields.
95
+ - `mcp__plugin_flutter_flutter-ultra-native-desktop__select_file_in_dialog` for file picker dialogs.
96
+ - `mcp__plugin_flutter_flutter-ultra-native-desktop__confirm_dialog` to accept/dismiss confirmation dialogs.
85
97
 
86
- After all steps complete, produce:
98
+ ### 8. Report the flow result
87
99
 
88
- - A numbered summary of steps taken, each with pass/fail status and the screenshot path if captured.
89
- - Any errors encountered (with stack traces from `get_runtime_errors`).
90
- - Final state description (current route, visible widget).
100
+ Produce a numbered summary: steps taken, pass/fail status per step, screenshot paths, and any errors from `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`.
91
101
 
92
102
  ## Handling edge cases
93
103
 
94
- - **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`.
95
- - **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.
96
- - **Text field requires focus first**: tap the field before entering text; use `find_widget` to confirm it has focus via `hasFocus` property.
97
- - **Async operations in progress**: check for loading indicators via `find_widget` with type `CircularProgressIndicator`; wait and retry.
98
- - **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.
99
-
100
- ## Key tool reference
101
-
102
- | Action | Tool |
103
- | ----------------------------- | ----------------------------------------------------------------------------------------------------- |
104
- | Find element by key/text | `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` |
105
- | Inspect widget hierarchy | `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` |
106
- | Run arbitrary Dart in-app | `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` |
107
- | Tap / enter text (marionette) | `mcp__marionette__tap`, `mcp__marionette__enter_text` |
108
- | Scroll to element | `mcp__marionette__scroll_to` |
109
- | Read runtime errors | `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` |
110
- | Read app logs | `mcp__plugin_flutter_flutter-ultra-runtime__get_logs` |
111
- | Screenshot | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` |
112
- | Web fill / click | `mcp__plugin_flutter_flutter-ultra-browser__fill`, `mcp__plugin_flutter_flutter-ultra-browser__click` |
113
- | Wait for URL (OAuth) | `mcp__plugin_flutter_flutter-ultra-browser__wait_for_url` |
114
- | Native permission grant | `mcp__plugin_flutter_flutter-ultra-native-mobile__native_permission_grant` |
104
+ - **Element not found**: call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` to find where the element is. Wait up to 3s via `mcp__plugin_flutter_flutter-ultra-gesture__wait_for`.
105
+ - **Wrong route**: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to read `GoRouter.of(context).routerDelegate.currentConfiguration.fullPath`, then navigate to the correct starting point.
106
+ - **Text field requires focus**: tap the field first with `mcp__plugin_flutter_flutter-ultra-gesture__tap`, then `mcp__plugin_flutter_flutter-ultra-gesture__enter_text`.
107
+ - **Async loading**: `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists` to check for `CircularProgressIndicator`; wait and retry.
108
+ - **Code change mid-flow**: `mcp__plugin_flutter_flutter-ultra-runtime__hot_reload` after edits, then re-verify the widget tree.
115
109
 
116
110
  ## Example
117
111
 
118
112
  ```
119
- User: "Drive the login flow for user@invora.app with password hunter2, then open the first invoice."
120
-
121
- 1. discover_sessions → attach(sessionId: "flutter-1")
122
- 2. screenshot → step-0-start.png (confirm login screen)
123
- 3. find_widget(key: "email-field") → found
124
- 4. evaluate: set email controller value to "user@invora.app"
125
- 5. find_widget(key: "password-field") → found
126
- 6. evaluate: set password controller value to "hunter2"
127
- 7. find_widget(key: "sign-in-button") → found; marionette tap(key: "sign-in-button")
128
- 8. evaluate: await SchedulerBinding.instance.endOfFrame (wait for navigation)
129
- 9. find_widget(key: "dashboard-root") → found (login succeeded)
130
- 10. screenshot → step-1-dashboard.png
131
- 11. evaluate: context.go('/invoices')
132
- 12. find_widget(text: "Invoice #1") → found; marionette tap(text: "Invoice #1")
133
- 13. find_widget(key: "invoice-detail-root") → found
134
- 14. screenshot → step-2-invoice-detail.png
135
-
136
- Summary: 3 major steps completed, all passed. Final route: /invoices/1.
113
+ User: "Drive the login flow for user@example.com, then open the first invoice."
114
+
115
+ 1. discover_sessions -> attach(sessionId: "flutter-1")
116
+ 2. screenshot -> confirm login screen visible
117
+ 3. interactive_elements -> found: email-field, password-field, sign-in-button
118
+ 4. tap(key: "email-field") -> enter_text(text: "user@example.com")
119
+ 5. tap(key: "password-field") -> enter_text(text: "password123")
120
+ 6. tap(key: "sign-in-button")
121
+ 7. wait_for(key: "dashboard-root") -> found
122
+ 8. screenshot -> dashboard loaded
123
+ 9. evaluate: context.go('/invoices')
124
+ 10. wait_for(text: "Invoice #1") -> found
125
+ 11. tap(text: "Invoice #1")
126
+ 12. wait_for(key: "invoice-detail") -> found
127
+ 13. screenshot -> invoice detail visible
128
+ -> "3 major steps completed. Final route: /invoices/1"
137
129
  ```
138
130
 
139
131
  ## See also
140
132
 
141
- - Sibling skill: `flutter-tour` for passive route screenshot sweeps (no interaction)
142
- - Sibling skill: `flutter-test` for orchestrated patrol E2E test runs
143
- - `mcp__marionette__*` — native gesture and text tools via VM service extensions
133
+ - `flutter-tour` — passive route screenshot sweeps without interaction
134
+ - `flutter-test` — orchestrated patrol E2E test runs
135
+ - `flutter-debug` — triage runtime errors encountered during a flow