@1aboveio/skills 1.0.16 → 1.0.18

package/README.md

@@ -52,7 +52,7 @@ See https://github.com/1aboveio/ai/blob/main/docs/native-codex.md for prerequisi
 | `core` | `@1aboveio/core-skills` | distill-writing, doc-to-md, editorial-review, house-style, plain-language, polish-cn, reg-parser, terminology, write-doc, write-report |
 | `engineering` | `@1aboveio/engineering-skills` | better-review, e2e-test, engineering, engineering-runtime, ensure-coverage, golden-path, harness-runtime, resolve-issues, resolve-release, rush-issues, rush-release, test-quality |
 | `cicd` | `@1aboveio/cicd-skills` | cloud-build, cloud-debug, cloud-deploy, docker, github-actions, github-flow, google-cloud, mergify, podman |
-| `app-dev` | `@1aboveio/app-dev-skills` | airflow, android-development, app-debug, better-auth, data-catalog, data-quality, ios-foundation, monorepo, nextjs-fullstack, prisma-setup, pyspark, python-backend, shadcn, zod-v4 |
+| `app-dev` | `@1aboveio/app-dev-skills` | airflow, android-development, app-debug, better-auth, data-catalog, data-quality, ios-foundation, maestro, monorepo, nextjs-fullstack, prisma-setup, pyspark, python-backend, shadcn, zod-v4 |
 | `risk-compliance` | `@1aboveio/risk-compliance-skills` | compliance-audit, contract-compare, contract-review, doc-authenticity, fraud-detection, payment-analysis, portfolio-payment-analysis, similar-domain, tld-detection |
 | `content` | `@1aboveio/content-skills` | article-review, article-to-image, flowchart-svg, image-gen, mermaid, wechat-article-writer, wechat-publisher, wechat-search, xai-search |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Every 1aboveio skill package in one: install once, then choose which packages Pi loads with npx @1aboveio/skills select.",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
   "nativeCodex": {
     "schemaVersion": 1,
     "metadataPath": ".codex-plugin/resources.json",
-    "metadataDigest": "efea727f2b53be74c1dad921e4d976e9a4bf22054a5461217bea9a5983de48cc",
-    "releaseIdentity": "357a73a8819a5c43f9e6d935ece7e5efc38519d0b83e0984798677c4cb9dfc0d"
+    "metadataDigest": "df95a008c88708ef577ba4b6f7653e24705322ed24ecae12b77e1c07b557ecdd",
+    "releaseIdentity": "9de073de5cc2dd8be4429305b357f5a84e711be2abc33164b265e92e2e467ea5"
   },
   "pi": {
     "skills": [
@@ -110,6 +110,7 @@
           "data-catalog",
           "data-quality",
           "ios-foundation",
+          "maestro",
           "monorepo",
           "nextjs-fullstack",
           "prisma-setup",
@@ -260,7 +261,7 @@
         ]
       }
     ],
-    "digest": "26eb35331224e4dd2e0e8ef13bafd6383af21ae416bcf9e5acc28e68c6b45221"
+    "digest": "8998d462290ef5cf1ccfc7b8644987344d80183d06478a08601f5ea4fed689e2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

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

@@ -2,7 +2,7 @@
 name: airflow
 description: Airflow DAG architecture and conventions. Use when designing, writing, reviewing, testing, or debugging Airflow DAGs and tasks, including TaskGroups, data intervals, timezone-aware date parameters, CLI validation, environment-based scheduling, and pytest integrity tests.
 user-invocable: true
-release-version: 0.48.0
+release-version: 0.49.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Airflow DAG Development Patterns

package/skills/app-dev/android-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: android-development
-description: "Prove and debug Expo / React Native apps on an owned Android emulator. Use for Android startup/rendering failures, Metro or ADB problems, UiAutomator/harness failures, APK builds, SDK/NDK/JDK workspace setup, native journey validation, and choosing Kotlin/Compose versus React Native for Android flows. Reproduce failed Android CI checkpoints off CI before fixing and redispatching. Standalone invocation offers Project or Session; init persists repo conventions. NOT for workflow YAML, CI speed or runners (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest tests, or signing/store release."
-release-version: 0.48.0
+description: "Prove and debug Expo / React Native apps on an owned Android emulator. Use for Android startup/rendering failures, Metro or ADB problems, native harness failures, APK builds, SDK/NDK/JDK workspace setup, native journey validation, and choosing Kotlin/Compose versus React Native for Android flows. Reproduce failed Android CI checkpoints off CI before fixing and redispatching. Standalone invocation offers Project or Session; init persists repo conventions. Maestro journey authoring, UI-driver migration and flow diagnosis belong to maestro. NOT for workflow YAML, CI speed or runners (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest tests, or signing/store release."
+release-version: 0.49.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android development
@@ -60,13 +60,17 @@ The contract, other languages and the Maestro/Detox mapping are in
 
 ## UI journey tool
 
-The skill references Maestro; it does not bundle or install it. A repo with no journey tool
-is offered Maestro for new single-device journeys; a repo with a working harness keeps it
-and adds Maestro flows alongside. Run it on the session's own emulator
-(`maestro --device <serial>`) and convert its output with
-[maestro_failure.py](scripts/maestro_failure.py), which writes the record above. Read
-[UI journeys](references/ui-journeys.md) for the device-ownership cost, evidence layout, MCP
-use and the cases that stay custom.
+Before selecting, authoring, running, debugging or migrating Maestro journeys, read and
+apply `{maestro baseDir}/SKILL.md`. That skill owns complete UI flows, the split between
+UI/backend/native proof, exclusive UI-driver execution and Maestro evidence conversion.
+It is a required companion; report it missing rather than improvising or installing it.
+
+Keep Android workspace, emulator/ADB, build/install, Metro and cleanup ownership here.
+Pass the existing owned device and identity contract to Maestro; it does not create a
+second runtime. Offer Maestro for new journeys without a tool, but an existing harness
+migration still needs task/repo authorization. Preserve this validation ladder and all
+assigned native assertions. The [journey routing note](references/ui-journeys.md) keeps
+the old reference location discoverable without duplicating Maestro's procedure.
 
 ## Validation ladder
 
@@ -149,6 +153,6 @@ higher levels still pending rather than claiming acceptance.
 | Builds, provisioning, device execution, cleanup and setup proof | [setup.md](references/setup.md); use [device-run.sh](scripts/device-run.sh) only without an existing resource owner |
 | Feature/fix validation and handoff | [feature-work.md](references/feature-work.md) |
 | Device failure record and evidence capture | [diagnosis.md](references/diagnosis.md#record-the-failed-device-case) |
-| UI journey tool (Maestro) and its evidence converter | [UI journeys](references/ui-journeys.md) |
+| Maestro journeys, UI-driver migration and evidence conversion | `{maestro baseDir}/SKILL.md` |
 | Failure reproduction and correction | [diagnosis.md](references/diagnosis.md), then the relevant [gotcha](references/gotchas.md) |
 | CI integration | [ci.md](references/ci.md), [template](assets/android-ci-job.yml), and `github-actions` |

package/skills/app-dev/android-development/references/diagnosis.md

@@ -137,12 +137,10 @@ and prints `NATIVE_FAILURE`. Its `original_stage_exit=<n> cleanup_exit=<n>` line
 status are unchanged, and a record the journey already wrote is left untouched.
 
 A repo that already runs Maestro or Detox maps its failing artifacts to this record instead
-of adding the helper: Maestro's failing-step screenshot, view hierarchy and logcat plus its
-`commands.json` step, and Detox's `failing` artifact preset output. For Maestro, run
-[maestro_failure.py](../scripts/maestro_failure.py) over the flow folder or the session folder
-it sits in; it writes the record and prints the line, and [UI journeys](ui-journeys.md#evidence)
-has the evidence layout. A record is written even when the source is the framework's artifact
-set, and the printed line still has the four fields.
+of adding the helper. For Maestro, read `{maestro baseDir}/references/evidence.md` and use
+its converter and non-competing capture path. The old local converter entry point forwards
+to that companion. Detox uses its `failing` artifact preset output. Preserve the same
+record fields and printed line rather than adding another failure format.
 
 ## Bound work and distinguish progress from waiting
 

package/skills/app-dev/android-development/references/feature-work.md

@@ -173,8 +173,9 @@ at L2. Required CI and L3 obligations remain assigned, not silently waived or ma
   rule for unreproduced or intermittent failures; report uncertainty until evidence
   supports the cause.
 - Report source SHA, commands, results and remaining gaps at review handoff. For device
-  checks, include the selected scenarios, `PASS` markers and cleanup exit. For a failure,
-  name the earliest failing checkpoint and link retained evidence; preserve failed attempts.
+  checks, include the selected scenarios, per-scenario results (`PASS` markers or the
+  journey tool's report) and cleanup exit. For a failure, name the earliest failing
+  checkpoint and link retained evidence; preserve failed attempts.
   Separate build duration, device-check duration and total worker time when discussing cost.
   Reuse existing logs to distinguish cold/warm builds, build count, ABI, test packaging,
   runtime startup and edit-to-feedback time. Do not infer a task's cost from total job time,

package/skills/app-dev/android-development/references/gotchas.md

@@ -20,8 +20,10 @@ the product.
 | Backend tool, CI only | a Backend-backed step gets a 5xx in CI only; the log names a missing program (`Browser was not found at the configured executablePath`) |
 | adb transport, mid-journey | `connection terminated: read failed` in the adb trace after boot, then lost `adb reverse`: usually guest RAM |
 | UiAutomator server | `RemoteDisconnected` while the adb transport stays up: the on-device server was relaunched |
+| Maestro driver | driver readiness fails while another UI client holds registration: read `{maestro baseDir}/references/diagnosis.md` |
 | Journey harness | a wait right after a navigation times out while the destination is on screen |
 | Journey harness, short screen | a wait for a label times out only on a short or landscape screen, which shows the content above it |
+| Journey adapter | an offscreen target stays hidden while scrolls move away from it |
 | Product assertion | a screen or state mismatch with a screenshot |
 
 Then match the signal against [gotchas.md](gotchas.md). If nothing
@@ -143,6 +145,11 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 
 ## Journey harness
 
+### A scroll adapter moves away from the target
+
+For the Maestro/custom-adapter direction mismatch and its offscreen regression case,
+read `{maestro baseDir}/references/diagnosis.md`. Maestro-specific diagnosis has one owner.
+
 ### A navigation check passes on the previous screen
 
 - **Signal:** intermittently, a wait right after the next tap times out even though the

package/skills/app-dev/android-development/references/init.md

@@ -31,7 +31,7 @@ to a newly created Android section; report unresolved commands instead of guessi
 | --- | --- |
 | `CONTRIBUTING.md` | The `## Android development` section, wrapped in `<!-- conventions:android:start -->` / `<!-- conventions:android:end -->`, with `references/android-conventions.md` as its body. |
 | `AGENTS.md` | An `Android task entry` skill-loading block between `conventions:android-task-entry` markers, plus a pointer to the selected `CONTRIBUTING.md` when missing. Check these independently: a contributor-guide link alone is not a skill loader. |
-| `<dir>/device-run.sh`, `<dir>/failure_capture.py` | Only with `--install-scripts`: the generic layer copied with a version header. |
+| `<dir>/device-run.sh`, `<dir>/failure_capture.py`, `<dir>/failure_record.py` | Only with `--install-scripts`: capture/runner scripts and their record dependency copied with version headers. |
 
 Each file is created only when it is absent. The helper never edits `CLAUDE.md`, never writes into
 a parent project, a home directory or global agent configuration, and never reaches outside the
@@ -113,7 +113,10 @@ Existing guidance wins over the template:
 ## Skill scripts: reference or copy
 
 `device-run.sh` and `failure_capture.py` are referenced from the installed skill by
-default: nothing is copied, and the run reads them from the skill directory. Copy them
+default: nothing is copied, and the run reads them from the skill directory, with the
+record module supplied by the required `maestro` companion. Explicit copies also include
+that dependency as `failure_record.py` beside `failure_capture.py`, so they run without
+installed skills. Copy them
 into the repo only on an explicit request, with `--install-scripts` (default target
 `scripts/android/`) or `--install-scripts <dir>` for another relative directory inside
 the project.

package/skills/app-dev/android-development/references/setup.md

@@ -228,9 +228,12 @@ does not stop that server: use a verified private endpoint on a shared host and
 through the caller's owner. Capture the command's exit status, the final summary line and,
 when the journey failed, the `NATIVE_FAILURE` line and its `failure.json`.
 
-Expect every selected scenario's `PASS` marker, screenshots, and backend and Metro logs
-when the selected variant uses those services. Preserve the failed checkpoint's evidence
-before cleanup. A release build with embedded assets does not require Metro by default.
+Expect every selected scenario's result (`PASS` marker or the journey tool's report),
+required screenshots, and backend and Metro logs when the selected variant uses those
+services. For Maestro's result, screenshot and non-competing capture rules, read
+`{maestro baseDir}/references/evidence.md` before executing its journey.
+Preserve the failed checkpoint's evidence before cleanup. A release build with embedded
+assets does not require Metro by default.
 
 ## Owned development session
 
@@ -385,8 +388,9 @@ For setup proof only. Record:
 - Each stage's exit status and duration.
 - The APK's SHA-256 (`shasum -a 256` or `sha256sum`) and its per-ABI `lib/` entries
   (`unzip -l`), checked on the APK itself rather than inferred from Gradle flags.
-- The journey's `PASS` markers and the cleanup results: database dropped, emulator exited,
-  container removed, no listeners left on the backend or Metro ports.
+- The journey's per-scenario results (`PASS` markers or the journey tool's report) and
+  cleanup results: database dropped, emulator exited, container removed, no listeners
+  left on the backend or Metro ports.
 - Earlier failed or incomplete attempts. A later pass does not erase them.
 
 State what the run does not prove: tablet, accessibility (TalkBack), physical devices,

package/skills/app-dev/android-development/references/ui-journeys.md

@@ -1,58 +1,15 @@
-# UI journey tool: Maestro
+# Mobile UI journey routing
 
-Maestro writes a single-device UI flow as YAML and records per-step failure evidence. The
-skill references it; it does not bundle or install it, and adding it is the repo's decision.
+Maestro instructions moved to the required companion skill. Before selecting, authoring,
+running, debugging or migrating Maestro flows, read `{maestro baseDir}/SKILL.md` and its
+task-specific references. Resolve that path from the installed skill, not the working
+directory. Report a missing companion; discovery does not authorize installation.
 
-## When to use it
+`maestro` owns UI/backend/native test splitting, flow structure, state and permissions,
+exclusive UI-driver execution, diagnosis and the Maestro failure converter. This skill
+still owns Android runtime setup, workspace/device identity, the validation ladder and
+cleanup. Reuse its existing owner and required gates; a UI-driver change is not another
+emulator or fixture lifecycle.
 
-| Situation | Recommendation |
-| --- | --- |
-| Repo has no UI journey tool | Offer Maestro for new single-device journeys. It replaces hand-written adb/UiAutomator launch, poll, capture and assertion code. |
-| Repo has a working harness | Keep the harness. Add Maestro flows for new journeys alongside it; do not migrate existing cases. |
-| Coordinated multi-device case | Keep the custom harness. Maestro sharding runs independent flows, and a shard cannot depend on another. |
-
-## Device ownership
-
-Run against the emulator the session owns and name it, so Maestro never starts or picks its
-own device:
-
-```bash
-maestro --device "$ANDROID_SERIAL" test --test-output-dir "$LOG_DIR" ./maestro-flows
-```
-
-Each session installs and starts Maestro's driver packages (`dev.mobile.maestro`,
-`dev.mobile.maestro.test`) through `am instrument`. That cost lands on the session's first
-flow, not on every step, so run every flow of the case in one session instead of one session
-per flow.
-
-## Evidence
-
-`--test-output-dir` receives one session folder holding one self-contained folder per flow:
-`manifest.json`, `commands.json` (one entry per executed step), the failing step's
-`screenshots/` image and `screen-hierarchy/` JSON, and `logs/device-logcat.txt`. Convert that
-into the [device failure record](diagnosis.md#record-the-failed-device-case) instead of
-adding the journey helper:
-
-```bash
-python3 <skill-base-dir>/scripts/maestro_failure.py --maestro-dir "$LOG_DIR/2026-07-31_173617" \
-  --evidence-dir "$LOG_DIR" --case "$DEVICE_CASE"
-```
-
-It takes the session folder or one flow folder, writes `failure.json` into `--evidence-dir`
-(the flow folder by default) and prints the one `NATIVE_FAILURE` line for the first failed
-step. A passing flow writes nothing, and an existing record is never replaced. The artifact
-fields name the Maestro files (`screenshots/…`, `screen-hierarchy/…`, `logs/…`) rather than
-copying them into the adb names, so the failing frame and its hierarchy stay paired.
-
-## Agents
-
-`maestro mcp` gives an agent `list_devices`, `inspect_screen`, `take_screenshot` and `run`.
-Explore the screen and draft a flow with it; the committed YAML flow is the proof, not the
-MCP session that found the selectors.
-
-## Limits
-
-- Coordinated multi-device cases, exact data or payment proofs, and process-death checks stay
-  on custom harness code.
-- Authentication codes still come from the harness's disposable database, passed into a flow
-  with `maestro test -e` or resolved by its `runScript`; do not add a second fixture path.
+The old `scripts/maestro_failure.py` entry point forwards to the companion for callers
+already using it. New commands use `{maestro baseDir}/scripts/maestro_failure.py`.

package/skills/app-dev/android-development/scripts/failure_capture.py

@@ -21,6 +21,10 @@ adapters described in ``references/diagnosis.md``:
 
     case, step, error, screenshot, uiDump, logcatTail, evidenceDir, cleanupErrors
 
+The record model, its constants and the ``failure.json`` read and write live in the
+sibling ``maestro`` skill (``scripts/failure_record.py``) and are re-exported here, so
+the Maestro converter writes the same record without this module or a device.
+
 ``screenshot``, ``uiDump`` and ``logcatTail`` are file names relative to
 ``evidenceDir`` and are ``null`` when that capture failed; the reason goes to
 ``cleanupErrors`` and never replaces the original ``error``. A record is written
@@ -39,32 +43,35 @@ always propagates unchanged.
 from __future__ import annotations
 
 import contextlib
-import json
 import os
 import subprocess
 import sys
 import tempfile
-from dataclasses import dataclass, field
 
-RECORD_NAME = "failure.json"
-NATIVE_FAILURE_PREFIX = "NATIVE_FAILURE "
+# Explicit project copies carry the record module beside this file. Installed skills
+# use the declared Maestro sibling dependency; neither route depends on the caller's cwd.
+_SCRIPTS = os.path.dirname(os.path.abspath(__file__))
+_RECORD_SCRIPTS = _SCRIPTS if os.path.isfile(os.path.join(_SCRIPTS, "failure_record.py")) else (
+    os.path.normpath(os.path.join(_SCRIPTS, "..", "..", "maestro", "scripts"))
+)
+if _RECORD_SCRIPTS not in sys.path:
+    sys.path.insert(0, _RECORD_SCRIPTS)
+
+from failure_record import (  # noqa: E402
+    NATIVE_FAILURE_KEYS,
+    NATIVE_FAILURE_PREFIX,
+    RECORD_KEYS,
+    RECORD_NAME,
+    Failure,
+    read_record,
+    write_record,
+)
+
 SCREENSHOT_NAME = "screenshot.png"
 UI_DUMP_NAME = "ui-dump.xml"
 LOGCAT_NAME = "logcat-tail.txt"
 UI_DUMP_REMOTE = "/sdcard/failure-capture.xml"
 
-RECORD_KEYS = (
-    "case",
-    "step",
-    "error",
-    "screenshot",
-    "uiDump",
-    "logcatTail",
-    "evidenceDir",
-    "cleanupErrors",
-)
-NATIVE_FAILURE_KEYS = ("case", "step", "error", "evidenceDir")
-
 
 class CaptureError(RuntimeError):
     """A bounded capture command failed, timed out or returned no usable output."""
@@ -152,74 +159,6 @@ class AdbClient:
         _write_bytes(destination, payload)
 
 
-@dataclass
-class Failure:
-    """One failed device case; also the payload of `failure.json`."""
-
-    case: str = None
-    step: str = None
-    error: str = ""
-    screenshot: str = None
-    uiDump: str = None
-    logcatTail: str = None
-    evidenceDir: str = None
-    cleanupErrors: list = field(default_factory=list)
-
-    def as_dict(self):
-        return {key: getattr(self, key) for key in RECORD_KEYS}
-
-    def native_failure_line(self):
-        compact = {key: getattr(self, key) for key in NATIVE_FAILURE_KEYS}
-        return NATIVE_FAILURE_PREFIX + json.dumps(compact, separators=(",", ":"))
-
-    @classmethod
-    def from_dict(cls, payload):
-        values = {key: payload[key] for key in RECORD_KEYS if key in payload}
-        errors = values.get("cleanupErrors")
-        values["cleanupErrors"] = list(errors) if isinstance(errors, list) else []
-        return cls(**values)
-
-
-def read_record(evidence_dir):
-    """The record already in `evidence_dir`, or None when there is no usable one."""
-    path = os.path.join(evidence_dir, RECORD_NAME)
-    try:
-        with open(path, "r", encoding="utf-8") as stream:
-            payload = json.load(stream)
-    except (OSError, ValueError):
-        return None
-    if not isinstance(payload, dict) or "error" not in payload:
-        return None
-    return Failure.from_dict(payload)
-
-
-def write_record(failure, evidence_dir):
-    """Store `failure` unless a record already exists; return the record on disk.
-
-    A valid earlier record wins, so a cleanup error or a second failing step cannot
-    replace the first failure. An unreadable file is not a record and is replaced,
-    with the replacement noted on the returned record's `cleanupErrors`.
-    """
-    os.makedirs(evidence_dir, exist_ok=True)
-    existing = read_record(evidence_dir)
-    if existing is not None:
-        return existing
-    path = os.path.join(evidence_dir, RECORD_NAME)
-    if os.path.exists(path):
-        failure.cleanupErrors.append("%s: replaced an unreadable record" % RECORD_NAME)
-    payload = json.dumps(failure.as_dict(), indent=2) + "\n"
-    handle, temporary = tempfile.mkstemp(dir=evidence_dir, prefix=".failure-", suffix=".json")
-    try:
-        with os.fdopen(handle, "w", encoding="utf-8") as stream:
-            stream.write(payload)
-        os.replace(temporary, path)
-    except BaseException:
-        if os.path.exists(temporary):
-            os.unlink(temporary)
-        raise
-    return failure
-
-
 class FailureRecorder:
     """Capture the first failing step of one device case.
 

package/skills/app-dev/android-development/scripts/init.mjs

@@ -22,6 +22,7 @@ const defaultScriptsDir = 'scripts/android'
 const installableScripts = [
   { name: 'device-run.sh', mode: 0o755 },
   { name: 'failure_capture.py', mode: 0o644 },
+  { name: 'failure_record.py', source: '../../maestro/scripts/failure_record.py', mode: 0o644 },
 ]
 const scriptHeaderPattern = /^# android-development skill (\S+) sha256:([0-9a-f]{64}) (\S+)$/
 
@@ -516,7 +517,7 @@ function scriptPlan(root, requested) {
   return installableScripts.map(script => {
     const file = path.join(root, target, script.name)
     assertScriptDirectory(root, file)
-    const source = scriptSource(script.name)
+    const source = scriptSource(script.source ?? script.name)
     const next = withHeader(source, scriptHeader(script.name, version, source))
     const entry = readGuidance(resolveTarget(root, path.posix.join(target, script.name)))
     const base = { ...entry, mode: script.mode, script: script.name }