--- description: "Mobile UI Bug Hunter - iOS Simulator (simctl) + Android Emulator (adb) - auto-detects platform" allowed-tools: Agent, Bash, Read, Write, Edit, TaskCreate, TaskUpdate, TaskList, TaskGet, mcp__multi-agent-toolkit__ios_list_devices, mcp__multi-agent-toolkit__ios_boot_device, mcp__multi-agent-toolkit__ios_screenshot, mcp__multi-agent-toolkit__ios_tap, mcp__multi-agent-toolkit__ios_swipe, mcp__multi-agent-toolkit__ios_type_text, mcp__multi-agent-toolkit__ios_launch_app, mcp__multi-agent-toolkit__ios_terminate_app, mcp__multi-agent-toolkit__ios_list_apps, mcp__multi-agent-toolkit__ios_go_home, mcp__multi-agent-toolkit__ios_set_appearance, mcp__multi-agent-toolkit__ios_set_content_size, mcp__multi-agent-toolkit__ios_set_locale, mcp__multi-agent-toolkit__ios_open_url, mcp__multi-agent-toolkit__ios_status_bar, mcp__multi-agent-toolkit__ios_push_notification, mcp__multi-agent-toolkit__ios_grant_permission, mcp__multi-agent-toolkit__ios_revoke_permission, mcp__multi-agent-toolkit__ios_reset_permissions, mcp__multi-agent-toolkit__ios_set_location, mcp__multi-agent-toolkit__ios_clear_location, mcp__multi-agent-toolkit__ios_set_increase_contrast, mcp__multi-agent-toolkit__ios_record_video, mcp__multi-agent-toolkit__ios_add_media, mcp__multi-agent-toolkit__ios_keychain_reset, mcp__multi-agent-toolkit__ios_get_app_container, mcp__multi-agent-toolkit__ios_erase_device, mcp__multi-agent-toolkit__ios_get_ui_tree, mcp__multi-agent-toolkit__android_list_devices, mcp__multi-agent-toolkit__android_screenshot, mcp__multi-agent-toolkit__android_tap, mcp__multi-agent-toolkit__android_swipe, mcp__multi-agent-toolkit__android_type_text, mcp__multi-agent-toolkit__android_key_event, mcp__multi-agent-toolkit__android_launch_app, mcp__multi-agent-toolkit__android_stop_app, mcp__multi-agent-toolkit__android_list_packages, mcp__multi-agent-toolkit__android_go_home, mcp__multi-agent-toolkit__android_go_back, mcp__multi-agent-toolkit__android_get_ui_tree, mcp__multi-agent-toolkit__android_set_dark_mode, mcp__multi-agent-toolkit__android_set_font_scale, mcp__multi-agent-toolkit__android_set_locale, mcp__multi-agent-toolkit__android_set_location, mcp__multi-agent-toolkit__android_grant_permission, mcp__multi-agent-toolkit__android_revoke_permission, mcp__multi-agent-toolkit__android_record_screen, mcp__multi-agent-toolkit__android_install_apk, mcp__multi-agent-toolkit__android_uninstall_app, mcp__multi-agent-toolkit__android_logcat, mcp__multi-agent-toolkit__android_get_screen_size, mcp__multi-agent-toolkit__android_open_url, mcp__multi-agent-toolkit__android_clear_app_data --- # Mobile UI Bug Hunter Auto-detects platform: iOS (simctl) or Android (adb). No external apps needed. - **iOS**: Xcode + Simulator - **Android**: Android SDK + Emulator (or physical device via USB) > **Note**: Tool names above assume MCP server is registered as `multi-agent-toolkit`. If you used a different name in your settings.json, update the `allowed-tools` list accordingly. ## Platform Detection ``` 1. Check cwd for .xcodeproj / Package.swift -> iOS 2. Check cwd for build.gradle / build.gradle.kts -> Android 3. Check running devices: simctl list booted / adb devices 4. If both available -> ask user which platform 5. If argument contains "android" or "ios" -> use that ``` For iOS: use `mcp__multi-agent-toolkit__ios_*` tools For Android: use `mcp__multi-agent-toolkit__android_*` tools **Android extras**: `get_ui_tree` returns XML with bounds/text/resource-id (uiautomator dump), `logcat` for crash detection, `go_back` button. ## Activation ``` /multi-agent test -> full app test /multi-agent test "dark mode" -> dark mode bug test /multi-agent test "accessibility" -> accessibility audit (visual + MCP audit tool) /multi-agent test "dynamic type" -> large text test /multi-agent test "screenshot tr" -> locale screenshots /multi-agent test "store-ready" -> hands off to /multi-agent:store-ready (package validation) /sim-test -> standalone (same thing) ``` Not offered, deliberately - `"biometric"` and `"performance"` were listed here with no implementation section, so reaching one fell through to the general sweep and got reported as the scenario asked for. Neither can be implemented symmetrically today: biometric has an iOS tool (`ios_biometric`) and no Android counterpart, and launch timing has `android_launch_time` and no iOS counterpart. Platform is auto-detected, so either one would work on one platform and silently do nothing on the other. They come back when the missing side exists, not before - do not re-add the rows to make the list look complete. Four scenarios also have a fixed-scenario command that pins the tag, so it does not have to be typed or quoted. They arrive here with the scenario already resolved - treat them as identical to the quoted form: ``` /multi-agent:test-dark-mode -> scenario "dark mode" /multi-agent:test-accessibility -> scenario "accessibility" /multi-agent:test-dynamic-type -> scenario "dynamic type" /multi-agent:test-screenshots [locale] -> scenario "screenshot ", locale defaults to tr ``` `store-ready` is not one of them, and does not belong to this file at all: it validates a built package on either platform and lives at `/multi-agent:store-ready`. The `"store-ready"` tag is kept as a hand-off so an existing invocation still lands somewhere correct. `/multi-agent:testflight-validation` is the iOS-pinned alias of that same command. ## Flow ### Step 1 - Device & App Discovery ``` Call: ios_list_devices (or android_list_devices) -> If no booted simulator: ask user which to boot, call ios_boot_device -> If booted: auto-select Call: ios_list_apps -> Auto-detect bundle_id from cwd project (xcodebuild -showBuildSettings | PRODUCT_BUNDLE_IDENTIFIER) -> Or ask user to pick from installed apps Call: ios_launch_app (bundle_id) -> Wait 2 seconds for app to load ``` ### Step 2 - Clean Status Bar (for screenshots) ``` Call: ios_status_bar (time: "09:41", battery_level: 100) ``` ### Step 3 - Systematic Screen Exploration For each screen in the app: ``` Call: ios_screenshot -> Claude analyzes the image for bugs (see Bug Detection below) Call: ios_tap (on each tab bar item, button, navigation link) -> After each tap: ios_screenshot -> analyze -> Navigate back: ios_swipe (left edge swipe) or tap back button coordinates ``` **Navigation strategy:** 1. Screenshot initial screen -> identify tab bar (usually bottom ~680-700y area) 2. Tap each tab position -> screenshot each 3. On each screen: tap interactive elements -> screenshot results 4. Scroll: `ios_swipe(200, 600, 200, 200)` to scroll down -> screenshot 5. Type in text fields: `ios_type_text("test input")` ### Step 4 - Variant Testing (based on input argument) **"dark mode":** ``` Call: ios_set_appearance("dark") -> Re-navigate all screens, screenshot each Call: ios_set_appearance("light") // reset ``` **"dynamic type":** ``` Call: ios_set_content_size("extra-extra-extra-large") -> Re-navigate, screenshot Call: ios_set_content_size("accessibility-extra-large") -> Re-navigate, screenshot Call: ios_set_content_size("medium") // reset ``` **"accessibility":** - Check each screenshot for: small tap targets, missing labels, poor contrast - Verify minimum 44x44pt touch areas - Check text readability at default + large sizes **"screenshot ":** ``` Call: ios_set_locale(language: "", bundle_id: "...") -> Navigate all screens, screenshot each -> Great for App Store screenshot generation ``` **"store-ready":** Not implemented here. `store-ready` validates a built **package**, which is a different job from driving a running app, and it is owned by one command on both platforms: ``` $HOME/.claude/commands/multi-agent/store-ready/SKILL.md ``` Read that file and follow it. Pass through any artifact path given after `store-ready` as its `--archive=` / `--ipa=` / `--aab=` / `--apk=` input. Its Step A is the visual + accessibility sweep in this file - it calls back here for the running-app half, then runs three gates per platform that nothing in this file can do: the static package audit, the store's own validator, and a policy review against repo source. It merges both halves into one severity-grouped report and offers the `/multi-agent:channels` follow-up. The archive-compliance audit used to be duplicated here, invoking `ios_app_store_audit` with exactly the arguments the store-ready command's Gate 1 uses. Two copies of one call is how the iOS path grew a second door with no Gate 2, no Gate 3 and no Android parity, so the copy is gone rather than kept in sync. **No argument (full test):** - Run light mode -> all screens - Run dark mode -> all screens - Run large text -> all screens - Compile complete report ### Step 5 - Bug Detection (on EVERY screenshot) When analyzing each screenshot, check for: | Category | What to Look For | | ---------------- | ------------------------------------------------------------------------------------ | | **Layout** | Overlapping elements, truncated text, off-screen content, broken alignment | | **Visual** | Wrong colors, missing images, placeholder text ("Lorem ipsum"), inconsistent spacing | | **Dark Mode** | Text invisible on dark background, hardcoded white/black, wrong tint colors | | **Typography** | Text overflow at large sizes, unreadable small text, line height issues | | **Navigation** | Missing back button, dead-end screens, broken tab bar | | **State** | Empty state without message, loading spinner stuck, error state visible | | **Localization** | Untranslated strings, text clipping in long translations | | **Interaction** | Button didn't respond (before/after screenshots identical after tap) | ### Step 6 - Report Create tasks for each bug found: ``` TaskCreate("BUG: [severity] title", "Screen: X, Category: Y, Steps: ...", activeForm: "Found bug...") ``` Then output full report: ```markdown # Simulator UI Test Report **App**: {bundle_id} **Device**: {device_name} (iOS {version}) **Date**: {timestamp} **Mode**: {full / dark mode / accessibility / screenshot} ## Bugs Found ({N} total) ### BUG-1: [{Critical/Major/Minor}] {title} - **Screen**: {which screen} - **Category**: Layout / Dark Mode / Typography / Navigation - **Steps**: 1. Open app -> 2. Tap {X} -> 3. Observe {issue} - **Expected**: {correct behavior} - **Actual**: {what's wrong} ### BUG-2: ... ## Screens Visited ({N}) | # | Screen | Light | Dark | Large Text | Bugs | | --- | -------- | ----- | ----- | ---------- | ---- | | 1 | Home | ok | BUG-1 | ok | 1 | | 2 | Login | ok | ok | BUG-2 | 1 | | 3 | Settings | ok | ok | ok | 0 | ## Summary - Screens tested: {N} - Clean: {N} - With bugs: {N} - Critical: {N} | Major: {N} | Minor: {N} ``` Save to: `$HOME/.claude/logs/sim-test/{bundle_id}/{timestamp}.md` ### Step 7 - Fix Offer After report is complete, if bugs were found: ``` {N} bug(s) found. Want me to fix them? y -> Create fix tasks, start fixing (reads source code, applies changes) n -> Report saved, you can review and fix manually pick -> Show bug list, user picks which to fix ``` If user says yes: 1. For each bug, locate the relevant View file 2. Analyze the screenshot + bug description 3. Apply the fix (color, padding, font, constraint, etc.) 4. Re-run screenshot on that screen to verify fix 5. Show before/after comparison ### Step 8 - Cleanup ``` Call: ios_set_appearance("light") Call: ios_set_content_size("medium") Call: ios_status_bar (clear override) ```