Maestro Flows

Maestro Flows

Create and run Maestro UI test flows for the application in the current repository. Discovers the project setup itself, keeps raw output in a project results folder, and returns only a compact result in chat.

Constraints

• Never guess credentials or test data. Use what exists in checked-in flows, pass via -e env vars, or ask the user.
• Never paste full build output, console streams, dumpsys window, or Maestro artifacts into the conversation. Redirect raw output to the results folder and parse the JUnit report instead.
• Before claiming success, run the relevant flows — or state explicitly why they were not run.
• Do not invent element IDs or selectors. Verify them against the app source or a hierarchy dump.
• Do not guess feature behavior. Read the feature's source (markup + handlers) before authoring a flow and before every flow fix — flows test what the code does, not what the UI probably does.
• For verification runs, use a full (non-incremental) install — fast-deploy mechanisms can leave stale code on the device.
• This skill NEVER changes application code. It creates/edits flow YAML, runs flows, and reports. Fixing app code is a separate task that starts only after the user picks what to fix (Phase 4).
• Wherever this skill says "ask the user": stop, surface the question and its options directly to the user in chat, and wait for the answer before proceeding. If the harness provides a structured question tool (e.g. AskUserQuestion in Claude Code), use it; otherwise plain chat is fine. Never proceed on an assumed answer.

Phase 0 — Load Context & Configure

Read gotchas.md first — it logs this skill's own past malfunctions.

Config lives at <repo root>/.maestro-flows.local.json — machine-local state, never inside this skill folder (the skill ships without it) and never committed.

If it exists: read it, validate the cached tool paths still exist (adb, maestro) and the device is connected (run devices via the configured adb path — do not assume adb is on PATH, or xcrun simctl list devices booted); re-discover any value that fails validation and write the file back. No device connected → first try to start one yourself (emulator/simulator start steps are in references/project-discovery.md step 4); ask the user only if that fails. If the config doesn't exist: follow references/project-discovery.md to discover everything and create it; ask the user only for ambiguous values.

Phase 1 — Create Flows (when authoring)

Read references/flow-authoring.md before writing any YAML. Start new flows from templates/flow.yaml.tmpl.

Phase 2 — Run Flows

Read references/running-flows.md for the run conventions (results folder layout, JUnit report parsing, tag filtering).

Pick the cheapest valid run:

• App code changed → run installCommand first.
• Only flow YAML changed and app already installed → skip install.
• Targeted check → filter with --include-tags instead of running the whole suite.
• User only wants the commands → print them, run nothing.

Phase 3 — Report

Report immediately after the run — do NOT investigate failures first (no log reading, no screenshot inspection, no troubleshooting). Print in chat only:

• command(s) used, whether install was skipped and why;
• pass/fail count and total duration (from the JUnit report);
• for failures: the failure message as stated in the JUnit report (verbatim, no interpretation) and the screenshot path under artifacts/;
• the run folder path (<resultsDir>/run-<timestamp>/) for later verification.

Phase 4 — Diagnose & Fix Planning (only if flows failed, only on request)

After the report, ask the user which failing tests to diagnose and plan fixes for. Only for the selected ones: read references/troubleshooting.md (most failure modes — startup crash despite green build, system overlays, stale field state, stale installs — are catalogued with exact diagnostic commands), diagnose the root cause, then lay out a plan: root cause, files involved, proposed change, how the fix will be verified (which flows to rerun). Present the plan only — do not modify application code within this skill.