@swmansion/argent 0.5.1

package/skills/argent-metro-debugger/references/failure-scenarios.md

@@ -0,0 +1,10 @@
+# Failure Scenarios: Recovery Steps
+
+When a debugger tool fails, use **`debugger-status`** first to diagnose. Then match the error or situation below and act as specified. Do not retry the same failing tool repeatedly without following the recovery steps.
+
+| Scenario                           | Error or situation                                                                         | What to do                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Metro not running**              | Error contains: `Metro at port 8081 is not running (got: ...)`                             | **Start Metro yourself** unless the user asked you not to: scan the workspace configuration and run the appropriate command to start Metro in the background (by default `npx react-native start` or `npx expo start`). Wait for Metro to be ready, then retry `debugger-connect` or `debugger-status`. If you cannot determine the project root, ask the user. |
+| **Metro not standard**             | Error contains: `Metro at port 8081 did not return X-React-Native-Project-Root header`     | Something on that port is not the standard React Native Metro server. Try starting Metro yourself from the app's project root using the command resolution above. If you cannot determine the correct root or the problem persists, inform the user what you found and what you tried.                                                                          |
+| **App not connected**              | Error contains: `Metro at port 8081 has no CDP targets — is a React Native app connected?` | 1) Confirm the app is running on simulator or device. 2) If simulator: use `restart-app` with the app's UDID and bundleId to relaunch so it connects to Metro. 3) Wait a few seconds for the bundle to load. 4) Retry `debugger-status`. Do **not** use `debugger-reload-metro` to fix this — it also requires at least one target.                             |
+| **Was connected, then tool fails** | Any debugger tool fails with a connection or disconnect error after it was working         | The app may have crashed or been closed. Use `restart-app` (simulator) to relaunch the app, then call `debugger-connect` again to pick up the fresh `logicalDeviceId` (UDID may change for booted-fresh simulators), and use that new `device_id` on all subsequent calls.                                                                                      |

package/skills/argent-metro-debugger/references/source-maps.md

@@ -0,0 +1,27 @@
+# Source Resolution for `inspect-element`
+
+`debugger-inspect-element` tries to resolve each component in the hierarchy to its source file and line. It uses a fallback chain:
+
+1. **`_debugStack`** (React fiber property) — a stack trace string from the bundled code. When available, the tool symbolicates it via Metro's `/symbolicate` endpoint to resolve to the original source file, then reads a code fragment from disk. Set `resolveSourceMaps: false` to skip symbolication and return raw bundled locations instead.
+2. **`_debugSource`** (React fiber property) — contains `{ fileName, lineNumber, columnNumber }` pointing directly to the original source file. No symbolication needed. The tool reads the code fragment from disk automatically.
+3. **Neither available** — the tool returns the component hierarchy with `source: null` and `code: null` for all items. The hierarchy (component names) is still useful.
+
+## When Source Info Is Missing
+
+If `debugger-inspect-element` returns all items with `source: null`, the React Native project's Babel configuration does not inject source information into JSX elements. This is common with the **automatic JSX transform** (used by Expo SDK 50+ and React Native 0.73+).
+
+**To enable source resolution**, inform the user that they can add `@babel/plugin-transform-react-jsx-source` to their project's Babel config. For example, in `babel.config.js`:
+
+```js
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ["babel-preset-expo"], // or 'module:@react-native/babel-preset'
+    plugins: [
+      "@babel/plugin-transform-react-jsx-source", // enables _debugSource on fibers
+    ],
+  };
+};
+```
+
+After adding the plugin, restart Metro (`npx react-native start --reset-cache` or `npx expo start --clear`) and reload the app. The tool will then automatically pick up `_debugSource` and resolve components to their source files. No extra `npm install` needed — the plugin ships with `babel-preset-expo` and `@babel/preset-env`.

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

@@ -0,0 +1,237 @@
+---
+name: argent-react-native-app-workflow
+description: Step-by-step workflows for developing or debugging React Native apps with iOS simulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests.
+---
+
+## 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:
+
+   ```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 to verify Metro is running and reachable.
+
+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 iOS 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`, `yarn ios:debug`). Only fall back to the default if no custom scripts are defined:
+
+```bash
+npx react-native run-ios
+```
+
+Optional: specify device or simulator, e.g. `npx react-native run-ios --simulator="iPhone 16"`.
+
+**Agent checklist:**
+
+- [ ] Metro is already running and shows "ready"
+- [ ] Command run from project root
+- [ ] If simulator not booted: use the `boot-simulator` tool with proper UDID. Refer to the `argent-simulator-setup` skill.
+
+---
+
+## 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. If not Metro — 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.
+
+### 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 |
+
+**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
+
+| 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 iOS Simulator Control
+
+| Action                     | Tool / Command                                     |
+| -------------------------- | -------------------------------------------------- |
+| List devices               | `list-simulators` tool                             |
+| Boot a simulator           | `boot-simulator` tool (pass UDID)                  |
+| Launch an app              | `launch-app` tool (pass UDID + bundle ID)          |
+| Restart an app             | `restart-app` tool (pass UDID + bundle ID)         |
+| Open a URL / deep link     | `open-url` tool (pass UDID + URL)                  |
+| Rotate simulator           | `rotate` tool                                      |
+| Stop simulator server      | `stop-simulator-server` tool (for a specific UDID) |
+| Stop all simulator servers | `stop-all-simulator-servers` tool                  |
+
+For full simulator setup workflow, refer to the `argent-simulator-setup` skill.
+
+---
+
+## 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`/`Read` to search.                                                                                                                                                                     |
+| **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.
+
+For the full workflow, flat entry format, and grep examples, see `argent-metro-debugger` skill §5.
+
+### 4.3 Do not try to use the DevMenu in React Native apps 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`.
+- **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`                                                                                                               |
+| List simulators              | `list-simulators` tool                                                                                                                   |
+| Boot simulator               | `boot-simulator` tool                                                                                                                    |
+| Take screenshot              | `screenshot` tool                                                                                                                        |
+| 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`                                                                                                               |
+| Clean + reinstall (nuclear)  | See §3.1 step 3                                                                                                                          |
+
+---
+
+## Related Skills
+
+| Skill                          | When to use                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------- |
+| `argent-simulator-setup`       | Initial simulator boot and connection setup                                     |
+| `argent-simulator-interact`    | Tapping, swiping, typing, hardware buttons, gestures on the simulator           |
+| `argent-metro-debugger`        | Full Metro CDP debugging: 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: 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.

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

@@ -0,0 +1,64 @@
+---
+name: argent-react-native-optimization
+description: Optimizes a React Native app by profiling first to find real bottlenecks, then sweeping for mechanical issues. Entry-point for all performance work. Use when the app feels slow, user asks to optimize, fix re-renders, reduce jank, or improve startup. Delegates to react-native-profiler for measurement.
+---
+
+## 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 `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 simulator interaction, record it as a flow (`create-flow` 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`).
+- **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 simulator - all profiling and E2E verification must happen in the main agent.
+
+## Pipeline
+
+**Lint and semantic sweeps catch deterministic issues cheaply. Profiling finds runtime bottlenecks that static analysis misses. Do both.**
+
+Copy this checklist into your TODO list:
+
+```
+Optimization Progress:
+- [ ] Phase 1: Lint sweep (deterministic — catch mechanical issues without a running app)
+- [ ] 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)
+```
+
+### 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.
+See [references/lint-rules.md](references/lint-rules.md) for ruleset and procedure.
+
+### Phase 2: Semantic sweep
+
+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
+
+1. Load `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` + `ios-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 flow breaks after a fix (e.g., UI layout changed), follow `create-flow` skill to repair the flow rather than silently discarding it.
+
+### 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 `simulator-interact`. Use `debugger-log-registry` to check for runtime errors 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.

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

@@ -0,0 +1,14 @@
+# Fix Reference
+
+Match profiler findings and semantic sweep results to concrete fixes.
+
+| 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                                                        |

package/skills/argent-react-native-optimization/references/lint-rules.md

@@ -0,0 +1,55 @@
+# Phase 1: Lint Rules
+
+Run once at the project root. Catches mechanical issues deterministically.
+Install missing plugins before running: `npm install --save-dev eslint-plugin-react-perf`.
+
+## Rules
+
+### Performance (eslint-plugin-react-perf)
+
+| Rule                                     | Catches                                                  |
+| ---------------------------------------- | -------------------------------------------------------- |
+| `react-perf/jsx-no-new-object-as-prop`   | Object literals `{}` as JSX props - new ref every render |
+| `react-perf/jsx-no-new-array-as-prop`    | Array literals `[]` as JSX props - new ref every render  |
+| `react-perf/jsx-no-new-function-as-prop` | Arrow functions / function expressions as JSX props      |
+| `react-perf/jsx-no-jsx-as-prop`          | JSX elements as prop values (e.g. `icon={<Icon />}`)     |
+
+### React (eslint-plugin-react)
+
+| Rule                                      | Catches                                                             |
+| ----------------------------------------- | ------------------------------------------------------------------- |
+| `react/no-array-index-key`                | `key={index}` - incorrect reconciliation on reorder                 |
+| `react/jsx-no-bind`                       | `.bind()` in JSX props - new function ref every render              |
+| `react/jsx-no-constructed-context-values` | Object/array literals as Context `value` - re-renders all consumers |
+| `react/no-unstable-nested-components`     | Components defined inside render - full remount each render         |
+| `react/no-object-type-as-default-prop`    | Object/array defaults in destructuring (e.g. `{ items = [] }`)      |
+
+### React Native (eslint-plugin-react-native)
+
+| Rule                                          | Catches                                          |
+| --------------------------------------------- | ------------------------------------------------ |
+| `react-native/no-inline-styles`               | Inline `style={{}}` - defeats shallow comparison |
+| `react-native/no-unused-styles`               | StyleSheet rules never referenced                |
+| `react-native/no-color-literals`              | Color literals in styles instead of constants    |
+| `react-native/no-single-element-style-arrays` | `style={[single]}` instead of `style={single}`   |
+
+### Hooks (eslint-plugin-react-hooks)
+
+| Rule                          | Catches                                  |
+| ----------------------------- | ---------------------------------------- |
+| `react-hooks/exhaustive-deps` | Missing/incorrect hook dependency arrays |
+| `react-hooks/rules-of-hooks`  | Hooks called conditionally or in loops   |
+
+### Error handling (ESLint core)
+
+| Rule                                       | Catches                               |
+| ------------------------------------------ | ------------------------------------- |
+| `no-empty` (with `allowEmptyCatch: false`) | Empty catch blocks - swallowed errors |
+
+## Procedure
+
+1. Check if the project has an existing ESLint config.
+   2a. If yes, extend it with missing rules from above.
+   2b. If no config, create a temporary `.eslintrc.json` with all rules above.
+2. Run: `npx eslint --format json <src_dir>` — replace `<src_dir>` with the project's JS/TS source root (check `package.json` scripts or look for `src/`, `app/`, `lib/`)
+3. Parse output into: `file:line -> rule -> message`.

package/skills/argent-react-native-optimization/references/semantic-checklist.md

@@ -0,0 +1,34 @@
+# Phase 2: Semantic Sweep
+
+Work through each area. Do not skip.
+See [fix-reference.md](fix-reference.md) for concrete fix patterns per finding.
+
+## Checklist
+
+### Memoization
+
+Check every exported function component: is it rendered in a list, a frequently-updating parent, or a context consumer? If yes and props are stable, wrap in `React.memo`. Check context providers for unstable `value` props. Skip `React.memo` if React Compiler is active.
+
+### List rendering
+
+Check all list-like rendering: ScrollView+map, manually iterated arrays, deeply nested FlatLists. Verify lists use virtualization (`FlatList`/`FlashList`), stable keys, and proper item sizing.
+
+### Animations
+
+Check all animation code against current library best practices. Prefer Reanimated over the Animated API. Check for JS-thread animation bottlenecks (`requestAnimationFrame` loops, state-driven animations).
+
+### Async patterns
+
+Check for sequential `await` calls that could be `Promise.all`. Check for missing `AbortController` / cancellation on unmount. Check for fetch waterfalls (parent fetches → child fetches → grandchild fetches).
+
+### Effect cleanup
+
+Check all `useEffect` hooks that create timers, listeners, or subscriptions. Verify each returns a cleanup function. Check for effects missing dependency arrays (runs every render).
+
+### State hygiene
+
+Check for unused state (set but never rendered), unbounded state growth (arrays/objects that grow without cap), and derived state that should be computed with `useMemo` instead.
+
+### Monolithic context
+
+Flag but do NOT auto-fix. Report as architectural recommendation.

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

@@ -0,0 +1,160 @@
+---
+name: argent-react-native-profiler
+description: Profile a React Native Hermes app to measure re-render and CPU performance using argent profiler tools. Use when optimizing for performance, measuring before/after a fix, spotting slow components, diagnosing re-renders, checking CPU hotspots, or producing a ranked issue report.
+---
+
+This skill is complementary to `argent-react-native-optimization`, not a replacement for it.
+
+## 2. Tool Overview
+
+### React Profiler (Hermes / React commits)
+
+| Tool                              | Purpose                                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `react-profiler-start`            | Start CPU sampling + inject React commit-capture hook. Optional: `sample_interval_us` (default 100).          |
+| `react-profiler-stop`             | Stop recording; stores cpuProfile + commitTree in session.                                                    |
+| `react-profiler-analyze`          | Run pipeline -> report with CPU-enriched hot commits, sorted by `totalRenderMs` DESC. Saves raw data to disk. |
+| `react-profiler-component-source` | AST lookup: file, line, memoization status, 50 lines of source for a component.                               |
+| `react-profiler-renders`          | Live fiber walk: render counts + durations per component (no profiling session required).                     |
+| `react-profiler-fiber-tree`       | Live fiber walk: full component hierarchy as JSON.                                                            |
+
+### Drill-Down Query Tools (call after analyze)
+
+| Tool                       | Purpose                                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| `profiler-cpu-query`       | Targeted CPU investigation: top functions, time-windowed CPU, call trees, per-component CPU. |
+| `profiler-commit-query`    | Targeted commit investigation: by component, time range, commit index, or cascade tree.      |
+| `profiler-stack-query`     | iOS Instruments drill-down: hang stacks, function callers, thread breakdown, leak details.   |
+| `profiler-combined-report` | Cross-correlated report when both React Profiler and iOS Instruments ran in parallel.        |
+| `profiler-load`            | List and reload previous profiling sessions from disk for re-investigation with query tools. |
+
+For native iOS profiling (CPU hotspots, UI hangs, memory leaks), see the `argent-ios-profiler` skill.
+
+---
+
+## 3. Agent Behavior Guidelines
+
+Follow these rules throughout the profiling workflow:
+
+- Start `react-profiler-start` and `ios-profiler-start` in parallel (two tool calls in one message). Both need `device_id`; use the same UDID for both so their data can be correlated later. This gives best coverage.
+- If the user only wants iOS-only, use the `argent-ios-profiler` skill workflow. Only skip `ios-profiler-start` if the user has **already explicitly said** they don't want native profiling in this session
+
+### After analysis: ask about next steps
+
+After presenting the analysis report, always ask the user what they want to do next. Present these options:
+
+1. **Investigate further** — drill down into specific findings using query tools (CPU call trees, commit cascades, hang stacks, etc.) to identify root causes with confidence before making changes.
+2. **Implement fixes** — apply changes based on the current findings, then re-profile to measure whether the metric changed (improved, regressed, or stayed flat).
+3. **Done for now** — accept the report as-is.
+
+Do NOT silently move on after the report. The report is the starting point, not the end — query tools exist specifically to let you dig deeper into anything the report flags.
+
+### During investigation: use query tools proactively
+
+When drilling down, chain query tool calls based on what you find:
+
+- A hot commit -> `profiler-commit-query` mode=`by_index` to see all components -> `profiler-cpu-query` mode=`component_cpu` for the slowest one -> `profiler-cpu-query` mode=`call_tree` for the hot function -> read the source file -> propose a fix.
+- A memory leak -> `profiler-stack-query` mode=`leak_stacks` to identify the responsible module -> read the native source if actionable.
+- An iOS hang -> `profiler-stack-query` mode=`hang_stacks` to get the native call chain -> correlate with React commit timing.
+
+### After fixes: always re-profile
+
+When you apply a fix, always re-profile the same scenario afterward. Compare before/after metrics (commit durations, CPU time, render counts) and report honestly: did the target metric improve, stay flat, or regress? Did any _other_ metric get worse? If you need to reference the original data, use `profiler-load` to reload the pre-fix session. If the fix showed no improvement or introduced a regression, say so explicitly and reconsider the approach.
+
+### Use flows for reproducible profiling
+
+When profiling requires a specific interaction sequence (scroll a list, navigate screens, trigger an animation), **record the interaction as a flow** using the `argent-create-flow` skill before the first profiling run. Then replay the same flow for every subsequent run. This eliminates interaction variance as a confounder and makes before/after comparisons meaningful. Especially important when:
+
+- You are about to re-profile after applying a fix (Step 8).
+- The user asks you to compare multiple profiling sessions.
+- The interaction path is more than 2-3 steps long.
+
+---
+
+## 4. Standard Profiling Workflow
+
+**Complete all steps in order — do not break mid-flow.**
+
+### Step 1: Start profiling
+
+Mind the react-native and ios-native profiler selection mentioned above when starting the session and start the tools. **Save `startedAtEpochMs` from the response** — you will need it later to compute annotation offsets. Every subsequent profiler/query call in this session must use the same `device_id`. Before beginning, define lightweight success criteria with the user: which metric matters most (e.g., `totalRenderMs`, specific commit duration, render count for a component) and what threshold would be meaningful. This anchors later evaluation. On success:
+
+- if user asked you to perform the profiling, determine how to profile yourself using tools described in `argent-simulator-interact` skill.
+- if the user stated they wish to perform the interaction themselves — suggest what interaction to perform (e.g. "scroll the list", "switch tabs") and wait for their reply.
+
+#### Annotate every interaction
+
+After each `gesture-tap` or `gesture-swipe` call, record an annotation using the returned `timestampMs`. Compute `offsetMs = timestampMs - startedAtEpochMs`. Do this for _every_ interaction — including back-navigation swipes, not just the primary action. Pass all collected annotations to `react-profiler-analyze` in Step 3.
+
+### Step 2: Stop and collect
+
+Call `react-profiler-stop` **and** `ios-profiler-stop` in parallel. Only skip `ios-profiler-stop` if you did not start it in Step 1. Note `duration_ms`, `fiber_renders_captured`, `hook_installed`.
+If `hook_installed: false` or `fiber_renders_captured: 0`, warn the user — React commit data may be missing.
+
+### Step 3: Analyze
+
+Call `react-profiler-analyze` with `port`, `device_id`, `project_root`, `platform`, and `rn_version`. The report includes metadata such as `reactCompilerEnabled`, `strictModeEnabled`, and `buildMode` — check these in the returned markdown report.
+
+If you performed interactions using `gesture-tap`/`gesture-swipe`, pass `annotations` to mark when each action occurred. Each annotation's `offsetMs` must be computed as `tapTimestampMs - startedAtEpochMs`, where `tapTimestampMs` is the `timestampMs` returned by the gesture-tap/gesture-swipe tool and `startedAtEpochMs` was returned by `react-profiler-start`. Do **not** use `Date.now()` for this calculation — only server-side timestamps from the tool return values.
+
+If dual profiling, also call `ios-profiler-analyze`, then **you must** call `profiler-combined-report` for the cross-correlated view — do not skip this step when both profilers ran; the combined report surfaces correlations that individual reports miss.
+
+The analyze report includes **CPU hotspots per commit** — showing exactly which JS functions ran during each slow React commit. Raw data is saved to disk automatically for later reload.
+
+### Step 4: Assess results
+
+Analyze whether the results give you a proper image of what is wrong with the application - **do not assume improvement always exists**, verify results logically with reference to how react-native works. Make sure to give honest feedback and be ready to change the approach if needed.
+
+### Step 5: Present findings and ask about next steps
+
+Present a concise summary of the key findings - present whether possibilities for improvement exist and how performing further actions could affect performance. Then follow the "After analysis" guideline — ask whether to investigate further, implement fixes (if available), or stop.
+
+### Step 6: Drill-down investigation (iterative)
+
+Based on findings from the report, use query tools to investigate deeper:
+
+- **Slow component?** -> `profiler-cpu-query` mode=`component_cpu` component_name=`AppNavigator` — shows what JS functions ran during that component's commits.
+- **Want to see the call tree?** -> `profiler-cpu-query` mode=`call_tree` function_name=`expensiveFunction` — shows callers and callees.
+- **What happened during a time window?** -> `profiler-commit-query` mode=`by_time_range` — lists all commits in a range.
+- **Full commit detail?** -> `profiler-commit-query` mode=`by_index` commit_index=38 — all components, props changes, parent cascade.
+- **Who triggered whom?** -> `profiler-commit-query` mode=`cascade_tree` — visual parent-child cascade.
+- **iOS hang details?** -> `profiler-stack-query` mode=`hang_stacks` — native call stacks during a hang.
+
+Repeat as needed until you identify the root cause function and file, referring to step 4 for honest evaluation. After each round of investigation, ask the user if they want to continue digging or move to fixing.
+
+### Step 7: Reload a previous session
+
+If you profiled multiple scenarios and need to revisit earlier data:
+
+1. Call `profiler-load` mode=`list` to see all saved sessions with timestamps (the list now also shows Runtime / Device / Metro bundle columns to help identify the right session).
+2. Call `profiler-load` mode=`load_react` session_id=`<timestamp>` device_id=`<UDID>` to reload React data. `device_id` scopes the reload into the `port:device_id` cache slot.
+3. Call `profiler-load` mode=`load_instruments` session_id=`<timestamp>` device_id=`<UDID>` to reload iOS data.
+4. Query tools now operate on the reloaded session data — **pass the same `device_id` you loaded with**, otherwise they will miss the cache.
+
+This is useful for before/after comparisons: profile, fix, re-profile, then reload the original session to compare metrics side by side.
+
+### Step 8: Apply fix and re-profile
+
+If fix is present, read the source code of the identified bottleneck using `react-profiler-component-source` or the Read tool. Apply the fix, then re-profile (Step 1 -> user interaction -> Step 2 -> Step 3 -> Step 4). Report whether the target metric improved, stayed flat, or regressed. Also check whether the fix introduced regressions in other metrics (e.g., render count dropped but CPU time increased, or a different component now re-renders more). If the fix showed no net benefit or unacceptable tradeoffs, revert and reconsider.
+
+**Tip:** If the interaction sequence was recorded as a flow (see "Use flows for reproducible profiling" above), replay it with `flow-execute` instead of manually repeating the steps. This guarantees identical interaction conditions for the comparison. If the flow fails during replay (e.g., a UI fix changed the layout), follow `argent-create-flow` skill §10 (Flow Self-Improvement) to diagnose and repair the flow before retrying the profiling cycle.
+
+If the user stated that they do not wish for changes, present the profiling report and skip the fix but suggest it to the user.
+
+**React Compiler rule:** If the analyze report indicates React Compiler is enabled, do NOT propose `useCallback`/`useMemo`/`React.memo` unless you confirmed compiler bail-out (check `react-profiler-fiber-tree` for absent `useMemoCache` on that component).
+
+---
+
+## 5. Important Caveats
+
+- **Dev mode inflation**: `buildMode: "dev"` renders are ~3x slower than production. Prioritize high `normalizedRenderCount` — it scales to prod.
+- **Re-run after fixes**: Always re-profile after changes. Report honestly whether the metric improved, regressed, or stayed flat — do not assume improvement.
+- **`excluded` is informational**: Components in `animatedSubtrees` and `recyclerChildren` re-render by design.
+- **Strict Mode**: Double-invokes renders. The pipeline halves `normalizedRenderCount` automatically when detected.
+- **Debugger connection**: If interrupted, started profiling also closes. Check debugger status and restart the flow on errors.
+- **Confounders to watch for**:
+  - Live API data may differ between runs (different payload sizes, content counts), which shifts render counts and durations independently of your fix. Note when data-dependent components show variance.
+  - Profiler overhead inflates CPU measurements. If iOS Instruments shows `JSLexer`, `JSONEmitter`, or Hermes internals dominating the JS thread, that reflects profiler instrumentation cost — not app work. Discount those entries.
+  - Runs are not perfectly reproducible. Small variations (under ~10-15%) in commit duration may be noise; only treat consistent, directional changes as signal.
+
+For standalone diagnostic tools (live render stats, fiber tree, CPU summary), see `references/diagnostic-tools.md`.