Update to Tuist

{
  "name": "migrate",
  "description": "Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.",
  "included_files": [],
  "skill_md_contents": "---\nname: migrate\ndescription: Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.\n---\n\n# Migrating to Tuist Generated Projects\n\n## Quick Start\n\n1. Baseline build and run the app with xcodebuild.\n2. Inventory targets, build settings, and external dependencies.\n3. Create `Tuist.swift`, `Project.swift`, and `Tuist/Package.swift`.\n4. Extract settings into `.xcconfig` files and wire them in `Project.swift`.\n5. Generate and build: `tuist generate --no-open` then `xcodebuild build`.\n6. Fix build issues, regenerate, and validate runtime on a simulator.\n\n## Preflight Checklist\n\n- Primary app scheme and any extension/test schemes\n- Targets list (app, extensions, tests, helper tools)\n- Deployment targets and bundle identifiers\n- Info.plist locations and entitlements\n- Custom build settings (per target and per configuration)\n- External dependencies (SPM, XCFrameworks, local packages)\n- Build scripts (SwiftGen, Sourcery, codegen)\n- Runtime validation plan (simulator destination and launch command)\n\n## Outputs\n\n- `Project.swift` and `Tuist.swift`\n- `Tuist/Package.swift` for external dependencies\n- `.xcconfig` files (optional but recommended)\n- Build and runtime validation notes\n- A short migration log of decisions and fixes\n\n## Migration Workflow\n\n### 1. Baseline the project\n\nStart by proving the current project builds and runs. Capture the command you use so the generated workspace can be validated the same way.\n\n```bash\nxcodebuild build \\\n  -project App.xcodeproj \\\n  -scheme App \\\n  -configuration Debug \\\n  -destination \"generic/platform=iOS Simulator\" \\\n  -derivedDataPath DerivedDataBaseline\n```\n\n### 2. Map targets and settings\n\nList every target and its role. Extract build settings into `.xcconfig` files when they are large or shared across targets. Keep deployment targets and bundle identifiers identical to the original project to avoid runtime surprises.\n\n### 3. Add Tuist manifests\n\nCreate the manifests and keep them minimal and close to the existing project.\n\n- `Tuist.swift`: enable generation options you need and keep them explicit.\n- `Project.swift`: define targets, sources, resources, scripts, and dependencies.\n- `Tuist/Package.swift`: list external dependencies and map product types.\n\nUse `.external` for third-party dependencies to keep the graph consistent.\n\n### 4. Handle sources and resources carefully\n\nBe precise here. Small mistakes often cause large failures later.\n\n- `.intentdefinition` files belong in `sources`, not `resources`.\n- `.xcstrings` should remain the primary localization source. Avoid double-including `.strings` or `.stringsdict` from overlapping globs.\n- Use `.folderReference` for bundles like `Settings.bundle`.\n- If a resource bundle is missing, ensure the package target declares `.process(\"Resources\")`.\n\n### 5. Generate and build\n\n```bash\ntuist install\ntuist generate --no-open\nxcodebuild build \\\n  -workspace App.xcworkspace \\\n  -scheme App \\\n  -configuration Debug \\\n  -destination \"generic/platform=iOS Simulator\" \\\n  -derivedDataPath DerivedDataTuist\n```\n\n### 6. Resolve build issues iteratively\n\nCommon fixes you will likely need:\n\n- **Missing SDK frameworks**: add `.sdk(name: ..., type: .framework)`.\n- **SPM resource bundles**: verify `.process(\"Resources\")` and `Bundle.module` usage.\n- **File-system-synchronized groups**: avoid over-excluding directories; compare with the pbx if a type vanishes.\n- **Invalid bundle identifiers**: override with `PackageSettings` or vendor a local package.\n- **Generated sources**: ensure codegen outputs (SwiftGen/Sourcery) are part of the build.\n\n### 7. Validate runtime\n\nA build is not enough; launch the app on a simulator.\n\n```bash\nxcrun simctl boot \"iPhone 17 Pro\"\nxcrun simctl install booted DerivedDataTuist/Build/Products/Debug-iphonesimulator/App.app\nxcrun simctl launch booted com.example.app\n```\n\n## Common Failure Patterns\n\n- **Type not found**: a source file or entire directory was excluded accidentally.\n- **Copy Bundle Resources errors**: Swift files are being treated as resources; fix the resource globs.\n- **Localization conflicts**: `.xcstrings` colliding with `.strings` globs.\n- **Undefined symbols**: missing SDK frameworks or dependency products.\n- **Unrecognized selector at launch**: ObjC categories in static frameworks were stripped. Add `-ObjC` to `OTHER_LDFLAGS` or `-force_load` for the library that defines the category.\n- **Runtime crash on launch**: mismatched bundle id, missing entitlements, or miswired resources.\n\n## Migration Notes to Capture\n\n- What changed in `Project.swift` and why\n- Any exclusions or overrides (and the reason)\n- Dependency patches or local vendoring\n- The exact build and run commands used for validation\n\n## Done Checklist\n\n- Generated workspace builds cleanly\n- App launches on simulator without immediate crash\n- All targets and extensions build\n- Dependencies are wired through `.external`\n- Settings match the original Xcode project\n"
}