/xcode-build-run-workflow

name: xcode-build-run-workflow
description: Guide build, run, preview-adjacent, workspace-inspection, diagnostics, toolchain, and guarded mutation work in existing Xcode-managed projects and workspaces. Use when Xcode-aware execution is needed and the task is primarily about build, run, or project-integrity work rather than testing.

Xcode Build Run Workflow

Purpose

Use this skill as the primary execution workflow for non-testing work in or around Xcode-managed projects and workspaces. Keep it focused on workspace inspection, read/search diagnostics, builds, runs, previews, toolchain management, file membership, Release-versus-Debug validation, and the `.pbxproj` warning boundary. `scripts/run-workflow.fsx` is the runtime entrypoint for MCP-first build/run execution, official CLI fallback planning, and direct `.pbxproj` warning enforcement.

When To Use

• Use this skill for Xcode workspace inspection, project discovery, read/search diagnostics, build, run, preview, and navigator-issue tasks.
• Use this skill for Xcode MCP operations, scheme-aware execution, and official Apple CLI fallback when the work is primarily about build/run rather than tests.
• Use this skill when direct filesystem mutation around an Xcode-managed project may be required.
• Use this skill for file-membership and target-membership verification after on-disk edits.
• Use this skill for Debug/Release build-configuration work, artifacts, archives, toolchain checks, and Metal-toolchain-aware build execution.
• Recommend `xcode-coding-intelligence-workflow` when the request is primarily about Xcode Intelligence setup, Xcode-hosted agents, external-agent access through `xcrun mcpbridge`, command/tool permissions, or Xcode-only agent configuration homes.
• Do not use this skill as the default path for Swift Testing, XCTest, XCUITest, `.xctestplan`, flaky-test diagnosis, retries, or test filtering.
• Recommend `xcode-testing-workflow` when the task is primarily about tests or test diagnosis.
• Recommend `explore-apple-swift-docs` when the user needs Apple or Swift documentation lookup rather than execution work.
• Recommend `swift-package-build-run-workflow` or `swift-package-testing-workflow` when the task is ordinary SwiftPM package work outside Xcode-managed execution.
• Recommend `bootstrap-xcode-workspace --operation align` when an existing Apple product workspace needs managed guidance alignment rather than active engineering work.

Single-Path Workflow

1. Classify the request into one operation type:

• workspace or session inspection
• read, search, or diagnostics
• build or run
• package or toolchain management
• mutation

2. Apply the Apple docs gate before any Apple design, architecture, implementation, or refactor guidance:

• use `explore-apple-swift-docs` to gather the relevant Apple documentation first
• state the documented API behavior, lifecycle rule, or workflow requirement being relied on before proposing changes
• do not rely on memory as the primary source when Apple docs exist
• if the docs and the current code conflict, stop and report that conflict
• if no relevant Apple docs can be found, say that explicitly before proceeding

3. Apply the shared Swift policy before giving implementation guidance:

• apply the detailed local policy in `references/snippets/apple-xcode-project-core.md`
• preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance
• preserve its project-appropriate logging, telemetry, and SwiftUI architecture guidance

4. Run `scripts/run-workflow.fsx` to apply runtime configuration, `.pbxproj` warning safeguards, and CLI fallback planning. 5. Use the guidance in `references/mcp-tool-matrix.md` for agent-executed MCP operations. 6. Use `references/xcodegen-project-maintenance.md` when the repo is XcodeGen-backed and the task touches generated targets, schemes, build settings, packages, file membership, resource membership, or generation options. 7. Use `references/testing-plans-file-membership-and-configurations.md` when the task touches file membership after filesystem edits or Debug/Release validation. 8. If MCP fails, use the structured fallback output from `scripts/run-workflow.fsx` together with `references/cli-fallback-matrix.md`. 9. Report which parts were agent-executed, which parts were locally enforced by script, the Apple docs relied on, any tracked `.pbxproj` diff that must be staged and committed with the branch, and any required next step.

Inputs

• `operation_type`: one of the operation types listed above.
• `request`: optional short natural-language request text used to infer `operation_type` when the explicit operation is omitted.
• `workspace_path`: optional absolute path for the target Xcode or Swift workspace.
• `tab_identifier`: optional MCP tab identifier when already known.
• `mcp_failure_reason`: optional input when continuing from an earlier MCP failure.
• `direct_pbxproj_edit`: optional flag when the requested mutation would directly edit a `.pbxproj` file.
• `direct_pbxproj_edit_opt_in`: optional explicit opt-in after the user has been warned about direct `.pbxproj` edit risks.
• Defaults:
• runtime entrypoint: executable `scripts/run-workflow.fsx`
• the runtime may infer `operation_type` from `--request` text when the request wording is clear enough
• agent-side MCP retries once for transient failures
• direct edits are allowed by default when they do not directly edit `.pbxproj`

Outputs

• `status`
• `success`: the workflow completed on its primary or fallback path
• `handoff`: the workflow is handing off to another skill because the request is actually test-focused
• `blocked`: prerequisites, policy, or mutation safeguards prevented completion
• `path_type`
• `primary`: the guided agent-side MCP path completed successfully
• `fallback`: the official CLI fallback path completed successfully
• `output`
• operation type
• `guard_result`
• `fallback_