---
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`