maestro-flows

name	maestro-flows
description	Create and run Maestro UI test flows for the app in this repo. Use when writing Maestro YAML flows or verifying app behavior on a device/emulator.
version	1.0.0
level	advanced
category	testing

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.