XCode-Claude-Workflow/INSTRUCTIONS.md

Converting a Web App to iOS / iPadOS / macOS

Step-by-step instructions for using the XCode-Claude-Workflow to convert any web-based project (React, HTML5, Vue, vanilla JS, etc.) into a native SwiftUI app.

Prerequisites

• Xcode 16.3+ installed
• xcodegen installed (brew install xcodegen)
• Claude Code running in your terminal or IDE
• A Forgejo/GitHub account for the new repo
• The source project folder on your local machine

Steps

1. Create a new repo for the app

On your Forgejo (or GitHub) instance, create an empty repo. Use a descriptive name:

MyApp-iOS-iPadOS-MacOS

Clone it locally:

cd ~/Documents/FORGEJO
git clone https://git.istratai.cloud/aj/MyApp-iOS-iPadOS-MacOS.git
cd MyApp-iOS-iPadOS-MacOS

2. Copy the workflow prompt

cp ~/Documents/FORGEJO/XCode-Claude-Workflow/PROMPT.md .

3. Open Claude Code in the new repo

claude

Or open the folder in VS Code / Cursor with Claude Code extension.

4. Start the workflow

Tell Claude:

@PROMPT.md execute this prompt

Claude will ask for the target platform (iOS, macOS, etc.) and then ask you to point to the source code folder. Provide the full path:

/Users/macpro2019/Documents/FORGEJO/my-web-app/

5. Follow the 8 phases

Claude will walk you through each phase and ask for approval before proceeding:

Phase	What Happens	Your Role
0 — Audit	Reads every file, produces audit report	Review and approve
1 — Architecture	Proposes MVVM/TCA, scaffolds Xcode project	Choose architecture, confirm
2 — Features	Implements one feature at a time with tests	Test in Simulator after each
3 — Persistence	Adds SwiftData, auto-save, preferences	Verify save/resume works
4 — Accessibility	VoiceOver, Dynamic Type, localization	Test with VoiceOver on
5 — Quality	Static analysis, 70%+ test coverage	Review test results
6 — App Store	Privacy manifest, icons, metadata	Provide App Store details
7 — Documentation	SETUP.md, CHANGELOG.md, ARCHITECTURE.md	Review and commit

6. Test on simulators

# Generate Xcode project
xcodegen generate

# Build and run on iPhone
xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16'

# Build and run on iPad
xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPad Pro 11-inch (M4)'

# Build and run on Mac
xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
  -destination 'platform=macOS' CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO

Or just open the .xcodeproj in Xcode and press Cmd+R.

7. Commit and push

git add -A
git commit -m "feat: MyApp v1.0.0 — native SwiftUI for iOS, iPadOS, macOS"
git push origin main

Tips

• Don't rush — approve each phase before moving on. Quality > speed.
• Test on device — Simulator is good but real devices catch touch/scroll issues.
• Screenshot everything — share screenshots with Claude when something looks off. It will fix the layout.
• Landscape matters — always test both orientations on iPhone.
• Start a new game/session — if Claude's context gets too long, start a new conversation and point it to the repo + PROMPT.md again. It will pick up where you left off.
• Keep PROMPT.md in the app repo — it serves as documentation of the conversion methodology used.

Template repo

The workflow template lives at:

https://git.istratai.cloud/aj/XCode-Claude-Workflow

Example project

SoliCards (solitaire card game) was converted using this exact workflow:

Source:  https://git.istratai.cloud/aj/game-SoliCards
Result:  https://git.istratai.cloud/aj/SoliCards-iOS-iPadOS-MacOS