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 the managed FSX planner through the owning repository recipe for nearest-package resolution 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. Use Xcode only when the requested operation changes an Xcode scheme, target, build phase, preview, or other Xcode-owned state; co-located Xcode files never change package routing.
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.