apple-xcode-workflow（Apple Xcode 工作流）

Apple Xcode Workflow

Purpose

Use this skill as the top-level entry point for Apple and Swift work in or around Xcode. The skill guides agent-side tool use and applies the shared simplicity-first Swift policy, while scripts/run_workflow.py enforces local policy, mutation guards, cooldown behavior, docs routing, and structured fallback planning.

When To Use

• Use this skill for Xcode workspace inspection, read or search, diagnostics, build, test, and run tasks.
• Use this skill for Swift toolchain checks and official Apple CLI fallback.
• Use this skill for Apple and Swift documentation requests that should prefer Dash local sources before official web docs.
• Use this skill when direct filesystem mutation in an Xcode-managed scope may be required.
• Recommend apple-dash-docsets when the user needs Dash docset search, install, or generation work instead of Apple execution work.
• Recommend apple-swift-package-bootstrap when the user needs to create a brand new Swift package rather than work inside an existing Xcode or Swift project.

Single-Path Workflow

1. Classify the request into one operation type:

- workspace or session inspection - read, search, or diagnostics - build, test, or run - package or toolchain management - docs lookup - mutation

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

- read the relevant Apple documentation first - use Dash or Xcode-local documentation first, then official Apple documentation if needed - 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

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

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

1. Run scripts/run_workflow.py to apply runtime configuration, mutation-guard checks, docs-routing order, advisory cooldown, and CLI fallback planning.
2. Use the guidance in references/mcp-tool-matrix.md for agent-executed MCP operations.
3. If MCP fails, use the structured fallback output from scripts/run_workflow.py together with references/cli-fallback-matrix.md.
4. Report which parts were agent-executed, which parts were locally enforced by script, the Apple docs relied on, and any required next step.

Inputs

• operation_type: one of the operation types listed above.
• 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.
• docs_query: required when operation_type is docs.
• filesystem_fallback_opt_in: optional explicit opt-in when planning direct filesystem fallback in Xcode-managed scope.
• Defaults:

- runtime entrypoint: executable scripts/run_workflow.py - agent-side MCP retries once for transient failures - advisory cooldown is 21 days - docs source order is dash-mcp,dash-local,official-web - mutation operations require the explicit guard in Xcode-managed scope

Outputs

• status

- success: the workflow completed on its primary or fallback path - blocked: prerequisites, policy, or mutation safeguards prevented completion - handoff: the workflow is handing off supporting context to another step or skill

• path_type

- primary: the guided agent-side MCP path completed successfully - fallback: the official CLI fallback path completed successfully

• output

- operation type - guard_result - docs_route - fallback_commands - advisory status - one next step or handoff payload when needed

Guards and Stop Conditions

• Apply the mutation guard from references/mutation-risk-policy.md only when the operation type is mutation.
• Do not skip the mutation guard for direct filesystem edits inside Xcode-managed scope.
• Stop with blocked when the required workspace context cannot be resolved and the operation cannot safely continue.
• Stop with blocked when allowlist or sandbox rules prevent the official CLI fallback and no safe alternative exists.
• Stop with blocked when operation_type=docs and docs_query is missing.

Fallbacks and Handoffs

• Official CLI execution is the only fallback path when the primary agent-side MCP path cannot complete.
• Use references/mcp-failure-handoff.md for the canonical fallback and handoff payload.
• Use references/allowlist-guidance.md when a safe official CLI fallback is blocked by local rules.
• Use references/dash-docs-flow.md to describe docs lookup as an operation profile under this same execution engine.
• Recommend apple-dash-docsets directly when the task becomes Dash management work.
• Recommend apple-swift-package-bootstrap directly when the task becomes new-package scaffolding.
• scripts/run_workflow.py plans fallback commands and docs-route changes; MCP execution itself remains agent-side tool usage guided by this skill.

Customization

• Use references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• scripts/run_workflow.py loads and enforces the runtime-safe knobs documented in references/customization-flow.md.
• MCP tool execution itself remains agent-side and is not performed by the local runtime entrypoint or by the skill as a direct runtime.

References

Workflow References

• references/workflow-policy.md
• references/mcp-tool-matrix.md
• references/cli-fallback-matrix.md
• references/toolchain-management.md
• references/mutation-risk-policy.md
• references/mutation-via-mcp.md
• references/dash-docs-flow.md

Contract References

• references/mcp-failure-handoff.md
• references/customization-flow.md

Support References

• Recommend references/snippets/apple-swift-core.md when the user needs reusable Apple and Swift baseline policy content in their own repo alongside execution, docs, or mutation workflows.
• references/allowlist-guidance.md
• references/skills-installation.md
• references/mcp-setup-advisory.md
• references/skills-discovery.md
• references/snippets/apple-swift-core.md

Script Inventory

• scripts/run_workflow.py
• scripts/advisory_cooldown.py
• scripts/detect_xcode_managed_scope.sh
• scripts/customization_config.py