@1aboveio/skills 1.0.17 → 1.0.19

package/skills/app-dev/maestro/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: maestro
+description: "Design, run, debug and migrate mobile E2E journeys with Maestro: complete flows and subflows, selectors, parameters, exclusive UI-driver ownership, non-UI authentication/backend helpers and failure evidence. Use for Maestro YAML/CLI/MCP work, slow fragmented mobile journeys, UiAutomation driver collisions, or replacing a hybrid Python/uiautomator2 UI harness. Android-first; use platform-neutral flow guidance for iOS only with its verified device/runtime contract. NOT for Android provisioning/builds (android-development), iOS setup (ios-foundation), browser Playwright tests (e2e-test), or CI workflow YAML (github-actions)."
+release-version: 0.49.1
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Maestro
+
+Make the journey, not each tap, the unit of UI execution. Maestro owns ordinary app UI;
+the existing runner owns resources and cleanup; existing non-UI helpers establish backend
+and platform facts. Preserve the repository's acceptance criteria and selected checkpoint.
+
+## Read the assignment
+
+Read applicable `AGENTS.md`, `CONTRIBUTING.md`, test guidance and relevant ADRs from the
+assigned workspace. Resolve the actual case, caller, source, app artifact, served code,
+device identifier and runtime owner before execution. Follow nested guidance for touched
+paths. Existing policy wins; missing guidance uses the defaults here, while unreadable
+guidance or an unresolved ownership conflict is reported before affected operations.
+
+This skill writes requested flows, helpers and tests, not project conventions or agent
+settings on discovery. It has no `init` command and installs no tools automatically.
+For missing Android workflow conventions, offer `android-development init` once without
+blocking the task; that skill owns its authorized writes. A task override lasts only for
+the assignment and survives context reload, not as a saved policy change.
+
+## Work loop
+
+1. **Select proof.** Name the user journey and its required observations. Map each to a
+   UI assertion, non-UI helper or specifically justified native case using
+   [the test split](references/journeys.md#split-by-responsibility). Reuse sufficient
+   existing proof; do not add a matrix or gate because Maestro is being used.
+2. **Use the owned runtime.** Consume the existing runner's device assignment, app/code
+   identity, private endpoints and disposable fixture contract. For Android environment
+   work use `android-development`; for iOS setup use `ios-foundation`. Neither a new flow
+   nor this skill authorizes another emulator, dependency install or fixture lifecycle.
+3. **Compose the journey.** Prefer one top-level flow invoking reusable `runFlow` subflows
+   within one Maestro invocation. Group contiguous UI work; split only for a real external
+   or native checkpoint. Read [journeys](references/journeys.md) before authoring or running.
+4. **Verify the real path.** Test actual case dispatch, caller parameters, production
+   selectors and fixture composition before allocating a device when host checks suffice.
+   Then run the selected case through the maintained local/CI caller on the identified app.
+   Syntax checks, mocks, a readiness probe or YAML files alone are not execution proof.
+5. **Diagnose and correct.** At failure, identify the earliest failed stage and retain its
+   evidence before teardown. Use [diagnosis](references/diagnosis.md); confirm the original
+   reproduction after the correction and repeat only invalidated checks.
+6. **Report and finish.** Name executed cases/assertions, source/app identities, results,
+   remaining requirements and cleanup or explicit runtime handoff. Follow
+   [evidence](references/evidence.md); a converter's success is not a journey pass.
+
+For an authorized existing-harness conversion, read [migration](references/migration.md).
+An installed Maestro CLI or a broken harness alone does not authorize a migration.
+
+## One UI driver
+
+A Maestro-only case starts no uiautomator2 client in its parent, child, observer or failure
+capture. A reader that acquires Android UI automation is still a competing driver.
+Use Maestro's hierarchy/artifacts and suitable non-conflicting platform probes instead.
+
+During migration, a necessary handoff goes through the process that actually launched the
+old server: verify ownership, stop and confirm release, run Maestro to completion, then
+reclaim only if the next native phase needs it. A joined child client cannot necessarily
+stop the parent's server. Keep the existing security/currentness checks and never stop a
+peer. Treat this as transitional, not the default around every action.
+
+## Framework responsibilities
+
+| Responsibility | Owner | Rule |
+| --- | --- | --- |
+| Setup, source/app identity, timeouts and cleanup | Existing runner | One authoritative resource owner per device; retain its emulator/ADB/Metro/backend and fixture lifecycle |
+| Ordinary app interactions and UI assertions | Maestro | No uiautomator2 server starts in this case's parent, child, observer or failure capture |
+| Financial and backend verification | Existing backend test code | Verify real records, amounts, request counts and isolation, not just success text; preserve required checkpoint order |
+| Specialized native assertions requiring another UI driver | Existing native test code | Separate exclusive case/phase; Maestro is stopped and its registration released before the native driver starts |
+| Logic and module tests | Existing host/JVM tests | Run without an emulator where sufficient; do not convert these tests to UI journeys |
+
+The runner may use Python or another existing language. It orchestrates resources and
+case/checkpoint boundaries, not individual taps. Backend helpers remain non-UI; a reader
+that acquires UI automation belongs in the exclusive native path. Suitable non-conflicting
+platform probes may run during a Maestro case, but do not silently substitute them for
+required native proof. Grouping UI actions never moves a financial guard past its action.
+
+This skill owns the Maestro side of that split. `android-development` owns Android runtime
+and build work; `ios-foundation` owns iOS setup without Android addressing assumptions.
+Use `test-quality` for test honesty, `e2e-test` for browser journeys and `github-actions`
+for workflow implementation. This is a test-framework contract, not an agent-role policy.
+
+Maestro supports focused-element assertions; focus alone is not a reason to keep another
+driver. App stop/relaunch does not automatically prove OS process death, reboot, continuous
+focus retention, physical hardware or payment-provider acceptance. Match each claim to its
+observation. A multi-device coordinator may orchestrate separate Maestro journeys, but
+independent shards do not establish an ordered cross-device interaction.
+
+The skill ships no Maestro binary and no resource runner. Reuse the repo-pinned CLI and
+check its actual `--help`/version for flags and artifact shape. Shared flow guidance can
+apply to iOS, but this extraction does not certify iOS provisioning, transport or native
+assertions. Keep that evidence gap explicit.
+
+## References
+
+- [Journeys and helpers](references/journeys.md): test split, state, selectors and invocation.
+- [Flow authoring](references/authoring.md): a complete flow/subflow example and parameter checks.
+- [Diagnosis](references/diagnosis.md): driver startup, action failures and useful comparisons.
+- [Android connection](references/android-connection.md): direct adbd versus ADB-server routing and JVM key lookup.
+- [Evidence](references/evidence.md): reports, converter and original-status preservation.
+- [Migration](references/migration.md): replace hybrid UI paths without losing assertions.
+
+## Sources
+
+- [Nested flows](https://docs.maestro.dev/maestro-flows/flow-control-and-logic/nested-flows)
+- [State selectors](https://docs.maestro.dev/reference/selectors/state-selectors)
+- [JavaScript HTTP requests](https://docs.maestro.dev/advanced/javascript/make-http-requests)
+- [Launch behavior](https://docs.maestro.dev/reference/commands-available/launchapp)

package/skills/app-dev/maestro/references/android-connection.md

@@ -0,0 +1,54 @@
+# Android connection and driver startup
+
+Read this when ADB sees the device but Maestro cannot find/authenticate it, or when the
+driver never reaches its first flow command. The runtime owner supplies the assigned
+serial, server/guest endpoints and authorized credentials. This reference does not
+provision devices or change global ADB state.
+
+## Distinguish the endpoints
+
+The Maestro 2.12.0 connection implementation has separate direct-adbd and ADB-server
+factories. Discovery/by-ID paths and explicit endpoint paths are not interchangeable.
+Do not assume `ADB_SERVER_SOCKET`, `ANDROID_ADB_SERVER_PORT`, `ADB_VENDOR_KEYS` or the
+fact that the host `adb` works means the JVM followed the same route.
+
+Inspect the actual pinned CLI `--help`, launcher and bundled connection implementation
+to establish which route the invocation selects. Use supported flags through the existing
+adapter. For a conventional Android emulator the console and adbd transport ports differ;
+the console port is not an adbd endpoint. Read the owner's actual mapping instead of
+guessing from another session's serial. Keep peer/default-server endpoints untouched.
+
+## Check the effective JVM credentials
+
+The Dadb `AdbKeyPair.readDefault()` implementation reads `.android/adbkey` and
+`.android/adbkey.pub` under Java's `user.home`. If the private key is absent it generates
+a new pair there. A private shell HOME, `ADB_VENDOR_KEYS`, or a successful host ADB
+connection does not by itself establish that Java used the guest-authorized pair.
+
+Verify that behavior in the pinned dependency before applying it to another version.
+Compare the launcher's effective JVM home and public-key identity with the runtime
+owner's authorized key. Use the owner's supported JVM-home/credential configuration;
+do not copy another owner's key, print private key material, approve an unexpected USB
+dialog or alter a shared server to work around failed authentication. Bound the probe
+and record missing credential authority rather than retrying the whole journey.
+
+## Separate authentication from instrumentation
+
+On Android, a session installs/starts Maestro's `dev.mobile.maestro` and
+`dev.mobile.maestro.test` driver packages and launches instrumentation. A working adbd
+connection does not prove this succeeded. Retain installation output, instrumentation
+errors and the guest log interval covering startup before cleanup.
+
+If instrumentation reports an existing UiAutomation registration, inspect its real
+owner as described in [diagnosis](diagnosis.md). If no commands ran, do not debug a UI
+selector yet. Once startup is corrected, the selected case still owes its UI/backend
+assertions; driver readiness alone is not acceptance.
+
+## Sources and version limits
+
+- [Maestro 2.12.0 AndroidDeviceConnection](https://github.com/mobile-dev-inc/Maestro/blob/cli-2.12.0/maestro-client/src/main/java/maestro/android/AndroidDeviceConnection.kt)
+- [Dadb default key lookup](https://github.com/mobile-dev-inc/dadb/blob/master/dadb/src/main/kotlin/dadb/AdbKeyPair.kt)
+
+The Dadb source link follows its branch and is explanatory evidence, not a dependency pin.
+Recheck the installed implementation; these sources do not certify every consumer's CLI,
+transport or launcher configuration.

package/skills/app-dev/maestro/references/authoring.md

@@ -0,0 +1,113 @@
+# Author a flow, not a CLI loop
+
+Start from the repo's existing selectors, copies and fixtures. The following is a structural
+example for a warm History filter case, not runnable proof against an arbitrary app.
+Replace the IDs and assertion with the actual production controls and required result;
+keep its existing caller and `APP_ID`/`FILTER_DATE` input validation.
+
+```yaml
+# maestro/flows/history-filter.yaml
+appId: ${APP_ID}
+name: History filter
+---
+- launchApp:
+    stopApp: false
+- runFlow:
+    file: ../shared/open-history.yaml
+- tapOn:
+    id: history_filters
+- tapOn:
+    id: history_filter_from
+- assertVisible:
+    id: history_filter_from
+    focused: true
+- inputText: ${FILTER_DATE}
+- tapOn:
+    id: history_filter_apply
+- assertNotVisible:
+    id: history_filter_apply
+- assertVisible:
+    id: history_filter_active
+    text: ${FILTER_DATE}
+```
+
+```yaml
+# maestro/shared/open-history.yaml
+appId: ${APP_ID}
+---
+- tapOn:
+    id: navigation_history
+- assertVisible:
+    id: history_list
+```
+
+One CLI invocation executes the top-level flow and its subflow. The subflow does not
+restart, clear state or grant permissions behind the caller's back. An ordinary focused
+selector is useful at a checkpoint, not a replacement for a required continuous hold.
+
+Bind the expected value to the intended control, as `id` plus `text` above. Separate
+assertions for a badge and a date anywhere on screen can pass when another row contains
+that date. If the real renderer puts the value on a child, use a verified parent/descendant
+relationship (for example `containsDescendants`) instead of dropping that binding.
+
+## Parameters and input
+
+Pass required values through the existing caller and `-e NAME=value`/subflow `env` route
+supported by the pinned version. Prefer required inputs over hidden defaults. If a default
+is actually needed, preserve undefined versus empty/false/zero and verify its expansion
+with the real CLI before adopting it. Do not put the caller's input name in a competing
+flow-level default block and assume CLI precedence.
+
+Assert the exact resulting value when text entry is part of the requirement. A successful
+`inputText` command does not prove the entire string reached the intended field. Current
+Maestro docs flag Android Unicode input limitations: verify the selected CLI/input route
+for non-ASCII data, and use an existing supported alternative if required. Do not claim
+Chinese input proof from ASCII-only data, silently change locale, or add sleeps/retries
+without identifying the failed operation.
+
+Use existing syntax/admission checks before allocating the device, then run the actual
+selected journey. Syntax validation does not check that an ID is in the real app, that
+the caller supplied the right parameter, or that the destination rendered.
+
+## Consume an existing helper result
+
+When the case requires real Login-code delivery and an authorized helper interface already
+exists, a flow can retrieve that result without restarting Maestro. The following fragments
+assume the existing helper returns JSON with a string `code` scoped to this invocation and
+the exact preceding Login request. They are not permission to build an endpoint.
+
+```yaml
+- runScript:
+    file: ../scripts/read-auth-code.js
+- tapOn:
+    id: authentication_code
+- inputText: ${output.authCode}
+- tapOn:
+    id: authentication_verify
+```
+
+```javascript
+// maestro/scripts/read-auth-code.js; use the existing helper's real contract.
+var response = http.get(AUTH_HELPER_URL, {
+  headers: { Authorization: 'Bearer ' + AUTH_HELPER_TOKEN }
+});
+if (response.status !== 200) throw new Error('Authentication helper failed');
+var body = json(response.body);
+if (typeof body.code !== 'string' || body.code.length === 0) {
+  throw new Error('Authentication code unavailable');
+}
+output.authCode = body.code;
+```
+
+The caller supplies the already-authorized URL/token without logging them, and the existing
+owner bounds helper waits and closes any owned endpoint. Scope/authorization belong to the
+helper, not a guessed query parameter. Sanitize code-entry artifacts before publishing. For
+an approved non-Login fixture, keep that fixture rather than adding a code-delivery step.
+
+## Sources
+
+- [runFlow](https://docs.maestro.dev/reference/commands-available/runFlow)
+- [State selectors](https://docs.maestro.dev/reference/selectors/state-selectors)
+- [inputText](https://docs.maestro.dev/reference/commands-available/inputText)
+- [runScript output](https://docs.maestro.dev/reference/commands-available/runScript)
+- [Relational selectors](https://docs.maestro.dev/reference/selectors/relational-selectors)

package/skills/app-dev/maestro/references/diagnosis.md

@@ -0,0 +1,50 @@
+# Diagnose the failing stage
+
+Preserve the first failure and inspect the actual operation before another device run.
+Use the assigned source and runtime; do not substitute a newer checkout or relabel an old
+APK. Keep uncertainty when the retained evidence cannot distinguish causes.
+
+| Earliest failed stage | Smallest useful evidence/question |
+| --- | --- |
+| CLI/flow admission | Real arguments, supported selector, syntax and selected flow count |
+| Device discovery/authentication | Actual endpoint, owned serial, authorized key and JVM home; did a command reach the intended guest? |
+| Driver startup | Installation/instrumentation output and guest startup log interval before teardown; which process owns UI automation? |
+| UI action/selector | Failing command, hierarchy, screenshot, actual foreground state and caller parameters |
+| Business assertion | Real record IDs, fixture and backend/provider readback at the required checkpoint |
+| Teardown | Cleanup status separately from the original failed stage |
+
+For `UiAutomationService ... already registered!`, identify the registration holder. In a
+parent/child harness, a child's uiautomator2 client may have joined the parent's server;
+stopping that client releases nothing. Ask the verified owner to stop and confirm exit for
+a necessary transitional handoff. For a migrated Maestro-only path, remove competing setup
+and observers once equivalent observations are in place. Never use broad kills, another
+namespace or longer timeouts as a substitute for correct ownership.
+
+A correct transport and key do not prove driver readiness. Capture installation,
+instrumentation and crash logs covering startup, not only a tail after the driver failed.
+For endpoint modes, JVM `user.home` key lookup and driver packages, read
+[Android connection](android-connection.md) before changing private transport settings.
+A ready driver does not prove the app used the expected Metro/backend endpoint. Compare
+with an existing known-working caller on the same relevant contract before inventing a
+new transport or collector; explain differences instead of claiming all callers are alike.
+
+For UI failures, test the actual producer/consumer where a host reproduction suffices:
+localized labels with country suffixes, undefined-versus-empty parameters, exact selected
+case, fixture prerequisites and executable path. Preserve original gesture coverage such
+as a deliberate double tap; a single successful submit does not replace it.
+
+When comparing scroll adapters, content DOWN requires an upward finger swipe; content UP
+requires a downward swipe. A regression fixture must keep the target offscreen until the
+correct gesture, rather than reveal it after an arbitrary gesture count. Prefer Maestro's
+existing scroll command over adding a comparison adapter.
+
+Use bounded searches over named files and installed module paths. An unbounded recursive
+search through workspaces/caches can outlast the journey being debugged. Every experiment
+answers a stated question and has an execution/cleanup bound. Correct the supported cause,
+confirm the original reproduction, then rerun invalidated checks; neither a full unchanged
+campaign nor a new worker is required for each small correction.
+
+Measure case wall time, invocation count and time inside Maestro separately. Invocation
+time includes UI execution and is not all removable startup cost. Use existing logs;
+do not promise a speedup, increase sensitive assertion windows or build a metrics system
+solely to explain one slow case.

package/skills/app-dev/maestro/references/evidence.md

@@ -0,0 +1,74 @@
+# Journey results and failure evidence
+
+Record selected cases and executed assertions, source/native artifact/served code identity,
+device/OS and relevant configuration, original status, evidence paths and cleanup outcome.
+The existing runner owns deadlines and cleanup. Successful rendering is not a packaged-app
+or release claim unless that checkpoint's artifact/source requirements were satisfied.
+
+Use the pinned Maestro's per-flow results/JUnit report or the existing runner's honest PASS
+markers. A zero exit with no selected flows is not a pass. Capture passing checkpoints with
+`takeScreenshot` when required; ordinary passing flows have no automatic screenshots.
+
+The bundled `scripts/maestro_failure.py` maps retained Maestro artifacts to `failure.json`:
+`case`, `step`, `error`, `screenshot`, `uiDump`, `logcatTail`, `evidenceDir`, `cleanupErrors`.
+It prints one `NATIVE_FAILURE` JSON line with `case`, `step`, `error`, `evidenceDir`. The
+first existing failure wins; later capture or cleanup failures never replace its cause.
+Artifact fields are paths relative to the evidence directory or null with a capture reason.
+The converter reads retained files and writes only under the selected evidence directory;
+it starts no device or UI-automation client. Absolute/escaping artifact paths and symlinks
+outside the Flow or destination are rejected as capture gaps, preserving the original error.
+
+Confirm the pinned CLI's actual output layout first. The converter understands session/flow
+folders with `commands.json`, failing-step screenshots/hierarchies and device logs. When a
+version uses a different shape, retain its original output and adapt/test the real reader;
+do not assume missing converter output means a passing case. iOS log-name fallbacks in the
+reader are not an observed iOS-device certification.
+
+Malformed command entries or unsupported statuses are conversion errors, not empty passing
+flows. If part of a session is unreadable, the CLI retains an available failed record,
+reports the omitted Flow(s) and returns 2 for incomplete conversion. Its selection is only
+the earliest readable failure, not proof of the session's first failure. An explicitly
+empty command list produces no record and still does not prove a selected journey ran.
+
+Nested `runFlow` output may include a failed parent summary as well as a failed child.
+The reader's timestamp/entry selection is mechanical; deepest-child/root-cause attribution
+is not certified without a retained nested-output fixture from the pinned CLI. Keep the
+raw command sequence and inspect it when that distinction matters.
+
+Give every case/attempt a new owned `LOG_DIR`, shared with its launcher. Reusing a runtime
+does not reuse its failure-record destination. After finalized CLI output, convert before
+teardown with the original status preserved. Inside the existing owner's bounded command:
+
+```bash
+maestro_status=0
+maestro --device "$DEVICE_ID" test --test-output-dir "$LOG_DIR/maestro" \
+  --format junit --output "$LOG_DIR/report.xml" ./maestro/flows/checkout.yaml \
+  || maestro_status=$?
+conversion_status=0
+python3 <skill-base-dir>/scripts/maestro_failure.py \
+  --maestro-dir "$LOG_DIR/maestro" --evidence-dir "$LOG_DIR" --case "$DEVICE_CASE" \
+  || conversion_status=$?
+printf 'maestro_exit=%s conversion_exit=%s\n' "$maestro_status" "$conversion_status"
+if [ "$maestro_status" -ne 0 ]; then
+  exit "$maestro_status"
+fi
+exit "$conversion_status"
+```
+
+Here `<skill-base-dir>` is the installed **maestro** directory. Retain the repo's actual
+qualified invocation/transport in place of the example. Converter exit zero means evidence
+processing succeeded, not that the journey passed: a recorded failure also returns zero.
+
+If startup leaves no step report, retain CLI logs and the actual driver-start interval.
+Have the existing owner write its partial failure record before teardown, preserving the
+original exit/error. Capture with Maestro artifacts or non-conflicting probes; a fallback
+`uiautomator dump` can itself acquire UI automation, so it must not run alongside Maestro.
+Report missing capture as a gap, not permission to start a competing client.
+
+Keep raw credentials, authentication codes and payment data private. Publish only sanitized
+findings. Report build time, device time and total worker time separately; one cannot be
+inferred from another.
+
+## Source
+
+- [Reports and artifacts](https://docs.maestro.dev/maestro-flows/workspace-management/test-reports-and-artifacts)

package/skills/app-dev/maestro/references/journeys.md

@@ -0,0 +1,100 @@
+# Complete journeys
+
+## Split by responsibility
+
+| Required observation | Default location |
+| --- | --- |
+| Navigation, form entry, scrolling, visible results, enabled/selected/focused state | Maestro flow and assertions |
+| Exact records, amounts, duplicate-call counts, authorization isolation and recovery identity | Existing backend/database helper |
+| Authentication/fixtures required by this case | Existing approved helper; for real Login-code acceptance, the code produced by that request |
+| Device setup, installation, Metro, fixture creation and cleanup | Existing runtime owner |
+| OS/security/accessibility fact not exposed with equivalent fidelity by Maestro | Non-conflicting platform probe or named exclusive native case |
+
+Use the cheapest observation that proves the requirement. An on-screen success is not an
+exact Sale assertion; conversely, a database row does not prove the intended screen rendered.
+Preserve the repository-approved authentication fixture: an unrelated authenticated-screen
+test may use an approved seeded session or test-account service. When acceptance includes
+Login or code delivery, exercise that real path and retrieve its actual code through the
+approved helper (for example disposable PostgreSQL). Do not substitute a hardcoded OTP or
+injected session for required authentication proof. Provider doubles remain only where
+repo policy allows them; no production fixture endpoint or replay of an Unknown payment
+to get a green journey.
+
+Separate helpers from UI clients. Run before/after checks directly through the existing
+runner. Where ordering needs a mid-flow result, first reuse an existing supported helper
+interface. Maestro `runScript` can issue HTTP requests, but a new bridge is a scoped design
+change, not required infrastructure: get authorization, reuse the same fixture/authority,
+limit it to owned disposable resources and required operations, keep credentials private,
+bound waits, and close it through the existing owner. It must not become arbitrary command
+execution or a public production test route. Record a necessary split if no safe interface
+exists instead of inventing one or omitting an assertion.
+
+## Starting state
+
+Declare the required app state, permissions, locale, window and fixture in the existing
+case setup. Inspect hooks and subflows for resets too.
+
+- For a warm app, keep it running or use `launchApp: {stopApp: false}` to foreground it.
+  Plain `launchApp` stops and relaunches by default.
+- `clearState` clears app data, not installs an APK or proves upgrade behavior. Clear only
+  owned disposable state and restore debug endpoint preferences when the reset removes them.
+- Set permissions explicitly for denied/unset/prompt cases: `launchApp` grants all by default.
+- Configure lifecycle-changing size/density settings before starting an observation whose
+  Activity must survive. Preserve real restart/process-death checks where assigned.
+
+## Flow structure and selectors
+
+Read [flow authoring](authoring.md) for a complete top-level/subflow example and the
+required-input/text-entry checks before writing a new journey.
+
+Keep one top-level business case with subflows for reusable Login, context selection or
+editor actions. A subflow call is not another CLI process. Host code should not decide every
+tap or reacquire UI automation between subflows. Do not combine independent stateful cases
+merely to reduce process count; each retains its starting state, result and failure record.
+
+Prefer existing stable accessibility/resource IDs. Otherwise derive complete, unambiguous
+labels from the real renderer and metadata, including localization and suffixes. Maestro
+text selectors use regular expressions; escape literal dynamic values as appropriate.
+Confirm destination-only state after navigation, and use bounded `scrollUntilVisible` for
+offscreen controls. A fake exposing every control cannot prove scrolling works.
+Bind a dynamic expected value to its intended field/row/container, using the verified
+hierarchy when needed. A separate screen-wide text match may come from an unrelated row
+and cannot establish that a filter, receipt or selected item has the expected value.
+
+Verify parameter precedence against the pinned CLI and actual caller. Supply defaults only
+when an input is undefined, preserving intentional empty/false/zero values. A YAML `env`
+default can override a CLI value in some versions; a test of each side with handwritten
+fixtures misses this. Exercise the real caller-to-flow parameter path.
+
+## Execute through the existing owner
+
+Use the assigned device explicitly, with the owner's endpoint and credentials. For a
+standard supported route the command shape is:
+
+```bash
+maestro --device "$DEVICE_ID" test --test-output-dir "$LOG_DIR/maestro" \
+  --format junit --output "$LOG_DIR/report.xml" ./maestro/flows/checkout.yaml
+```
+
+Check flags and selectors with the repo-pinned CLI. A private Android ADB server may need
+an existing adapter's explicit transport/credential configuration; `--device` alone does
+not prove that the CLI uses that endpoint. Keep the qualified route rather than replacing
+it with this example. If no qualified route exists or ADB works while Maestro cannot
+authenticate, read [Android connection](android-connection.md) and inspect the pinned
+implementation before changing settings. The runner bounds the invocation and cleanup, captures the original
+status, and follows [evidence](evidence.md).
+
+Reuse valid development resources between fixes. New case evidence gets a new directory;
+this does not require a fresh emulator. Fresh-install acceptance still uses its required
+disposable app/data state. Keep one owner through the diagnosis/fix/recheck cycle where
+possible; a bounded attempt is not automatically the end of the assignment.
+
+Maestro MCP inspection can help choose selectors and author a flow. The executed assertions
+on the identified candidate, not exploration or syntax validation, establish the result.
+
+## Sources
+
+- [runFlow](https://docs.maestro.dev/reference/commands-available/runFlow)
+- [launchApp](https://docs.maestro.dev/reference/commands-available/launchapp)
+- [runScript](https://docs.maestro.dev/reference/commands-available/runScript)
+- [HTTP requests](https://docs.maestro.dev/advanced/javascript/make-http-requests)

package/skills/app-dev/maestro/references/migration.md

@@ -0,0 +1,35 @@
+# Replace a hybrid UI driver
+
+Start only with task/repo authorization. Existing working journeys are not migration scope
+merely because Maestro is installed. Preserve required CI and every original criterion.
+
+1. **Map the real case.** Trace its local and CI commands to maintained callers, fixtures,
+   UI actions, observers and assertions. Include private/copied callers if they are actually
+   executed. Record which observations move to Maestro, stay in a non-UI helper or require
+   a named native exception. Reuse existing flows and applicable evidence.
+2. **Prove one complete path.** Choose a representative case with meaningful UI work,
+   required backend assertions, failure capture and owned cleanup. Genuine Login
+   is required when it is part of that case's acceptance; otherwise retain the approved
+   authentication fixture. Use the current runner, not a new emulator manager. Test actual dispatch and parameter/fixture composition
+   on the host before spending a device run where those defects can be exposed there.
+3. **Move sequencing.** Replace Python deciding each tap with a top-level Maestro journey
+   and subflows. Extract existing non-UI helpers from UI clients without duplicating financial
+   or authentication logic. Keep mid-flow assertions in their required order. Grouping is not
+   permission to move a safety check until after a financial action.
+4. **Remove competition.** After equivalent proof exists, stop creating uiautomator2 in the
+   ordinary case's setup, parent/child, observation and failure paths. During transition,
+   handoffs retain verified ownership, expiry/currentness and cleanup checks. Keep specialist
+   drivers exclusive and explicit; retain only assertions not yet equivalently proven.
+5. **Replace callers and retire code.** Put the working case in tracked source. Local and
+   CI use that same implementation with environment-specific configuration. Once it passes,
+   remove equivalent legacy UI helpers, private copied callers and silent driver fallbacks.
+   A public flow wired correctly does not establish that a private caller uses it.
+6. **Verify the replacement.** Real run artifacts must show selected cases, Maestro commands,
+   unchanged domain/native assertions and cleanup on the final candidate. Keep old failures
+   and still-valid proof. A zero-Maestro run may prove business behavior, not the migration.
+
+Finish the assigned scope, not every possible device campaign. Report unmigrated paths and
+unrun acceptance explicitly. Script extraction, host tests and successful driver startup
+are useful intermediate results, not whole-issue acceptance. Do not duplicate a working
+journey permanently as reassurance, weaken an oracle, or add gates and broad framework
+work outside the authorized migration.

package/skills/app-dev/maestro/release-check.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const bundle = readJson(join(resolve(here, '../../..'), 'package.json'));
+  if (bundle.name === '@1aboveio/skills' && bundle.nativeCodex?.schemaVersion === 1) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }