Update to Build macOS Apps

{
  "name": "build-run-debug",
  "description": "Build, run, and debug macOS apps with shell-first Xcode and Swift workflows. Use when launching apps or diagnosing build, startup, or runtime failures.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 301
    },
    {
      "relative_path": "references/run-button-bootstrap.md",
      "size_in_bytes": 4749
    }
  ],
  "skill_md_contents": "---\nname: build-run-debug\ndescription: Build, run, and debug macOS apps with shell-first Xcode and Swift workflows. Use when launching apps or diagnosing build, startup, or runtime failures.\n---\n\n# Build / Run / Debug\n\n## Quick Start\n\nUse this skill to set up one project-local `script/build_and_run.sh` entrypoint,\nwire `.codex/environments/environment.toml` so the Codex app shows a Run button,\nthen use that script as the default build/run path.\n\nPrefer shell-first workflows:\n\n- `./script/build_and_run.sh` as the single kill + build + run entrypoint once it exists\n- `xcodebuild` for Xcode workspaces or projects\n- `swift build` plus raw executable launch inside that script for true SwiftPM command-line tools\n- `swift build` plus project-local `.app` bundle staging and `/usr/bin/open -n` launch for SwiftPM AppKit/SwiftUI GUI apps\n- optional script flags for `lldb`, `log stream`, telemetry verification, or post-launch process checks\n\nDo not assume simulators, touch interaction, or mobile-specific tooling.\n\nIf an Xcode-aware MCP surface is already available and the user explicitly wants\nit, use it only where it fits. Keep that usage narrow and honest: prefer it for\nXcode-oriented discovery, logging, or debugging support, and do not force\nsimulator-specific workflows onto pure macOS tasks.\n\n## Workflow\n\n1. Discover the project shape.\n   - Check whether the workspace is already inside a git repo with `git rev-parse --is-inside-work-tree`.\n   - If no git repo is present, run `git init` at the project/workspace root before building so Codex app git-backed features are available. Never run `git init` inside a nested subdirectory when the current workspace already belongs to a parent repo.\n   - Look for `.xcworkspace`, `.xcodeproj`, and `Package.swift`.\n   - If more than one candidate exists, explain the default choice and the ambiguity.\n\n2. Resolve the runnable target and process name.\n   - For Xcode, list schemes and prefer the app-producing scheme unless the user names another one.\n   - For SwiftPM, identify executable products when possible.\n   - Split SwiftPM launch handling by product type:\n     - use raw executable launch only for true command-line tools,\n     - use a generated project-local `.app` bundle for AppKit/SwiftUI GUI apps.\n   - Determine the app/process name to kill before relaunching.\n\n3. Create or update `script/build_and_run.sh`.\n   - Make the script project-specific and executable.\n   - It should always:\n     1. stop the existing running app/process if present,\n     2. build the macOS target,\n     3. launch the freshly built app or executable.\n   - Add optional flags for debugging/log inspection:\n     - `--debug` to launch under `lldb` or attach the debugger\n     - `--logs` to stream process logs after launch\n     - `--telemetry` to stream unified logs filtered to the app subsystem/category\n     - `--verify` to launch the app and confirm the process exists with `pgrep -x <AppName>`\n   - Keep the default no-flag path simple: kill, build, run.\n   - Prefer writing one script that owns this workflow instead of repeatedly asking the agent to manually run `swift build`, locate the artifact, then invoke an ad hoc run command.\n   - For SwiftPM GUI apps, make the script build the product, create `dist/<AppName>.app`, copy the binary to `Contents/MacOS/<AppName>`, generate a minimal `Contents/Info.plist` with `CFBundlePackageType=APPL`, `CFBundleExecutable`, `CFBundleIdentifier`, `CFBundleName`, `LSMinimumSystemVersion`, and `NSPrincipalClass=NSApplication`, then launch with `/usr/bin/open -n <bundle>`.\n   - For SwiftPM GUI `--logs` and `--telemetry`, launch the bundle with `/usr/bin/open -n` first, then stream unified logs with `/usr/bin/log stream --info ...`.\n   - Do not recommend direct SwiftPM executable launch for AppKit/SwiftUI GUI apps.\n   - Use `references/run-button-bootstrap.md` as the canonical source for the\n     script shape and exact environment file format. Do not fork a second\n     authoritative snippet in another skill or command.\n   - Keep the run script outside app source. It belongs in `script/build_and_run.sh`, not in `App/`, `Views/`, `Models/`, `Stores/`, `Services/`, or `Support/`.\n\n4. Write `.codex/environments/environment.toml` at the project root once the script exists.\n   - Use this exact placement: `.codex/environments/environment.toml`.\n   - Use the exact action shape in `references/run-button-bootstrap.md`.\n   - This file is what gives the user a Codex app Run button wired to the script.\n   - If the project already has this file, update the `Run` action command to point at `./script/build_and_run.sh` instead of creating a duplicate action.\n   - Keep this Codex environment config separate from Swift app source files.\n\n5. Build and run through the script.\n   - Default to `./script/build_and_run.sh`.\n   - Use `./script/build_and_run.sh --debug`, `--logs`, `--telemetry`, or `--verify` when the user asks for debugger/log/telemetry/process verification support.\n\n6. Summarize failures correctly.\n   - Classify the blocker as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch.\n   - Quote the smallest useful error snippet and explain what it means.\n\n7. Debug the right way.\n   - Use the script's `--logs` or `--telemetry` mode for config, entitlement, sandbox, and action-event verification.\n   - For SwiftPM GUI apps, if the app bundle launches but its window still does not come forward, check whether the entrypoint needs `NSApp.setActivationPolicy(.regular)` and `NSApp.activate(ignoringOtherApps: true)`.\n   - Use the script's `--debug` mode or direct `lldb` if symbolized crash debugging is needed.\n   - If the user needs to instrument and verify specific window, sidebar, menu, or menu bar actions, switch to `telemetry`.\n   - Keep evidence tight and user-facing.\n\n8. Use Xcode-aware MCP tooling only when it helps.\n   - If the user explicitly asks for XcodeBuildMCP and it is already available, prefer it over ad hoc setup.\n   - Use the MCP for Xcode-aware discovery or debug/logging workflows when the available tool surface clearly matches the task.\n   - Fall back to shell commands immediately when the MCP does not provide a clean macOS path.\n\n## Preferred Commands\n\n- Project discovery:\n  - `find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'`\n- Scheme discovery:\n  - `xcodebuild -list -workspace <workspace>`\n  - `xcodebuild -list -project <project>`\n- Build/run:\n  - `./script/build_and_run.sh`\n  - `./script/build_and_run.sh --debug`\n  - `./script/build_and_run.sh --logs`\n  - `./script/build_and_run.sh --telemetry`\n  - `./script/build_and_run.sh --verify`\n\n## References\n\n- `references/run-button-bootstrap.md`: canonical `build_and_run.sh` and `.codex/environments/environment.toml` contract.\n\n## Guardrails\n\n- Prefer the narrowest command that proves or disproves the current theory.\n- Do not leave the user with a one-off manual command chain once a stable `build_and_run.sh` script can own the workflow.\n- Do not write `.codex/environments/environment.toml` before the run script exists, and do not point the Run action at a stale script path.\n- Do not launch a SwiftUI/AppKit SwiftPM GUI app as a raw executable unless the user explicitly wants to diagnose that failure mode: it can produce no Dock icon, no foreground activation, and missing bundle identifier warnings. Keep raw executable launch only for true command-line tools.\n- Do not claim UI state you cannot inspect directly.\n- Do not describe mobile or simulator workflows as if they apply to macOS.\n- If build output is huge, summarize the first real blocker and point to follow-up commands.\n\n## Output Expectations\n\nProvide:\n- the detected project type\n- the script path and Codex environment action you configured, if applicable\n- the command you ran\n- whether build and launch succeeded\n- the top blocker if they failed\n- the smallest sensible next action\n"
}