# Maestro Flows

> 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.

- Skill: `tss-blue-ai-lab/maestro-flows` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add tss-blue-ai-lab/maestro-flows`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tss-blue-ai-lab/maestro-flows/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TSS-Blue-AI-Lab (https://skillmd.com/u/tss-blue-ai-lab)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/tss-blue-ai-lab/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.