---
name: build-ios-app
description: "Develops iOS apps using Swift and SwiftUI with xtool."
---

## CONTEXT & OBJECTIVE
You are an expert iOS Swift/SwiftUI developer and automation assistant.
The environment is Windows (via WSL2/PowerShell) or Linux.
The developer uses AI-driven coding ("vibe coding") and relies ONCE AND ONLY ONCE on `xtool` to compile, sign, and deploy iOS applications directly to a physical iPhone connected via USB.
---

## WORKFLOW RULES

### 1. Code Generation Constraints
- Write ALL UI components natively in **pure SwiftUI** (no Storyboards, no XIBs).
- Ensure the project strictly uses **Swift Package Manager (SwiftPM)** with a valid `Package.swift` or standard Xcode-compatible folder structure.
- Never suggest opening Xcode or using macOS Simulators. All UI/UX validation happens on the connected physical device.

---

## 2. AUTONOMOUS REVIEW & FIX LOOP

```
    ┌────────────────────────────────────────────────────────┐
    │ 1. GENERATE / EDIT CODE (SwiftUI / SwiftPM)            │
    └───────────────────────────┬────────────────────────────┘
                                │
                                ▼
    ┌────────────────────────────────────────────────────────┐
    │ 2. DEPLOY TO IPHONE (`xtool run`)                       │
    └───────────────────────────┬────────────────────────────┘
                                │
                                ▼
    ┌────────────────────────────────────────────────────────┐
    │ 3. REVIEW PHASE (Syntax, Build Logs, Device Output)    │
    └───────────────────────────┬────────────────────────────┘
                                │
                     ┌──────────┴──────────┐
                     │ Meets Expectations? │
                     └────┬───────────┬────┘
                       NO │           │ YES
                          │           │
                          ▼           ▼
               [ Auto-Fix & Loop ]   [ EXIT & NOTIFY USER ]
```

### Reviewer Gate Rules
- **Loop Condition:** Continue fixing and deploying automatically as long as errors or unmet requirements exist.
- **Exit Condition:** Stop looping ONLY when:
  1. The code builds and deploys to the physical iPhone with exit code `0`.
  2. All functional constraints defined in the prompt are met.
- **User Hand-Off:** Once the loop exits, inform the user:
  > *"Review completed and satisfied. App deployed to your iPhone. Please test the physical interactions on your device!"*

---

## 3. COMMAND CHEATSHEET (xtool CLI)

### Prerequisites Check
Before running build commands, verify device connectivity and credentials:
```bash
# Check connected iOS devices
xtool device list

# Pair/Pairing status with physical iPhone
xtool device pair
```

### Build & Deploy Loop
To compile, sign, and install the app on the physical iPhone in one step:
```bash
# General Build & Run command
xtool run --device <DEVICE_ID_OR_NAME>
```

### Project Setup & Provisioning
When initializing a new app or fixing signing issues:
```bash
# Sign application bundle with Apple Developer Account
xtool sign --team-id <APPLE_TEAM_ID> --bundle-id com.example.appname
```

---

## 4. TROUBLESHOOTING & COMMON FAULTS

### Issue A: "Device Locked / Untrusted"
- **Symptom:** `xtool` fails to communicate with the iPhone over USB.
- **Fix:** Unlock the iPhone, accept the "Trust This Computer" prompt, and re-run `xtool device pair`.

### Issue B: Developer Mode Disabled (iOS 16+)
- **Symptom:** App installs but fails to launch.
- **Fix:** On iPhone, go to **Settings > Privacy & Security > Developer Mode** and turn it ON. Restart device if prompted.

### Issue C: Code Signing / Provisioning Error
- **Symptom:** `xtool` fails at the signing stage.
- **Fix:** Verify Apple Team ID configuration. Ensure the device UDID is added to the Apple Developer portal under test devices.