bootstrap-swift-package

name	bootstrap-swift-package
description	Bootstrap new Swift Package Manager repositories with consistent defaults, generated AGENTS guidance, validation, and customizable bootstrap settings. Use when creating a new Swift package, choosing platform or version presets, scaffolding its initial structure, or maintaining this skill's bootstrap defaults.

Bootstrap Swift Package

Purpose

Create a new Swift package repository with one top-level entry point, a simplicity-first Swift baseline, and a local-first maintainer surface. scripts/run_workflow.py is the runtime wrapper, and scripts/bootstrap_swift_package.sh is the deterministic implementation core for scaffold creation, testing-mode selection, validation, and maintain-project-repo installation with the swift-package profile.

Companion Plugin Requirement

This skill can be discovered from a standalone apple-dev-skills install, but its mutating bootstrap path installs repo-maintenance files through the companion repository-skills plugin. If the companion maintain-project-repo runner is missing, tell the user to install repository-skills alongside apple-dev-skills, or add the socket marketplace with codex plugin marketplace add gaelic-ghost/socket and then install or enable both apple-dev-skills and repository-skills from the Socket catalog.

When To Use

• Use this skill for new Swift package scaffolding.
• Use this skill when the user wants consistent package defaults, AGENTS.md generation, and immediate validation.
• Use this skill when the user wants to customize the documented bootstrap defaults for future runs.
• Do not use this skill as the default path for normal Xcode app collaboration work.
• Do not use this skill as the default path for guidance sync inside an already-existing Swift package repo.
• Recommend swift-package-build-run-workflow or swift-package-testing-workflow when the user is doing ordinary package development after bootstrap.
• Recommend xcode-build-run-workflow when the user is working in an existing Xcode project or needs Xcode-managed Apple-platform build, run, toolchain, Metal, or mutation work after bootstrap.
• Recommend xcode-testing-workflow when the user needs Xcode-managed Apple-platform test execution after bootstrap.
• Recommend sync-swift-package-guidance when an existing Swift package repo needs AGENTS.md or workflow-guidance alignment rather than fresh bootstrap.
• Recommend explore-apple-swift-docs when the user needs Apple or Swift docs exploration, Dash-compatible lookup, or Dash follow-up work.

Single-Path Workflow

1. Collect the required inputs:
   • name
   • type
   • destination
   • platform
   • version_profile
   • optional testing_mode
   • optional skip_validation
2. Normalize aliases exactly as scripts/bootstrap_swift_package.sh does:
   • macos -> mac
   • ios -> mobile
   • both -> multiplatform
   • latest -> latest-major
   • minus-one -> current-minus-one
   • minus-two -> current-minus-two
3. Run scripts/run_workflow.py so documented defaults are loaded from customization state and normalized into one JSON contract.
4. Select testing mode before scaffold creation:
   • require Swift 6.2 or newer before bootstrap planning continues because the generated manifest uses PackageDescription package traits for the default swift-configuration dependency; treat 6.2 as the current minimum floor, not as a ceiling
   • prefer swift-testing on supported toolchains that expose swift package init --enable-swift-testing
   • use explicit XCTest-selection flags when xctest is requested and the active toolchain exposes them
   • fall back to the toolchain's default XCTest template only when xctest is requested and the active swift package init command exposes no testing-selection flags at all
   • stop with blocked when the local toolchain is older than 6.2 or when the active swift package init command cannot guarantee the requested testing mode
5. Let the wrapper invoke the bundled script:

   scripts/bootstrap_swift_package.sh --name <Name> --type <library|executable|tool> --destination <dir> --platform <mac|macos|mobile|ios|multiplatform|both> --version-profile <latest-major|current-minus-one|current-minus-two|latest|minus-one|minus-two> --testing-mode <swift-testing|xctest>
   

6. Verify the generated repository:
   • Package.swift
   • .swiftformat
   • explicit swiftLanguageModes: [.v6] in Package.swift
   • default swift-configuration dependency in Package.swift with the Configuration product on the primary target and package traits Reloading, YAML, and CommandLineArguments
   • // swift-tools-version: remains 6.2 or newer when the generated manifest keeps trait-enabled dependencies
   • .git
   • AGENTS.md
   • .codex/environments/swift-package.toml
   • scripts/repo-maintenance/hooks/pre-commit.sample
   • scripts/repo-maintenance/validate-all.sh
   • scripts/repo-maintenance/release.sh
   • Tests/
   • swift build and swift test unless --skip-validation was requested
   • branch protection, when enabled, requires the GitHub Actions check context validate; do not require the display-style string Validate Repo Maintenance / validate
   • when a GitHub remote is created or already exists, route repository settings audit or mutation through repository-skills:maintain-github-repository instead of embedding a separate Apple-specific baseline
7. Ensure the generated guidance encodes the shared Swift policy:
   • apply the detailed local policy in references/snippets/apple-swift-package-core.md
   • keep the generated repo aligned with the simplicity-first, shape-preserving, and anti-ceremony Swift guidance in that snippet
   • keep the generated repo aligned with the checked-in .swiftformat plus format-then-verify pre-commit-hook baseline in that snippet
   • keep the generated Apple and Swift docs-source guidance aligned with the Xcode MCP, Dash, source-repository, and readable-web fallback order in that snippet
   • verify the generated guidance does not treat generic no-JS web search/open results, snippets, metadata shells, or bare Apple Developer URLs as evidence that Apple docs were read
   • keep the generated manifest aligned with the explicit Swift 6 default language-mode declaration swiftLanguageModes: [.v6]
   • keep the generated manifest aligned with the default swift-configuration dependency, using the Configuration product and package traits .defaults, Reloading, YAML, and CommandLineArguments
   • treat the generated // swift-tools-version: as a starting point that can be lowered to match the real package compatibility target, but never below the current 6.2 floor while trait-enabled dependencies remain in the manifest
   • preserve the project-appropriate logging and telemetry guidance from that snippet
8. Hand off package execution guidance cleanly:
   • use swift build and swift test by default
   • recommend sync-swift-package-guidance when a later repo-guidance refresh or merge is needed for the created package repo
   • recommend swift-package-build-run-workflow or swift-package-testing-workflow for ordinary package development after bootstrap
   • recommend xcode-build-run-workflow for package builds that need Xcode-managed toolchain behavior, such as package builds that depend on Xcode-provided Metal or other Apple-managed build assets
9. Return one JSON execution summary with the created path, normalized options, and validation result.

Inputs

• name: required; must start with a letter and contain only letters, numbers, _, or -.
• type: library, executable, or advanced explicit tool.
• destination: parent directory for the new package.
• platform: mac, mobile, or multiplatform, with aliases normalized by the script.
• version_profile: latest-major, current-minus-one, or current-minus-two, with aliases normalized by the script.
• testing_mode: swift-testing or xctest.
• skip_validation: optional flag to skip swift build and swift test.
• dry_run: optional flag to resolve defaults and emit the normalized command contract without creating files.
• Defaults:
  • runtime entrypoint: executable scripts/run_workflow.py
  • type defaults to library
  • destination defaults to .
  • platform defaults to multiplatform
  • version_profile defaults to current-minus-one
  • testing_mode defaults to swift-testing
  • validation runs unless --skip-validation is passed
  • supported and validated Swift toolchain floor is Swift 6.2; newer stable Swift toolchains are allowed and preferred when validation passes
  • generated manifests should preserve an explicit Swift 6 language-mode declaration with swiftLanguageModes: [.v6] when the active manifest surface supports it
  • generated manifests include swift-configuration by default with the Configuration product on the primary target and traits .defaults, Reloading, YAML, and CommandLineArguments
  • generated manifests may lower // swift-tools-version: from the scaffold default when the package should support the previous supported Swift minor, but they should never go below the current 6.2 floor while trait-enabled dependencies remain in the manifest
  • Codex GUI local environments are installed from templates/codex-local-environments/swift-package.toml into .codex/environments/swift-package.toml
  • maintain-project-repo installs scripts/repo-maintenance/ on successful mutating runs

Outputs

• status
  • success: the package was created and verification succeeded
  • blocked: prerequisites, unsupported toolchains, unsupported testing-mode selections, or target-directory constraints prevented the run
  • failed: the script started but did not complete successfully
• path_type
  • primary: the bundled script completed successfully
  • fallback: manual scaffold guidance is being used instead of the bundled script
• output
  • resolved package path
  • normalized inputs
  • resolved testing_strategy
  • detected swift_toolchain on real runs
  • installed .codex/environments/swift-package.toml
  • installed maintain-project-repo paths
  • validation result
  • one concise next step

Guards and Stop Conditions

• Stop with blocked if swift is missing.
• Stop with blocked if swift --version cannot be parsed into a supported toolchain version.
• Stop with blocked if the local Swift toolchain is older than 6.2.
• Stop with blocked if git is missing.
• Stop with blocked if assets/AGENTS.md is missing.
• Stop with blocked if the target exists and contains non-ignorable files.
• Stop with blocked if name is missing.
• Stop with blocked if the requested testing mode cannot be honored or guaranteed by the active swift package init command.

Fallbacks and Handoffs

• Preferred path is always scripts/bootstrap_swift_package.sh.
• Use manual swift package init guidance only when the script is unavailable or the user explicitly asks for the manual path.
• tool is an advanced explicit passthrough, not a default branch of the workflow.
• Within the supported Swift 6.2 or newer floor, prefer current swift package init testing flags when the active toolchain exposes them; only rely on the older default XCTest template when xctest is requested and the active swift package init command exposes no testing-selection flags at all.
• After a successful scaffold, hand off ordinary package execution tasks to swift-package-build-run-workflow or swift-package-testing-workflow.
• After a successful scaffold, hand off Xcode-managed package build or run tasks to xcode-build-run-workflow.
• After a successful scaffold, hand off Xcode-managed package test tasks to xcode-testing-workflow.
• After a successful scaffold, use scripts/repo-maintenance/validate-all.sh for local maintainer validation and scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z from a feature branch or worktree for protected-main releases.
• After a successful scaffold, configure protected branches to require validate for the managed repo-maintenance workflow; GitHub exposes that job check context directly rather than the workflow title plus job string.
• When the new package is published to GitHub, use repository-skills:maintain-github-repository to audit repository features, merge modes, security automation, sign-off policy, and branch protection.
• After a successful scaffold, hand off later repo-guidance alignment work to sync-swift-package-guidance.
• For ordinary package work, prefer swift build and swift test.
• For package builds that need Xcode-managed SDK or toolchain behavior, use xcode-build-run-workflow and xcodebuild guidance instead of stretching the bootstrap skill into an execution skill.
• Recommend explore-apple-swift-docs directly when the user’s next step is Apple or Swift docs exploration or Dash-compatible docs management.
• scripts/run_workflow.py is the top-level runtime entrypoint and converts the shell script result into the documented JSON contract.

Customization

• Use references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• scripts/run_workflow.py loads runtime-safe defaults from customization state before invoking the shell script.
• scripts/bootstrap_swift_package.sh now honors the wrapper's git and AGENTS.md copy flags.
• Run the Python wrapper and customization entrypoints through uv, because they rely on inline PyYAML script metadata rather than a repo-global Python environment.
• In consuming repos, the supported path is uv run scripts/run_workflow.py ... and uv run scripts/customization_config.py ...; do not assume plain python or python3 will have the needed YAML dependency installed.

References

Workflow References

• references/package-types.md

Contract References

• references/automation-prompts.md
• references/customization-flow.md

Support References

• Recommend references/snippets/apple-swift-package-core.md when the new package repo should start with reusable SwiftPM baseline policy content next to the generated AGENTS.md.
• assets/AGENTS.md
• references/snippets/apple-swift-package-core.md

Script Inventory

• scripts/run_workflow.py
• scripts/bootstrap_swift_package.sh
• scripts/customization_config.py