Flow Next Drive

flow-next-drive — surface-aware UI automation

Drive any UI surface the way a real user would. Whatever driver the environment has, the work is the same shape: observe / navigate → snapshot → act on fresh refs → capture evidence → release. This skill is a router: it detects the surface, picks the highest available driver on a ladder, degrades gracefully when a richer driver is absent, and hands off to a per-rung reference for the command detail.

It orchestrates drivers — it does not reimplement them. The default rung (Vercel's agent-browser CLI) is the only driver assumed present; every other rung is detected and optional. A pass must succeed with whatever the environment actually has — most cloud VMs, Linux, and CI have no Computer Use, so it is never a hard dependency and never on a headless/no-display path.

Driver ladder + universal-flow structure adapted from Ray Fernando's running-bug-review-board skill (Apache-2.0).

Step 1 — Detect the surface, then branch

Classify the target into one of three buckets and take the matching path. The universal flow (Step 2) is shared; only the actuation and the per-surface reference differ.

How to decide:

• A bare URL, or a dev/staging/prod web app → A.
• A desktop app you can launch with --remote-debugging-port=<n> (or one already exposing one) → B. Electron and Windows WebView2 are Chromium; the web ladder drives them by CDP-attach. Do not route these to Computer Use.
• A desktop app with no CDP port — genuinely native (AppKit/SwiftUI), or a macOS WKWebView / Tauri-on-macOS app — → C. Per-platform caveat: Windows WebView2 is CDP-drivable (→ B); macOS WKWebView generally is not (→ C) — verify per platform.

When unsure whether a desktop app exposes CDP, probe for B first (try to launch/attach with a debug port). If no port is reachable, fall to C.

When .flow/features/ exists and the caller did not pass unmapped, Read .flow/features/README.md and the feature file the caller names, else the one matching feature file, first; never the whole map. They pre-resolve the route, preconditions, and gotchas. Select by **Surface:** plus sub-feature IDs (feature-entry-contract.md, "Live-app stages"). Live detection above remains the fallback when the map is absent or does not cover this target. A mapped route that no longer matches the live app gets a drift note per the contract's "Writers and drift notes" section, then live detection continues; never edit the map mid-run.

Done when

• The target is classified A, B, or C before any driving starts, and the classification is stated. A pass that started acting before naming the surface has broken this.
• A desktop app was probed for a CDP port before being routed to C.
• When .flow/features/ existed, the index and the named or one matching feature file were read before driving (none after a caller's unmapped); live detection was the fallback otherwise, and a stale mapped route was filed as a drift note.

Step 2 — The universal flow (all surfaces)

observe / list what's open
navigate to the target (URL, or focus the app window)
snapshot              → fresh element refs (after a DOM change; for ONE known target prefer semantic find)
act                   → click / fill / type / press / scroll toward the next step
verify                → expected text/state appeared AND console clean + no failed API/network requests
capture               → screenshot + console/errors at the moment of interest (and on failure)
release               → close the tab / end the session when fully done

verify is not DOM-only — every verify checks the console is clean and no API/network request failed, alongside the expected text or state. A pass declared on a green-looking DOM while a request returned 500 or the console threw an uncaught exception has broken this: that is exactly the silent breakage a real user hits, and the /flow-next:qa qa_verdict rests on this evidence. The tooling is already on the default rung (agent-browser console, agent-browser network requests --filter api; the DevTools-MCP rung has richer inspection). A failed request or console error under a green DOM is a finding, not noise.

Snapshot cost: a full interactive snapshot -i before every act is the dominant token cost of a long flow. Re-snapshot after a DOM change, but for a single known target prefer a semantic locator (find role|text|label … <action> — no snapshot needed), and use snapshot -c / -d <depth> when you only need to verify one region.

Refs (@e1, @e2, …) go stale after any navigation, click, or form submit. Element refs are refreshed by re-snapshotting after any navigation, click, or submit. A "ref not found" or pointer-events: none result reported as a bug before a re-snapshot has broken this — it is a stale snapshot until a fresh one says otherwise.

Done when

• Every act ran against refs from a snapshot taken after the last DOM change (or against a semantic locator that needs none).
• Every verify carries three checks — expected text/state, clean console, no failed API/network request. Native rungs (cua, computer use) have no console or network channel: verify the expected state plus any app log, and say those checks were unavailable.
• Evidence was captured at the moment of interest and on failure — screenshot plus console/network output — so a downstream /flow-next:qa verdict rests on artifacts rather than narration.
• The session or tab is released when the pass is done. A left-open session or daemon has broken this.

Step 3 — Web ladder (surfaces A and B)

Probe availability top-down and use the highest rung that passes; fail soft to the next; the terminal rung is manual. Never hard-depend on any rung above the default.

Surface B note: an Electron / WebView2 app is driven through this same web ladder, over its CDP debug port. Routing a Chromium-backed desktop app to the native rung has broken this. Attach to the app's remote-debugging port (agent-browser --cdp <port> / --auto-connect; chrome-devtools-mcp --browser-url=http://127.0.0.1:<port>). Launch the app with a dedicated debug port and a dedicated user-data-dir; treat the open debug port as a security exposure (any local app can drive that session).

agent-browser command detail lives in the rung reference, not here. The default-rung reference references/agent-browser.md is the entry point — setup/version check, the universal flow in agent-browser commands, the Chromium-desktop (Electron / WebView2) CDP driver, the --headed daemon-reuse gotcha, and an index into the per-topic references it folds: commands.md, advanced.md (CDP attach), auth.md, snapshot-refs.md, session-management.md, proxy.md, debugging.md.