Skip to content

Commit e2f8d52

Browse files
Merge branch 'main' into fix/opencode-health-check-cli
2 parents f311ca6 + 08993a5 commit e2f8d52

68 files changed

Lines changed: 8088 additions & 1423 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) OpenAI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
name: ios-debugger-agent
3+
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.
4+
---
5+
6+
# iOS Debugger Agent
7+
8+
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.
9+
10+
## Confirm availability
11+
12+
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.
13+
14+
If the tools are missing:
15+
16+
1. Confirm the repository is trusted and its project MCP server was approved.
17+
2. Restart or recreate the agent session after approving configuration.
18+
3. Run `npx --yes [email protected] doctor` when the server starts but simulator or UI-automation tools are unavailable. Follow its actionable Xcode or AXe setup guidance.
19+
4. Fall back to the pinned XcodeBuildMCP CLI or native Apple CLIs only when the current agent client cannot expose project MCP tools.
20+
21+
Do not ask contributors to install the OpenAI `build-ios-apps` plugin globally.
22+
23+
## Establish one simulator context
24+
25+
1. Call `session_show_defaults` before discovery, build, launch, or UI work.
26+
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.
27+
3. Call `session_set_defaults` with the project or workspace, scheme, Debug configuration, simulator ID, and bundle identifier when known.
28+
4. Keep every subsequent build, launch, screenshot, log capture, and UI action pinned to that same UDID.
29+
30+
Avoid generic Mac window automation for switching among Simulator windows. Explicit device identity is more reliable.
31+
32+
## Choose build or launch
33+
34+
- Use `build_run_sim` when native source, native dependencies, entitlements, or project configuration changed.
35+
- Use `test_sim` for the smallest relevant native test target or test cases; do not run an entire workspace test matrix routinely.
36+
- Use `launch_app_sim` when a compatible app is already installed and no native rebuild is needed.
37+
- 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.
38+
- Do not run a build-only action immediately before `build_run_sim` unless the task requires both artifacts.
39+
40+
After launch, call `snapshot_ui` or `screenshot` before interacting. An open Simulator window alone is not evidence that the intended app launched.
41+
42+
## Drive the UI semantically
43+
44+
1. Call `snapshot_ui` to obtain the current accessibility hierarchy and element references.
45+
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.
46+
3. Refresh with `snapshot_ui` after navigation or layout changes. Element references are snapshot-specific.
47+
4. Use `wait_for_ui` for asynchronous transitions when available rather than fixed sleeps.
48+
5. Capture a final `screenshot` for the state that proves the affected flow.
49+
50+
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.
51+
52+
## Capture logs and debug
53+
54+
- Use `start_sim_log_cap` and `stop_sim_log_cap` with the exact bundle identifier for focused runtime logs.
55+
- Use debugger tools only when the task requires runtime diagnosis; attach to the selected simulator and app rather than an ambiguous process.
56+
- Summarize relevant errors instead of returning unbounded logs.
57+
58+
## Clean up
59+
60+
Stop only log captures, debugger sessions, apps, or simulators started for the current test. Leave pre-existing simulators and unrelated sessions alone.
61+
62+
## Upstream
63+
64+
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.
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
interface:
2+
display_name: "iOS Debugger Agent"
3+
short_description: "Build and drive iOS Simulator apps"
4+
default_prompt: "Use $ios-debugger-agent to build, launch, and inspect the current iOS app on Simulator."
5+
dependencies:
6+
tools:
7+
- type: "mcp"
8+
value: "xcodebuildmcp"
9+
description: "Repository-configured Xcode build, simulator, logging, debugging, and semantic UI tools"
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) OpenAI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
name: ios-simulator-browser
3+
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.
4+
---
5+
6+
# iOS Simulator Browser
7+
8+
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.
9+
10+
## Confirm availability
11+
12+
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.
13+
14+
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.
15+
16+
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.
17+
18+
## Start one owned stream
19+
20+
1. Obtain the exact simulator UDID from the iOS build or launch workflow.
21+
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.
22+
3. Otherwise, clear only a stale stream for that UDID and start the pinned version with scoped cleanup:
23+
24+
```bash
25+
SIMULATOR_ID=<simulator-udid>
26+
cleanup_serve_sim() {
27+
npx --yes [email protected] --kill "$SIMULATOR_ID" >/dev/null 2>&1 || true
28+
}
29+
trap cleanup_serve_sim EXIT INT TERM HUP
30+
cleanup_serve_sim
31+
npx --yes [email protected] "$SIMULATOR_ID"
32+
```
33+
34+
4. Keep the terminal alive and open the exact local URL printed by serve-sim in the agent's browser.
35+
5. Verify that a live simulator frame renders. A loaded wrapper page is not sufficient evidence.
36+
37+
## Observe while driving semantically
38+
39+
- Let the user watch the serve-sim stream while XcodeBuildMCP performs `snapshot_ui`, semantic taps, typing, gestures, and screenshots.
40+
- Keep the browser and Xcode tooling pinned to the same simulator UDID.
41+
- Do not switch to generic desktop automation or browser-canvas clicking merely because the stream is visible.
42+
43+
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.
44+
45+
## Finish
46+
47+
Stop the long-running terminal and wait for its cleanup trap to finish. If it disappeared without cleanup, run `npx --yes [email protected] --kill <simulator-udid>` for that exact simulator. Never run an unscoped `--kill`.
48+
49+
## Upstream
50+
51+
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.
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "iOS Simulator Browser"
3+
short_description: "Stream iOS Simulator in the browser"
4+
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‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: Launch and test the T3 Code web app in isolated development environ
55

66
# Test T3 App
77

8+
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.
9+
810
## Start an isolated web environment
911

1012
1. Run commands from the repository root.

0 commit comments

Comments
 (0)