Add portable mobile app testing guidance

.agents/skills/ios-debugger-agent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.agents/skills/ios-debugger-agent/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ios-debugger-agent
+description: Build, launch, inspect, and drive iOS apps with the repository-configured XcodeBuildMCP server. Use on macOS for iOS Simulator builds, focused native test runs, semantic UI automation, screenshots, logs, or debugging, including T3 Code Mobile verification.
+---
+
+# iOS Debugger Agent
+
+Use the repository-configured `xcodebuildmcp` tools instead of requiring a globally installed Codex plugin. Prefer MCP tools over raw `xcodebuild`, `xcrun`, or `simctl` when the client exposes them.
+
+## Confirm availability
+
+This workflow requires macOS 14.5 or newer, Xcode 16 or newer, and Node.js 18 or newer. The repository pins XcodeBuildMCP in both `.mcp.json` for Claude Code and `.codex/config.toml` for Codex. Project MCP servers may require one-time trust or approval followed by a new session.
+
+If the tools are missing:
+
+1. Confirm the repository is trusted and its project MCP server was approved.
+2. Restart or recreate the agent session after approving configuration.
+3. Run `npx --yes xcodebuildmcp@2.6.2 doctor` when the server starts but simulator or UI-automation tools are unavailable. Follow its actionable Xcode or AXe setup guidance.
+4. Fall back to the pinned XcodeBuildMCP CLI or native Apple CLIs only when the current agent client cannot expose project MCP tools.
+
+Do not ask contributors to install the OpenAI `build-ios-apps` plugin globally.
+
+## Establish one simulator context
+
+1. Call `session_show_defaults` before discovery, build, launch, or UI work.
+2. Call `list_sims` and select one explicit simulator UDID. Prefer a simulator that is already booted; boot an installed simulator when verification requires it, but do not create or download runtimes without user authorization.
+3. Call `session_set_defaults` with the project or workspace, scheme, Debug configuration, simulator ID, and bundle identifier when known.
+4. Keep every subsequent build, launch, screenshot, log capture, and UI action pinned to that same UDID.
+
+Avoid generic Mac window automation for switching among Simulator windows. Explicit device identity is more reliable.
+
+## Choose build or launch
+
+- Use `build_run_sim` when native source, native dependencies, entitlements, or project configuration changed.
+- Use `test_sim` for the smallest relevant native test target or test cases; do not run an entire workspace test matrix routinely.
+- Use `launch_app_sim` when a compatible app is already installed and no native rebuild is needed.
+- To reuse an existing build artifact, use `get_sim_app_path` or `get_app_bundle_id`, install it with `install_app_sim` when necessary, and then launch it.
+- Do not run a build-only action immediately before `build_run_sim` unless the task requires both artifacts.
+
+After launch, call `snapshot_ui` or `screenshot` before interacting. An open Simulator window alone is not evidence that the intended app launched.
+
+## Drive the UI semantically
+
+1. Call `snapshot_ui` to obtain the current accessibility hierarchy and element references.
+2. Use only current `elementRef` values whose snapshot entries list the intended action. XcodeBuildMCP `2.6.2` does not accept coordinates for `tap`; when the app exposes no actionable reference, prefer a registered deep link or another app-supported route and otherwise report the accessibility blocker.
+3. Refresh with `snapshot_ui` after navigation or layout changes. Element references are snapshot-specific.
+4. Use `wait_for_ui` for asynchronous transitions when available rather than fixed sleeps.
+5. Capture a final `screenshot` for the state that proves the affected flow.
+
+Use `gesture` or scoped swipe actions when needed. If a gesture is unreliable, return to a known route or relaunch rather than switching to generic desktop automation.
+
+## Capture logs and debug
+
+- Use `start_sim_log_cap` and `stop_sim_log_cap` with the exact bundle identifier for focused runtime logs.
+- Use debugger tools only when the task requires runtime diagnosis; attach to the selected simulator and app rather than an ambiguous process.
+- Summarize relevant errors instead of returning unbounded logs.
+
+## Clean up
+
+Stop only log captures, debugger sessions, apps, or simulators started for the current test. Leave pre-existing simulators and unrelated sessions alone.
+
+## Upstream
+
+Adapted from OpenAI's [`build-ios-apps`](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) plugin version `0.1.2` (`ios-debugger-agent`, MIT) and aligned with XcodeBuildMCP `2.6.2` tool names.

.agents/skills/ios-debugger-agent/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "iOS Debugger Agent"
+  short_description: "Build and drive iOS Simulator apps"
+  default_prompt: "Use $ios-debugger-agent to build, launch, and inspect the current iOS app on Simulator."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "xcodebuildmcp"
+      description: "Repository-configured Xcode build, simulator, logging, debugging, and semantic UI tools"

.agents/skills/ios-simulator-browser/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.agents/skills/ios-simulator-browser/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ios-simulator-browser
+description: Stream an explicit iOS Simulator through pinned serve-sim into the T3 Code in-app browser or another agent browser. Use on Apple Silicon macOS when the user should watch simulator verification live or when browser-visible simulator evidence is needed.
+---
+
+# iOS Simulator Browser
+
+Use serve-sim as the shared visual feed for an iOS Simulator. Use `ios-debugger-agent` and XcodeBuildMCP semantic UI tools to drive the app; do not treat browser-canvas coordinates as a substitute for missing app accessibility.
+
+## Confirm availability
+
+serve-sim `0.1.45` requires Apple Silicon macOS, Xcode command-line tools, and Node.js 20 or newer. If the host is unsupported, continue with XcodeBuildMCP screenshots and report that live streaming was unavailable.
+
+When running inside T3 Code, use its product-native browser MCP to open the stream. Other agent hosts may use their own browser or preview surface.
+
+Keep serve-sim on its default `127.0.0.1` binding. Do not expose its preview to a LAN or tunnel unless the user explicitly requests that access and the network is trusted; the preview includes a token-gated shell-execution route.
+
+## Start one owned stream
+
+1. Obtain the exact simulator UDID from the iOS build or launch workflow.
+2. Check whether an existing serve-sim stream for that UDID belongs to another task. Reuse it only when explicitly shared; never kill another task's stream.
+3. Otherwise, clear only a stale stream for that UDID and start the pinned version with scoped cleanup:
+
+   ```bash
+   SIMULATOR_ID=<simulator-udid>
+   cleanup_serve_sim() {
+     npx --yes serve-sim@0.1.45 --kill "$SIMULATOR_ID" >/dev/null 2>&1 || true
+   }
+   trap cleanup_serve_sim EXIT INT TERM HUP
+   cleanup_serve_sim
+   npx --yes serve-sim@0.1.45 "$SIMULATOR_ID"
+   ```
+
+4. Keep the terminal alive and open the exact local URL printed by serve-sim in the agent's browser.
+5. Verify that a live simulator frame renders. A loaded wrapper page is not sufficient evidence.
+
+## Observe while driving semantically
+
+- Let the user watch the serve-sim stream while XcodeBuildMCP performs `snapshot_ui`, semantic taps, typing, gestures, and screenshots.
+- Keep the browser and Xcode tooling pinned to the same simulator UDID.
+- Do not switch to generic desktop automation or browser-canvas clicking merely because the stream is visible.
+
+If the in-app browser explicitly reports that previews are unavailable, do not install unrelated browser automation. Continue through XcodeBuildMCP, capture a simulator screenshot, report the unavailable live stream, and clean up the owned serve-sim process.
+
+## Finish
+
+Stop the long-running terminal and wait for its cleanup trap to finish. If it disappeared without cleanup, run `npx --yes serve-sim@0.1.45 --kill <simulator-udid>` for that exact simulator. Never run an unscoped `--kill`.
+
+## Upstream
+
+Adapted from OpenAI's [`build-ios-apps`](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) plugin version `0.1.2` (`ios-simulator-browser`, MIT). It invokes serve-sim `0.1.45` under its Apache-2.0 license without vendoring the package.

.agents/skills/ios-simulator-browser/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "iOS Simulator Browser"
+  short_description: "Stream iOS Simulator in the browser"
+  default_prompt: "Use $ios-simulator-browser to stream the selected iOS Simulator into the T3 Code in-app browser."

.agents/skills/test-t3-app/SKILL.md

@@ -5,6 +5,8 @@ description: Launch and test the T3 Code web app in isolated development environ
 
 # Test T3 App
 
+Use this skill for the web client. For iOS Simulator, Android Emulator, or physical-device testing against an isolated T3 backend, use the sibling [`test-t3-mobile`](../test-t3-mobile/SKILL.md) skill.
+
 ## Start an isolated web environment
 
 1. Run commands from the repository root.