agentic-mobile-kit 0.0.2 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/README.md +20 -8
  2. package/bin/cli.js +31 -5
  3. package/lib/init.js +199 -0
  4. package/package.json +9 -3
  5. package/stacks/react-native/template/.agents/skills/LICENSE-callstack +21 -0
  6. package/stacks/react-native/template/.agents/skills/THIRD_PARTY.md +9 -0
  7. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +23 -0
  8. package/stacks/react-native/template/.agents/skills/m-bugfix/agents/openai.yaml +3 -0
  9. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +22 -0
  10. package/stacks/react-native/template/.agents/skills/m-continue/agents/openai.yaml +3 -0
  11. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +50 -0
  12. package/stacks/react-native/template/.agents/skills/m-feature/agents/openai.yaml +3 -0
  13. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +14 -0
  14. package/stacks/react-native/template/.agents/skills/m-pause/agents/openai.yaml +3 -0
  15. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +29 -0
  16. package/stacks/react-native/template/.agents/skills/m-review/agents/openai.yaml +3 -0
  17. package/stacks/react-native/template/.agents/skills/react-native-best-practices/POWER.md +172 -0
  18. package/stacks/react-native/template/.agents/skills/react-native-best-practices/SKILL.md +238 -0
  19. package/stacks/react-native/template/.agents/skills/react-native-best-practices/agents/openai.yaml +4 -0
  20. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-analyze-app.md +208 -0
  21. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-analyze-js.md +264 -0
  22. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-barrel-exports.md +250 -0
  23. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-code-splitting.md +255 -0
  24. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-hermes-mmap.md +167 -0
  25. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-library-size.md +164 -0
  26. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-native-assets.md +208 -0
  27. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-r8-android.md +231 -0
  28. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-tree-shaking.md +215 -0
  29. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-animations-reanimated.md +273 -0
  30. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-atomic-state.md +190 -0
  31. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-bottomsheet.md +339 -0
  32. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-concurrent-react.md +238 -0
  33. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-lists-flatlist-flashlist.md +223 -0
  34. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-measure-fps.md +178 -0
  35. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-memory-leaks.md +168 -0
  36. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-profile-react.md +138 -0
  37. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-react-compiler.md +261 -0
  38. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-uncontrolled-components.md +219 -0
  39. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-android-16kb-alignment.md +114 -0
  40. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-measure-tti.md +221 -0
  41. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-memory-leaks.md +206 -0
  42. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-memory-patterns.md +240 -0
  43. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-platform-setup.md +112 -0
  44. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-profiling.md +140 -0
  45. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-sdks-over-polyfills.md +192 -0
  46. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-threading-model.md +230 -0
  47. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-turbo-modules.md +210 -0
  48. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-view-flattening.md +180 -0
  49. package/stacks/react-native/template/.agents/skills/react-navigation/SKILL.md +63 -0
  50. package/stacks/react-native/template/.agents/skills/react-navigation/agents/openai.yaml +4 -0
  51. package/stacks/react-native/template/.agents/skills/react-navigation/references/bottom-tabs.md +496 -0
  52. package/stacks/react-native/template/.agents/skills/react-navigation/references/drawers.md +474 -0
  53. package/stacks/react-native/template/.agents/skills/react-navigation/references/form-sheet.md +305 -0
  54. package/stacks/react-native/template/.agents/skills/react-navigation/references/header.md +270 -0
  55. package/stacks/react-native/template/.agents/skills/react-navigation/references/material-top-tabs.md +453 -0
  56. package/stacks/react-native/template/.agents/skills/react-navigation/references/native-bottom-tabs.md +365 -0
  57. package/stacks/react-native/template/.agents/skills/react-navigation/references/safe-areas.md +95 -0
  58. package/stacks/react-native/template/.agents/skills/react-navigation/references/stacks.md +392 -0
  59. package/stacks/react-native/template/.agents/skills/upgrading-react-native/SKILL.md +79 -0
  60. package/stacks/react-native/template/.agents/skills/upgrading-react-native/agents/openai.yaml +4 -0
  61. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/expo-sdk-upgrade.md +65 -0
  62. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/monorepo-singlerepo-targeting.md +34 -0
  63. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/react.md +42 -0
  64. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrade-helper-core.md +122 -0
  65. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrade-verification.md +53 -0
  66. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrading-dependencies.md +41 -0
  67. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrading-react-native.md +52 -0
  68. package/stacks/react-native/template/.githooks/pre-commit +49 -0
  69. package/stacks/react-native/template/.githooks/pre-push +5 -0
  70. package/stacks/react-native/template/.github/pull_request_template.md +19 -0
  71. package/stacks/react-native/template/.github/workflows/ci.yml +61 -0
  72. package/stacks/react-native/template/.github/workflows/ios.yml +43 -0
  73. package/stacks/react-native/template/.gitleaks.toml +12 -0
  74. package/stacks/react-native/template/.rulesync/hooks.jsonc +8 -0
  75. package/stacks/react-native/template/.rulesync/permissions.jsonc +36 -0
  76. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +15 -0
  77. package/stacks/react-native/template/AGENTS.md +45 -0
  78. package/stacks/react-native/template/CLAUDE.md +1 -0
  79. package/stacks/react-native/template/docs/ai/conventions.md +8 -0
  80. package/stacks/react-native/template/docs/ai/decisions.md +6 -0
  81. package/stacks/react-native/template/docs/ai/known-issues.md +17 -0
  82. package/stacks/react-native/template/docs/ai/product.md +7 -0
  83. package/stacks/react-native/template/docs/ai/react-native.md +27 -0
  84. package/stacks/react-native/template/docs/ai/structure.md +7 -0
  85. package/stacks/react-native/template/docs/ai/team-process.md +9 -0
  86. package/stacks/react-native/template/docs/ai/tech.md +7 -0
  87. package/stacks/react-native/template/rulesync.jsonc +9 -0
  88. package/stacks/react-native/template/scripts/ai/guard.js +35 -0
  89. package/stacks/react-native/template/scripts/ai/handoff-check.js +28 -0
  90. package/stacks/react-native/template/scripts/ai/install-deps.sh +14 -0
  91. package/stacks/react-native/template/scripts/ai/ios-build.sh +11 -0
  92. package/stacks/react-native/template/scripts/ai/pm-run.sh +16 -0
  93. package/stacks/react-native/template/specs/_templates/design.md +15 -0
  94. package/stacks/react-native/template/specs/_templates/progress.md +14 -0
  95. package/stacks/react-native/template/specs/_templates/requirements.md +30 -0
  96. package/stacks/react-native/template/specs/_templates/tasks.md +6 -0
@@ -0,0 +1,392 @@
1
+ ---
2
+ title: Native Stack Navigator
3
+ impact: HIGH
4
+ tags: react-navigation, native-stack, navigation, header, header-items, search-bar, large-title, modal, animation, form-sheet
5
+ ---
6
+
7
+ # Skill: Native Stack Navigator
8
+
9
+ ## Description
10
+
11
+ Use `createNativeStackNavigator` for screen-to-screen flows.
12
+
13
+ ## When to Use
14
+
15
+ - Building the default push-based flow for an app
16
+ - Using platform-native headers, large titles, or a native search bar
17
+ - Presenting modal or sheet screens with native-stack presentations
18
+
19
+ ## Basic Example
20
+
21
+ **Static API**
22
+
23
+ ```tsx
24
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
25
+
26
+ const AppStack = createNativeStackNavigator({
27
+ screens: {
28
+ Home: HomeScreen,
29
+ Profile: ProfileScreen,
30
+ },
31
+ });
32
+ ```
33
+
34
+ **Dynamic API**
35
+
36
+ ```tsx
37
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
38
+
39
+ const Stack = createNativeStackNavigator();
40
+
41
+ function AppStack() {
42
+ return (
43
+ <Stack.Navigator>
44
+ <Stack.Screen name="Home" component={HomeScreen} />
45
+ <Stack.Screen name="Profile" component={ProfileScreen} />
46
+ </Stack.Navigator>
47
+ );
48
+ }
49
+ ```
50
+
51
+ ## Common Features
52
+
53
+ ### Large Title
54
+
55
+ Use `headerLargeTitleEnabled: true` for an iOS large title that collapses into the regular header on scroll.
56
+
57
+ **Static API**
58
+
59
+ ```tsx
60
+ const AppStack = createNativeStackNavigator({
61
+ screens: {
62
+ Library: {
63
+ screen: LibraryScreen,
64
+ options: {
65
+ headerLargeTitleEnabled: true,
66
+ },
67
+ },
68
+ },
69
+ });
70
+ ```
71
+
72
+ **Dynamic API**
73
+
74
+ ```tsx
75
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
76
+
77
+ const Stack = createNativeStackNavigator();
78
+
79
+ function AppStack() {
80
+ return (
81
+ <Stack.Navigator>
82
+ <Stack.Screen
83
+ name="Library"
84
+ component={LibraryScreen}
85
+ options={{
86
+ headerLargeTitleEnabled: true,
87
+ }}
88
+ />
89
+ </Stack.Navigator>
90
+ );
91
+ }
92
+ ```
93
+
94
+ - Only supported on iOS.
95
+ - The scroll view in the screen must use `contentInsetAdjustmentBehavior="automatic"`.
96
+ - Don't set a background color on the header if large title is enabled as it makes title invisible on iOS 26.
97
+ - Don't set `headerTransparent: false` if large title is enabled.
98
+ - If the scrollable area does not fill the screen, the large title will not collapse on scroll.
99
+
100
+ ### Header Search Bar
101
+
102
+ Use `headerSearchBarOptions` to render a native search bar. If the search configuration depends on screen state, update it with `navigation.setOptions(...)`.
103
+
104
+ **Static API**
105
+
106
+ ```tsx
107
+ const AppStack = createNativeStackNavigator({
108
+ screens: {
109
+ Search: {
110
+ screen: SearchScreen,
111
+ options: {
112
+ headerSearchBarOptions: {
113
+ placeholder: 'Search',
114
+ },
115
+ },
116
+ },
117
+ },
118
+ });
119
+ ```
120
+
121
+ **Dynamic API**
122
+
123
+ ```tsx
124
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
125
+
126
+ const Stack = createNativeStackNavigator();
127
+
128
+ function AppStack() {
129
+ return (
130
+ <Stack.Navigator>
131
+ <Stack.Screen
132
+ name="Search"
133
+ component={SearchScreen}
134
+ options={{
135
+ headerSearchBarOptions: {
136
+ placeholder: 'Search',
137
+ },
138
+ }}
139
+ />
140
+ </Stack.Navigator>
141
+ );
142
+ }
143
+ ```
144
+
145
+ - The scroll view in the screen must use `contentInsetAdjustmentBehavior="automatic"`.
146
+ - If the screen doesn't have a scroll view, use `headerTopInsetEnabled: true`.
147
+
148
+ ### Header Buttons and Custom Content
149
+
150
+ Use `unstable_headerLeftItems` and `unstable_headerRightItems` for native iOS header buttons or menus. Use `headerLeft`, `headerRight`, `headerTitle`, and `headerBackground` for custom React content, and as a fallback on other platforms.
151
+
152
+ **Static API**
153
+
154
+ ```tsx
155
+ import { Button, Text, View } from 'react-native';
156
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
157
+
158
+ const AppStack = createNativeStackNavigator({
159
+ screens: {
160
+ Profile: {
161
+ screen: ProfileScreen,
162
+ options: {
163
+ headerTitle: ({ tintColor, children }) => (
164
+ <Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
165
+ ),
166
+ headerBackground: () => (
167
+ <View style={{ flex: 1, backgroundColor: '#fff' }} />
168
+ ),
169
+ unstable_headerLeftItems: () => [
170
+ {
171
+ type: 'button',
172
+ label: 'Edit',
173
+ onPress: () => {
174
+ // Do something
175
+ },
176
+ },
177
+ ],
178
+ unstable_headerRightItems: () => [
179
+ {
180
+ type: 'button',
181
+ label: 'Done',
182
+ icon: {
183
+ type: 'sfSymbol',
184
+ name: 'checkmark',
185
+ },
186
+ onPress: () => {
187
+ // Do something
188
+ },
189
+ },
190
+ ],
191
+ headerLeft: ({ tintColor }) => (
192
+ <Button title="Edit" color={tintColor} onPress={() => {}} />
193
+ ),
194
+ headerRight: ({ tintColor }) => (
195
+ <Button title="Done" color={tintColor} onPress={() => {}} />
196
+ ),
197
+ },
198
+ },
199
+ },
200
+ });
201
+ ```
202
+
203
+ **Dynamic API**
204
+
205
+ ```tsx
206
+ import { Button, Text, View } from 'react-native';
207
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
208
+
209
+ const Stack = createNativeStackNavigator();
210
+
211
+ function AppStack() {
212
+ return (
213
+ <Stack.Navigator>
214
+ <Stack.Screen
215
+ name="Profile"
216
+ component={ProfileScreen}
217
+ options={{
218
+ headerTitle: ({ tintColor, children }) => (
219
+ <Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
220
+ ),
221
+ headerBackground: () => (
222
+ <View style={{ flex: 1, backgroundColor: '#fff' }} />
223
+ ),
224
+ unstable_headerLeftItems: () => [
225
+ {
226
+ type: 'button',
227
+ label: 'Edit',
228
+ onPress: () => {
229
+ // Do something
230
+ },
231
+ },
232
+ ],
233
+ unstable_headerRightItems: () => [
234
+ {
235
+ type: 'button',
236
+ label: 'Done',
237
+ icon: {
238
+ type: 'sfSymbol',
239
+ name: 'checkmark',
240
+ },
241
+ onPress: () => {
242
+ // Do something
243
+ },
244
+ },
245
+ ],
246
+ headerLeft: ({ tintColor }) => (
247
+ <Button title="Edit" color={tintColor} onPress={() => {}} />
248
+ ),
249
+ headerRight: ({ tintColor }) => (
250
+ <Button title="Done" color={tintColor} onPress={() => {}} />
251
+ ),
252
+ }}
253
+ />
254
+ </Stack.Navigator>
255
+ );
256
+ }
257
+ ```
258
+
259
+ - `unstable_headerLeftItems` and `unstable_headerRightItems` are only supported on iOS and override `headerLeft` and `headerRight` when both are specified.
260
+ - Use `headerLeft` when replacing the back button. Add `headerBackVisible: true` if the back button should still be shown alongside the custom left element.
261
+ - `headerTitle` is useful when the title needs custom typography or extra layout, but custom title elements do not animate with the native title transition.
262
+ - Use `headerBackground` for a gradient, image, or custom background view. For translucent native headers on iOS, prefer `headerTransparent: true` with `scrollEdgeEffects` for iOS 26+ or `headerBlurEffect` for earlier versions.
263
+ - Some behavior differs between iOS versions. On iOS 26+, `unstable_headerRightItems` can collapse into the system overflow menu when there is not enough space.
264
+ - Custom items with `type: 'custom'` in `unstable_headerRightItems` are not collapsed into the overflow menu.
265
+ - Labels are used when items collapse into the overflow menu, and for accessibility.
266
+
267
+ ### Screen Presentations
268
+
269
+ Use the screen `presentation` option to control whether a screen is pushed normally or shown as a modal or sheet.
270
+
271
+ **Static API**
272
+
273
+ ```tsx
274
+ const AppStack = createNativeStackNavigator({
275
+ screens: {
276
+ Home: HomeScreen,
277
+ Compose: {
278
+ screen: ComposeScreen,
279
+ options: {
280
+ presentation: 'modal',
281
+ animation: 'slide_from_bottom',
282
+ },
283
+ },
284
+ },
285
+ });
286
+ ```
287
+
288
+ **Dynamic API**
289
+
290
+ ```tsx
291
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
292
+
293
+ const Stack = createNativeStackNavigator();
294
+
295
+ function AppStack() {
296
+ return (
297
+ <Stack.Navigator>
298
+ <Stack.Screen name="Home" component={HomeScreen} />
299
+ <Stack.Screen
300
+ name="Compose"
301
+ component={ComposeScreen}
302
+ options={{
303
+ presentation: 'modal',
304
+ animation: 'slide_from_bottom',
305
+ }}
306
+ />
307
+ </Stack.Navigator>
308
+ );
309
+ }
310
+ ```
311
+
312
+ - Use `card` for the default push presentation.
313
+ - Use `modal` for a standard modal presentation.
314
+ - Use `containedModal` for a current-context modal presentation on iOS and the default modal presentation on Android.
315
+ - Use `fullScreenModal` when the screen should take over the whole screen. On iOS, this presentation cannot be dismissed by gesture.
316
+ - Use `transparentModal` or `containedTransparentModal` when the previous screen should remain visible behind translucent content.
317
+ - Use `formSheet` when the design calls for a native sheet. Use [form-sheet.md](./form-sheet.md) for detents and platform-specific caveats.
318
+ - Use the `animation` option in the section below when the default transition does not fit the flow.
319
+
320
+ ### Transition Animations
321
+
322
+ Use `animation` option to customize the transition animation.
323
+
324
+ **Static API**
325
+
326
+ ```tsx
327
+ const AppStack = createNativeStackNavigator({
328
+ screens: {
329
+ Home: HomeScreen,
330
+ Details: {
331
+ screen: DetailsScreen,
332
+ options: {
333
+ animation: 'fade_from_bottom',
334
+ animationDuration: 300,
335
+ },
336
+ },
337
+ },
338
+ });
339
+ ```
340
+
341
+ **Dynamic API**
342
+
343
+ ```tsx
344
+ import { createNativeStackNavigator } from '@react-navigation/native-stack';
345
+
346
+ const Stack = createNativeStackNavigator();
347
+
348
+ function AppStack() {
349
+ return (
350
+ <Stack.Navigator>
351
+ <Stack.Screen name="Home" component={HomeScreen} />
352
+ <Stack.Screen
353
+ name="Details"
354
+ component={DetailsScreen}
355
+ options={{
356
+ animation: 'fade_from_bottom',
357
+ animationDuration: 300,
358
+ }}
359
+ />
360
+ </Stack.Navigator>
361
+ );
362
+ }
363
+ ```
364
+
365
+ - Supported `animation` values include `default`, `fade`, `fade_from_bottom`, `simple_push`, `slide_from_bottom`, `slide_from_right`, `slide_from_left`, `flip`, and `none`.
366
+ - `flip` requires `presentation: 'modal'` on iOS.
367
+ - `slide_from_right` and `slide_from_left` fall back to the default transition on iOS.
368
+ - `simple_push` removes the shadow and native header transition on iOS and falls back to the default transition on Android.
369
+ - Use `animationTypeForReplace: 'pop'` when `navigation.replace(...)` should feel like going back, such as auth or onboarding flows.
370
+ - Use `animationDuration` on iOS to tune `slide_from_bottom`, `fade_from_bottom`, `fade`, and `simple_push`. It does not apply to `default`, `flip`, or screens presented as `modal` or `formSheet`.
371
+ - Gesture-related transition options are only supported on iOS.
372
+ - Use `gestureEnabled` to disable swipe-to-dismiss when the animation should only run programmatically.
373
+ - Use `fullScreenGestureEnabled` to start the dismiss gesture anywhere on the screen. This uses `simple_push`-style behavior, and the default iOS transition cannot be matched due to platform limitations.
374
+ - Use `animationMatchesGesture` when the interactive dismiss gesture should follow the `animation` option. It does not affect screens presented modally.
375
+ - Use `fullScreenGestureShadowEnabled` to control the shadow shown during a full-screen dismiss gesture.
376
+ - On iOS, `gestureDirection: 'vertical'` implies `animation: 'slide_from_bottom'` together with full-screen dismissal gestures.
377
+
378
+ ## Notes
379
+
380
+ - For scrollable content and `contentInsetAdjustmentBehavior="automatic"`, native stack needs it to be in the first-descendant chain — no views should be rendered before the scrollable view.
381
+
382
+ ## Canonical Docs
383
+
384
+ - [Native Stack Navigator](https://reactnavigation.org/docs/native-stack-navigator)
385
+ - [Moving between screens](https://reactnavigation.org/docs/navigating)
386
+ - [Configuring the header bar](https://reactnavigation.org/docs/headers)
387
+ - [Opening a modal](https://reactnavigation.org/docs/modal)
388
+
389
+ ## Related Skills
390
+
391
+ - [form-sheet.md](./form-sheet.md)
392
+ - [safe-areas.md](./safe-areas.md)
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: upgrading-react-native
3
+ description: Upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, updating package.json dependencies, migrating native iOS and Android configuration, resolving CocoaPods and Gradle changes, and handling breaking API updates. Use when upgrading React Native, bumping RN version, updating from RN 0.x to 0.y, or migrating Expo SDK alongside a React Native upgrade.
4
+ license: MIT
5
+ ---
6
+
7
+ # Upgrading React Native
8
+
9
+ ## Overview
10
+
11
+ Covers the full React Native upgrade workflow: template diffs via Upgrade Helper, dependency updates, Expo SDK steps, and common pitfalls.
12
+
13
+ ## Typical Upgrade Sequence
14
+
15
+ 1. **Route**: Choose the right upgrade path via [upgrading-react-native.md][upgrading-react-native]
16
+ 2. **Diff**: Fetch the canonical template diff using Upgrade Helper via [upgrade-helper-core.md][upgrade-helper-core]
17
+ 3. **Dependencies**: Assess and update third-party packages via [upgrading-dependencies.md][upgrading-dependencies]
18
+ 4. **React**: Align React version if upgraded via [react.md][react]
19
+ 5. **Expo** (if applicable): Apply Expo SDK layer via [expo-sdk-upgrade.md][expo-sdk-upgrade]
20
+ 6. **Verify**: Run post-upgrade checks via [upgrade-verification.md][upgrade-verification]
21
+
22
+ ```bash
23
+ # Quick start: detect current version and fetch diff
24
+ npm pkg get dependencies.react-native --prefix "$APP_DIR"
25
+ npm view react-native dist-tags.latest
26
+
27
+ # Example: upgrading from 0.76.9 to 0.78.2
28
+ # 1. Fetch the template diff
29
+ curl -L -f -o /tmp/rn-diff.diff \
30
+ "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.76.9..0.78.2.diff" \
31
+ && echo "Diff downloaded OK" || echo "ERROR: diff not found, check versions"
32
+ # 2. Review changed files
33
+ grep -n "^diff --git" /tmp/rn-diff.diff
34
+ # 3. Update package.json, apply native changes, then install + rebuild
35
+ npm install --prefix "$APP_DIR"
36
+ cd "$APP_DIR/ios" && pod install
37
+ # 4. Validate: both platforms must build successfully
38
+ npx react-native build-android --mode debug --no-packager
39
+ xcodebuild -workspace "$APP_DIR/ios/App.xcworkspace" -scheme App -sdk iphonesimulator build
40
+ ```
41
+
42
+ ## When to Apply
43
+
44
+ Reference these guidelines when:
45
+ - Moving a React Native app to a newer version
46
+ - Reconciling native config changes from Upgrade Helper
47
+ - Validating release notes for breaking changes
48
+
49
+ ## Quick Reference
50
+
51
+ | File | Description |
52
+ |------|-------------|
53
+ | [upgrading-react-native.md][upgrading-react-native] | Router: choose the right upgrade path |
54
+ | [upgrade-helper-core.md][upgrade-helper-core] | Core Upgrade Helper workflow and reliability gates |
55
+ | [upgrading-dependencies.md][upgrading-dependencies] | Dependency compatibility checks and migration planning |
56
+ | [react.md][react] | React and React 19 upgrade alignment rules |
57
+ | [expo-sdk-upgrade.md][expo-sdk-upgrade] | Expo SDK-specific upgrade layer (conditional) |
58
+ | [upgrade-verification.md][upgrade-verification] | Post-upgrade verification checklist, including agent-device-assisted checks |
59
+ | [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] | Monorepo and single-repo app targeting and command scoping |
60
+
61
+ ## Problem → Skill Mapping
62
+
63
+ | Problem | Start With |
64
+ |---------|------------|
65
+ | Need to upgrade React Native | [upgrade-helper-core.md][upgrade-helper-core] |
66
+ | Need dependency risk triage and migration options | [upgrading-dependencies.md][upgrading-dependencies] |
67
+ | Need React/React 19 package alignment | [react.md][react] |
68
+ | Need workflow routing first | [upgrading-react-native.md][upgrading-react-native] |
69
+ | Need Expo SDK-specific steps | [expo-sdk-upgrade.md][expo-sdk-upgrade] |
70
+ | Need manual or agent-assisted regression validation | [upgrade-verification.md][upgrade-verification] |
71
+ | Need repo/app command scoping | [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] |
72
+
73
+ [upgrading-react-native]: references/upgrading-react-native.md
74
+ [upgrade-helper-core]: references/upgrade-helper-core.md
75
+ [upgrading-dependencies]: references/upgrading-dependencies.md
76
+ [react]: references/react.md
77
+ [expo-sdk-upgrade]: references/expo-sdk-upgrade.md
78
+ [upgrade-verification]: references/upgrade-verification.md
79
+ [monorepo-singlerepo-targeting]: references/monorepo-singlerepo-targeting.md
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Upgrade React Native"
3
+ short_description: "React Native upgrade workflow updated templates, dependencies, and common pitfalls"
4
+ default_prompt: "Use $upgrading-react-native to plan and execute a React Native upgrade."
@@ -0,0 +1,65 @@
1
+ ---
2
+ title: Expo SDK Upgrade Layer
3
+ impact: HIGH
4
+ tags: expo, sdk, react-native, dependencies
5
+ ---
6
+
7
+ # Skill: Expo SDK Upgrade Layer
8
+
9
+ Expo-specific add-on to the core Upgrade Helper workflow. Use only when `expo` exists in app `package.json`.
10
+
11
+ ## Quick Commands
12
+
13
+ ```bash
14
+ npm pkg get dependencies.expo devDependencies.expo --prefix "$APP_DIR"
15
+ cd "$APP_DIR" && npx expo install --fix
16
+ cd "$APP_DIR" && npx expo-doctor
17
+ ```
18
+
19
+ ## When to Apply
20
+
21
+ - `expo` or `expo-updates` is present in the target app package
22
+ - RN upgrade is paired with Expo SDK upgrade
23
+
24
+ ## Official Expo Reference
25
+
26
+ - Follow Expo's official upgrade skill as a primary guide:
27
+ - [Expo Upgrading Expo Skill][expo-upgrading-expo-skill]
28
+ - Important for this workflow: skip `app.json` changes, because this is not an Expo Managed project.
29
+
30
+ ## Pre-Upgrade Audit (Required)
31
+
32
+ - Confirm SDK version and target path.
33
+ - Inventory dependencies and native modules.
34
+ - Review config plugins and prebuild behavior.
35
+ - Review native build setup (Gradle, iOS settings, CI/EAS config).
36
+ - Identify critical app flows for regression testing before changes.
37
+
38
+ ## Workflow Additions
39
+
40
+ 1. Run Expo compatibility alignment.
41
+ - `npx expo install --fix` (source of truth for SDK-compatible versions).
42
+ - Treat `expo-modules` package versions as SDK-coupled; align them with Expo recommendations.
43
+ 2. Run health checks.
44
+ - `npx expo-doctor`; resolve blocking issues first.
45
+ 3. If native folders are part of workflow, reconcile prebuild output.
46
+ - `npx expo prebuild --clean` (when applicable).
47
+ 4. Handle React 19 pairing.
48
+ - Run [react.md](react.md).
49
+ 5. Run [upgrade-verification.md](upgrade-verification.md) for manual or agent-assisted regression checks and release gates.
50
+
51
+ ## Notes
52
+
53
+ - Use `npx expo ...`; do not require global `expo-cli`.
54
+ - Some package bumps may be optional if not SDK-bound; validate before deferring.
55
+ - Read Expo and React Native release notes deeply before editing code, then map each breaking change to a concrete code/task item.
56
+
57
+ ## Related Skills
58
+
59
+ - [upgrading-react-native.md](upgrading-react-native.md) - Routing and mode selection
60
+ - [upgrade-helper-core.md](upgrade-helper-core.md) - Base upgrade workflow
61
+ - [react.md](react.md) - React and React 19 alignment
62
+ - [upgrade-verification.md](upgrade-verification.md) - Post-upgrade validation, including agent-device-assisted checks
63
+ - [monorepo-singlerepo-targeting.md](monorepo-singlerepo-targeting.md) - Repo/app selection and command scoping
64
+
65
+ [expo-upgrading-expo-skill]: https://github.com/expo/skills/blob/main/plugins/upgrading-expo/skills/upgrading-expo/SKILL.md
@@ -0,0 +1,34 @@
1
+ ---
2
+ title: Monorepo vs Single-App Targeting
3
+ impact: HIGH
4
+ tags: monorepo, workspace, react-native, app-selection
5
+ ---
6
+
7
+ # Skill: Monorepo vs Single-App Targeting
8
+
9
+ Small instruction set for selecting the correct app package and running upgrade commands in the right scope.
10
+
11
+ ## Quick Commands
12
+
13
+ ```bash
14
+ APP_DIR=apps/mobile
15
+ npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"
16
+ ```
17
+
18
+ ## Rules
19
+
20
+ 1. Pick one target app package before any upgrade command.
21
+ 2. Run all app-specific commands with `--prefix "$APP_DIR"` or from `cd "$APP_DIR"`.
22
+ 3. Use `APP_DIR=.` for single-package repos.
23
+ 4. Never apply diffs to workspace root when RN app lives in a subpackage.
24
+
25
+ ## Verification
26
+
27
+ - `react-native` is present in `APP_DIR/package.json`.
28
+ - `ios/` and `android/` paths used for build/pods are under `APP_DIR`.
29
+
30
+ ## Related Skills
31
+
32
+ - [upgrading-react-native.md](upgrading-react-native.md) - Routing and mode selection
33
+ - [upgrade-helper-core.md](upgrade-helper-core.md) - Base upgrade workflow
34
+ - [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-specific steps
@@ -0,0 +1,42 @@
1
+ ---
2
+ title: React Upgrade Layer
3
+ impact: HIGH
4
+ tags: react, react-19, rntl, types
5
+ ---
6
+
7
+ # Skill: React Upgrade Layer
8
+
9
+ React-specific upgrade rules to run when `react` changes during a React Native or Expo upgrade.
10
+
11
+ ## When to Apply
12
+
13
+ - `react` version changes (major, minor, or patch).
14
+ - React Native target implies a newer React pairing.
15
+ - Tests/types break after React upgrade.
16
+
17
+ ## React Pairing Rules
18
+
19
+ 1. Keep companion packages aligned with installed React version:
20
+ - `react-test-renderer`
21
+ - `@types/react`
22
+ - `react-dom` (if used by the app)
23
+ 2. Prefer matching React major and minor exactly; patch should also match when available.
24
+ 3. Do not leave these packages on older `x.y` after upgrading `react`.
25
+
26
+ ## React 19 Rules
27
+
28
+ 1. Upgrade `@testing-library/react-native` to `v13+`.
29
+ 2. Follow:
30
+ - [Expo React 19 Reference][expo-react-19-reference]
31
+ - [RNTL LLM Docs][rntl-llm-docs]
32
+ 3. Expect type-level breakages from deprecated API removals; fix code and mocks accordingly.
33
+
34
+ ## Related Skills
35
+
36
+ - [upgrade-helper-core.md](upgrade-helper-core.md) - Core RN upgrade workflow
37
+ - [upgrading-dependencies.md](upgrading-dependencies.md) - Dependency compatibility triage
38
+ - [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-specific upgrade layer
39
+ - [upgrade-verification.md](upgrade-verification.md) - Post-upgrade validation, including agent-device-assisted checks
40
+
41
+ [expo-react-19-reference]: https://github.com/expo/skills/blob/main/plugins/upgrading-expo/skills/upgrading-expo/references/react-19.md
42
+ [rntl-llm-docs]: https://oss.callstack.com/react-native-testing-library/llms.txt