Run

---
name: run
description: Build, install, and run the app on a target device (auto-detects platform)
argument-hint: "[--no-install] [--device <target>] [--variant <variant>]"
---

# Run App

Build, install, and launch the application on a target device. Auto-detects the project platform and build system.

## Arguments

Parse `$ARGUMENTS` for named flags:
- `--no-install` — Skip the install step (assume already installed)
- `--device <target>` — Target device. Values:
  - **Android**: `emulator`, `physical`, or a device serial from `adb devices`
  - **iOS**: `simulator`, `physical`, or a device UDID
  - **Web**: `chrome`, `firefox`, `safari`, `edge`
  - **Flutter**: any `flutter devices` id
- `--variant <variant>` — Build variant (e.g. `debug`, `release`, `demo`). Defaults to `debug`. Passed through to `/skills:install`.

## Platform Detection (Parallel)

Launch parallel agents to detect the project platform:

**Agent 1 — Android**:
Check for: `build.gradle.kts` or `build.gradle` containing `android`, `AndroidManifest.xml`

**Agent 2 — iOS**:
Check for: `*.xcodeproj`, `*.xcworkspace`, `Podfile`, `Package.swift` with iOS platform

**Agent 3 — Web**:
Check for: `package.json` with `dev`/`start` script, `deno.json`, `composer.json`, `Gemfile`

**Agent 4 — Cross-platform**:
Check for: `pubspec.yaml` (Flutter), `build.gradle.kts` with `kotlin("multiplatform")` (KMP)

## Execution

### 1. Install (unless `--no-install`)

Run the `/skills:install` command with the resolved device target. This handles build + install.

### 2. Resolve Device

Determine the target device for launching:

**Android:**
1. `adb devices -l`
2. Match `--device` value:
   - `emulator` → device line containing `emulator`
   - `physical` → device line NOT containing `emulator`
   - Serial string → exact match
   - No value, one device → use it
   - No value, multiple devices → ask the user which to target
3. Extract serial for `adb -s <serial>` commands

**iOS:**
1. `simulator` → `xcrun simctl list devices booted` (boot one if none running)
2. `physical` → `xcrun devicectl list devices`
3. No value, one target → use it
4. No value, multiple targets → ask the user which to target

**Web:**
1. Resolve browser:
   - `chrome` → `open -a "Google Chrome"` (macOS) / `google-chrome` (Linux)
   - `firefox` → `open -a Firefox` / `firefox`
   - `safari` → `open -a Safari`
   - `edge` → `open -a "Microsoft Edge"` / `microsoft-edge`
   - No value → use whatever `open` or `xdg-open` defaults to
2. Dev server URL from framework detection (usually `http://localhost:3000` or `:5173` or `:8080`)

**Flutter:**
1. `flutter devices` to list available
2. Match `--device` value against device id or name
3. No value → first available

### 3. Launch

**Android:**
1. Detect the app package and main activity:
   - Parse `AndroidManifest.xml` for `package` attribute and the activity with `android.intent.action.MAIN`
   - Or parse from `build.gradle.kts`: `applicationId`
2. Launch: `adb -s <serial> shell am start -n <package>/<activity>`

**iOS Simulator:**
1. Detect bundle ID from `Info.plist` or Xcode project
2. Launch: `xcrun simctl launch booted <bundle-id>`

**iOS Device:**
1. `xcrun devicectl device process launch --device <udid> <bundle-id>`

**Web:**
1. Start dev server in background if not running:
   - `package.json` with `dev` script → `<pm> run dev`
   - `package.json` with `start` script → `<pm> run start`
   - `composer.json` (Laravel) → `php artisan serve`
   - `Gemfile` (Rails) → `bin/rails server`
   - `deno.json` → `deno task dev` or `deno task start`
2. Wait for server to be ready (poll localhost)
3. Open browser to the dev URL

**Flutter:**
1. `flutter run -d <device-id>`

### 4. Report

Confirm the app is running with:
- Device name and serial/id
- Package/bundle identifier
- Any relevant URL (for web)

## Error Handling

- **App not installed**: Run `/skills:install` even if `--no-install` was passed, then retry launch
- **Activity not found**: Re-detect from manifest, try alternate activity names
- **Device offline**: Report and suggest reconnecting
- **Port in use (web)**: Find the process on the port, report to user, suggest killing or using alternate port
- **Build failure**: Delegate to `/skills:build` command for diagnosis and fixing