Durable PR monitoring with feedback delivery and fallback ownership

.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

@@ -0,0 +1,90 @@
+---
+name: test-t3-app
+description: Launch, retain, and test the T3 Code web app in isolated development environments, including first-try browser authentication with one-time pairing URLs, pairing-token recovery, worktree-safe state directories, cross-turn dev server lifecycle, and direct SQLite inspection or fixture seeding. Use when an agent needs to run T3 locally, iteratively test UI behavior with a human, recover from an expired or consumed pairing token, isolate dev state, or prepare test data in state.sqlite.
+---
+
+# 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.
+2. Choose a base directory that belongs only to the current worktree or test:
+   - Use the repository's ignored `.t3` directory for reusable worktree-local state.
+   - Use `mktemp -d /tmp/t3code-test.XXXXXX` for disposable state and retain the printed absolute path.
+3. Start the full web stack with `vp run dev`. Add `--share` when the user needs to open it from another tailnet device. In a linked worktree it defaults to that worktree's gitignored `.t3`; pass `--home-dir <base-dir>` only when the test needs a different isolated directory.
+4. Keep the terminal session alive and read the selected server port, web port, base directory, and pairing URL from its output.
+
+Treat a base directory as disposable only when it was created or deliberately selected for the current test. Never delete or directly seed the shared `~/.t3` directory. Prefer starting with a new temporary base directory over clearing state of uncertain ownership.
+
+The worktree-local default deliberately outranks an ambient `T3CODE_HOME`; do not pass the shared home through to a worktree dev server.
+
+Ports are derived from the worktree path but can shift when occupied. Always read the actual values from the `[dev-runner]` line.
+
+Shared browser dev is single-origin: Vite proxies the backend paths, so never set `VITE_HTTP_URL` or `VITE_WS_URL` for `dev`/`dev:web`.
+
+The dev runner disables browser auto-open by default. Do not pass `--browser` during automated testing: an automatically opened page can consume the one-time bootstrap token before the controlled browser uses it.
+
+### Verify a shared environment before human handoff
+
+When another person will use the printed pairing URL, first open the shared origin without the pairing path or fragment in the controlled browser and confirm the T3 Code app loads. This browser navigation is required even when curl succeeds because browsers block some otherwise reachable ports before making a network request.
+
+Do not open the other person's complete pairing URL during this reachability check; doing so consumes its one-time token. If the agent also needs an authenticated browser, create and consume a separate pairing token, then leave a fresh token for the other person.
+
+## Preserve the environment while iterating
+
+Treat the overall testing or implementation loop—not an assistant turn or one verification pass—as the environment lifecycle boundary.
+
+- Keep the dev process, base directory, selected ports, authenticated browser tab, registered projects, and seeded fixtures alive while the user may inspect the result or request follow-up changes.
+- Do not stop the server merely because one verification pass completed or because you are yielding a response to the user.
+- Before starting another environment, check whether the existing process and browser tab still serve the task. Reuse them when healthy instead of discarding useful state.
+- On a later turn, verify that the existing process is alive and reuse its printed ports and base directory. If it exited, restart with the same base directory; create a new pairing token only when the browser session is no longer valid.
+- Tell the user when a test environment remains available, including its non-secret web URL when useful. Include a pairing token only when the user still needs to pair (see below).
+
+## Authenticate the browser on the first navigation
+
+1. Wait for the server log that says authentication is required and includes a URL ending in `/pair#token=...`.
+2. Use the controlled in-app browser or browser-automation surface available to the agent. Do not use a system-browser launch command during automated testing.
+3. Open that complete URL exactly once as the controlled browser's first navigation. Preserve the fragment and token verbatim.
+4. Wait for the pairing exchange and redirect to finish before navigating elsewhere.
+5. Continue in the same browser context so its stored bearer session remains available.
+
+Keep pairing URLs out of screenshots, committed files, and durable logs. When the user asked for a shared environment, the deliverable IS the full pairing URL — paste it in your reply, token and all; a bare origin is useless to them. A pairing token is short-lived and single-use; opening the URL in another browser or opening it twice can consume it, so never open a URL you handed to the user.
+
+## Recover a consumed or expired pairing token
+
+Run `node apps/server/src/bin.ts pair` from the repository root. It discovers the running dev server (worktree `.t3` first, same precedence as the dev runner) and prints a fresh `Pair URL` against the server's current web origin, including a `--share` tailnet origin. Pass `--base-dir <base-dir>` only when the server was started with `--home-dir`, using the identical path.
+
+Tokens from `pair` carry standard client scopes. The startup pairing URL carries admin scopes; if the user needs Settings → Connections management (`access:write`), restart the server and hand over the new startup URL instead.
+
+## Inspect or seed SQLite state
+
+Read [references/sqlite-fixtures.md](references/sqlite-fixtures.md) before changing the database.
+
+- Use `node apps/server/scripts/t3-sqlite-state.ts query` for schema discovery and read-only checks.
+- Stop the dev server before using `node apps/server/scripts/t3-sqlite-state.ts exec`, then restart it with the same base directory.
+- Seed projection tables only for disposable UI fixtures. Use application commands and APIs when testing business behavior or projection correctness.
+- Use the auth CLI, not direct `auth_*` table edits, for pairing and sessions.
+
+The helper refuses to write to the shared `~/.t3` directory by default and creates a database backup before each mutation.
+
+## Tear down only when the testing loop is finished
+
+Tear down when the user explicitly asks, confirms the iteration is finished, or the overall task is genuinely complete with no pending human review. Do not infer completion from the end of an assistant turn.
+
+When teardown is appropriate:
+
+1. Stop the dev process with its terminal interrupt.
+2. Preserve the isolated base directory when it contains useful reproduction evidence or state for a likely follow-up.
+3. Otherwise remove only a path created for this test after resolving and verifying the exact target.
+
+If completion is uncertain, keep the environment alive and mention that it is retained for further iteration. A fresh isolated base directory remains the safest reset when authentication, migrations, or fixture state becomes ambiguous.
+
+## Troubleshoot predictably
+
+- If the browser shows an unauthenticated pairing screen, issue a new token instead of retrying the consumed URL.
+- If the pairing URL is no longer visible, create a replacement token with both `--dev-url` and `--base-url`.
+- If the replacement token is rejected, verify that the CLI and server use the identical absolute base directory and web URL.
+- If the UI shows unexpected data, verify that every command uses the identical explicit base directory before editing anything.
+- If ports move because another instance is running, trust the current dev-runner output rather than assuming ports `13773` and `5733`.

.agents/skills/test-t3-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "T3 App Testing"
+  short_description: "Launch and retain isolated T3 test environments"
+  default_prompt: "Use $test-t3-app to launch an isolated T3 environment and iteratively test it in the browser while preserving state."