migrate-xcode-project-to-xcodegen

name

migrate-xcode-project-to-xcodegen

description

Migrate or modernize native Apple app projects into the current XcodeGen baseline. Use when an existing macOS, iOS, or iPadOS app has a hand-managed .xcodeproj that should become XcodeGen-managed, when an existing project.yml is stale or broken, when Xcode GUI build settings/capabilities must be promoted into .xcconfig, .entitlements, Info.plist, schemes, test plans, or resource files before regeneration, or when Codex needs a safe non-destructive audit before running xcodegen generate.

Migrate Xcode Project To XcodeGen

Purpose

Convert existing native Apple app projects to the current XcodeGen baseline without losing user-made Xcode GUI changes. This skill owns migration planning, project-state inventory, promotion of generated .pbxproj state into tracked source files, and validation before any generated project is replaced.

When To Use

• Use this skill when an existing Xcode-managed app project should move to XcodeGen.
• Use this skill when an existing project.yml should be modernized to the current baseline: synced folders, external .xcconfig layers, external entitlements, default asset catalog, and current Swift/Xcode build settings.
• Use this skill before regenerating an .xcodeproj when the repository has tracked .pbxproj changes from Xcode, XcodeGen, or another project-aware tool.
• Use this skill when Xcode GUI edits need to be moved back into project.yml, .xcconfig, .entitlements, Info.plist, .xcscheme, .xctestplan, or resources.
• Do not use this skill for brand-new app bootstrap; use bootstrap-xcode-app-project.
• Do not use this skill for ordinary build, run, diagnostics, previews, or file edits after migration; use xcode-build-run-workflow.
• Do not use this skill for test diagnosis except to preserve test-plan and test-target project state during migration; use xcode-testing-workflow for active testing work.
• Do not use this skill for plain Swift packages.

Single-Path Workflow

1. Collect the required inputs:
   • repo_root
   • optional project_path
   • optional project_yml
   • optional mode
   • optional dry_run
2. Apply the Apple docs gate before proposing migration changes:
   • read the relevant Apple documentation first
   • use Xcode MCP DocumentationSearch first for Xcode project, build setting, asset catalog, signing, entitlement, and scheme behavior
   • use the Dash.app MCP second when its installed docsets cover the question; use Dash HTTP only when that MCP is unavailable or incomplete
   • use XcodeGen's official docs or source repository for XcodeGen-specific behavior such as synced folders, source entries, configs, schemes, packages, and generated project output only after those local MCP paths
   • state the documented behavior being relied on before proposing edits
   • if no relevant Apple or XcodeGen docs can be found, say that explicitly before proceeding
3. Run scripts/run_workflow.py from this skill to inventory the current repo and choose the migration path.
4. Classify the migration:
   • xcode-managed-to-xcodegen: repo has an .xcodeproj or .xcworkspace and no meaningful project.yml
   • modernize-xcodegen: repo already has project.yml
   • blocked: repo lacks enough project evidence or the requested mode conflicts with discovered files
5. Review the audit output before writing:
   • treat tracked .pbxproj diffs as intentional user/project state until reviewed
   • identify build settings that need .xcconfig owners
   • identify entitlements that need checked-in .entitlements owners
   • identify Info.plist values that need checked-in plist or build-setting owners
   • identify resources and asset catalogs that must be preserved under the broad app source root or under one separate top-level resource root when the repo actually has that shape
   • identify schemes and test plans that need explicit tracked files
6. Prepare the migration branch:
   • add or update project.yml
   • add or update Configurations/*.xcconfig
   • add or preserve the standard top-level directories: Sources/, Tests/, Shared/, Extensions/, Configurations/, Scripts/, and Packages/
   • add or update Sources/Support/<AppName>.entitlements
   • add or update Sources/Support/Info.plist
   • add or update Sources/Resources/Assets.xcassets
   • keep the app target's XcodeGen source declaration collapsed to one top-level Sources entry, shared app/extension code collapsed to one top-level Shared entry, and the test target's declaration collapsed to one top-level Tests entry
   • preserve exactly one app lifecycle entry point; do not create alternate @main app types, duplicate main.swift files, target-specific app entry files, or parallel app structs for variants
   • preserve existing package, framework, source, resource, script phase, scheme, and test-plan state
7. Generate into a temp or reviewed branch state:
   • run xcodegen generate only after promoted state is represented in tracked source files
   • never treat generated .pbxproj deletion or replacement as cleanup until the promoted files and generated result have been reviewed
8. Validate equivalence:
   • run xcodebuild -list
   • run xcodebuild -showBuildSettings for the main app target and compare key values against the pre-migration audit
   • run a Debug build when practical
   • run tests or at least xcodebuild test -list-tests when the repo has test targets
9. Hand off after migration:
   • use sync-xcode-project-guidance to refresh repo guidance when needed
   • use xcode-build-run-workflow for normal build/run work
   • use xcode-testing-workflow for test execution and diagnosis

Inputs

• repo_root: optional absolute or relative repository root; defaults to .
• project_path: optional .xcodeproj or .xcworkspace path when discovery is ambiguous
• project_yml: optional XcodeGen spec path; defaults to project.yml under repo_root when present
• mode: auto, xcode-managed, or xcodegen-modernize; defaults to auto
• dry_run: optional flag; the audit workflow is non-mutating by default, so this mainly documents intent
• Defaults:
  • runtime entrypoint: executable scripts/run_workflow.py
  • audit implementation: scripts/migrate_xcode_project_to_xcodegen.py
  • no files outside the audit output are changed by the script
  • migration edits are performed by Codex after reviewing audit output and user intent

Outputs

• status
  • success: project evidence was discovered and a migration plan was produced
  • blocked: required project evidence was missing or inconsistent with the requested mode
  • failed: the audit script could not inspect the repo
• path_type
  • primary: a supported migration or modernization path was identified
  • fallback: a non-mutating diagnostic result was returned
• output
  • resolved repo root
  • discovered Xcode project/workspace/spec/config markers
  • inferred migration path
  • XcodeGen baseline gaps
  • build settings that should be promoted to .xcconfig
  • entitlement, Info.plist, asset catalog, scheme, and test-plan evidence
  • recommended migration phases
  • validation commands to run after generation

Guards and Stop Conditions

• Stop with blocked if repo_root cannot be resolved.
• Stop with blocked if no .xcodeproj, .xcworkspace, or project.yml is discovered.
• Stop with blocked if the user asks for Xcode-managed conversion but no project file is present.
• Stop with blocked if the user asks for XcodeGen modernization but no project.yml is present.
• Stop before running xcodegen generate if tracked .pbxproj changes have not been reviewed and promoted or explicitly preserved.
• Stop before replacing an .xcodeproj if generated output has not been compared against the audit and build settings.
• Stop before deleting legacy project files, schemes, configs, entitlements, or resources unless the replacement owner is tracked and validated.

Fallbacks and Handoffs

• If project discovery is ambiguous, rerun the audit with --project-path or --project-yml.
• If the repo is a new project request, hand off to bootstrap-xcode-app-project.
• If the repo only needs guidance refresh, hand off to sync-xcode-project-guidance.
• If a migration uncovers build or test failures unrelated to project generation, hand off to xcode-build-run-workflow or xcode-testing-workflow.
• If the XcodeGen baseline cannot represent a project feature cleanly, preserve the hand-managed project and report the unsupported feature instead of forcing conversion.

Customization

• Use references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• The current runtime-enforced customization surface is intentionally minimal; migration should be driven by discovered project state and explicit user intent rather than persistent broad defaults.
• Run the Python wrapper and customization entrypoints through uv when using customization commands, because repo skill scripts may rely on inline script metadata or local dependencies.

References

Workflow References

• references/migration-audit-and-promotion.md

Contract References

• references/customization-flow.md

Support References

• Recommend references/snippets/apple-xcode-project-core.md when an existing Xcode repo needs the reusable baseline policy content in a human-reviewable form.
• references/snippets/apple-xcode-project-core.md
• bootstrap-xcode-app-project/references/xcodegen-synced-folder-and-config-notes.md
• bootstrap-xcode-app-project/references/project-generators.md

Script Inventory

• scripts/run_workflow.py
• scripts/migrate_xcode_project_to_xcodegen.py
• scripts/customization_config.py