Sync Swift Package Guidance

Purpose

Bring an existing Swift package repository up to the expected guidance baseline without stretching the package bootstrap skill into an ongoing repo-guidance surface. This skill owns deterministic AGENTS.md creation or bounded section append behavior for existing SwiftPM repos and runs maintain-project-repo with the swift-package profile alongside that guidance. scripts/run_workflow.py is the runtime entrypoint, and scripts/sync_swift_package_guidance.py applies the current sync behavior.

Companion Plugin Requirement

This skill can be discovered from a standalone apple-dev-skills install, but its mutating guidance-sync path refreshes repo-maintenance files through the companion productivity-skills plugin. Before giving filesystem-level fallback instructions, first check the skills exposed in the current Codex session and use the harness-discovered productivity-skills:maintain-project-repo workflow when it is available. If the companion skill is not exposed, tell the user to add the socket marketplace with codex plugin marketplace add gaelic-ghost/socket, then install the relevant plugins from Codex's plugin directory so future sessions expose both apple-dev-skills and productivity-skills.

When To Use

• Use this skill when an existing Swift package repo needs AGENTS.md added, refreshed, or merged with the current SwiftPM workflow baseline.
• Use this skill when the repository already has Package.swift and the user wants package workflow guidance, onboarding rules, or repo policy brought up to date.
• Use this skill when the user wants the repo guidance that used to be implied by the Swift package bootstrap flow to be made explicit in an existing package repo.
• Do not use this skill for brand-new package creation from nothing.
• Do not use this skill for ordinary package development, builds, tests, diagnostics, or dependency changes.
• Do not use this skill for Xcode app repos, workspaces, or native Apple app projects.
• Recommend bootstrap-swift-package when the package repo does not exist yet.
• Recommend swift-package-build-run-workflow or swift-package-testing-workflow when the task is ordinary package execution rather than repo guidance sync.
• Recommend xcode-build-run-workflow when the task is Xcode-managed package build, run, toolchain, Metal, or mutation work rather than repo guidance sync.
• Recommend xcode-testing-workflow when the task is Xcode-managed package test execution or test diagnosis rather than repo guidance sync.
• Recommend sync-xcode-project-guidance when the repo is an Xcode app project instead of a plain Swift package.
• After updating this plugin's package-policy surfaces, recommend rerunning sync-swift-package-guidance in downstream repos so their AGENTS.md and maintain-project-repo output stay aligned.
• For maintainer notes about this repository itself, say plainly that the repo exports from top-level skills/ today and does not ship repo-local installer workflows.

Single-Path Workflow

1. Collect the required inputs:
   • repo_root
   • optional skip_validation
   • optional dry_run
2. Classify the request as existing Swift package guidance sync before continuing:
   • continue only when the repo already contains Package.swift
   • stop if the request is really new-package bootstrap or Xcode app-repo guidance sync
   • stop if the repo boundary is ambiguous because both package and Xcode app markers are present at the same root
3. Apply the Apple and Swift docs gate before shaping workflow guidance:
   • read the relevant SwiftPM and Swift documentation first
   • prefer Dash or local Swift docs first, then official Swift or Apple web docs when needed
   • state the documented workflow boundary being relied on before proposing repo guidance changes
   • current documented anchors for this workflow include:
     • Swift Package Manager overview: Swift Package Manager
     • package manifest structure: PackageDescription
     • package manifest entrypoint: Package
   • if the docs and the current guidance template conflict, stop and report that conflict
   • if no relevant SwiftPM docs can be found, say that explicitly before proceeding
4. Apply the shared Swift-package policy before making repo-guidance changes:
   • apply the detailed local policy in references/snippets/apple-swift-package-core.md
   • preserve its explicit swiftLanguageModes: [.v6] package-manifest default and prefer that spelling over the legacy swiftLanguageVersions alias on current manifest surfaces
   • preserve its default swift-configuration package guidance: depend on https://github.com/apple/swift-configuration from 1.2.0, enable .defaults, Reloading, YAML, and CommandLineArguments, and add the Configuration product to the primary target unless the package has a concrete reason to remove it
   • preserve its optional swift-configuration trait note: PropertyList is available for property-list configuration parsing, and Logging is available when configuration access should integrate with SwiftLog.Logger
   • preserve its simplicity-first Swift, SwiftPM, logging, telemetry, testing, package-resource, Metal handoff, and Debug/Release guidance
5. Run scripts/run_workflow.py to normalize inputs, detect whether the repo is really SwiftPM-managed, and shape the sync plan.
6. Apply the sync path:
   • if AGENTS.md is missing, copy assets/AGENTS.md
   • if AGENTS.md exists and already contains the managed section, keep the file unchanged
   • if AGENTS.md exists but lacks the managed section, append assets/append-section.md as a bounded section
7. Validate the synced repo guidance:
   • verify AGENTS.md exists
   • verify the synced file mentions bootstrap-swift-package
   • verify the synced file mentions sync-swift-package-guidance
   • verify the synced file preserves swift build and swift test as default validation paths
8. Refresh maintain-project-repo:
   • refresh scripts/repo-maintenance/
   • refresh .github/workflows/validate-repo-maintenance.yml
   • preserve repo-specific extra scripts that are not part of the managed file set
9. Verify the synced maintenance guidance still points at the expected maintainer files:
   • .swiftformat
   • scripts/repo-maintenance/hooks/pre-commit.sample
   • scripts/repo-maintenance/validate-all.sh
   • scripts/repo-maintenance/sync-shared.sh
   • scripts/repo-maintenance/release.sh
   • protected branches, when configured, require the GitHub Actions check context validate rather than Validate Repo Maintenance / validate
10. Hand off ongoing package work cleanly:

• prefer swift-package-build-run-workflow or swift-package-testing-workflow for ordinary package work after guidance sync
• recommend xcode-build-run-workflow or xcode-testing-workflow only when package work needs Xcode-managed SDK, toolchain, or test behavior
• recommend bootstrap-swift-package only when the user actually needs a fresh repo instead of guidance sync

Inputs

• repo_root: optional absolute or relative path to the repository root; defaults to .
• skip_validation: optional flag to skip post-sync file validation
• dry_run: optional flag to emit the planned contract without writing files
• Defaults:
  • runtime entrypoint: executable scripts/run_workflow.py
  • repo_root=. when omitted
  • writeMode=sync-if-needed
  • validation runs unless --skip-validation is passed
  • successful mutating runs refresh maintain-project-repo output in place

Outputs

• status
  • success: guidance sync completed or was already satisfied
  • blocked: prerequisites, repo classification, or sync policy prevented completion
  • failed: the sync path started but did not complete successfully
• path_type
  • primary: the documented sync path completed
  • fallback: a non-mutating guided result was returned
• output
  • resolved repo root
  • detected package and Xcode markers
  • AGENTS.md path
  • actions applied or planned
  • refreshed maintain-project-repo paths
  • validation result
  • one concise next step or handoff

Guards and Stop Conditions

• Stop with blocked if the repo root cannot be resolved.
• Stop with blocked if the repo does not contain Package.swift.
• Stop with blocked if the repo root looks ambiguous because it contains both Package.swift and Xcode app markers.
• Stop with blocked if the chosen writeMode does not allow the mutation the repo still needs, such as creating a missing AGENTS.md or appending the bounded Swift package guidance section.
• Stop with blocked if the target AGENTS.md path exists but is not a regular file.

Fallbacks and Handoffs

• The only current fallback is a non-mutating dry-run or guided result that explains what the sync would do.
• After a successful sync, use swift-package-build-run-workflow or swift-package-testing-workflow for ordinary package work by default.
• After a successful sync, 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 sync, 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.
• Recommend xcode-build-run-workflow when package work needs Xcode-managed SDK or toolchain behavior.
• Recommend xcode-testing-workflow when package work needs Xcode-managed test execution behavior.
• Recommend bootstrap-swift-package when the repository still needs to be created from scratch.
• Recommend sync-xcode-project-guidance when the repo root is really an Xcode app project rather than a plain Swift package.

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 supported sync path.
• The current runtime-enforced customization surface is one writeMode knob that controls whether the workflow may create missing AGENTS.md, append the bounded Swift package section, or stay report-only.
• 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/project-detection.md

Contract References

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

Support References

• assets/AGENTS.md
• assets/append-section.md
• Recommend references/snippets/apple-swift-package-core.md when an existing Swift package repo needs the reusable baseline policy content in a human-reviewable form.
• references/snippets/apple-swift-package-core.md

Script Inventory

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