@swmansion/argent 0.32.0 → 0.32.1-next.1

package/skills/argent-native-profiler/SKILL.md

@@ -3,107 +3,38 @@ name: argent-native-profiler
 description: Native profiling for CPU hotspots, UI hangs, memory issues. iOS via xctrace; Android via Perfetto. Use when diagnosing native-level performance issues.
 ---
 
-## 1. Tools
+## 1. Tools and platforms
 
-- `native-profiler-start`: start profiling on a booted device. iOS: xctrace recording for CPU, hangs, and leaks.
-- `native-profiler-stop`: stop the profiler and export trace data to timestamped XML files.
-- `native-profiler-analyze`: parse exported trace data and return a structured bottleneck payload.
-- `profiler-stack-query`: drill into parsed data: hang stacks, function callers, thread breakdown, leak details.
-- `profiler-load`: list and reload previous trace sessions from disk for re-investigation.
-- Physical iPhone: not supported; use a simulator.
+- `native-profiler-start` → `native-profiler-stop` → `native-profiler-analyze`: record, export, and report.
+- `profiler-stack-query`: drill into the analyzed data (hang stacks, function callers, thread breakdown, leaks).
+- `profiler-load`: reload an earlier session from disk.
 
----
-
-## 2. Platform Support
-
-- **iOS**: Backend: Xcode Instruments via `xctrace` on a booted simulator or connected device. Requires Xcode command-line tools on PATH. Surfaces CPU hotspots, UI hangs, and memory leaks (instruments `Leaks` table).
-- **Android**: Backend: Perfetto via `adb shell perfetto` + an in-process WASM trace-processor engine. Surfaces CPU hotspots and UI hangs, with per-hang jank reason codes, a main-thread state breakdown with `blocked_function` attribution, and a GC overlap annotation. Also reports an RSS-growth signal for memory pressure; treat it as a hint to confirm manually, not a confirmed leak. The target app must be debuggable or include `<profileable android:shell="true"/>` in its manifest for `perf_sample` callstacks to be captured.
-
----
+**iOS** (Instruments via `xctrace`): simulator only; a physical iPhone is not supported. Needs full Xcode (`xcrun xctrace version`). Reports CPU hotspots, UI hangs and memory leaks.
 
-## 3. Investigation Patterns
+**Android** (Perfetto): emulator or physical device. Reports CPU hotspots and UI hangs (with jank reasons and the main thread's blocking function), plus an RSS-growth signal for memory pressure: treat it as a hint to confirm, not a confirmed leak. The app must be debuggable or declare `<profileable android:shell="true"/>` in its manifest, or no `perf_sample` callstacks are captured.
 
-After `native-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes:
+`argent-react-native-profiler` starts native profiling alongside React profiling by default; this skill's workflow and investigation patterns apply in both cases.
 
-- **Hang detected** → `profiler-stack-query` mode=`hang_stacks` for full native call chains → mode=`function_callers` for the suspected function → read native source.
-- **CPU hotspot** → `profiler-stack-query` mode=`thread_breakdown` for per-thread distribution → mode=`function_callers` for the dominant function.
-- **Memory leak** → `profiler-stack-query` mode=`leak_stacks` filtered by `object_type` for responsible frames and libraries.
-  - iOS: if leaks come back unattributed (responsible frame `<Call stack limit reached>`), re-run `native-profiler-start` with `malloc_stack_logging: true`. This cold-launches the app with Malloc Stack Logging so leaks carry a real allocation backtrace (responsible frame + library). It restarts the app and adds overhead, so use it only when you need leak attribution, not for CPU/hang passes.
-
-After presenting findings, ask the user whether to investigate further, implement fixes, or stop. After applying fixes, always re-profile the same scenario and compare with `profiler-load`. Report honestly whether the target metric improved, regressed, or stayed flat. If the fix showed no net benefit or introduced regressions elsewhere, say so and reconsider.
-
-**Tip:** For reproducible before/after comparisons, record the interaction sequence as an e2e test using the `argent-create-e2e` skill before the first profiling run. Replay with `e2e-execute` on subsequent runs to eliminate interaction variance.
-
-> **Note:** The `argent-react-native-profiler` instructs to start native profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases.
-
----
-
-## 4. Workflow
+## 2. Workflow
 
 **Complete all steps in order; do not break mid-flow.**
 
-### Step 0: Ensure the target app is running
-
-The `native-profiler-start` tool **auto-detects** the running app on the device.
-You do not need to derive `app_process` manually; just make sure the app is launched.
-
-1. If the app is already running on the device, skip to Step 1 (do not pass `app_process`).
-2. If the app is not running, use `launch-app` with the correct bundle ID first.
-3. Only pass `app_process` explicitly if the tool reports multiple running user apps and you need to disambiguate.
-
-> **Note**: If multiple build flavors are installed (dev, staging, prod), the tool will detect whichever one is currently running. If both are running, it will ask you to specify.
-
-### Step 1: Start recording
-
-Call `native-profiler-start` with `device_id` (iOS UDID or Android serial). The tool auto-detects the running app and saves the trace to `/tmp/argent-profiler-cwd/` with a timestamped filename.
-Let the user interact with the app or drive interaction via simulator tools (see `argent-device-interact` skill).
-While a profiler records, interaction tools return no automatic screenshot or element tree, so the capture does not load the app. Call `screenshot` or `describe` when you need to see the screen; interaction tools still wait for the screen to settle before they return, so add no wait of your own; on an Android emulator each screenshot during a profile takes one frame in about 100 ms and does not wake the screen capture; on a physical Android device it takes about 150–200 ms and briefly wakes the device screen capture, so take them sparingly there.
-
-### Step 2: Stop and export
+1. **Start.** Make sure the app is running (`launch-app` if not); `native-profiler-start` detects it. Pass `app_process` only if it reports several running user apps (e.g. dev and prod flavors) or picks the wrong one. Then let the user interact, or drive the app yourself (`argent-device-interact` skill). While a profiler records, interaction tools return no automatic screenshot or element tree, so the capture does not load the app. Call `screenshot` or `describe` when you need to see the screen; interaction tools still wait for the screen to settle before they return, so add no wait of your own; on an Android emulator each screenshot during a profile takes one frame in about 100 ms and does not wake the screen capture; on a physical Android device it takes about 150–200 ms and briefly wakes the device screen capture, so take them sparingly there.
+2. **Stop.** `native-profiler-stop`. On iOS, check `exportDiagnostics` for export warnings.
+3. **Analyze.** `native-profiler-analyze`. Findings are 🔴 RED (act on it) or 🟡 YELLOW (worth investigating, may be acceptable).
+4. **Present and ask.** Summarize the key findings, then ask the user whether to investigate further, implement fixes, or stop. Do not move on silently.
+5. **Drill down** with `profiler-stack-query` (patterns below).
+6. **Fix and re-profile** the same scenario; compare with the earlier session via `profiler-load` (`list`, then `load_native` with its `session_id` and the `device_id`). Report honestly whether the target metric improved, regressed, or stayed flat; if there is no net benefit or something else regressed, say so and reconsider. For reproducible before/after runs, record the interaction as an e2e test (`argent-create-e2e` skill) before the first run and replay it with `e2e-execute`.
 
-Call `native-profiler-stop` with `device_id`. iOS sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML; check `exportDiagnostics` for any export warnings. Android sends SIGTERM to the on-device perfetto daemon, polls `/proc/<pid>` until it exits, then `adb pull`s the `.pftrace` to the host.
+### Investigation patterns
 
-### Step 3: Analyze
-
-Call `native-profiler-analyze` with `device_id`. Returns a markdown report with bottlenecks categorized as CPU hotspots, UI hangs, or memory leaks, sorted by severity.
-
-### Step 4: Present findings and ask about next steps
-
-Present a concise summary of the key findings. Then follow the "After analysis" guideline: ask whether to investigate further with query tools, implement fixes, or stop.
-
-### Step 5: Drill-down investigation
-
-Use `profiler-stack-query` to investigate specific findings. See §3 Investigation Patterns for chaining guidance.
-
-### Step 6: Reload previous sessions
-
-To revisit a previous trace:
-
-1. Call `profiler-load` mode=`list` to see available sessions.
-2. Call `profiler-load` mode=`load_native` session_id=`<timestamp>` device_id=`<UDID>` to re-parse the XML files.
-3. Use `profiler-stack-query` to investigate the reloaded data.
-
----
-
-## 5. Understanding Results
-
-Bottlenecks are categorized by severity:
-
-- **RED**: CPU functions taking >15% of total time, all UI hangs, and **attributed** memory leaks (those with a resolved responsible frame). These require immediate attention.
-- **YELLOW**: CPU functions taking 3-15% of total time, and **unattributed** memory leaks (`<Call stack limit reached>`, no library; see the memory-leaks caveat below). Worth investigating but may be acceptable.
-
-Each bottleneck type indicates a different class of problem:
-
-- **CPU hotspots**: Native functions consuming excessive CPU time. Look for tight loops, expensive computations, or redundant work.
-- **UI hangs**: Main thread blocked long enough to cause visible jank or unresponsiveness. Often caused by synchronous I/O, heavy layout passes, or lock contention.
-- **Memory leaks**: Objects allocated but never freed. Common causes include retain cycles, unclosed resources, or forgotten observers. Argent records via `xctrace --attach`, which has no malloc-stack history, so on the simulator most leaks come back **unattributed** (`<Call stack limit reached>`, no library) and are dominated by benign system allocations; these are reported as a low-confidence YELLOW summary, not confirmed RED leaks. For attributed stacks, capture with malloc stack logging enabled at launch.
-
----
+- **Hang** → mode `hang_stacks` for the native call chain → `function_callers` for the suspected function → read the native source.
+- **CPU hotspot** → `thread_breakdown` for the per-thread split → `function_callers` for the dominant function.
+- **Memory leak** (iOS) → `leak_stacks`, filtered by `object_type`, for the responsible frames and libraries. To attribute leaks shown as `<Call stack limit reached>`, re-run `native-profiler-start` with `malloc_stack_logging: true`; it restarts the app and adds overhead, so not for CPU or hang passes.
 
-## 6. Important Caveats
+## 3. Caveats
 
-- **Simulator vs device**: Simulator profiling reflects host Mac performance, not real device hardware. Use device profiling for accurate CPU timings and memory behavior.
-- **xctrace availability (iOS)**: Requires Xcode command-line tools installed. Verify with `xcrun xctrace version`.
-- **Profiler overhead**: xctrace instrumentation adds CPU load. If `JSLexer`, `JSONEmitter`, or Hermes runtime internals dominate the JS thread in CPU hotspot results, those reflect profiler overhead, not app work. Discount those entries when evaluating findings.
-- **Run-to-run variance**: Small fluctuations in CPU percentages between runs are normal. Treat only consistent directional changes (across 2+ runs or >15% delta) as actionable signal.
-- **Live data variability**: If the app fetches live API data, different responses between runs change rendering workload independently of code changes. Note when data-dependent screens show variance.
+- **Simulator and emulator timings reflect the host machine**, not device hardware. Compare runs against each other rather than trusting absolute numbers; a physical Android device gives real-hardware numbers.
+- **Profiler overhead:** if `JSLexer`, `JSONEmitter` or Hermes internals dominate the JS thread, that is instrumentation cost, not app work. Discount those entries.
+- **Run-to-run variance:** treat only consistent, directional changes (across 2+ runs, or a >15% delta) as signal.
+- **Live data:** if the app fetches live API data, different responses change the workload independently of code changes. Note when data-dependent screens vary.

package/skills/argent-qa-e2e/SKILL.md

@@ -9,9 +9,9 @@ Load `argent-create-e2e` as the authoring engine. Follow its required references
 
 **Vega** supports every item below: `launch: { vega: ... }`, `await:`/`assert:` selectors, `snapshot:`, and `idle` all run there. Only the touch directives are missing, because Vega is remote-driven. Navigate with recorded `tool: tv-remote` steps and type with `tool: keyboard`, which leaves item 5 with nothing to govern. A D-pad path is relative to where focus already is, so gate every move with item 4's identity check rather than assuming the cursor landed. Read `argent-tv-interact` for focus reading and remote navigation.
 
-**Apple TV and Android TV are out of scope.** The runner does not reject touch directives there, so they fail at the gesture layer instead of with authoring guidance. Use `argent-tv-interact` and report the limitation.
+**Apple TV and Android TV are out of scope.** The runner does not reject touch directives there: on Apple TV they fail at the gesture layer, and on Android TV a `tap:` can pass without doing anything. Use `argent-tv-interact` and report the limitation.
 
-**Physical iPhones** run QA e2e tests, with two hardware limits: replay never auto-binds a phone, so pass its udid as `device` (CLI `--device`) and keep it `connected`; the runner tree is the `describe` tree (same ids and roles), so a selector authored on a simulator can miss there. `pinch`/`rotate` steps run as two-finger gestures, in apps drawn in portrait. Read `argent-ios-device-interact` for the app-scoped contract before recording.
+**Physical iPhones** run QA e2e tests under the hardware limits listed in `argent-create-e2e`. Expect a selector authored on a simulator to miss on the phone's `describe`-based runner tree.
 
 ## Definition of done
 
@@ -98,7 +98,7 @@ Complete the create-e2e polish and blocking audit. Then:
 | ------------------ | ----------- | ------------------------- | --------- |
 | Tap `settings-tab` | Settings    | `settings-screen` visible | `idle`    |
 
-The two are repaired differently. A missing identity check must be recorded live on the restored screen. A missing `idle` check is added in YAML, because `await: { idle: true }` has no recorder form and is one of `argent-create-e2e`'s three permitted polish insertions. Re-record any missing action or other structural check.
+Repair a missing gate as the create-e2e blocking audit says: record identity live on the restored screen, and add `idle` in YAML as one of the three permitted polish insertions. Re-record any missing action or other structural check.
 
 ## 5. Prove two consecutive passes
 
@@ -106,9 +106,9 @@ After the last edit and audit, set the streak to zero:
 
 1. Choose one runner for both passes. Use `e2e-execute` locally or `argent e2e run <name> --platform <platform>` for CI. Switching runners resets the streak.
 2. Seed, review, and freeze snapshot baselines. Baseline updates do not count as passes.
-3. Before mobile pass 1, recycle Argent services for this test's device: two warm passes are correlated evidence, because a fixed timing margin can pass twice simply because environment speed did not change. Scope `stop-all-simulator-servers` to `devices: [<device>]`. Never omit the scope: a bare call is the machine-wide sweep, and step 7 restarts this proof often enough to reap every other agent's devices repeatedly. Use the MCP call for `e2e-execute`, or `argent run stop-all-simulator-servers --devices <device>` from the CLI's install. The reset must not change app or account data. For Chromium, let the runner boot the declared app and omit `device`. Vega owns no recyclable Argent services, so the teardown is a no-op there and both passes are warm.
+3. Before mobile pass 1, recycle Argent services for this test's device: two warm passes are correlated evidence, because a fixed timing margin can pass twice simply because environment speed did not change. Scope `stop-all-simulator-servers` to `devices: [<device>]`. Never omit the scope: step 7 restarts this proof often, and every bare call sweeps the devices of all other agents. Use the MCP call for `e2e-execute`, or `argent run stop-all-simulator-servers --devices <device>` from the CLI's install. The reset must not change app or account data. For Chromium, let the runner boot the declared app and omit `device`. Vega owns no recyclable Argent services, so the teardown is a no-op there and both passes are warm.
 4. Run from the test's launch and setup without baseline-update mode. Count a pass only when `ok: true` and every acceptance check executed. A false `when:` can skip optional setup only. An errored step does not advance the streak, and the count mixes two kinds: read each reason. One that could not run (an unreadable tree under `idle`, an unresolvable `run:` target) is environment: fix it and rerun. **A failed `launch:` also scores `errored`, and it is a verdict about the app**; an app that no longer installs or starts is the regression this test exists to catch, so report it instead of rerunning.
-5. Resolve every passing-step warning before completion. Also resolve recorded-wait warnings from `e2e-finish-recording`. Follow [Live waits and checks](../argent-create-e2e/references/live-authoring.md#live-waits-and-checks). For runner warnings, `await: { idle: true }` raises [six different warnings](../argent-create-e2e/references/e2e-yaml.md#idle-readiness), so read which one it is first. Two say the screen was moving. One says the wait ran out mid-hold and needs a larger `timeout:`. One says the tree stayed empty. One, **settled on the UI tree alone**, says the hierarchy did hold still and only the screenshot pairs were missing, so inspect the capture path rather than the app's rendering. One says the step ended with no evidence either way. Inspect the screen, disclose the cause, and verify that surrounding acceptance checks use stable elements rather than stillness. A [selector-less gesture](../argent-create-e2e/references/e2e-yaml.md#directives) (a coordinate `tap`/`long-press`/`swipe`, or a `pinch`/`rotate` with no `on:`) warns in a different shape: a tree-source outage left it unsettled, so it dispatched blind and the green says only that the gesture was sent. Restore the tree source, usually by relaunching the app so the instrumentation loads, and rerun. Accepting that warning needs an app that serves no tree, which cannot satisfy this contract anyway.
+5. Resolve every passing-step warning before completion. Also resolve recorded-wait warnings from `e2e-finish-recording`. Follow [Live waits and checks](../argent-create-e2e/references/live-authoring.md#live-waits-and-checks). For runner warnings, `await: { idle: true }` raises [six different warnings](../argent-create-e2e/references/e2e-yaml.md#idle-readiness), each with its own repair, so read which one it is first. Inspect the screen, disclose the cause, and verify that surrounding acceptance checks use stable elements rather than stillness. A [selector-less gesture](../argent-create-e2e/references/e2e-yaml.md#directives) warning means the gesture was dispatched blind during a tree-source outage: restore the tree source, usually by relaunching the app, and rerun. Accepting that warning needs an app that serves no tree, which cannot satisfy this contract anyway.
 6. Run the same YAML again immediately with the same runner. Do not manually reset app or account data.
 7. Reset the streak after any failure, edit, re-recording, baseline update, or state-changing manual recovery. Repair through `argent-create-e2e`, audit again, and restart with fresh services.
 

package/skills/argent-react-native-app-workflow/SKILL.md

@@ -7,245 +7,76 @@ Physical iPhone (`kind: "device"`): Metro debugging and profiling tools reject i
 
 ## 1. Starting the React Native App
 
-### 1.1 Explore Configuration (MANDATORY: Do This First)
+### 1.1 Read the project's configuration 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).
+**Before running commands**, read the project's build and run setup: every `package.json` script (custom scripts such as `start:local`, `start:dev`, `ios`, `build:ios` or flavors take priority over the defaults) and `metro.config.js` (a non-default port or `watchFolders`). Do NOT default to `npx react-native …` or `npx expo …` without checking. Before the first build, install dependencies if `node_modules` or `ios/Pods` is missing.
 
 **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)
+Once you know how the project starts Metro, builds and runs the app, and what environment setup it needs, **save that to project memory** so you don't need to rediscover it each time.
 
 ### 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:
-
-   ```bash
-   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. If Metro is already running on the project's port, do not start another (§2).
+2. Start it in the background with the project's start script (e.g. `npm run start:local`, `yarn start:dev`). With none: `npx expo start` in an Expo project, `npx react-native start` otherwise.
+3. Verify with `debugger-status`: `status: "connected"` or `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.
 
 ### 1.3 Run the App
 
-In a **separate** terminal (Metro keeps running in the first):
+Start the app only once Metro is ready, from the project root. Use the project's build/run script if one exists (e.g. `npm run ios`, `npm run android`, `yarn ios:debug`); fall back to the defaults below only if there is none.
 
-**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>`):
+**Pass the target device explicitly**, taken from `list-devices`: use the platform the user named, and do not pick a cabled physical phone just because it is listed. If the device isn't booted yet, boot it with `boot-device` (see `argent-ios-simulator-setup` / `argent-android-emulator-setup`).
 
 ```bash
-npx react-native run-ios --simulator="<name>"        # iOS (or --udid <UDID>)
-npx react-native run-android --deviceId=<adb-serial> # Android
+npx expo run:ios --device <UDID>                     # Expo
+npx expo run:android --device <avdName from list-devices>
+npx react-native run-ios --udid <UDID>               # bare RN (needs @react-native-community/cli)
+npx react-native run-android --deviceId=<adb-serial>
 ```
 
-**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. If `list-devices` returns a `hint` about the adb server, prefix this and every other `adb` command that you run yourself, as the hint shows.
-
-**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:
-
-```bash
-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:
-
-| Method      | How                                                                                               |
-| ----------- | ------------------------------------------------------------------------------------------------- |
-| Reload tool | Use the `debugger-reload-metro` tool                                                              |
-| Restart app | Use the `restart-app` tool, or kill the app in simulator and run `npx react-native run-ios` again |
+## 2. Metro Already on the Port?
 
-**Agent checklist:**
+The default port is 8081 unless the project configures another. Check it with `lsof -i :<port>`. If something is listening, `debugger-status` tells you whether it is Metro: `status: "connected"` or `reason: "no_app_connected"` means it is. `reason: "metro_not_running"` while `lsof` shows a listener means the port is held by something that is **not** Metro; the result's `detail` shows what answered (`... (got: ...)`). In that case ask the user whether you may kill the process.
 
-- [ ] Only one Metro process (no duplicate on port)
-- [ ] App was started after Metro was ready
-- [ ] When needing to reload: refer to 2.3
+To stop a Metro process, use the `stop-metro` tool.
 
 ---
 
-## 3. Build / Install / Retry (React Native & iOS Native)
+## 3. Build, Reload, Reinstall
 
-### 3.1 When Build Fails (e.g. xcodebuild exit code 65)
+| Situation                                     | Action                                                           |
+| --------------------------------------------- | ---------------------------------------------------------------- |
+| JS/React only changed                         | `debugger-reload-metro`, or `restart-app`. No rebuild.           |
+| Native code, pods or project config changed   | Rebuild with the project's run command (Metro can stay running). |
+| App needs reinstalling from a `.app` / `.apk` | `reinstall-app`.                                                 |
 
-**Order of operations (simplest first):**
+When a build fails (e.g. xcodebuild exit code 65), try the simplest fix first: clean the build folder and retry, then clear caches and reinstall dependencies and pods.
 
-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
-
-| Situation                                             | Action                                                                                |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| JS/React only changed                                 | Use `debugger-reload-metro` tool. No rebuild.                                         |
-| Native code or `pod install` / project config changed | Rebuild: `npx react-native run-ios` (Metro can stay running).                         |
-| `node_modules` or `package.json` changed              | `npm install`, then if native deps changed run `cd ios && pod install`. Then rebuild. |
-| App needs reinstalling from .app path                 | Use `reinstall-app` tool with UDID, bundle ID, and .app path.                         |
-| Persistent native build errors                        | Full clean + reinstall (step 2 above).                                                |
-
-### 3.5 Device Control
-
-| Action                     | Tool / Command                                                                                                                                                                                            |
-| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| List devices               | `list-devices` tool (iOS + Android)                                                                                                                                                                       |
-| Boot an iOS simulator      | `boot-device` tool with `udid`                                                                                                                                                                            |
-| Boot an Android emulator   | `boot-device` tool with `avdName`                                                                                                                                                                         |
-| Launch an app              | `launch-app` tool (pass device id + bundle id / package name)                                                                                                                                             |
-| Restart an app             | `restart-app` tool (pass device id + bundle id / package name)                                                                                                                                            |
-| Open a URL / deep link     | `open-url` tool (pass device id + URL)                                                                                                                                                                    |
-| Rotate device              | `rotate` tool                                                                                                                                                                                             |
-| Stop simulator server      | `stop-simulator-server` tool (iOS UDID or Android serial, one device)                                                                                                                                     |
-| Stop all simulator servers | `stop-all-simulator-servers` tool: pass `devices: [...]` to scope the teardown to this session's devices (an unscoped call also tears down other agents' devices; use it only for a machine-wide cleanup) |
-
-For full simulator setup workflow, refer to the `argent-ios-simulator-setup` skill.
+**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 correct build approach is not obvious, **ask the user early** rather than guessing.
 
 ---
 
 ## 4. Runtime Problems in the App
 
-### 4.1 Where to Look
-
-| Problem type                      | Tool / Where to look                                                                                                                                                                                                                                              |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **JavaScript errors / logs**      | Use `debugger-log-registry` to get a summary and log file path, then `Grep` to search. If it returns `status: "not_connected"`, no log file is returned; follow its `guidance` to reconnect first.                                                                |
-| **React component hierarchy**     | Use `debugger-component-tree` tool for a text tree, or `debugger-inspect-element` at specific logical pixel coordinates (not normalized 0-1).                                                                                                                     |
-| **Visual state of the app**       | Use `screenshot` tool to capture the current screen, but prefer `describe` or `debugger-component-tree` for actual navigation and target discovery. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to `screenshot`. |
-| **Evaluate JS in the app**        | Use `debugger-evaluate` tool to run JavaScript in the app's runtime.                                                                                                                                                                                              |
-| **Native crashes / native stack** | `npx react-native log-ios` or iOS Simulator: Debug → Open System Log.                                                                                                                                                                                             |
-| **Build/runtime config**          | `metro.config.js`, `babel.config.js`, `package.json` scripts, `ios/Podfile`.                                                                                                                                                                                      |
-
-For comprehensive Metro debugging workflows (component inspection, console logs, JS evaluation), refer to the `argent-metro-debugger` skill.
-
-### 4.2 JS Console Logs (Log Registry)
-
-Logs are written to a flat log file on disk under `~/.argent/tmp/`. Use the **log-registry → grep** pattern instead of reading logs inline.
+| Problem type                      | Where to look                                                                                                    |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **JavaScript errors / logs**      | `debugger-log-registry` for a summary and the log file path, then `Grep` the file                                |
+| **React component hierarchy**     | `debugger-component-tree`, or `debugger-inspect-element` at logical pixel coordinates (not normalized 0-1)       |
+| **App state**                     | `debugger-evaluate` to run JavaScript in the app's runtime                                                       |
+| **Native crashes / native stack** | iOS: `~/Library/Logs/DiagnosticReports/`. Android: `adb -s <serial> logcat -d`, with `-b crash` for crashes only |
 
-For the full workflow, flat entry format, and grep examples, see `argent-metro-debugger` skill §5.
+If `list-devices` returns a `hint` about the adb server, prefix the `adb` command above as the hint shows.
 
-### 4.3 Do not try to use the DevMenu in React Native apps by default.
+For connection failures, component inspection and searching the console log file, use the `argent-metro-debugger` skill.
 
-Use the argent tools instead.
+Do not open the React Native DevMenu by default; use the argent tools instead.
 
 ---
 
 ## 5. Testing the App
 
-Check the `argent-environment-inspector` result for test commands. For interactive UI testing with automatic screenshot verification, use the `argent-test-ui-flow` skill.
-
-- **Unit tests**: Look for Jest in `package.json` (`"test": "jest"`, `jest` config). Run: `npm test` or `yarn test`.
-- **E2E**: Look for Detox (`.detoxrc.js` or similar), or other E2E config. Dependencies: `detox`, `detox-cli`, and for iOS often `applesimutils`.
-- **Visible UI changes**: Use `argent-test-ui-flow` for manual QA. For `screenshot-diff` rules and parameters, follow the `argent-screenshot-diff` skill. Use it when stable before/after screenshots add meaningful pixel-visible evidence.
-- **UI flow testing**: For interactive UI testing with automatic screenshot verification, refer to the `argent-test-ui-flow` skill.
-
-### 5.2 Running Tests (Typical)
-
-If the user's intent is ambiguous (run existing tests, write new tests, or find missing coverage), clarify before proceeding.
-
-- **Jest**: `npm test` or `npx jest`.
-- **Detox (example)**:
-  - Build: `detox build --configuration ios.sim.release` (or debug).
-  - Run: `detox test --configuration ios.sim.release`.
-  - Ensure simulator is booted and not used by another process.
-
-### 5.3 Agent Testing Checklist
-
-- [ ] Read `package.json` and test config (Jest, Detox, etc.).
-- [ ] If E2E: confirm simulator/device and build config.
-- [ ] If unclear: clarify whether to use existing workflows or write new tests.
-
----
-
-## Quick Reference: Tools & Commands
-
-| Goal                         | Tool / Command                                                                                                                           |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Check port 8081              | `lsof -i :8081`                                                                                                                          |
-| Kill Metro                   | `stop-metro` tool                                                                                                                        |
-| Start Metro                  | `npx react-native start`                                                                                                                 |
-| Start Metro (reset cache)    | `npx react-native start --reset-cache`                                                                                                   |
-| Run iOS app                  | `npx react-native run-ios`                                                                                                               |
-| Run Android app              | `npx react-native run-android`                                                                                                           |
-| List devices                 | `list-devices` tool (iOS + Android)                                                                                                      |
-| Boot a device                | `boot-device` tool (pass `udid` for iOS or `avdName` for Android)                                                                        |
-| Take screenshot              | `screenshot` tool                                                                                                                        |
-| Compare visible UI changes   | `screenshot-diff` tool; follow the `argent-screenshot-diff` skill for baseline/current capture choices                                   |
-| Describe screen (a11y tree)  | `describe` tool for normal app screens and in-app modals; use `screenshot` only when permission/system overlays are not exposed reliably |
-| Read JS console logs         | `debugger-log-registry` tool                                                                                                             |
-| Reload JS bundle             | `debugger-reload-metro` tool                                                                                                             |
-| Check Metro status           | `debugger-status` tool                                                                                                                   |
-| Inspect React component tree | `debugger-component-tree` tool                                                                                                           |
-| Run JS in app                | `debugger-evaluate` tool                                                                                                                 |
-| iOS native logs              | `npx react-native log-ios`                                                                                                               |
-| Android native logs          | `npx react-native log-android` or `adb -s <serial> logcat`                                                                               |
-| Clean + reinstall (nuclear)  | See §3.1 step 3                                                                                                                          |
-
-If `list-devices` returns a `hint` about the adb server, prefix the `adb` commands above as the hint shows.
-
----
-
-## Related Skills
-
-| Skill                           | When to use                                                                                                                                              |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `argent-ios-simulator-setup`    | Initial iOS simulator boot and connection setup                                                                                                          |
-| `argent-android-emulator-setup` | Initial Android emulator boot and connection setup                                                                                                       |
-| `argent-device-interact`        | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator                                                                           |
-| `argent-metro-debugger`         | JS-runtime CDP debugging (Metro on iOS / Android; the four ported tools also drive Chromium/CDP apps): component inspection, console logs, JS evaluation |
-| `argent-react-native-profiler`  | Profiling performance, finding re-render issues, CPU hotspots                                                                                            |
-| `argent-test-ui-flow`           | Interactive UI testing with automatic screenshot verification after each action                                                                          |
+Ask the user before running tests: which suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself. Find the test commands in `package.json` and the test config (Jest, Detox, …).
 
-Ask the user before running tests: confirm which test suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself.
+For interactive UI testing with screenshot verification after each action, use the `argent-test-ui-flow` skill. For visible UI changes, follow the `argent-screenshot-diff` skill when stable before/after screenshots add meaningful pixel-visible evidence.

package/skills/argent-react-native-optimization/SKILL.md

@@ -6,15 +6,10 @@ description: Optimizes a React Native app by profiling first to find real bottle
 ## Rules
 
 - Do not apply shotgun optimizations. Measure first, define what "good enough" looks like (target metric + threshold), fix the top offender, re-measure honestly.
-- **Quick scan**: `react-profiler-renders` for a live render count table. Identifies hot components instantly.
-- **Deep measure**: load `argent-react-native-profiler` skill. `react-profiler-start` → interact → `react-profiler-stop` → `react-profiler-analyze`.
-- **Inspect**: `react-profiler-component-source` per finding. `react-profiler-fiber-tree` to trace component ancestry and render cost.
-- **Verify correctness** - before fixing, recollect information from steps above and make a logical conclusion whether the approach is worth undertaking.
-- **Fix**: apply one fix. Validate with `debugger-evaluate` before committing.
-- **Re-measure**: report whether the target metric improved, regressed, or stayed flat. Check for regressions in other areas. If no net benefit or unacceptable tradeoffs, revert.
 - **Profile for discovery, not only verification.** Use the profiler to find issues static analysis missed, not only to confirm fixes.
-- **One fix per cycle for architectural changes.** Mechanical batch fixes (inline styles, index keys) can be grouped; re-profile once after the batch. When the measurement involves device interaction, record it as an e2e test (`argent-create-e2e` skill) before the first run so all subsequent cycles replay identical steps.
-- **React Compiler**: if `react-profiler-analyze` reports `reactCompilerEnabled: true`, do NOT propose `useCallback`/`useMemo`/`React.memo` unless you confirmed compiler bail-out via `react-profiler-fiber-tree` (absent `useMemoCache`).
+- **Verify before fixing:** recollect the evidence and conclude whether the fix is worth undertaking. Validate a fix with `debugger-evaluate` before committing it.
+- **One fix per cycle for architectural changes.** Mechanical batch fixes (inline styles, index keys) can be grouped; re-profile once after the batch. When the measurement involves device interaction, record it as an e2e test (`argent-create-e2e` skill) before the first run so every cycle replays identical steps.
+- **React Compiler**: if the project uses it (`babel-plugin-react-compiler` in the Babel config, or `experiments.reactCompiler: true` in the Expo config), skip memoization fixes (`React.memo`, `useMemo`, `useCallback`, hoisting inline objects and functions) in every phase; the compiler does them. Keep them for components the compiler skips (`compilationMode: "annotation"`, `"use no memo"`, a `sources` filter). Where the profiler report marks a component ⚠️ (bailout suspected), fix what stops the compiler.
 - **Sub-agents**: Phases 1–2 dispatch sub-agents: one per file for lint results, one per checklist item for semantic. Sub-agents CANNOT touch the device - all profiling and E2E verification must happen in the main agent.
 
 ## Pipeline
@@ -29,11 +24,12 @@ Optimization Progress:
 - [ ] Phase 2: Semantic sweep (judgment: memoization, lists, animations, etc.)
 - [ ] Phase 3: Baseline profile (find real bottlenecks, fix top offenders)
 - [ ] Phase 4: Verify no regressions (crashes, errors, red screens)
+- [ ] Re-run lint to confirm the fixes added no new issues and none were missed
 ```
 
 ### Phase 1: Lint sweep
 
-Run ESLint once at the project root with a comprehensive RN performance ruleset. Dispatch sub-agents to fix results: one per file.
+Run ESLint once at the project root with a comprehensive RN performance ruleset. Dispatch sub-agents to fix results: one per file, in parallel.
 See [references/lint-rules.md](references/lint-rules.md) for ruleset and procedure.
 
 ### Phase 2: Semantic sweep
@@ -41,24 +37,12 @@ See [references/lint-rules.md](references/lint-rules.md) for ruleset and procedu
 Review each area requiring judgment: memoization, list rendering, animations, async patterns, effect cleanup, state hygiene, context architecture. Dispatch one sub-agent per checklist item.
 See [references/semantic-checklist.md](references/semantic-checklist.md) for full checklist.
 
-### Phase 3: Visual profiling
+### Phase 3: Profiling
 
-1. Load `argent-react-native-profiler` skill, start dual profiling
-2. Exercise key user flows (navigate screens the user specified, or all major flows)
-3. Analyze with `react-profiler-analyze` + `native-profiler-analyze` + `profiler-combined-report`
-4. Cross-reference profiling results with Phase 1–2 findings
-5. Fix highest-impact issues. Re-profile after architectural changes; batch mechanical fixes. If a recorded e2e test breaks after a fix (e.g., UI layout changed), follow `argent-create-e2e` skill to repair the e2e test rather than silently discarding it.
+1. For a quick look without a session, `react-profiler-renders` lists how many instances of each component are mounted (not how often they re-render).
+2. Load the `argent-react-native-profiler` skill and follow its workflow (React and native profiling together) on the key user flows: the screens the user named, or all major flows. It covers analysis, drill-down, and re-profiling after each fix.
+3. Cross-reference the profiling results with the Phase 1–2 findings, and fix the highest-impact issues top-down. Re-profile after architectural changes; batch mechanical fixes.
 
 ### Phase 4: Verify no regressions
 
-Navigate every screen and UI flow within scope, confirm each renders without errors. If no scope was specified, verify the entire app: cover all reachable screens via `argent-device-interact`. Use `debugger-log-registry` to check for runtime errors (if it returns `status: "not_connected"` there is no log file; follow its `guidance` to reconnect first) and take screenshots to check for red/yellow error screens. Check for regressions introduced by fixes (e.g., fewer re-renders but higher CPU, or new jank in a different screen). Main agent only.
-
-## App-wide optimization
-
-1. **Phase 1**: run lint centrally (one command), dispatch sub-agents to fix per-file in parallel
-2. **Phase 2**: one sub-agent per checklist item for semantic sweep
-3. **Phase 3**: main agent profiles top offending screens; fixes architectural issues top-down
-4. **Phase 4**: main agent navigates all screens to verify nothing crashes
-
-After the entire run, run lint again to verify no new issues were introduced with your changes.
-This also helps ensure you haven't missed any issues which could've been fixed.
+Navigate every screen and UI flow within scope (the entire app if no scope was given, via `argent-device-interact`) and confirm each renders without errors. Check `debugger-log-registry` for warnings and errors (`Grep` its log file). Argent hides LogBox toasts once a `debugger-*` tool connects, so screenshots catch only full-screen red errors. Look for regressions the fixes introduced (e.g. fewer re-renders but higher CPU, or new jank on a different screen). Main agent only.

package/skills/argent-react-native-optimization/references/fix-reference.md

@@ -1,14 +1,14 @@
 # Fix Reference
 
-Match profiler findings and semantic sweep results to concrete fixes.
+Match profiler findings and semantic sweep results to concrete fixes. With React Compiler active, skip the first three rows for the components it compiles; keep them for components it skips (`compilationMode: "annotation"`, `"use no memo"`, a `sources` filter).
 
-| Finding                                      | Fix                                                                           | Detail                                                                                            |
-| -------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Re-renders with same props                   | `React.memo(Comp)`                                                            | **Skip if React Compiler active**: `react-profiler-analyze` reports compiler status per component |
-| Expensive recomputation / unstable callbacks | `useMemo(fn, [deps])` / `useCallback(fn, [deps])`                             | `useCallback` must pair with `React.memo` on child; alone it has no effect                        |
-| Inline objects/arrays in JSX                 | `StyleSheet.create()` / module-level const                                    | New reference every render breaks shallow equality                                                |
-| List jank                                    | `removeClippedSubviews`, `maxToRenderPerBatch`, `windowSize`, `getItemLayout` | Or migrate to `@shopify/flash-list` with `estimatedItemSize`                                      |
-| JS-thread animation jank                     | `useNativeDriver: true` or `react-native-reanimated`                          | `useNativeDriver` only works for `transform` and `opacity` properties                             |
-| Heavy work during transitions                | `InteractionManager.runAfterInteractions()`                                   | Defers execution until active animations complete                                                 |
-| Slow startup                                 | Hermes + inline requires in `metro.config.js`                                 | Lazy `require()` defers loading heavy modules until first use                                     |
-| Redundant, heavy, or n+1 network calls       | `view-network-logs` → `view-network-request-details`                          | Batch, debounce, or cache at the data layer                                                       |
+| Finding                                      | Fix                                                                           | Detail                                                                       |
+| -------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Re-renders with same props                   | `React.memo(Comp)`                                                            | Only where the props really are equal between renders                        |
+| Expensive recomputation / unstable callbacks | `useMemo(fn, [deps])` / `useCallback(fn, [deps])`                             | `useCallback` must pair with `React.memo` on child; alone it has no effect   |
+| Inline objects/arrays in JSX                 | `StyleSheet.create()` / module-level const                                    | New reference every render breaks shallow equality                           |
+| List jank                                    | `removeClippedSubviews`, `maxToRenderPerBatch`, `windowSize`, `getItemLayout` | Or migrate to `@shopify/flash-list` (v2 needs the New Architecture)          |
+| JS-thread animation jank                     | `useNativeDriver: true` or `react-native-reanimated`                          | `useNativeDriver` can't animate layout props (width, height, margins, …)     |
+| Heavy work during transitions                | `requestIdleCallback()`                                                       | Runs the work when the JS thread is idle; `InteractionManager` is deprecated |
+| Slow startup                                 | Defer heavy imports (lazy `require()`)                                        | Check inline requires in the Metro config (on in bare RN, off in Expo)       |
+| Redundant, heavy, or n+1 network calls       | `view-network-logs` → `view-network-request-details`                          | Batch, debounce, or cache at the data layer                                  |