Swift Package Build Run Workflow

Swift Package Build Run Workflow

Purpose

Use this skill as the primary execution workflow for ordinary non-testing work in existing Swift package components. Keep it focused on manifest and dependency changes, package resources, builds, runs, and Release-versus-Debug validation. scripts/run-workflow.fsx resolves the nearest package root and plans commands without classifying the containing repository.

When To Use

• Use this skill for ordinary build and run work inside an existing Swift package repo.
• Use this skill for ordinary manifest, target, product, dependency, and package-resource work driven by Package.swift.
• Recommend swift-package-extension-workflow for package plugins, macros, traits, generated source, or plugin permissions.
• Use this skill for package resources, Bundle.module, .process(...), .copy(...), .embedInCode(...), and package-local fixture layout decisions.
• Use this skill for Metal library packaging, distribution, and the SwiftPM side of Metal-related package work before Xcode-managed Apple toolchain behavior becomes the real concern.
• Use this skill for Debug-versus-Release validation, build artifacts, and tagged-release package expectations.
• Use this skill for Swift Package Index readiness checks in package repositories, but hand external add-package submission to Socket's guarded scripts/spi_add_package.py issue-form flow when that script is available.
• Do not use this skill for package-testing-first work, test-plan execution, XCTest or Swift Testing diagnosis, or test-specific filtering and retries.
• Do not use this skill for brand-new package bootstrap from nothing.
• Do not use this skill for repo-guidance alignment in an existing package repo.
• Do not use this skill as the default path for Xcode workspace, scheme, preview, simulator, or navigator-driven work.
• Recommend swift-package-testing-workflow when the request is primarily about running, diagnosing, organizing, or evolving tests.
• Recommend bootstrap-xcode-workspace --operation create --component-kind library when the package repo does not exist yet.
• Recommend root workspace just align when product guidance needs to be refreshed.
• Recommend xcode-build-run-workflow when the task depends on active Xcode workspace state, scheme-aware execution, previews, navigator diagnostics, simulator or device flows, or guarded mutation inside Xcode-managed scope.
• Recommend explore-apple-swift-docs when the user needs Apple or Swift docs exploration before implementation or package changes.

Single-Path Workflow

1. Classify the request into one operation type:
   • package inspection
   • read or search
   • manifest or dependency changes
   • build
   • run
   • package extension handoff
   • toolchain management
   • mutation
2. Apply the Apple and Swift docs gate before any design, architecture, implementation, or refactor guidance:
   • use explore-apple-swift-docs to gather the relevant SwiftPM, Swift, or Apple documentation first
   • when SwiftPM behavior, manifest syntax, package plugins, resources, products, targets, or dependency rules matter, prefer the Dash.app docset workflow with the swiftlang/swift-package-manager docset first
   • fall back to the canonical swiftlang/swift-package-manager GitHub repository only when the local Dash docset is unavailable or insufficient
   • state the documented API behavior, package rule, or workflow requirement being relied on before proposing changes
   • do not rely on memory as the primary source when docs exist
   • if the docs and the current code conflict, stop and report that conflict
   • if no relevant docs can be found, say that explicitly before proceeding
3. Apply the shared Swift-package policy before giving implementation guidance:
   • apply the detailed local policy in references/snippets/apple-swift-package-core.md when package-policy wording is needed
   • preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance
   • preserve its explicit swiftLanguageModes: [.v6] package-manifest default and prefer that spelling over the legacy swiftLanguageVersions alias on current manifest surfaces
   • preserve its package-appropriate logging, telemetry, and structured-concurrency guidance
4. Run scripts/run-workflow.fsx to resolve the nearest package root, confirm the request stays on the build/run surface, and plan the SwiftPM command path.
5. Use references/cli-command-matrix.md for agent-executed SwiftPM commands and terminal-first editor workflows.
6. Use references/package-resources-testing-and-builds.md when the request touches package resources, Metal artifacts, Bundle.module, or Debug/Release and tagged-release validation.
7. Apply ../../shared/execution-surface-routing.md; use xcode-build-run-workflow only when the requested operation needs Xcode-owned state.
8. For Swift Package Index add-package work, distinguish local readiness from external submission:
   • local readiness may include Package.swift, semantic-version tag, swift package dump-package, swift build, swift test, .spi.yml, and DocC checks
   • external submission must use the official SwiftPackageIndex/PackageList Add Package issue form
   • when working from Socket, run uv run /Users/galew/Workspace/gaelic-ghost/socket/scripts/spi_add_package.py hands-free <package-root> and follow its Codex Computer Use handoff
   • never create PackageList issues with gh issue create, apply labels manually, fork PackageList, edit packages.json, or open PackageList PRs
9. Report which parts were agent-executed, the docs relied on, the resolved package context, and any required next step or handoff.

Inputs

• operation_type: one of the operation types listed above.
• request: optional short natural-language request text used to infer operation_type when the explicit operation is omitted.
• repo_root: optional absolute path for the target package repo.
• Defaults:
  • runtime entrypoint: executable scripts/run-workflow.fsx
  • repo_root=. when omitted
  • the runtime may infer operation_type from --request text when the request wording is clear enough
  • package execution prefers swift package, swift build, and swift run
  • Xcode files do not change package routing

Outputs

• status
  • success: the workflow completed on the SwiftPM-first path
  • handoff: the workflow is handing off to another skill because testing or Xcode-managed behavior is the safer surface
  • blocked: prerequisites or package-root resolution prevented completion
• path_type
  • primary: the SwiftPM-first path completed
  • fallback: a non-mutating planned command path was returned
• output
  • operation type
  • resolved package root
  • package context
  • planned_commands
  • one concise next step or handoff payload

Guards and Stop Conditions

• Stop with blocked when the package root cannot be resolved.
• Stop with blocked when the repo does not contain Package.swift.
• Stop with handoff when the request is really package-testing or package-extension work.
• Stop with handoff only when the requested operation requires an Xcode scheme, destination, preview, target membership, build phase, or app bundle integration.
• Stop with handoff when the requested work crosses into Xcode project membership, scheme, preview, simulator, or other Xcode-managed concerns.
• Stop with blocked when no safe SwiftPM-first command path exists for the requested operation.
• Stop with blocked when Swift Package Index submission is requested but the package is only locally ready, the official Add Package issue form is unavailable, the Socket guarded script reports incomplete readiness, or the created issue cannot be verified with the Add Package label.

Fallbacks and Handoffs

• SwiftPM and ordinary filesystem edits are the default execution surface for this skill.
• The only current fallback is a non-mutating planned command result when the user asked for guidance rather than immediate execution.
• Hand off to swift-package-testing-workflow when the request becomes primarily about tests, test plans, or test diagnosis.
• Hand off to swift-package-extension-workflow when the request becomes primarily about plugins, macros, traits, generated source, or plugin permissions.
• Hand off to xcode-build-run-workflow when package build or distribution work depends on:
  • active Xcode workspace or scheme state
  • previews, snippet execution, simulator, or device flows
  • navigator issues or Xcode build-log inspection
  • Xcode MCP mutation tools
  • Metal shader compilation, Apple-managed Metal toolchain inspection, or package distribution that depends on Xcode-managed Apple SDK integration
  • direct changes inside .xcodeproj, .xcworkspace, or .pbxproj managed scope
• Recommend root workspace just align when the request is really about product guidance instead of execution.
• Recommend bootstrap-xcode-workspace --operation create --component-kind library when the repository still needs to be created from scratch.
• When maintaining this repository itself, refresh guidance-sync consumers after substantial package-policy changes and keep the top-level export-surface docs aligned. Do not tell users to rely on repo-local installer workflows; this repository does not ship them.

Fixed Policy

• scripts/run-workflow.fsx enforces the fixed SwiftPM-first policy without runtime customization.

References

Workflow References

• references/workflow-policy.md
• references/cli-command-matrix.md
• references/package-resources-testing-and-builds.md
• ../../shared/execution-surface-routing.md

Contract References

Support References

• Recommend references/snippets/apple-swift-package-core.md when the user needs reusable SwiftPM baseline policy wording in an end-user repo.
• references/snippets/apple-swift-package-core.md
• For Swift Package Index add-package automation in Socket, use /Users/galew/Workspace/gaelic-ghost/socket/scripts/spi_add_package.py and /Users/galew/Workspace/gaelic-ghost/socket/docs/maintainers/spi-add-package-automation-plan.md.

Script Inventory

• scripts/run-workflow.fsx