Autonom

View saved version →

---
name: android-app-actions
description: Design, implement, and validate Android deep links, verified App Links, launcher shortcuts, external intents, and Assistant-facing actions through one typed and sanitized routing model.
---

# Android App Actions

Use one routing model for every external entry into the app. Prefer a small
surface over exposing the full navigation graph.

## Steps

1. List one to three high-value destinations or verbs the user actually needs.
2. Map each to the thinnest surface that fits: App Link / deep link, static or
   dynamic shortcut, notification action, widget action, or Assistant capability.
3. Funnel all external entry points through a single typed destination or
   domain-command type.
4. Validate and sanitize host, path, and query parameters before navigation or
   business logic runs.
5. Exercise cold start, warm start, duplicate launch, back stack, bad input, and
   missing content on a real device.

## Smoke invocation

```bash
adb -s <serial> shell am start -W \
  -a android.intent.action.VIEW \
  -d "https://example.com/path?item=123" \
  <package>
```

For Flutter, keep URI parsing and destination mapping unit-testable in Dart;
manifest verification and system launch remain Android concerns.

## Hard rules

- Do not open the entire navigation tree to the outside world.
- Do not invent parallel routers for links, shortcuts, notifications, and widgets.
- Never trust inbound ids, hosts, paths, or query values.
- Compilation of XML or manifests is not proof — invoke the action on a target
  and confirm the destination.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: android-debugger-agent
description: Build, install, launch, inspect, and debug Android apps on explicit adb targets using Gradle or Flutter builds, screenshots, robust UI Automator selectors, input events, and focused logcat evidence.
---

# Android Debugger Agent

Drive a native or hybrid Android app on one explicit adb target. Prefer
Autonom CLI when a session is active; fall back to the helpers below when you
need raw adb or offline XML analysis.

## 1. Pin a single device

```bash
adb devices -l
emulator -list-avds
```

If more than one target is connected, pass `-s <serial>` on every adb call.

## 2. Build and install

Discover the real Gradle task; do not invent module names.

```bash
./gradlew tasks --all
./gradlew :app:installDebug --console=plain
```

Flutter apps: use `flutter-debugger-agent` for the Dart/engine path and keep
this skill for the Android shell layer. Stop at the first actionable build error.

## 3. Launch and capture state

```bash
PACKAGE=<application-id>
ACTIVITY="$(adb -s <serial> shell cmd package resolve-activity --brief "$PACKAGE" | tr -d '\r')"
adb -s <serial> shell am start -W -n "$ACTIVITY"
adb -s <serial> exec-out screencap -p > /tmp/android-screen.png
adb -s <serial> exec-out uiautomator dump /dev/tty > /tmp/android-ui.xml
```

## 4. Selectors and taps

```bash
python3 <skill-root>/scripts/ui_tree_summarize.py /tmp/android-ui.xml
python3 <skill-root>/scripts/ui_query.py /tmp/android-ui.xml --text Settings --json
python3 <skill-root>/scripts/ui_query.py --serial <serial> \
  --desc "Open settings" --wait 10 --click
```

Supported selectors: text, content-desc / Flutter semantics, resource-id, class,
package, booleans, exact / contains / regex, index, live wait. Ambiguous
matches must be narrowed or indexed — never silently tap the first hit.

## 5. Logs

```bash
adb -s <serial> logcat -c
PID="$(adb -s <serial> shell pidof -s "$PACKAGE" | tr -d '\r')"
adb -s <serial> logcat --pid "$PID"
adb -s <serial> logcat -b crash -d
```

## 6. Replay

After a fix, reuse the same target, setup, inputs, screenshot, query, and logs.

## Testing note

Compose test tags and Flutter semantics belong in automated tests. UI Automator
is for system UI and black-box evidence, not a substitute for widget tests.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: android-emulator-browser
description: Mirror and lightly control an Android target or iOS Simulator in the visible Codex browser through the authenticated Autonom Mobile Canvas.
---

# Mobile Canvas browser

Stream one explicit target into a localhost browser for visual proof and light
control. Install and launch the app first. Canvas actions use the same Autonom
action pipeline and journal as CLI input; the browser is not a second runner.

## Launch

```bash
autonom canvas serve --platform android --serial <adb-serial> --transport auto

autonom canvas serve --platform ios --target <simulator-udid> --transport screencap
```

Open the printed fragment-token URL in the agent browser panel. The page
exchanges it for an HttpOnly cookie and removes the fragment. Leave the process
running and confirm frames advance before calling the setup successful.

## Transport modes

| Mode | Behavior |
| --- | --- |
| `auto` | Prefer `screenrecord` + ffmpeg H.264→MJPEG; fall back if unavailable |
| `screenrecord` | Require accelerated path; fail loudly when prerequisites missing |
| `screencap` | Multipart JPEG screenshots; no ffmpeg |

Android also exposes authenticated Annex-B H.264 at `/stream.h264`. iOS uses
public `simctl` screenshots with idb input and always chooses the screenshot
fallback; pixel-to-point mapping is handled by the Canvas status channel.

The UI shows active transport and frame health. Use Reconnect after rotation or
when device-side recording stops.

## Input surface

Tap, drag, wheel-as-swipe, Back/Home/Enter/Delete/D-pad/wake, and conservative
ASCII typing. Every action records `human`, `agent`, `replay`, or `system`
origin. The control endpoint supports pause, resume, takeover, and release.
Structural selection still belongs to Autonom `ui` commands.

## Security

Binds to `127.0.0.1` with a random token by default. Do not expose publicly.
Anyone with a forwarded port and the bootstrap token can drive the device.
`--no-auth` is for isolated local debugging only.

## Performance boundary

Good for iteration; not a measurement tool. Use scrcpy for high-fidelity manual
review and Macrobenchmark / Perfetto / Flutter profile mode for claims.

## Evidence to record

Side-panel screenshot, platform and target id, transport, package/activity,
variant, control owner, and the exact flow replayed.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: android-memory-leaks
description: Investigate Android Java, Kotlin, native, and process memory using repeatable flows, meminfo, heap dumps, retaining paths, heapprofd, and before-after evidence without confusing growth with proof.
---

# Android Memory Leaks

Growth is a lead. A leak is a retained object with a root path, or a repeatable
accumulation under an equivalent flow.

## Evidence ladder

1. Directional snapshots via `dumpsys meminfo` and `/proc/<pid>/status`.
2. Managed-heap dump when the process is debuggable and the suspect lives in
   Java/Kotlin heap.
3. Class counts, retained size, fields, and GC roots (Studio Profiler,
   LeakCanary, Shark).
4. Perfetto `heapprofd` for native allocation growth.
5. Same flow again after the fix; same metrics and paths.

## Capture

Prefer the Autonom CLI — artifacts land in the session's `metrics/` dir and
the journal keeps the timeline:

```bash
autonom metrics snapshot --label baseline        # cheap directional point
autonom metrics memory capture --label after-flow [--no-hprof]
autonom metrics memory analyze                   # series math, leads only
autonom metrics series --count 5 --interval 2    # snapshots + slope/leads
```

Pass `--no-hprof` for release/profileable builds where dumpheap is
unavailable. The standalone scripts remain for hosts without a session:

```bash
<skill-root>/scripts/capture_android_memory.sh \
  --serial <serial> --package <application-id> \
  --out-dir <artifact-dir> --label after-flow
python3 <skill-root>/scripts/analyze_meminfo_series.py <artifact-dir> \
  --glob '*-meminfo.txt' --json
```

## Interpretation rules

- One spike ≠ leak.
- Prove managed leaks with a retaining path or repeatable accumulation.
- Separate Dart/Flutter heap from Android managed and native memory.
- Separate intentional process caches from feature-lifetime objects.
- Fix the retaining edge; do not sprinkle forced GC or blanket clear calls.

## Frequent retainers

Activities, fragments, platform views, contexts, listeners, coroutines,
adapters, bitmaps, singletons, plugin registrars, event channels, JNI handles,
and caches without clear ownership.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: android-project-setup
description: Create, inspect, or modernize native Android modules with Kotlin, Gradle, Compose, SDK configuration, version catalogs, and compatibility checks based on the active repository and official guidance.
---

# Android Project Setup

Change the smallest coherent surface that the repository already uses.

## Workflow

1. Read settings, module builds, version catalogs, wrapper, `gradle.properties`,
   manifests, build logic, and CI.
2. Run `scripts/toolchain_snapshot.py` instead of trusting a hardcoded matrix.
3. Classify: new module, focused dependency change, or toolchain migration.
4. Keep existing dependency-management and architecture conventions when they
   are coherent.
5. Re-check official AGP / Kotlin / Gradle / library docs for version-sensitive
   work.
6. Apply a minimal patch and run the narrowest Gradle tasks that prove it.

## Defaults

- Checked-in Gradle wrapper only.
- Versions live in the existing catalog or shared build logic.
- Stable production deps unless a required API needs a preview artifact.
- Prefer KSP when supported; do not mix processor migration with unrelated work.
- `minSdk` follows product policy; `compileSdk` / `targetSdk` changes need
  platform review.
- AGP built-in Kotlin only after verifying the active AGP migration guide.

## Verify

```bash
./gradlew help --console=plain
./gradlew :app:assembleDebug --console=plain
./gradlew :app:testDebugUnitTest --console=plain
./gradlew :app:lintDebug --console=plain
```

Discover tasks with `./gradlew tasks --all`.

## Guardrails

- No dynamic dependency versions.
- No generic template pasted over a live project.
- No broad dependency upgrades during a feature-only task.
- No package rename + architecture rewrite + toolchain bump in one change
  unless the user asked for all of it.
- No “latest” claims without an observed snapshot and a dated official source.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: android-runtime-performance
description: Capture and interpret Android runtime performance with Macrobenchmark, Baseline Profiles, Perfetto, Simpleperf, gfxinfo, and comparable device flows while separating native and Flutter evidence.
---

# Android Runtime Performance

Measure one user-visible flow on an explicit device. Separate Flutter UI/raster
evidence from Android/native evidence.

## Choose the instrument

- **Macrobenchmark** — repeatable startup / interaction metrics on a
  profileable or release-like build.
- **Baseline Profiles** — hot paths only; confirm the shipped binary consumes
  the profile.
- **Perfetto** — frame lanes, scheduler, binder, locks, I/O, GC, custom sections.
- **Simpleperf** — sampled CPU stacks (not wall-clock waits by itself).
- **gfxinfo** — quick directional frame snapshot.
- **heapprofd** — native allocation stacks when managed-heap evidence is not enough.

Read `references/native-performance-workflows.md` before capture.

## Fast frame snapshot

Prefer the Autonom CLI inside a session — it owns reset/capture, keeps the
raw text as the artifact, and journals the run:

```bash
autonom metrics frames reset
# replay one focused flow
autonom metrics frames capture
autonom metrics trace --preset simpleperf --duration 30
```

Raw adb equivalent without a session:

```bash
adb -s "$SERIAL" shell dumpsys gfxinfo "$PACKAGE" reset
# replay one focused flow
adb -s "$SERIAL" shell dumpsys gfxinfo "$PACKAGE" framestats \
  > "$ARTIFACT_DIR/gfxinfo-framestats.txt"
```

## Simpleperf

```bash
adb -s "$SERIAL" shell rm -f /data/local/tmp/perf.data
adb -s "$SERIAL" shell simpleperf record \
  --app "$PACKAGE" -e cpu-clock -f 4000 -g \
  --duration 30 -o /data/local/tmp/perf.data
adb -s "$SERIAL" pull /data/local/tmp/perf.data "$ARTIFACT_DIR/perf.data"
<skill-root>/scripts/simpleperf_report.sh \
  "$ARTIFACT_DIR/perf.data" "$ARTIFACT_DIR" \
  --first-party-regex 'com\\.example|libapp\\.so'
```

## Heapprofd reports

```bash
<skill-root>/scripts/heapprofd_report.sh "$ARTIFACT_DIR/trace.pftrace" "$ARTIFACT_DIR"
```

## Comparison contract

Record device, Android version, refresh rate, package/variant, Flutter mode,
compilation mode, data state, thermal state, exact flow, and run count. Compare
only equivalent captures; state units and aggregation.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: autonom
description: Start here for Autonom — the universal mobile test/debug harness for AI agents on Android and the iOS Simulator. The map of the whole system — what it can do, how it works, and how to use it end to end (own a session, see the screen, drive it, watch logs and network, mock responses, capture evidence, journal every step). Read this first when asked to test, debug, profile, reproduce, or validate a running app, or when unsure which Autonom skill to load. Then let project-router narrow to the stack-specific skills.
---

# Autonom — how the whole harness works

Autonom lets an AI agent **test and debug a real mobile app** on an Android
emulator or an iOS Simulator, with evidence. You describe a goal in plain words;
this skill is the map that tells you what the harness can do and how to drive it.
The same verbs work on both platforms.

## When this applies

Any task about a *running* app: reproduce a bug, walk a flow, check a screen,
read logs, see what the app sent and how it reacts to a bad response, profile,
or validate a release. If the task is only about *writing* code, route straight
to the stack skills via `project-router`.

## How it is built (the mental model)

Three layers, and it helps to know which is which:

1. **The CLI control plane** — `scripts/autonom.py` (installed as `autonom`).
   One dependency-free JSON API. Every command prints JSON; an expected failure
   prints `{"ok": false, "error_code": "...", "hint": "..."}` on stderr with exit
   code 2, so you branch on a stable code, never parse prose. This is the source
   of truth; the skills are how to use it well.
2. **Thin verb-skills** — `mobile-session`, `mobile-screen`, `mobile-network`
   wrap the CLI verbs with the judgement to use them.
3. **Knowledge** — `mobile-memory` (`~/.autonom/apps/<pkg>/`) carries what was
   learned about an app once, so a flow is replayed, not re-derived.

Sessions, mocks, the process registry, and per-app knowledge are all
**machine-global** under `~/.autonom/` — a run is not tied to the directory it
was launched from, and the active session is found from anywhere.

## First moves

```bash
autonom doctor          # what can this machine actually do? tools, session, orphans
autonom devices         # Android + iOS in one list; each entry has a `running` flag
```

`doctor` is honest: green means installed, not proven. If something is missing it
names the exact fix.

## The end-to-end loop

```bash
# 1. Own a target (boot it first if needed)
autonom devices boot --avd Pixel_9                 # or --udid <sim>; session start also boots a sim
autonom session start --serial emulator-5554 --app-id com.example.app

# 2. See the screen, then act by meaning (not coordinates)
autonom ui tree                                    # compact accessibility tree
autonom ui tap --desc "Log In"
autonom ui type "test-user"                        # into the focused field

# 3. Watch what happens
autonom session outputs                            # what is followable + tail -f hints
autonom logs follow --source device --grep 'Error' --max-seconds 60   # live, bounded NDJSON
autonom network start --i-understand-mitm          # decrypt + record (consent-gated)
autonom network attach --i-understand-mitm
autonom network requests list --host api.example.com --status 401
autonom metrics snapshot --label baseline          # memory/CPU point, honest semantics

# 4. Force a failure and check the UI reacts
autonom network mock add --url '.../v1/login' --status 500 --json '{"error":"x"}'
autonom ui tap --desc "Log In"
autonom ui find --text "Something went wrong"

# 5. Capture evidence + record what you did
autonom screenshot --task login --label "500 error state"
autonom note add "login shows the generic error banner on 500; retry works" --task login

# 6. Read the run back, then clean up
autonom journal                                    # the full timeline of this session
autonom session stop                               # tears 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: autonom-setup
description: Install or hand off the Autonom harness — the CLI plus all skills — onto a new machine or into another agent. Build a single transferable bundle, copy it, install with one command, verify, and register it with Claude, Grok, or Codex. Triggers when setting up Autonom somewhere new, packaging it for handoff, or asking how to get it onto another device or agent.
---

# Autonom Setup

Autonom is a plugin: 23 skills plus a dependency-free CLI they drive. This skill
packages the whole thing into one file you can carry to another machine and
install with one command — the skills travel with the CLI and land in whatever
agent is there.

Not a compiled binary, on purpose: the CLI is stdlib-only Python (nothing to
compile), and the network addon must be a real file on disk because `mitmdump`
loads it by path. So the transferable artifact is a **tarball** — one file to
copy, one command to install.

## Build the bundle

```bash
./scripts/build_release.sh
# -> dist/autonom-<version>.tgz  (~200 KB: CLI + library + all skills + manifest)
```

The bundle carries its own `install.sh`, so the target needs nothing but
`python3` (already present on macOS and Linux) and, for real device work, the
device tools (`adb`, `xcrun`, `idb`, `mitmdump`) that `doctor` checks.

## Install on another machine

Copy `dist/autonom-<version>.tgz` over any transport, then:

```bash
tar xzf autonom-<version>.tgz
./autonom-<version>/install.sh          # checkbox picker: tools, Claude, Codex, Grok
./autonom-<version>/install.sh --all    # headless: everything
./autonom-<version>/install.sh claude   # or any explicit subset
```

`install.sh` copies the bundle to a stable home (`AUTONOM_PREFIX`, default
`~/.local/share/autonom`) so the extracted folder can be deleted afterwards,
puts `autonom` on `PATH`, installs the selected device tools and agents, and
verifies with `autonom doctor`. Headless runs never prompt — no flags means
CLI only. Overrides: `AUTONOM_PREFIX`, `AUTONOM_BIN_DIR`.

## Into each agent

`install.sh <target>`, or run the layer directly:

```bash
./scripts/install_claude.sh              # Claude Code plugin (marketplace + install)
./scripts/install_codex.sh               # Codex plugin (marketplace + add)
./scripts/install_skills.sh grok         # ~/.grok/skills
./scripts/install_skills.sh --link <dir> # any skill-root, by symlink
./scripts/install_skills.sh --copy <dir> # by copy (no live repo)
```

Claude and Codex install Autonom as a **plugin** from the bundle's marketplace
manifests and copy it into a versioned cache. After the source changes, re-run
the script — or `claude plugin update autonom@autonom` /
`codex plugin add autonom@autonom` — so the cache catches up; the version is
bumped on every release exactly so those caches notice. Skills load namespaced
(`autonom:mobile-network`). Without the `claude` CLI the Claude path falls back
to loose `autonom-*` skills in `~/.claude/skills`.

## Verify it actually works

`doctor` reports what is present; a green install still means *installed*, not
*proven*. Confirm the chain end to end on a connected device:

```bash
autonom doctor                     # tools + capabilities + session + orphans
autonom devices                    # a real device/simulator is listed
autonom session start --platform android --target <id>
autonom ui tree --max-nodes 5      # a real tree comes back
autonom session stop
```

If any step fails, `doctor`'s per-tool `state` and install hint name what is
missing — do not proceed as if it worked.

## Knowledge stays behind

The bundle ships the **skills**, not the per-app knowledge under
`~/.autonom/apps/` (see `mobile-memory`). That store is machine-local and
per-person; it accumulates on each machine as work happens and is not part of
the handoff.

## Related

- `mobile-session`, `mobile-screen`, `mobile-network` — the verbs the CLI exposes.
- `mobile-memory` — per-app knowledge, kept out of the bundle on purpose.
- `toolchain-doctor` — 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: compose-performance-audit
description: Audit Compose performance from code and runtime evidence, focusing on invalidation scope, stability, lazy identity, effects, layout, draw work, images, and comparable profiling captures.
---

# Compose Performance Audit

Find unnecessary recomposition, layout, and draw work with code review plus
comparable runtime captures.

## Order of work

1. Name one screen and one user-visible symptom (jank, slow open, scroll hitch).
2. Trace state owners: which state reads invalidate which composables.
3. Check stability of parameters, `key` / identity in lazy lists, and effect
   scopes (`LaunchedEffect`, `DisposableEffect`, `SideEffect`).
4. Look for expensive work in composition, intrinsic measurements, excessive
   modifiers (clip / graphicsLayer / shadow), oversized images, and layout
   thrash.
5. Capture a comparable profile (Macrobenchmark, Perfetto, or Studio) on an
   explicit target and mode.
6. Apply the smallest fix; re-run the same flow.

## Code signals

- Unstable lambdas / objects crossing composition boundaries without remember.
- Reading broad state higher than needed.
- Lazy items without stable keys.
- `derivedStateOf` misused or missing where it would shrink invalidation.
- Layout that measures children twice without need.
- Images decoded at full resolution for small on-screen size.

## Runtime signals

Frame time, recomposition counts (when available), overdraw, and timeline
sections. Emulator numbers are directional; use a physical device for claims
users will feel.

## Report

Flow, device, mode, code findings, capture artifacts, fix, and before/after
metrics with units.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: flutter-android-platform
description: Implement and debug the Android platform layer of Flutter apps including Gradle, manifests, flavors, permissions, platform channels, plugins, app links, notifications, and native lifecycle behavior.
---

# Flutter Android Platform

Own the Android shell of a Flutter app: Gradle, manifests, flavors, plugins,
channels, links, notifications, and lifecycle.

## Inspect first

- `android/` Gradle files, flavors, application ids, signing config location
- manifests and merged manifest output
- plugin registrations and GeneratedPluginRegistrant assumptions
- platform channels and method/event APIs
- deep links / App Links, notification intents, launch modes

Use `toolchain-doctor` / `toolchain_snapshot.py` for SDK and AGP pins.

## Common work

1. Keep Flutter Gradle plugin and Android embedding conventions the project
   already uses.
2. Add permissions and queries only with a product reason; document why.
3. Implement channel handlers with explicit error codes and main-thread rules.
4. Verify deep links with `adb` VIEW intents and App Link verification where
   required.
5. Confirm flavor × build-mode matrix before release packaging.

## Debug loop

```bash
flutter build apk --debug --flavor <flavor>
adb -s <serial> install -r <apk>
adb -s <serial> shell am start -W -n <package>/<activity>
adb -s <serial> logcat --pid "$(adb -s <serial> shell pidof -s <package> | tr -d '\r')"
```

## Boundaries

- Do not “fix” Flutter UI bugs by rewriting Android unless evidence points
  there.
- Do not print keystore secrets or signing material.
- Prefer repository scripts for flavors and dart-defines.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: flutter-debugger-agent
description: Build, launch, attach to, inspect, and debug Flutter applications on explicit devices using Flutter machine output, Dart VM service evidence, adb, screenshots, logs, and repeatable user flows.
---

# Flutter Debugger Agent

Debug a Flutter app on one explicit device with machine-readable Flutter output
plus Android evidence when needed.

## Resolve the tool chain

```bash
python3 <marketplace-root>/scripts/flutter_exec.py --root . -- --version
python3 <marketplace-root>/scripts/flutter_exec.py --root . -- devices
```

Never silently fall back to a system Flutter when the repo is FVM-pinned.

## Run / attach

```bash
python3 <marketplace-root>/scripts/flutter_exec.py --root . -- \
  run -d <device-id> --target <target> --machine
```

Capture VM service URI from machine events when you need DevTools or custom
inspectors. Prefer Autonom session + `ui` / `screenshot` / `logs` once the app
is up.

## Evidence ladder

1. Reproduce on a single pinned device/mode.
2. Screenshot + accessibility / UI tree (Autonom or adb).
3. Dart logs / VM service errors.
4. `adb logcat` filtered to the app process for platform issues.
5. After a patch, replay the same flow end-to-end.

## Rules

- One device id on every command when multiple are present.
- Debug mode is fine for functional bugs; profile mode for performance claims.
- Do not treat a green build as a green UX path — observe the screen.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: flutter-memory-leaks
description: Investigate Flutter and Android memory growth using Dart retaining paths, DevTools snapshots, disposal and lifecycle review, native heap evidence, and comparable before-after flows.
---

# Flutter Memory Leaks

Separate Dart heap, external/graphics memory, Android managed heap, and native
allocations. Compare equivalent idle points.

## Ladder

1. Define one flow and an equivalent idle baseline.
2. Capture DevTools heap snapshots (or allocation tracing) before and after.
3. Inspect retaining paths for growing types.
4. Review disposal: controllers, streams, timers, listeners, `BuildContext`
   capture, image caches, statics, platform-channel subscriptions.
5. Escalate to platform metrics when process growth is not explained by Dart
   snapshots: `autonom metrics snapshot` / `series` on both platforms, then
   `android-memory-leaks` (`autonom metrics memory capture|analyze`) for the
   Android evidence pack.
6. Fix the retaining edge; repeat the same flow.

Read `references/memory-evidence.md`.

## Rules

- RSS/PSS growth alone is not proof.
- Disposed ≠ unreachable; check the path.
- Do not paper over leaks with forced GC or global cache wipes.
- Add leak-tracking libraries only if the repo already uses them or the user
  asks.

## Report

Flow, device, mode, artifacts, retained types, path or accumulation proof,
fix, before/after.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: flutter-performance-audit
description: Audit Flutter runtime performance from code and profile evidence, separating UI-thread build cost, raster cost, startup, memory pressure, image work, and native Android bottlenecks.
---

# Flutter Performance Audit

Separate UI-thread build cost from raster cost. Measure in **profile mode** on
an explicit device.

## Evidence order

1. One user-visible flow and symptom.
2. Code pass: rebuild scope, sync Dart work, list identity, images, layout/paint,
   state churn, isolate boundaries.
3. Profile-mode capture on a named device.
4. DevTools frames / timeline / CPU / raster / custom `dart:developer` events.
5. For repeatable flows: `integration_test` `watchPerformance` or `traceAction`;
   keep the JSON.
6. Smallest fix; equivalent re-capture.

Read `references/performance-evidence.md` first.

## Commands

```bash
flutter run --profile -d <device-id> --target <target>
flutter test integration_test/performance_test.dart -d <device-id>
autonom metrics frames flutter-summary build/integration_response_data.json
```

(`<skill-root>/scripts/frame_timings_summary.py` is the same math for hosts
without the Autonom CLI.)

## Metrics

Report build and raster average, p90, p99, worst, and over-budget frames. State
the budget (refresh rate). Keep startup and app size as separate claims.

## Boundaries

- Debug timings are not representative.
- Emulator results are directional.
- Flutter UI/raster evidence does not replace Perfetto/Simpleperf for Android,
  binder, codec, DB, or native plugin bottlenecks.
- Compare same device, thermal state, mode, target, data, and flow.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: flutter-release-validation
description: Validate Flutter Android release candidates across flavors, targets, Dart defines, signing boundaries, analysis, tests, APK or app bundle builds, smoke flows, and app-size artifacts.
---

# Flutter Release Validation

Lock the exact flavor, target, application id, version, dart-defines, signing
source, backend environment, and output artifact before building.

## SDK selection

```bash
python3 <marketplace-root>/scripts/flutter_exec.py --root . -- --version
```

Respect FVM pins; no silent system fallback.

## Ladder

1. Clean only if stale build state is plausible.
2. Resolve deps / codegen via repo commands.
3. Format, analyze, release-critical tests.
4. Build the requested artifact.
5. Install the closest installable variant on an explicit device.
6. Smoke: startup, auth/bootstrap, navigation, network failure, deep links,
   background/foreground, one critical transaction.
7. Record artifact paths, sizes, mapping/symbols, checksums when required.

## Typical commands

```bash
flutter analyze
flutter test
flutter build appbundle --release --flavor <flavor> --target <target> \
  --analyze-size
```

Use APK for local smoke when the deliverable is an AAB. Prefer project scripts
for `--dart-define-from-file`.

## Signing

Never print keystore material or service-account JSON. Report only which signing
source was used and whether verification succeeded.

## Report

Commit, toolchain snapshot, flavor/target/mode, commands, tests, artifacts,
device smoke, blockers, untested areas.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: flutter-testing
description: Design and run a layered Flutter test strategy across unit, widget, golden, integration, platform-channel, and native-UI tests with focused commands and reproducible device setup.
---

# Flutter Testing

Pick the narrowest layer that proves the behavior.

| Layer | Owns |
| --- | --- |
| unit | pure mapping, validation, state, repositories |
| widget | UI states, semantics, forms, callbacks without a full device |
| golden | visual contracts with pinned fonts/locale/size/renderer |
| integration_test | full Flutter flows on a real target |
| native | Kotlin/plugin implementation |
| Patrol / Espresso / UI Automator | permissions, notifications, platform views |

```bash
python3 <marketplace-root>/scripts/flutter_exec.py --root . -- --version
```

Read `references/testing-boundaries.md` when Flutter and native UI meet.

## Loop

1. Read the change, acceptance criteria, nearby tests, past flakes.
2. Draft happy / boundary / failure / lifecycle / a11y / platform cases.
3. Implement highest-signal missing tests first.
4. Run, refine once from failures, then widen the suite.

## Commands

```bash
flutter test test/path/to/test.dart
flutter test --plain-name "specific behavior"
flutter test integration_test/app_test.dart -d <device-id>
```

Use `flutter drive` only when the project’s driver/lab requires it.

## Stability

Prefer type/text/semantics/key finders. Avoid unbounded `pumpAndSettle` when
animations or streams never idle. Control clocks, randomness, network, and
storage.

## Platform channels

Fake the Dart side, unit-test native handlers, and keep one device path for
each critical channel.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: ios-debugger-agent
description: Build, run, and debug iOS apps on the Simulator for AI agents — resolve the scheme and destination, install and launch, then climb an evidence ladder through accessibility trees, screenshots, logs, and crash reports.
---

# iOS Debugger Agent (Simulator)

## Purpose

Turn "the iOS app misbehaves" into measured evidence. Build with the project's own
toolchain, drive the app through the Autonom CLI, and separate what was observed
from what is inferred.

Physical devices are out of scope: they need Developer Mode, signing, and tunnels.

## Prerequisites

```bash
python3 <autonom-root>/scripts/autonom.py doctor
```

Everything except `ui *` works with Xcode alone. The accessibility tree
additionally needs `idb` plus `idb_companion`; input (tap, swipe, type, key)
needs a companion that can load SimulatorKit, or AXe. `doctor` reports
`capabilities.ios_tree` and `capabilities.ios_hid` separately and prints the
exact fix for each gap.

**Xcode 27 trap:** SimulatorKit moved to `Contents/SharedFrameworks`, and an
`idb_companion` built before that looks in `Library/PrivateFrameworks`. The
tree still works, but every input fails with `ios_hid_framework_missing`.
Fix it with `brew update && brew upgrade idb-companion`, or install AXe
(`brew install cameroncooke/axe/axe`): the default `--ios-hid auto` then
routes input through AXe while the tree stays on idb, and each `ui` input
payload reports `backend: axe`. Pin a route with `--ios-hid idb|axe` (or
`AUTONOM_IOS_HID`) before the verb. Do not report a failed tap as an app
defect until `doctor` shows input ready. On Xcode 27 with AXe carrying input,
`capabilities.ios_hid.ready` stays `false` (it describes idb's own HID) while
`ios_hid.axe_ready` is `true`, `ios_hid.backend` is `axe`, and
`capabilities.ios_ui.ready` is `true`: read `ios_ui` and `axe_ready`, and keep
going — input works.

## 1. Build

Use whatever the repository already uses — never introduce a second build path.

```bash
# Flutter
flutter build ios --simulator --debug
# -> build/ios/iphonesimulator/Runner.app

# Xcode project or workspace
xcodebuild -scheme <Scheme> -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  -derivedDataPath build/DerivedData build
# -> build/DerivedData/Build/Products/Debug-iphonesimulator/<App>.app

# SwiftPM executable targets
swift build
```

Resolve the scheme from `xcodebuild -list` rather than guessing. When FVM or a
pinned Flutter SDK is present, resolve it with `scripts/flutter_exec.py` instead of
falling back to a system SDK.

## 2. Own a session

```bash
python3 <autonom-root>/scripts/autonom.py devices --platform ios
python3 <autonom-root>/scripts/autonom.py session start \
  --platform ios --target <UDID> \
  --install <path>.app --launch --app-id <bundle-id> --log-stream
```

`--log-stream` starts a background `log stream` for the session, filtered to
the app and capped on disk (`AUTONOM_IOS_LOG_MAX_MB`, default 50, one
rotation), which makes `logs tail` cheap afterwards. Without it, tailing
falls back to `log show`. A second `session start` while one is live is
refused with `session_already_active`; stop the old one first.

## 3. Reproduce and capture

```bash
python3 <autonom-root>/scripts/autonom.py ui tree
python3 <autonom-root>/scripts/autonom.py ui find --desc "Log In" --mode exact
python3 <autonom-root>/scripts/autonom.py screenshot --out /tmp/before.png
python3 <autonom-root>/scripts/autonom.py ui tap --desc "Log In" --mode exact
python3 <autonom-root>/scripts/autonom.py screenshot --out /tmp/after.png
python3 <autonom-root>/scripts/autonom.py logs tail --package <bundle-id> --since 60
python3 <autonom-root>/scripts/autonom.py crash list --app-id <bundle-id>
```

**Compare the two screenshots.** A tap that exits 0 has not been proven to do
anything; a changed screen (or a changed tree) is the proof. Pin the status
bar first (`simulator status-bar pin`) so the battery and signal glyphs do not
show up as a difference, and pin the 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: ios-project-setup
description: Inspect an iOS project's real layout for AI agents — resolve workspace vs project, schemes, configurations, bundle identifiers, simulator destinations, and the built .app path without hard-coding versions.
---

# iOS Project Setup

## Purpose

Establish **what this repository actually builds** before running anything. Every
value below is discovered from the project, never assumed. Do not assert a "latest"
or "recommended" Xcode, Swift, or deployment-target version; report what is
declared.

## 1. Toolchain, as installed

```bash
xcode-select -p
xcodebuild -version
xcrun simctl list runtimes
python3 <autonom-root>/scripts/autonom.py doctor
```

## 2. Workspace or project

```bash
ls *.xcworkspace *.xcodeproj Package.swift 2>/dev/null
```

| Found | Build with |
| --- | --- |
| `*.xcworkspace` | `-workspace <name>.xcworkspace` — required when CocoaPods is used |
| `*.xcodeproj` only | `-project <name>.xcodeproj` |
| `Package.swift` | `swift build` / `swift test` |
| `ios/` inside a Flutter app | drive Flutter; touch Xcode only for native/platform work |

A Flutter repository has `pubspec.yaml` with a Flutter SDK dependency and an `ios/`
directory containing `Runner.xcworkspace`. Route Dart work to the `flutter-*`
skills; use this skill for signing, capabilities, plist, or native module work.

## 3. Schemes, configurations, destinations

```bash
xcodebuild -list -workspace <name>.xcworkspace
xcodebuild -showBuildSettings -scheme <Scheme> | grep -E 'PRODUCT_BUNDLE_IDENTIFIER|PRODUCT_NAME|IPHONEOS_DEPLOYMENT_TARGET|CONFIGURATION_BUILD_DIR'
xcrun simctl list devices available
```

Take the bundle id from `PRODUCT_BUNDLE_IDENTIFIER` rather than reading `Info.plist`
directly — the plist usually contains `$(PRODUCT_BUNDLE_IDENTIFIER)`, and per-flavor
schemes can differ.

Destination for a simulator build:

```text
-destination 'platform=iOS Simulator,id=<UDID>'      # exact, preferred
-destination 'platform=iOS Simulator,name=iPhone 17 Pro'
```

Prefer the UDID from `autonom devices --platform ios`: a name can match several
runtimes.

## 4. Locate the built `.app`

```bash
# Flutter
build/ios/iphonesimulator/Runner.app

# xcodebuild with an explicit derived-data path
build/DerivedData/Build/Products/<Configuration>-iphonesimulator/<PRODUCT_NAME>.app
```

Pass that path to `session start --install`. Storing it in the session is what lets
`session clear` do a full uninstall + reinstall later.

## 5. Flavors and configurations

Multi-flavor apps usually carry one scheme per flavor and per-configuration
`PRODUCT_BUNDLE_IDENTIFIER` values. Confirm which scheme maps to which bundle id
with `-showBuildSettings` before installing, so the session's `--app-id` matches
what was actually built.

## Accessibility readiness

`ui find` selects by label and identifier. Before a UI-automation pass, check the
app exposes them:

- SwiftUI — `.accessibilityLabel("Log In")`, `.accessibilityIdentifier("login_button")`
- UIKit — `accessibilityLabel`, `accessibilityIdentifier`
- Flutter — `Semantics(label: ..., identifier: ...)`

An identifier is worth more than a label: it survives localization, so a selector
built on it does not break when the app is translated.

## Rules

- Never hard-code an Xcode, Swift, or iOS version as "current".
- Never modify signing settings, certificates, provisioning profiles, or
  entitlements as a side effect of a build or test task.
- Keep secrets out of logs: no keychain contents, API keys, or `.env` values.
- Prefer the repository's existing build entry point over inventing a new one.

## Related

- `ios-debugger-agent` — build, run, and gather evidence
- `mobile-session`, `mobile-screen`
- `project-router` — decide whether iOS skills are needed at all

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: mobile-flow
description: Author, validate, and run repeatable Flow v1 files for AI agents — strict YAML flows with exact selectors, polling assertions, single-fire mutations, failure classes, and per-run event evidence via the Autonom CLI.
---

# Mobile Flow (Android + iOS Simulator)

## Purpose

Turn a working journey into a **repeatable, reviewable flow file** — and run
it with exact semantics. A flow is strict YAML in the app repository
(conventionally `.autonom/flows/`, shared steps in `.autonom/subflows/`);
runtime artifacts land under `~/.autonom/sessions/<id>/flows/<run_id>/`.

The language refuses what it cannot execute exactly: unknown commands,
fuzzy-by-default matching, YAML cleverness (anchors, block scalars, tabs),
and implicit retries of mutating actions. Every rejection carries
`file:line:column` and a stable `error_code`. Full reference: `docs/FLOW.md`.

## CLI

```bash
# Validate (whole runFlow graph, no device needed)
python3 <autonom-root>/scripts/autonom.py flow check .autonom/flows
python3 <autonom-root>/scripts/autonom.py flow check login.yaml

# Canonical form — expands shorthand, materializes `match: exact`
python3 <autonom-root>/scripts/autonom.py flow fmt login.yaml --write
python3 <autonom-root>/scripts/autonom.py flow fmt .autonom/flows --check   # exit 1 = needs formatting
python3 <autonom-root>/scripts/autonom.py flow fmt login.yaml --write --drop-comments   # only when losing comments is intended

# Enumerate: file, id, name, tags, platforms
python3 <autonom-root>/scripts/autonom.py flow list

# Run (needs an active session — see mobile-session)
python3 <autonom-root>/scripts/autonom.py flow run login.yaml
python3 <autonom-root>/scripts/autonom.py flow run .autonom/flows --include-tag smoke --exclude-tag flaky
python3 <autonom-root>/scripts/autonom.py flow run login.yaml --secret TEST_PASSWORD --env LOCALE=en_US
python3 <autonom-root>/scripts/autonom.py flow run login.yaml --events     # NDJSON stream on stdout
python3 <autonom-root>/scripts/autonom.py flow run login.yaml --dry-run    # pre-flight only; top-level status "planned", `planned` list with runtime indexes

# Approve for promotion: N consecutive clean replays of the current bytes
python3 <autonom-root>/scripts/autonom.py teach approve login.yaml --run --minimum-runs 3 --secret TEST_PASSWORD --env LOCALE=en_US
```

`flow check` catches what used to fail only on the device: negative
`timeoutMs`/`delayMs`/`durationMs`/`maxSwipes`/`chars`, a latitude or
longitude out of range, an empty selector string, and a `match: regex`
pattern that does not compile (`timeoutMs: 0` is legal: one check). An
unknown command, argument, selector field, or match mode names its closest
legal spelling (`Did you mean 'tapOn'?`). `flow fmt --write` refuses with
`comments_would_be_lost` rather than silently dropping YAML comments; in a
directory nothing is written until every file is safe.

## A minimal flow

```yaml
schema: autonom.dev/flow/v1
appId: com.example.app
name: Login
tags: [smoke, auth]
---
- launchApp
- tapOn: Sign in
- inputText:
    value: ${TEST_EMAIL}
    sensitive: true
- assertVisible:
    selector:
      id: home_screen
    timeoutMs: 7000
```

`flow fmt` expands `- tapOn: Sign in` into the explicit selector form with
`match: exact`. Selectors: `id`, `text`, `description`, `role`, plus
`enabled`/`checked`/`selected` and `index`. **iOS puts the visible label in
`description`, not `text`** — cross-platform flows prefer `id`, then
`description`.

## Reading a run

- Exit `0`: passed. Exit `1`: a **test failure** — the app did not do what
  the flow asserts; the stdout summary carries `status: "failed"` and
  `failure.failure_class: "test_failure"`. Exit `2`: the flow or the
  machine is wrong (definition/infrastructure) — stderr envelope as usual.
- Assertions poll (default 10 s, per-step `timeoutMs`); mutating steps fire
  **exactly once** — a duplicate selector match refuses instead of tapping.
- Selectors match **on-screen** nodes onl

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: mobile-memory
description: Reuse and record per-app Autonom knowledge for device work. Read the app's overlay and flow runbooks before driving a device, and save a new flow only when it is durable, reusable, and evidence-backed. Triggers on a device task against a known app (a package/bundle id is in play), and after working out a repeatable procedure — make an order, mock a screen, log in, reproduce a bug.
---

# Mobile Memory

Per-app knowledge that a device task needs but the CLI cannot know: the backend,
how the app's network is wired, where its response schemas live, and step-by-step
flows worked out once and replayed after. It exists so the same hour of digging
is not spent twice.

## Where it lives

```
~/.autonom/apps/<package>/
  app.md              identity, backend, network model, TLS, schema roots, gotchas
  flows/<name>.md     a runbook: goal, endpoint, schema source, exact steps, verify
  bodies/<name>.json  ready mock payloads that flows reference
```

**Machine-local and per-person**, plain markdown — not in the app repo, not in
the Autonom repo. The same idea as a personal memory store: it accumulates as you
work and stays yours. The skill (this file) ships with Autonom; the knowledge
does not.

## Before a device task

1. Resolve the package id — from `--app-id`, the current session
   (`autonom session show`), or the repository under test.
2. Read `~/.autonom/apps/<package>/app.md` if it exists. It answers, up front,
   the questions that otherwise surface as wasted time: which backend, does the
   app cache the proxy, is `dart:io` even used, where are the schemas.
3. If the task matches a flow (mock a screen, make an order), read
   `flows/<name>.md` and follow it instead of re-deriving the endpoint, schema
   and gotchas.
4. Nothing there yet? Proceed normally — and consider leaving a flow behind when
   you crack something that will recur.

## When to save — and when not

Save **only** knowledge that is durable, reusable, and evidence-backed: the exact
endpoint, the exact glob, the path to the schema, the gotcha that cost time.
Prefer updating the existing file over adding a near-duplicate.

Do **not** save one-off exploration, obvious single commands, or anything already
in the code. **Never** write secrets — reference "log in as the test driver", not
an account or token. Keep each entry id-centric and concrete (`com.example.rides`,
`POST /api/v1/orders`, `lib/models/**/*_response.dart`), never vague.

A flow is worth a file when it is multi-step and will happen again. A single verb
is not a flow.

## Format

- **app.md** — identity (package, backend, build), how the network works (native
  vs `dart:io`, proxy caching), TLS/CA notes, where schemas live, a *known
  screens* table (screen → endpoint → flow), and gotchas already handled by the
  tool so a reader does not redo them.
- **flows/<name>.md** — Goal · Endpoint · Schema source · Steps (exact CLI) ·
  Verify · Gotchas. Reconstruct a response schema from the freezed model:
  `@JsonKey(name: ...)` is the JSON field, `required` without `?` is mandatory.
  These are prose runbooks — working knowledge. When one has become fully
  deterministic (stable selectors, no judgment calls), propose converting it
  into an Autonom Flow v1 file in the app repository (`mobile-flow`), which
  the CLI can then validate and replay exactly.
- **bodies/<name>.json** — a captured or hand-built payload a flow points at, so
  the shape is not rebuilt each time.

## How it connects

`project-router` detects the app → this skill loads its overlay and any matching
flow → the `mobile-session` / `mobile-screen` / `mobile-network` skills run the
CLI verbs → new knowledge is written back here. The knowledge layer sits beside
the thin verb-skills; it does not replace them.

## Related

- `project-router` — routes here once a device task targets a known app.
- `mobile-session`, `mobile-screen`, `mobile-network` — the verbs a flow drives.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: mobile-network
description: Inspect and mock a mobile app's HTTP(S) traffic for AI agents — start a localhost MITM proxy, attach a device with explicit consent, filter recorded requests, force responses, and export HAR without leaking credentials.
---

# Mobile Network (inspect and mock)

## Purpose

Answer **what did the app actually send and receive**, and **what does it do when
the server misbehaves**. Backed by mitmproxy, bound to localhost, scoped to one
Autonom session.

Use it when the task mentions an API, a request, a response, a status code, a
mock, a HAR, a proxy, or "why is this call failing".

## Before you start: this is privileged

Starting the proxy decrypts and records traffic. Attaching a device changes that
device's network configuration, and `--install-ca` writes to its trust store.
None of that happens without **explicit consent for that exact action**:

- every privileged verb requires its flag (`--i-understand-mitm`, plus
  `--install-ca` for a trust-store write);
- on an interactive terminal you must additionally type a confirmation phrase;
- consent is **never** cached — a grant earlier in the session does not carry to
  the next command;
- there is no environment variable or config file that grants it.

Only use this against devices and apps you own or are authorized to test.

## Workflow

```bash
# 1. Own a session first
python3 <autonom-root>/scripts/autonom.py session start --serial emulator-5554 --app-id com.example.app

# 2. Start the proxy (127.0.0.1 only; port is auto-chosen when omitted)
python3 <autonom-root>/scripts/autonom.py network start --i-understand-mitm

# 3. Point the device at it
python3 <autonom-root>/scripts/autonom.py network attach --i-understand-mitm

# 4. Exercise the app, then look
python3 <autonom-root>/scripts/autonom.py network requests list --path '*/login'
python3 <autonom-root>/scripts/autonom.py network requests list --host api.example.com --status 401
python3 <autonom-root>/scripts/autonom.py network requests show f_0003

# 5. Force a failure and check the UI reacts
python3 <autonom-root>/scripts/autonom.py network mock add \
  --match '*/v1/login' --method POST --status 500 \
  --body-file fixtures/login_error.json --header 'Content-Type: application/json'
python3 <autonom-root>/scripts/autonom.py ui tap --text "Log In"
python3 <autonom-root>/scripts/autonom.py ui find --text "Something went wrong"

# 6. Keep the evidence, then clean up
python3 <autonom-root>/scripts/autonom.py network export --har network/session.har
python3 <autonom-root>/scripts/autonom.py network mock disable --all
python3 <autonom-root>/scripts/autonom.py network detach
python3 <autonom-root>/scripts/autonom.py network stop
```

Step 6 uses `disable --all`, not `clear`: the registry is persistent, so `clear`
throws away rules you may want tomorrow. Use `clear` only to actually delete them.

`session stop` performs detach and stop best-effort anyway, in that order, so the
device is never left pointing at a dead proxy.

## Transparent capture on Android (no app change)

The workflow above sets the device's **global HTTP proxy** and trusts the CA in
the **user** store. That is enough for a native app with a debug
`network_security_config`, but it captures **nothing** from a Flutter app:
`dart:io` ignores the Android global proxy, and apps targeting API 24+ do not
trust user CAs. The fix routes the whole emulator through the proxy at launch and
puts the CA in the **system** store — with **zero changes to the app**:

`-http-proxy` is a **launch-time** flag, so pick the proxy port up front and pass
the *same* port to the boot and to `network start`. The emulator tolerates the
proxy being down at boot and connects once `network start` brings it up on that
fixed port. This is the exact order verified live on a rooted API 37 emulator:

```bash
# 1. Boot a dedicated, rootable AVD ROUTED through a chosen port (here 18091).
#    `-http-proxy` cannot be injected into an already-running emulator.
py

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: mobile-screen
description: Understand and control what is on an Android or iOS screen for AI agents using compact accessibility/UI trees, semantic find/tap, gestures, screenshots, and key/text input via the Autonom CLI.
---

# Mobile Screen (Android + iOS Simulator)

## Purpose

Answer **what is on screen** and **act on it** without relying on pixel-only guessing.

1. Prefer a **compact UI tree** (UI Automator on Android, accessibility tree via idb on iOS).
2. Confirm with a **screenshot** when visual layout matters or the tree is ambiguous.
3. Act with **semantic selectors** first; coordinates only as fallback.

The compact node schema is identical on both platforms, so the same reasoning works
either way. What differs is **which field carries the visible label** — see below.

## CLI

```bash
# Compact tree (meaningful nodes by default)
python3 <autonom-root>/scripts/autonom.py ui tree
python3 <autonom-root>/scripts/autonom.py --platform ios --target <UDID> ui tree
python3 <autonom-root>/scripts/autonom.py ui tree --format outline --interactable   # one indented line per actionable node

# Wait until the screen stops changing (animations, spinners, loading lists)
python3 <autonom-root>/scripts/autonom.py ui wait --settled --timeout-ms 5000       # settled, snapshots, changes, elapsed_ms; exit 1 if never settled

# Find
python3 <autonom-root>/scripts/autonom.py ui find --text "Login" --mode contains     # Android
python3 <autonom-root>/scripts/autonom.py ui find --desc "Log In" --mode exact       # iOS
python3 <autonom-root>/scripts/autonom.py ui find --resource-id com.apple.settings.general

# Act
python3 <autonom-root>/scripts/autonom.py ui tap --desc "Continue"
python3 <autonom-root>/scripts/autonom.py ui tap --x 540 --y 1600
python3 <autonom-root>/scripts/autonom.py ui type "user@example.com"
python3 <autonom-root>/scripts/autonom.py ui swipe --from 200,600 --to 200,200
python3 <autonom-root>/scripts/autonom.py ui key KEYCODE_BACK      # Android
python3 <autonom-root>/scripts/autonom.py ui key HOME              # iOS

# Evidence
python3 <autonom-root>/scripts/autonom.py screenshot --out /tmp/screen.png
python3 <autonom-root>/scripts/autonom.py record start --name login
python3 <autonom-root>/scripts/autonom.py record stop

# Offline parse of a dump (CI / fixtures) — the platform is detected from the file
python3 <autonom-root>/scripts/autonom.py ui tree --dump tests/fixtures/ui_dump.xml
python3 <autonom-root>/scripts/autonom.py ui tree --dump tests/fixtures/idb_describe_all_sample.json
```

## Compact node schema (identical on both platforms)

```json
{
  "ref": "n5",
  "role": "button",
  "text": null,
  "desc": "General",
  "resource_id": "com.apple.settings.general",
  "bounds": [16, 380, 386, 432],
  "clickable": true,
  "long_clickable": false,
  "checkable": false,
  "enabled": true
}
```

## Where the visible label lives

**This is the one asymmetry that matters.**

| Platform | Visible label lands in | Select with |
| --- | --- | --- |
| Android | `text` (and `desc` for content-description) | `--text`, `--desc`, `--resource-id` |
| iOS | **`desc`** (from `AXLabel`); `text` comes from `AXValue` and is often `null` | **`--desc`**, `--resource-id` |

On iOS a control labelled "General" has `desc: "General"` and `text: null`, so
`ui find --text "General"` returns **zero matches**. Read the tree first and select
by `--desc`, or by `--resource-id` when the app sets accessibility identifiers.
Flutter on Android puts its labels in `desc` (content-description) too. On both
platforms, when a `--text` miss would have matched a `desc`, the response says so
with a `label_is_in_desc` warning whose hint is the `--desc` retry. A `ui find` or
`ui tap` with no selector at all is `selector_required`. Whitespace is normalised
(iOS joins a merged Flutter label with a newline, Android with a space), except
in `--mode regex`.

## What is on screen, and which match is picked

iOS lists Flutter's scroll cache — nodes laid out but

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: mobile-session
description: Own an explicit Android device or iOS simulator session for AI agents — list targets, start Autonom session artifacts, install/launch/force-stop/clear apps, and stop cleanly with evidence directories.
---

# Mobile Session (Android + iOS Simulator)

## Purpose

Give the agent a **single explicit target** and an artifact directory before UI,
log, or network work. Prefer this skill over ad-hoc `adb` or `simctl` when testing
or debugging.

One verb set covers both platforms. `--serial` remains a permanent Android alias
of `--target`, so existing Android workflows are unchanged.

## CLI entrypoint

```bash
python3 <autonom-root>/scripts/autonom.py devices          # Android + iOS in one list
python3 <autonom-root>/scripts/autonom.py doctor           # what this machine can actually do
```

Each device carries `running` (true when Booted / `device`), so you can tell a
live target from a cold one without knowing each platform's wording. The
Android listing also reports `avds` (bootable emulator images not yet started)
and `avd_profiles` — each AVD's hardware profile, screen size and density, and
API level read from its `config.ini` — so "the phone-sized emulator" is a
lookup, not a guess from the name. A running emulator names the `avd` it
booted from.

`doctor` lists every active `AUTONOM_*` override under `overrides` and warns
with `override_path_missing` when one points at a binary that does not exist —
the usual reason a tool reads as missing while `which` finds it.

### Boot and shut down a target

```bash
python3 <autonom-root>/scripts/autonom.py devices boot --avd Pixel_9      # start an Android emulator, wait for boot
python3 <autonom-root>/scripts/autonom.py devices boot --udid <UDID>      # boot an iOS simulator
python3 <autonom-root>/scripts/autonom.py devices shutdown --serial emulator-5554
python3 <autonom-root>/scripts/autonom.py devices shutdown --udid <UDID>
```

`boot --avd` waits for `sys.boot_completed` and returns the serial it came up
as (`--no-wait` to skip the wait). `session start` still boots a shutdown
simulator on its own, so `devices boot` is only needed to start an Android
emulator up front or to pre-warm a target. `shutdown` refuses any serial that
is not `emulator-<port>` — it never powers off physical hardware.

An emulator started by `devices boot` is registered as **harness-owned**:
`doctor` does not list it as an orphan while it runs, and `devices shutdown`
releases its registry entry, so no stale process warning follows.

### Android

```bash
python3 <autonom-root>/scripts/autonom.py session start --serial emulator-5554 --app-id com.example.app
python3 <autonom-root>/scripts/autonom.py session launch com.example.app            # resume where it was
python3 <autonom-root>/scripts/autonom.py session launch com.example.app --fresh    # launcher activity on a cleared task
python3 <autonom-root>/scripts/autonom.py session launch com.example.app --fresh --activity .MainActivity
python3 <autonom-root>/scripts/autonom.py session force-stop com.example.app
python3 <autonom-root>/scripts/autonom.py session clear com.example.app
python3 <autonom-root>/scripts/autonom.py session stop
```

### iOS Simulator

```bash
python3 <autonom-root>/scripts/autonom.py session start \
  --platform ios --target <UDID> \
  --install build/ios/iphonesimulator/Runner.app \
  --launch --app-id com.example.app --log-stream

python3 <autonom-root>/scripts/autonom.py session launch com.example.app --setenv FLAVOR=staging
python3 <autonom-root>/scripts/autonom.py session force-stop com.example.app
python3 <autonom-root>/scripts/autonom.py session stop
```

Target flags work before or after the subcommand. A shutdown simulator is booted
automatically and the response reports `"booted": true` when this call did it.
The response also says what `--install` and `--launch` did: `installed`
(true/false) and `launched` (`null`, or the app id with the iOS `pid` / the
Android `am start -W` report: `mode

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: project-router
description: Route Flutter, native Android, native iOS, and device test/debug tasks to the smallest relevant Autonom skill set after inspecting the repository stack and runtime boundary.
---

# Project Router

## Purpose

For the whole-system map — what Autonom can do, how it works, the end-to-end
device loop — read the `autonom` skill first. This router is the dispatcher that
narrows that map to the smallest stack-specific skill set for the task at hand.

Classify the repository and task before changing code or driving a device.
A Flutter app contains `pubspec.yaml` with a Flutter SDK dependency. A native
Android project normally starts from Gradle settings and Android modules. A native
iOS project starts from `*.xcodeproj`, `*.xcworkspace`, or `Package.swift`.
Hybrid repositories can contain several, so route by the layer being changed.

For **runtime QA / UI debug** on a device, emulator, or simulator, load
`mobile-session` and `mobile-screen` (Autonom CLI) in addition to the
stack-specific debugger. Load `mobile-network` when the task mentions an API,
request, response, mock, HAR, proxy, or "why is this call failing". Load
`mobile-flow` when the task mentions a repeatable flow, regression check,
smoke suite, replaying a journey, or a `.yaml` flow file.

Once the target app is known (a package/bundle id is in play), load
`mobile-memory` and read `~/.autonom/apps/<package>/app.md` and any matching
`flows/` runbook **before** driving the device — it carries the backend, network
model, schema locations, and step-by-step flows worked out on earlier runs, so
the same digging is not repeated. Record a new flow there only when it is
durable, reusable, and evidence-backed.

Use the repository-selected Flutter SDK for executable commands. When selection
is ambiguous or FVM is pinned, resolve it without silently falling back:

```bash
python3 <marketplace-root>/scripts/flutter_exec.py --root . -- --version
```


## Routing workflow

1. Inspect repository documentation and the project root.
2. Run the shared toolchain snapshot when build layout or SDK state is unclear:

   ```bash
   python3 <plugin-root>/../../scripts/toolchain_snapshot.py . --execute
   ```

3. Detect the primary path:

   - Flutter feature, Dart code, widgets, navigation, tests, or package work:
     load the relevant `flutter-*` skills.
   - Android manifest, Gradle, Kotlin, platform channels, app links,
     notifications, permissions, or plugin native code inside a Flutter app:
     load `flutter-android-platform` plus the narrow Android skill.
   - Pure Kotlin or Compose project: load the native Android/Compose skills.
   - `*.xcodeproj`, `*.xcworkspace`, `Package.swift`, or work inside a Flutter
     app's `ios/` directory (plist, capabilities, Swift/Obj-C module, signing
     configuration): load `ios-project-setup`, and `ios-debugger-agent` when the
     app must actually run.
4. Load runtime skills only when device evidence is required:
   - session + screen: `mobile-session`, `mobile-screen` via `scripts/autonom.py`
   - per-app knowledge and flows: `mobile-memory` (read `~/.autonom/apps/<package>/`)
   - deeper debug: `android-debugger-agent` / `ios-debugger-agent` / `flutter-debugger-agent`
   - network inspect or mock: `mobile-network`
   - visual mirror: `android-emulator-browser`
5. When the machine's capabilities are unclear, run
   `python3 <autonom-root>/scripts/autonom.py doctor` — it reports which platforms
   are usable and what is missing, instead of discovering it mid-task.
6. Do not load every skill pre-emptively; progressive loading keeps the task
   focused.

## Default verification ladder

For Flutter:

```bash
flutter pub get
dart format --output=none --set-exit-if-changed <changed-paths>
flutter analyze <changed-paths-or-project>
flutter test <narrow-test-path>
```

For native Android:

```bash
./gradlew <narrow-task> --console=plain
```

Broaden checks when shared architecture, generated code, Gradle configurati

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: toolchain-doctor
description: Inspect Flutter, Dart, Gradle, Android Gradle Plugin, Kotlin, SDK levels, Java, adb devices, and repository-pinned toolchain configuration without asserting stale latest versions.
---

# Toolchain Doctor

Use before project creation, SDK upgrades, Gradle migrations, broken builds, or
any claim about installed tool versions.

## Snapshot

```bash
python3 <repository-or-plugin-root>/scripts/toolchain_snapshot.py . --execute --json
```

Declarations first; optional local command execution. Never labels a version as
“latest”. Re-check `references/official-sources.md` for migrations.

## Read before editing

- `pubspec.yaml`, `.fvmrc`, `.fvm/`, `analysis_options.yaml`
- Android Gradle settings/modules, catalogs, wrapper, `gradle.properties`
- CI scripts and documented commands
- `flutter --version --machine`, `flutter doctor -v`, `dart --version`
- `./gradlew --version`, `java -version`, `adb devices -l`

Prefer `fvm flutter` when the repo is FVM-pinned and `fvm` is available.

## Policy

- Re-check official docs for version-sensitive work.
- Keep toolchain migrations separate from feature work.
- Do not paste a generic template over a live project.
- Do not upgrade the world to fix one conflict.
- Report exact observed versions and the compatibility error text.

Referenced files: 2 — file references are metadata, not package contents.