---
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 [`productivity-skills`](https://github.com/gaelic-ghost/productivity-skills) plugin. If the companion `maintain-project-repo` runner is missing, tell the user to install `productivity-skills` alongside `apple-dev-skills`, or add the [`socket`](https://github.com/gaelic-ghost/socket) marketplace with `codex plugin marketplace add gaelic-ghost/socket` and then install or enable both `apple-dev-skills` and `productivity-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 a supported and validated Swift toolchain from the current window, currently `6.3.x` and `6.2.x`, before bootstrap planning continues because the generated manifest uses PackageDescription package traits for the default `swift-configuration` dependency
   - 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:
   ```bash
   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`
   - `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`
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 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 `6.2` while the current supported window is Swift `6.3.x` and `6.2.x`
   - 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 window is Swift `6.3.x` and `6.2.x`
  - 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 `6.2` while the current supported window is Swift `6.3.x` and `6.2.x`
  - `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 `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.3.x` and `6.2.x` window, 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.
- 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`