Argent React Native App Workflow

Physical iPhone (kind: "device"): Metro debugging and profiling tools reject it. Use a simulator.

1. Starting the React Native App

1.1 Explore Configuration (MANDATORY — Do This First)

Before running commands, read the project's build and run configuration from the argent-environment-inspector subagent result.

Do NOT default to npx react-native start or npx react-native run-ios without first checking for custom scripts and workflows.

Manual fallback (if neither the agent nor the tool is available): read ALL package.json scripts — look for custom scripts like start:local, start:dev, ios, build:ios, flavors, etc. Custom scripts take priority over default commands. Also check metro.config.js for non-default port or watchFolders. For iOS builds, prefer opening .xcworkspace over .xcodeproj (CocoaPods generates the workspace).

If the project structure is convoluted, ask the user before proceeding.

Remember the workflow: Once you discover the project's build/run workflow, save it to project memory so you don't need to re-discover it each time.

Checklist before start:

• [ ] node_modules present (if not: npm install or yarn)
• [ ] For iOS: ios/Podfile exists; if ios/Pods missing or stale, run cd ios && pod install && cd ..
• [ ] No conflicting Metro on default port (see 1.2)

1.2 Start Metro

1. Check whether metro is already running on port found in configuration and if it is - do not start another server. Refer to point 2.1.

1. Use the project's custom start script if one exists (e.g. npm run start:local, yarn start:dev). Fall back to default commands if no custom scripts are defined:

   npx react-native start

Optional: npx react-native start --reset-cache if cache issues are suspected.

1. Verify Metro is ready: use the debugger-status tool. It returns a status result instead of erroring: status: "connected" or status: "not_connected" with reason: "no_app_connected" both mean Metro is up (the app just hasn't attached yet); reason: "metro_not_running" means Metro is not reachable — follow the result's guidance.

1. Projects with flavors or custom configs: Use project-specific start script if present (e.g. npm run start:local), and start Metro before running the app.

1.3 Run the App

In a separate terminal (Metro keeps running in the first):

Use the project's custom build/run script if one exists (e.g. npm run ios, npm run android, yarn ios:debug). Only fall back to the defaults below if no custom scripts are defined.

Pass the target device explicitly — derive it from list-devices (see <device_selection_rule>):

npx react-native run-ios --simulator="<name>"        # iOS (or --udid <UDID>)
npx react-native run-android --deviceId=<adb-serial> # Android

Android only: after install, run adb -s <serial> reverse tcp:8081 tcp:8081 so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops.

Agent checklist:

• [ ] Metro is already running and shows "ready"
• [ ] Command run from project root
• [ ] If the device isn't booted yet: use boot-device with the iOS udid or Android avdName. Refer to the argent-ios-simulator-setup / argent-android-emulator-setup skill.
• [ ] Android: adb -s <serial> reverse tcp:8081 tcp:8081 done.

2. Ensuring / Debugging Metro

2.1 Check for Existing Metro

Before starting Metro, avoid "port already in use" errors. Default port to check is :8081, infer the port from documentation:

lsof -i :PORT

• No output → Port free; safe to start Metro.
• Output with PID → Another process is using the port.

Use the debugger-status tool to check whether the process on that port is actually a Metro server — it returns a structured result, not an error. status: "connected" or reason: "no_app_connected" → the process is Metro. reason: "metro_not_running" while lsof shows a listener → the port is occupied by something that is not Metro; the result's detail field shows what the process answered (Metro at port ... is not running (got: ...)). In that case ask the user whether you may kill the process.

To kill a Metro process, use the stop-metro tool (requires user confirmation).

2.2 Confirm Correct Server Connection

• App must point at the same host/port as the running Metro. Default: same machine, port 8081.
• iOS Simulator: By default uses localhost; no extra config needed for same-machine Metro.

Verify Metro is reachable: use the debugger-status tool. reason: "metro_not_running" means Metro did not answer on that port — start it (§2.1); "no_app_connected" means Metro answered but the app has not attached (§2.3). Any other reason: follow the result's guidance (it does not by itself prove Metro is up).

2.3 Reload the App (Ensure New Bundle)

After code or config changes, the app must load the new bundle:

Agent checklist:

• [ ] Only one Metro process (no duplicate on port)
• [ ] App was started after Metro was ready
• [ ] When needing to reload: refer to 2.3

3. Build / Install / Retry (React Native & iOS Native)

3.1 When Build Fails (e.g. xcodebuild exit code 65)

Order of operations (simplest first):

1. Clean build folder, then retry the build command
2. Clear caches and reinstall dependencies: reset Metro cache, watchman watch-del-all, remove node_modules + lockfile, npm install, then cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update
3. CocoaPods issues: pod deintegrate then pod install --repo-update
4. Open ios/*.xcworkspace in Xcode for detailed errors in the Report navigator

3.2 When to Ask the User

After 2-3 failed build or run attempts, STOP and ask the user for guidance. The user may know about required env vars, Xcode version requirements, custom build configurations, monorepo-specific setup, or required external services.

If the project structure is convoluted and the correct build approach is not obvious, ask the user early rather than guessing.

3.3 Saving Build Workflow for Later

Once you discover the correct build/run workflow for a project, save it to project memory. Capture: commands to start Metro, commands to build/run the app, and any required environment setup.

3.4 When to Reinstall vs Refresh

3.5 Device Control