git:20260305.8c07624 to git:20260305.601438e

18 added, 11 removed. Audit A to A.

---

name: apple-xcode-workflow

description: Execute Apple and Swift development workflows with one MCP-first engine, official CLI fallback, mutation guards, and local-first docs guidance. Use when tasks involve Xcode MCP operations, build/test/run, toolchain checks, or Apple/Swift docs routing.

---

# Apple Xcode Workflow

## Purpose

- Use this skill as the top-level entry point for Apple and Swift work in or around Xcode, with one MCP-first engine, official CLI fallback, explicit mutation guards, and local-first docs guidance.

+ Use this skill as the top-level entry point for Apple and Swift work in or around Xcode. Agent-side MCP tools remain the primary execution layer, 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. Resolve workspace context through Xcode MCP metadata when available.

- 3. Run the supported MCP path first by using `references/mcp-tool-matrix.md`.

- 4. Retry once when the failure is transient (`timeout` or `transport`).

- 5. If MCP is unsupported or the retry also fails, run the official CLI fallback from `references/cli-fallback-matrix.md`.

- 6. Report the completed path and any required next step.

+ 2. Run `scripts/run_workflow.py` to apply runtime configuration, mutation-guard checks, docs-routing order, advisory cooldown, and CLI fallback planning.

+ 3. Use MCP tools from `references/mcp-tool-matrix.md` for agent-executed 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`

- 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 MCP path completed successfully

- `fallback`: the official CLI fallback path completed successfully

- `output`

- operation type

- - MCP tool or CLI command used

- - concise reason when a fallback or handoff happened

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

- - Do not claim that customization metadata changes runtime behavior automatically; it does not today.

+ - Stop with `blocked` when `operation_type=docs` and `docs_query` is missing.

## Fallbacks and Handoffs

- Official CLI execution is the only fallback path for the primary workflow.

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

## Customization

- Use `references/customization-flow.md`.

- - All documented customization knobs for this skill are `policy-only`.

- - `scripts/customization_config.py` stores and reports customization state, but no knob in that file is auto-loaded by the execution scripts today.

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

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