name: apple-xcode-workflow
description: Guide Apple and Swift development work in or around Xcode. Use when tasks involve Xcode workspace inspection, diagnostics, builds, tests, runs, toolchain checks, or Apple and Swift documentation lookup.

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, 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
2. Run scripts/run_workflow.py to apply runtime configuration, mutation-guard checks, docs-routing order, advisory cooldown, and CLI fallback planning.
3. Use the guidance in references/mcp-tool-matrix.md for agent-executed MCP operations.
4. If MCP fails, use the structured fallback output from scripts/run_workflow.py together with references/cli-fallback-matrix.md.
5. Report which parts were agent-executed, which parts were locally enforced by script, 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: python3 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