Swift package extension workflow

Swift Package Extension Workflow

Purpose

Own SwiftPM extension work that does not belong in ordinary package build/run or testing workflows. Keep package plugins, macros, traits, generated-source policy, permission review, and toolchain comparison in one package-first path, then hand off when Xcode-managed project context becomes authoritative.

When To Use

• Use this skill for build tool plugins, command plugins, plugin products, target plugin usage, and plugin commands.
• Use this skill for macro targets, macro declaration/implementation boundaries, expansion inspection, diagnostics, and macro tests.
• Use this skill for package traits, default traits, optional dependencies, conditional compilation, and trait-aware build/test matrices.
• Use this skill for generated sources, generated build products, plugin sandboxing, write access, or network permissions.
• Use this skill when the Swiftly-selected toolchain and Xcode-selected toolchain may differ.
• Recommend swift-package-build-run-workflow for ordinary manifests, dependencies, resources, builds, and executable runs.
• Recommend swift-package-testing-workflow when ordinary test organization or failure diagnosis is primary.
• Recommend format-swift-sources for formatter-specific plugin operation after this skill establishes plugin permissions and ownership.
• Recommend xcode-build-run-workflow or xcode-testing-workflow when schemes, destinations, app hosts, Xcode project context, or Xcode-only evidence controls the result.
• Recommend explore-apple-swift-docs when the task is documentation lookup rather than package mutation or execution.

Single-Path Workflow

1. Inspect Package.swift, Plugins/, macro targets, generated outputs, test targets, and any Xcode project or workspace markers.
2. Establish both toolchain identities before planning commands:
   • Swiftly path: swiftly use --print-location, swift --version, and relevant swift package, swift build, or swift test help.
   • Xcode path: xcode-select -p, xcrun --find swift, xcrun swift --version, and matching xcrun swift package, build, or test help.
   • If Swiftly is set to xcode, record that bridge explicitly instead of presenting the two command paths as independent compiler distributions.
   • Do not assume the two toolchains expose identical SwiftPM commands, flags, manifest APIs, macro support, or plugin behavior.
3. Read the relevant official SwiftPM, Swift Evolution, or Apple/Xcode documentation and state the behavior relied on before editing.
4. Classify the primary extension concern as build-tool-plugin, command-plugin, macro, traits, or generated-source.
5. Run scripts/run_workflow.py for repo-shape inspection and a non-mutating command plan.
6. Load only the reference needed for the selected concern:
   • plugins: references/package-plugins-build-command-and-xcode.md
   • permissions: references/plugin-permissions-sandbox-and-outputs.md
   • macros: references/swift-macros-package-shape.md
   • traits: references/package-traits-feature-flags.md
   • generated files: references/generated-source-and-build-products.md
7. Use references/cli-command-matrix.md to keep Swiftly and Xcode commands distinct.
8. Apply references/xcode-handoff-conditions.md before using Xcode-managed execution or changing Xcode-owned project state.
9. Validate the smallest relevant matrix first, then the supported Swift minor window and both host toolchains when the package claims both.
10. Report the manifest/API floor, selected toolchain, commands run, generated or permission-sensitive outputs, and any handoff.

Inputs

• extension_type: build-tool-plugin, command-plugin, macro, traits, or generated-source.
• request: optional natural-language request used to infer extension_type.
• repo_root: package path; defaults to the current directory.
• toolchain_scope: swiftly, xcode, or both; defaults to both for Apple ecosystem compatibility work.
• mixed_root_opt_in: allow package-first planning when Xcode markers share the package root.

Outputs

• status: success, handoff, or blocked.
• path_type: primary or fallback.
• output: extension type, repo shape, toolchain scope, planned commands, evidence requirements, and one next step.

Guards and Stop Conditions

• Stop when the package root or Package.swift cannot be resolved.
• Stop before raising the tools-version or manifest API floor without confirming the package support window.
• Keep beta or snapshot toolchain evidence separate from the latest-stable-plus-previous-stable support promise.
• Do not treat swift --version as evidence for the Xcode toolchain; inspect xcrun swift --version separately.
• Do not disable the plugin sandbox as a routine workaround. Name the required capability and grant the narrowest permission.
• Do not let build tool plugins modify package sources; generate into plugin-controlled build output locations.
• Do not check in derived output merely to hide a nondeterministic generator.
• Do not use traits to remove API when enabled; design traits as additive feature choices.
• Stop with a handoff when Xcode project context, scheme/destination state, app-hosted execution, or project membership determines correctness.

Fallbacks and Handoffs

• Fall back to a command plan when execution would mutate the package or request permissions the user did not authorize.
• Hand ordinary package execution to swift-package-build-run-workflow after extension shape and flags are settled.
• Hand ordinary test diagnosis to swift-package-testing-workflow; retain ownership of macro/plugin test shape and trait matrices.
• Hand Xcode-managed builds to xcode-build-run-workflow and Xcode-native tests to xcode-testing-workflow with the exact package, plugin, macro, trait, scheme, and destination context.
• Use format-swift-sources for formatter-specific behavior without duplicating the general plugin permission model.

Customization

• Use references/customization.template.yaml and references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• The workflow currently keeps fixed package-first and least-permission defaults.

References

Workflow References

• references/package-plugins-build-command-and-xcode.md
• references/plugin-permissions-sandbox-and-outputs.md
• references/swift-macros-package-shape.md
• references/package-traits-feature-flags.md
• references/generated-source-and-build-products.md
• references/xcode-handoff-conditions.md
• references/cli-command-matrix.md

Contract References

• references/customization.template.yaml
• references/customization-flow.md

Support References

• Recommend references/snippets/apple-swift-package-core.md when reusable package policy is needed in an end-user repo.
• references/snippets/apple-swift-package-core.md

Script Inventory

• scripts/run_workflow.py
• scripts/customization_config.py