Xcode File Manager Skill

This skill handles adding and removing Swift files in the AIQ Xcode project using the xcodeproj Ruby gem.

When to Use This Skill

Use this skill whenever you:

• Create a new Swift file in the ios/AIQ/ directory
• Create a new test file in the ios/AIQTests/ directory
• Need to add existing Swift files to the Xcode project
• Need to remove dead or deleted Swift files from the Xcode project

How to Add Files

Using the Existing Script

There is a reusable Ruby script at ios/scripts/add_files_to_xcode.rb. Use it like this:

cd ios && ruby scripts/add_files_to_xcode.rb <relative_path_to_file>

Examples:

# Add a single file
cd ios && ruby scripts/add_files_to_xcode.rb AIQ/ViewModels/NewViewModel.swift

# Add multiple files
cd ios && ruby scripts/add_files_to_xcode.rb AIQ/Views/NewView.swift AIQ/ViewModels/NewViewModel.swift

# Add a test file (automatically added to AIQTests target)
cd ios && ruby scripts/add_files_to_xcode.rb AIQTests/NewTests.swift

File Path Convention

• Paths must be relative to the ios/ directory
• The script uses the directory structure to find the correct Xcode group
• Files in AIQ/ are added to the main AIQ target
• Files in AIQTests/ are added to the AIQTests target

Common Directories

New feature modules go under AIQ/Features/<Module>/{Views,ViewModels}/ (e.g., AIQ/Features/Dashboard/Views/). Use /xcode-group-manager to create the group hierarchy first.

Directory	Purpose	Target
AIQ/Features/<Module>/Views/	SwiftUI views for a feature module	AIQ
AIQ/Features/<Module>/ViewModels/	View models for a feature module	AIQ
AIQ/Views/	Legacy/shared SwiftUI views (not under a feature module)	AIQ
AIQ/ViewModels/	Legacy/shared view models (not under a feature module)	AIQ
AIQ/Models/	Data models	AIQ
AIQ/Services/	API and business services	AIQ
AIQ/Utilities/	Helper utilities	AIQ
AIQTests/	Unit tests	AIQTests

Creating New Groups

If you need to add a file to a group that does not yet exist in the Xcode project, use the /xcode-group-manager skill first to create the group hierarchy, then run this skill to add the files.

# Step 1: Create the missing group
cd ios && ruby scripts/manage_xcode_groups.rb --create-group AIQ/Features/Auth/Views

# Step 2: Then add the file normally
cd ios && ruby scripts/add_files_to_xcode.rb AIQ/Features/Auth/Views/LoginView.swift

Why: If the group is missing, add_files_to_xcode.rb silently places the file under the root AIQ group with an incorrect path, which causes "Build input files cannot be found" build failures. Always create the group first.

Verifying path attributes after adding files

After running add_files_to_xcode.rb for files in nested groups (e.g., AIQ/Features/Test/Views/), verify the PBXFileReference in project.pbxproj uses the full relative path — not just the filename. The script sometimes registers path = Filename.swift instead of path = Features/Module/Views/Filename.swift, which causes "Build input file cannot be found" errors. Compare against sibling files in the same group to confirm the format includes name = Filename.swift; path = Features/....

Migrating existing files to a new location

When files are already registered in the Xcode project and you're moving them (e.g., from AIQ/Views/X.swift to AIQ/Features/Y/Views/X.swift), add_files_to_xcode.rb detects the existing file reference by filename and moves it into the new group — but does not update its path attribute. This results in the file resolving to the wrong filesystem location and a "Build input files cannot be found" failure.

After running the add + remove scripts for a migration, verify the updated file references use the full relative path pattern:

name = Filename.swift; path = Features/Module/Views/Filename.swift; sourceTree = "<group>";

Compare against a known-good reference (e.g., WelcomeView.swift under Features/Auth/Views/) to confirm the format. If path attributes are wrong or missing the subdirectory, update them manually in ios/AIQ.xcodeproj/project.pbxproj before building.

How to Remove Files

There is a reusable Ruby script at ios/scripts/remove_files_from_xcode.rb. Use it like this:

cd ios && ruby scripts/remove_files_from_xcode.rb <relative_path_to_file>

Examples:

# Remove a single file (deletes from project and disk)
cd ios && ruby scripts/remove_files_from_xcode.rb AIQ/ViewModels/OldViewModel.swift

# Remove multiple files
cd ios && ruby scripts/remove_files_from_xcode.rb AIQ/Views/OldView.swift AIQ/ViewModels/OldViewModel.swift

# Remove from project only, keep file on disk
cd ios && ruby scripts/remove_files_from_xcode.rb --keep-files AIQ/openapi.json

The script:

• Removes the file reference from project.pbxproj
• Removes all build phase entries (Sources, Resources, etc.) across every target
• Deletes the file from disk (unless --keep-files is passed)

Warning: Disk deletion is permanent. Ensure the file is committed to git before running without --keep-files.

Note: The remove script does not stage any changes in git. After running the script, you must stage changes manually before committing:

• Without --keep-files: git add <path/to/file> ios/AIQ.xcodeproj/project.pbxproj
• With --keep-files: git add ios/AIQ.xcodeproj/project.pbxproj

Options

Flag	Effect
(none)	Remove from project and delete from disk
--keep-files	Remove from project only; file is not deleted

Prerequisites

The xcodeproj gem must be installed:

gem install xcodeproj

Troubleshooting

• "Group not found": The directory structure in the file path must match the group structure in the Xcode project
• "File already in project": The file reference already exists; the script will skip it unless the path is incorrect
• "File not found": The Swift file must exist on disk before running the add script
• "File not found in project": The file reference doesn't exist in the project; nothing to remove