agentic-mobile-kit 0.0.2 → 0.2.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 (99) 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/e2e.yml +72 -0
  73. package/stacks/react-native/template/.github/workflows/ios.yml +43 -0
  74. package/stacks/react-native/template/.gitleaks.toml +12 -0
  75. package/stacks/react-native/template/.rulesync/hooks.jsonc +8 -0
  76. package/stacks/react-native/template/.rulesync/permissions.jsonc +36 -0
  77. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +15 -0
  78. package/stacks/react-native/template/AGENTS.md +46 -0
  79. package/stacks/react-native/template/CLAUDE.md +1 -0
  80. package/stacks/react-native/template/docs/ai/conventions.md +8 -0
  81. package/stacks/react-native/template/docs/ai/decisions.md +6 -0
  82. package/stacks/react-native/template/docs/ai/known-issues.md +17 -0
  83. package/stacks/react-native/template/docs/ai/product.md +7 -0
  84. package/stacks/react-native/template/docs/ai/react-native.md +27 -0
  85. package/stacks/react-native/template/docs/ai/structure.md +7 -0
  86. package/stacks/react-native/template/docs/ai/team-process.md +9 -0
  87. package/stacks/react-native/template/docs/ai/tech.md +7 -0
  88. package/stacks/react-native/template/rulesync.jsonc +9 -0
  89. package/stacks/react-native/template/scripts/ai/guard.js +35 -0
  90. package/stacks/react-native/template/scripts/ai/handoff-check.js +28 -0
  91. package/stacks/react-native/template/scripts/ai/install-deps.sh +14 -0
  92. package/stacks/react-native/template/scripts/ai/ios-build.sh +14 -0
  93. package/stacks/react-native/template/scripts/ai/pm-run.sh +16 -0
  94. package/stacks/react-native/template/scripts/ai/verify.sh +139 -0
  95. package/stacks/react-native/template/specs/_templates/design.md +15 -0
  96. package/stacks/react-native/template/specs/_templates/flow.yaml +14 -0
  97. package/stacks/react-native/template/specs/_templates/progress.md +14 -0
  98. package/stacks/react-native/template/specs/_templates/requirements.md +30 -0
  99. package/stacks/react-native/template/specs/_templates/tasks.md +6 -0
@@ -0,0 +1,122 @@
1
+ ---
2
+ title: Upgrade Helper Core Workflow
3
+ impact: HIGH
4
+ tags: react-native, upgrade-helper, rn-diff-purge, ios, android
5
+ ---
6
+
7
+ # Skill: Upgrade Helper Core Workflow
8
+
9
+ Reliable, framework-agnostic workflow for React Native upgrades using Upgrade Helper and rn-diff-purge.
10
+
11
+ Run shared environment checks first in [upgrading-react-native.md](upgrading-react-native.md) under `Prerequisites (All Upgrade Paths)`.
12
+
13
+ ## Quick Commands
14
+
15
+ ```bash
16
+ npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"
17
+ npm view react-native dist-tags.latest
18
+ curl -L "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES"
19
+ curl -L -o /tmp/rn-diff-<current_version>..<target_version>.diff "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff"
20
+ grep -n "^diff --git" /tmp/rn-diff-<current_version>..<target_version>.diff
21
+ ```
22
+
23
+ ## Upgrade Helper API (Inline Reference)
24
+
25
+ - List supported versions:
26
+ - `https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES`
27
+ - Fetch raw unified diff:
28
+ - `https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff`
29
+ - GitHub compare view:
30
+ - `https://github.com/react-native-community/rn-diff-purge/compare/release/<current_version>..release/<target_version>`
31
+ - Upgrade Helper UI:
32
+ - `https://react-native-community.github.io/upgrade-helper/?from=<current_version>&to=<target_version>`
33
+ - Path mapping note:
34
+ - Diff paths are prefixed with `RnDiffApp/`; remap to your app paths and package names.
35
+
36
+ ## Inputs
37
+
38
+ - `APP_DIR`: app package path (`.` for single-package repos)
39
+ - `current_version`: current React Native version
40
+ - `target_version`: target React Native version (latest by default)
41
+
42
+ ## Reliable Workflow
43
+
44
+ 1. Detect app and versions.
45
+ - Read `react-native` from `APP_DIR/package.json`.
46
+ - Resolve target via `npm view react-native dist-tags.latest` unless user provides one.
47
+ 2. Validate `target_version` exists.
48
+ - Check `RELEASES` from rn-diff-purge and confirm `target_version` is listed.
49
+ - If missing, stop and ask user to choose one of available versions.
50
+ 3. Collect canonical sources.
51
+ - Upgrade Helper URL.
52
+ - rn-diff-purge raw diff.
53
+ 4. Fetch diff with fallback.
54
+ - Try exact raw diff: `<current_version>..<target_version>`.
55
+ - If 404, try nearest available patch versions and report what was attempted.
56
+ - If no available pair works, stop and ask user for target adjustment.
57
+ 5. Build dependency baseline from rn-diff-purge first.
58
+ - Start with the `RnDiffApp/package.json` diff for the exact version pair.
59
+ - Do not manually install RN packages one-by-one before this baseline is captured.
60
+ 6. Publish a short execution plan before edits.
61
+ - Include ordered phases: dependency baseline, one-pass install, native/tooling merges, verification.
62
+ - If dependency migrations are ambiguous, ask for user confirmation before modifying package choices.
63
+ 7. Run dependency risk planning.
64
+ - Use [upgrading-dependencies.md](upgrading-dependencies.md).
65
+ - Fold approved migrations into the same dependency update pass.
66
+ 8. Apply dependency updates in one pass.
67
+ - Update `APP_DIR/package.json` (and lockfile) from the baseline plus approved migrations.
68
+ - Run exactly one install command with the repo's package manager (`npm install`, `yarn install`, `pnpm install`, or `bun install`).
69
+ - Avoid piecemeal installs such as repeated `npm install <pkg>` unless explicitly requested.
70
+ 9. Build a change checklist from diff.
71
+ - Group by JS/TS, iOS, Android, tooling.
72
+ - Skip template-only UI (`App.tsx`) unless explicitly requested.
73
+ - Skip template-only dependencies (`@react-native/new-app-screen`) unless they exist in the app.
74
+ 10. Apply diff safely.
75
+ - Treat `RnDiffApp` as placeholder; remap app/package names.
76
+ - Merge, do not overwrite project-specific customizations.
77
+ 11. Sync native deps.
78
+ - Run iOS pods in `APP_DIR/ios`.
79
+ 12. Validate and gate completion.
80
+ - iOS build passes.
81
+ - Android build passes.
82
+ - tests/typecheck/lint pass or failures are documented with next actions.
83
+ - If `react` was upgraded, run [react.md](react.md).
84
+ - If `target_version >= 0.81` and tests fail due to missing modules, add proper mocks.
85
+ - Example (`BackHandler` mock removal): https://github.com/facebook/react-native/issues/52667#issuecomment-3094788618
86
+ - Run [upgrade-verification.md](upgrade-verification.md) before closing the upgrade.
87
+
88
+ ## Stop Conditions
89
+
90
+ - Missing `react-native` dependency in target package.
91
+ - Diff source unavailable and no fallback available.
92
+ - Unresolved native merge conflicts in iOS/Android entry files.
93
+
94
+ ## Reliability Rules
95
+
96
+ - Keep operations version-pair scoped (`current_version -> target_version`).
97
+ - Prefer official sources over ad-hoc guides.
98
+ - Record every manual deviation from Upgrade Helper.
99
+ - Do not run Expo-specific commands here.
100
+
101
+ ## Common Pitfalls
102
+
103
+ - Upgrading an Expo project with only RN CLI steps: apply the Expo layer ([expo-sdk-upgrade.md](expo-sdk-upgrade.md)).
104
+ - Skipping the Upgrade Helper: leads to missed native config changes.
105
+ - Treating `RnDiffApp` paths as literal project paths.
106
+ - Copying the entire template wholesale: use the diff as a guide and merge only needed changes.
107
+ - Using the wrong changelog: `0.7x` changes live in `CHANGELOG-0.7x.md`.
108
+ - Running the wrong package manager: always match the repo lockfile.
109
+ - Forgetting CocoaPods: iOS builds will fail without `pod install`.
110
+ - Not updating Android Gradle wrapper binary: update `android/gradle/wrapper/gradle-wrapper.jar` for the target RN version. Source template:
111
+ - `https://raw.githubusercontent.com/react-native-community/rn-diff-purge/release/<target_version>/RnDiffApp/android/gradle/wrapper/gradle-wrapper.jar`
112
+ - Flipper artifacts lingering after removal in v0.74: remove `ReactNativeFlipper.kt` and `FLIPPER_VERSION` when the target RN version drops Flipper.
113
+ - Skipping platform rebuilds after Pod/Gradle changes.
114
+
115
+ ## Related Skills
116
+
117
+ - [upgrading-react-native.md](upgrading-react-native.md) - Routing and mode selection
118
+ - [upgrading-dependencies.md](upgrading-dependencies.md) - Dependency compatibility and migration plan
119
+ - [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-only layer on top of core workflow
120
+ - [react.md](react.md) - React and React 19 alignment
121
+ - [upgrade-verification.md](upgrade-verification.md) - Post-upgrade validation, including agent-device-assisted checks
122
+ - [monorepo-singlerepo-targeting.md](monorepo-singlerepo-targeting.md) - Repo/app selection and command scoping
@@ -0,0 +1,53 @@
1
+ ---
2
+ title: Upgrade Verification
3
+ impact: HIGH
4
+ tags: verification, regression, android, ios, navigation
5
+ ---
6
+
7
+ # Skill: Upgrade Verification
8
+
9
+ Manual and agent-assisted validation checklist after React Native and/or Expo upgrades.
10
+
11
+ ## Scope
12
+
13
+ - Focus on behavior and UX regressions that static diffs cannot prove.
14
+ - Keep checks small, repeatable, and tied to critical user flows.
15
+
16
+ ## Agent-Assisted Checks
17
+
18
+ Use `agent-device` for runnable app verification. If it is missing and device verification is needed, install it through the environment's approved/trusted path or ask the user to install or enable it.
19
+
20
+ 1. If the agent environment exposes an `agent-device` skill, read it before planning exact commands.
21
+ 2. If the `agent-device` CLI is available, follow its `agent-device help workflow` guidance.
22
+ 3. Open or install the upgraded app, drive each critical scenario, and verify with UI snapshots.
23
+ 4. Capture screenshots, logs, and pass/fail evidence for changed flows.
24
+ 5. Fall back to human validation for credentials, physical-device-only hardware, or profiler surfaces the agent cannot inspect.
25
+
26
+ ## Behavior Checks (Required)
27
+
28
+ 1. App launch and core journeys work on both iOS and Android.
29
+ 2. Navigation behavior is correct (forward/back stack, params, deep links, modal flows).
30
+ 3. Android edge-to-edge is visually correct (status bar, nav bar, safe area insets, keyboard overlays).
31
+ 4. Permissions and device APIs work (camera, location, notifications, file/media access).
32
+ 5. Background/restore paths work (app resume, push open, interrupted flows).
33
+
34
+ ## Build and Test Gates
35
+
36
+ 1. Run unit/integration tests and fix all upgrade-related failures.
37
+ 2. If `target_version >= 0.81` and tests fail due to missing modules, add proper mocks.
38
+ - Example (`BackHandler` mock removal): https://github.com/facebook/react-native/issues/52667#issuecomment-3094788618
39
+ 3. Build installable artifacts for both platforms.
40
+ 4. For Expo apps, run `npx expo-doctor` from [expo-sdk-upgrade.md](expo-sdk-upgrade.md).
41
+
42
+ ## Evidence to Capture
43
+
44
+ - Screen recordings/screenshots for changed flows.
45
+ - List of verified scenarios and pass/fail status.
46
+ - Follow-up fixes for any observed regressions.
47
+
48
+ ## Related Skills
49
+
50
+ - [upgrading-react-native.md](upgrading-react-native.md) - Upgrade workflow router
51
+ - [upgrade-helper-core.md](upgrade-helper-core.md) - Core RN diff/merge workflow
52
+ - [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-specific checks and commands
53
+ - [react.md](react.md) - React-specific upgrade rules
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: Upgrading Dependencies
3
+ impact: HIGH
4
+ tags: react-native, dependencies, compatibility, migration
5
+ ---
6
+
7
+ # Skill: Upgrading Dependencies
8
+
9
+ Common dependency issues and mitigations when upgrading React Native.
10
+
11
+ ## Quick Checks
12
+
13
+ ```bash
14
+ npm ls --depth=0
15
+ ```
16
+
17
+ ## Dependency Risk and Migration Plan
18
+
19
+ 1. Review compatibility signals:
20
+ - [RN nightly tests](https://react-native-community.github.io/nightly-tests/)
21
+ - [React Native Directory](https://reactnative.directory/packages?newArchitecture=false)
22
+ 2. If `react` is upgraded, run [react.md](react.md) for companion package alignment and React 19 rules.
23
+ 3. Handle known risky packages:
24
+ - `react-native-fast-image` -> prefer `@d11/react-native-fast-image` or `expo-image` (confirm with user)
25
+ - `@react-native-cookies/cookies` -> prefer `@preeternal/react-native-cookie-manager` (confirm with user)
26
+ - `react-native-code-push` -> treat as incompatible; disable for upgrade and consider `@appzung/react-native-code-push`, `@bravemobile/react-native-code-push`, or `expo-updates`
27
+ - `react-native-image-crop-picker` -> upgrade to `>=0.51.1`; if unstable, plan migration to `expo-image-picker` (confirm with user)
28
+ - `react-native-network-logger` - lists `react` and `react-native` in peer deps as `*` which can be misleading. Upgrade to v2 if `target_version >= 0.79`.
29
+ - `react-native-permissions` - upgrade to v5 if possible (requires RN 0.74+)
30
+ 4. Apply additional cleanup rules:
31
+ - If `@rnx-kit/metro-resolver-symlinks` is present, remove it from deps and `metro.config.js` (Metro supports symlinks since 0.72)
32
+ - If app uses `react-native-localize` timezone APIs and `@callstack/timezone-hermes-fix` is missing, ask whether to add it
33
+ 5. If no safe alternative is found for a critical dependency, ask for explicit user confirmation before continuing.
34
+ 6. Read only breaking/manual steps from RN blog posts between `current_version` and `target_version`.
35
+
36
+ ## Related Skills
37
+
38
+ - [upgrade-helper-core.md](upgrade-helper-core.md) - Core upgrade workflow
39
+ - [react.md](react.md) - React and React 19 alignment
40
+ - [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-specific dependency alignment
41
+ - [upgrading-react-native.md](upgrading-react-native.md) - Routing and mode selection
@@ -0,0 +1,52 @@
1
+ ---
2
+ title: Upgrading React Native
3
+ impact: HIGH
4
+ tags: react-native, upgrade, routing
5
+ ---
6
+
7
+ # Skill: Upgrading React Native
8
+
9
+ Router for React Native upgrade workflows. Start with core Upgrade Helper instructions, then apply focused add-ons by project shape.
10
+
11
+ ## Prerequisites (All Upgrade Paths)
12
+
13
+ - Ensure the repo is clean or on a dedicated upgrade branch.
14
+ - Know which package manager the repo uses (`npm`, `yarn`, `pnpm`, `bun`).
15
+ - Use Node.js `20.19.4+`, Java `17`, and Xcode `16.4+` (with Command Line Tools), following https://reactnative.dev/docs/set-up-your-environment.
16
+ - Optional: use [Xcodes](https://github.com/XcodesOrg/XcodesApp) to manage Xcode versions.
17
+ - Verify active versions before upgrading: `node -v`, `java -version`.
18
+ - Verify Android Studio is installed.
19
+ - For iOS, verify Xcode CLI toolchain is in sync (common pitfall after Xcode upgrades):
20
+ - Check:
21
+ - `xcode-select --print-path`
22
+ - `xcodebuild -version`
23
+ - `xcrun --sdk iphoneos --show-sdk-version`
24
+ - If mismatch is suspected, re-point and initialize:
25
+ - `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`
26
+ - `sudo xcodebuild -runFirstLaunch`
27
+
28
+ ## Quick Start
29
+
30
+ 0. Run the [Prerequisites (All Upgrade Paths)](#prerequisites-all-upgrade-paths) checklist.
31
+ 1. Set `APP_DIR` to the app folder (`.` for single-app repos).
32
+ 2. Use [monorepo-singlerepo-targeting.md](monorepo-singlerepo-targeting.md) if you need help choosing `APP_DIR`.
33
+ 3. Run [upgrade-helper-core.md](upgrade-helper-core.md) first to anchor changes to rn-diff-purge.
34
+ 4. Publish a short plan (ordered phases) before making versioned edits.
35
+ 5. Run [upgrading-dependencies.md](upgrading-dependencies.md) to assess risky packages and migrations.
36
+ 6. Apply dependency updates in one pass and run a single install with the repo package manager.
37
+ 7. Run [react.md](react.md) when `react` is upgraded.
38
+ 8. Add [expo-sdk-upgrade.md](expo-sdk-upgrade.md) only if `expo` is present in `APP_DIR/package.json`.
39
+ 9. Finish with [upgrade-verification.md](upgrade-verification.md).
40
+
41
+ ## Decision Map
42
+
43
+ - Need canonical RN diff/merge workflow: [upgrade-helper-core.md](upgrade-helper-core.md)
44
+ - Need to ensure dependencies are compatible: [upgrading-dependencies.md](upgrading-dependencies.md)
45
+ - Need React and React 19 alignment: [react.md](react.md)
46
+ - Project contains Expo SDK deps: [expo-sdk-upgrade.md](expo-sdk-upgrade.md)
47
+ - Need manual or agent-assisted post-upgrade validation: [upgrade-verification.md](upgrade-verification.md)
48
+
49
+ ## Related Skills
50
+
51
+ - [native-platform-setup.md](../../react-native-best-practices/references/native-platform-setup.md) - Tooling and native dependency basics
52
+ - [native-android-16kb-alignment.md](../../react-native-best-practices/references/native-android-16kb-alignment.md) - Third-party library alignment for Google Play
@@ -0,0 +1,49 @@
1
+ #!/bin/sh
2
+ # agentic-mobile-kit pre-commit: runs for every commit, whichever person or AI tool makes it.
3
+ # Blocks secrets and broken Xcode project files, and lints the staged JS/TS files.
4
+ set -eu
5
+
6
+ staged=$(git diff --cached --name-only --diff-filter=ACMR)
7
+ [ -n "$staged" ] || exit 0
8
+
9
+ fail() { echo "pre-commit: $*" >&2; exit 1; }
10
+
11
+ # 1. files that must never be committed
12
+ if echo "$staged" | grep -E '(^|/)\.env(\..+)?$' | grep -qv '\.env\.example$'; then
13
+ fail "don't commit .env files; keep secrets out of git"
14
+ fi
15
+ if echo "$staged" | grep -qE '\.(keystore|jks|p8|p12|mobileprovision)$'; then
16
+ fail "don't commit signing keys or provisioning profiles"
17
+ fi
18
+
19
+ # 2. secrets inside staged changes
20
+ if command -v gitleaks > /dev/null; then
21
+ gitleaks git --staged --no-banner --redact > /dev/null || fail "gitleaks found a possible secret (run: gitleaks git --staged)"
22
+ elif git diff --cached -U0 | grep '^+' | grep -qE -- '-----BEGIN [A-Z ]*PRIVATE KEY-----|AKIA[0-9A-Z]{16}|ghp_[0-9A-Za-z]{36}|npm_[0-9A-Za-z]{36}|sk-[A-Za-z0-9_-]{20,}'; then
23
+ fail "possible secret in the staged changes (install gitleaks for a full scan)"
24
+ fi
25
+
26
+ # 3. Xcode project files must still parse (a broken one fails every build on the team)
27
+ if command -v plutil > /dev/null; then
28
+ for f in $(echo "$staged" | grep 'project\.pbxproj$' || true); do
29
+ plutil -lint -s "$f" || fail "$f is not a valid Xcode project file"
30
+ done
31
+ fi
32
+
33
+ # 4. lint the staged JS/TS files with the project's own ESLint config
34
+ files=$(echo "$staged" | grep -E '\.(js|jsx|ts|tsx)$' || true)
35
+ if [ -n "$files" ]; then
36
+ if [ -x node_modules/.bin/eslint ]; then
37
+ # ponytail: file names with spaces aren't supported here; split on newlines if that ever matters
38
+ node_modules/.bin/eslint $files || fail "fix the ESLint errors above"
39
+ else
40
+ echo "pre-commit: ESLint isn't installed, so staged files weren't linted (Expo: run 'npx expo lint' once)" >&2
41
+ fi
42
+ fi
43
+
44
+ # 5. warn about large commits (the PR size check in CI is the hard limit)
45
+ lines=$(git diff --cached --numstat -- . ':(exclude)*.lock' ':(exclude)package-lock.json' ':(exclude)pnpm-lock.yaml' ':(exclude)*.snap' |
46
+ awk '{ s += $1 + $2 } END { print s + 0 }')
47
+ [ "$lines" -le 400 ] || echo "pre-commit: warning: $lines changed lines; consider smaller commits" >&2
48
+
49
+ exit 0
@@ -0,0 +1,5 @@
1
+ #!/bin/sh
2
+ # agentic-mobile-kit pre-push: typecheck and tests before code leaves the machine.
3
+ set -eu
4
+ sh scripts/ai/pm-run.sh typecheck || { echo "pre-push: fix the type errors above" >&2; exit 1; }
5
+ CI=true sh scripts/ai/pm-run.sh test || { echo "pre-push: fix the failing tests above" >&2; exit 1; }
@@ -0,0 +1,19 @@
1
+ ## What and why
2
+
3
+ <!-- One or two sentences. Link the spec if there is one: specs/<id>/ -->
4
+
5
+ ## Evidence
6
+
7
+ - [ ] Tests: <!-- command you ran and its result -->
8
+ - [ ] iOS: <!-- screenshot, or why it isn't needed -->
9
+ - [ ] Android: <!-- screenshot, or why it isn't needed -->
10
+
11
+ ## Risk
12
+
13
+ <!-- What could break, and how to roll back -->
14
+
15
+ ## AI use
16
+
17
+ <!-- Tool and model, or "none" -->
18
+
19
+ - [ ] I can explain every change in this PR without AI help
@@ -0,0 +1,61 @@
1
+ # agentic-mobile-kit CI: checks every PR, whichever person or AI tool wrote it.
2
+ name: ci
3
+
4
+ on:
5
+ pull_request:
6
+ types: [opened, synchronize, reopened, labeled, unlabeled] # re-run when the large-pr label changes
7
+ push:
8
+ branches: [main]
9
+
10
+ concurrency:
11
+ group: ci-${{ github.ref }}
12
+ cancel-in-progress: true
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ checks:
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
22
+ with:
23
+ fetch-depth: 0 # full history for the secret scan and PR size
24
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
25
+ with:
26
+ node-version: 24
27
+ - run: sh scripts/ai/install-deps.sh
28
+ - run: sh scripts/ai/pm-run.sh lint
29
+ - run: sh scripts/ai/pm-run.sh typecheck
30
+ - run: CI=true sh scripts/ai/pm-run.sh test
31
+ - name: Tool configs match .rulesync/ (run "npx -y rulesync@27.0.0 generate" and commit if this fails)
32
+ if: hashFiles('rulesync.jsonc') != ''
33
+ run: npx -y rulesync@27.0.0 generate > /dev/null && git diff --exit-code -- .claude .codex .agents .antigravity
34
+ - name: Secret scan
35
+ run: docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1 git /repo --no-banner --redact
36
+ - name: PR size (max 600 changed lines; label "large-pr" to override)
37
+ if: github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'large-pr')
38
+ run: |
39
+ lines=$(git diff --numstat "origin/${{ github.base_ref }}...HEAD" -- . ':(exclude)*.lock' ':(exclude)package-lock.json' ':(exclude)pnpm-lock.yaml' ':(exclude)*.snap' | awk '{ s += $1 + $2 } END { print s + 0 }')
40
+ echo "$lines changed lines"
41
+ [ "$lines" -le 600 ] || { echo "This PR changes more than 600 lines. Split it, or add the 'large-pr' label."; exit 1; }
42
+
43
+ android:
44
+ runs-on: ubuntu-latest
45
+ steps:
46
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
47
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
48
+ with:
49
+ node-version: 24
50
+ - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
51
+ with:
52
+ distribution: temurin
53
+ java-version: 17
54
+ cache: gradle
55
+ - run: sh scripts/ai/install-deps.sh
56
+ - name: Generate the native project (Expo apps without android/)
57
+ if: hashFiles('android/settings.gradle', 'android/settings.gradle.kts') == ''
58
+ run: npx expo prebuild --platform android --no-install
59
+ - name: Build debug APK
60
+ working-directory: android
61
+ run: ./gradlew assembleDebug --no-daemon
@@ -0,0 +1,72 @@
1
+ # agentic-mobile-kit end-to-end check: runs the Maestro flows in .maestro/ on an Android emulator
2
+ # with a release build, the same way `sh scripts/ai/verify.sh android` does locally.
3
+ # Runs nightly, on demand, and on pull requests labelled "e2e". Screenshots are uploaded as an artifact.
4
+ name: e2e
5
+
6
+ on:
7
+ schedule:
8
+ - cron: "0 2 * * *"
9
+ workflow_dispatch:
10
+ pull_request:
11
+ types: [opened, synchronize, reopened, labeled]
12
+
13
+ concurrency:
14
+ group: e2e-${{ github.ref }}
15
+ cancel-in-progress: true
16
+
17
+ permissions:
18
+ contents: read
19
+
20
+ env:
21
+ MAESTRO_VERSION: 2.11.0
22
+ MAESTRO_SHA256: 5384593cb4e7a106489e75a821d157dd43f4e438df6bc308b72e82c685e1283a
23
+
24
+ jobs:
25
+ android:
26
+ if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'e2e')
27
+ runs-on: ubuntu-latest
28
+ timeout-minutes: 45
29
+ steps:
30
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
31
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
32
+ with:
33
+ node-version: 24
34
+ - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
35
+ with:
36
+ distribution: temurin
37
+ java-version: 17
38
+ cache: gradle
39
+ - run: sh scripts/ai/install-deps.sh
40
+ - name: Install Maestro (pinned version, checksum verified)
41
+ run: |
42
+ curl -fsSL -o maestro.zip "https://github.com/mobile-dev-inc/maestro/releases/download/cli-$MAESTRO_VERSION/maestro.zip"
43
+ echo "$MAESTRO_SHA256 maestro.zip" | sha256sum -c -
44
+ unzip -q maestro.zip -d "$HOME" && rm maestro.zip
45
+ echo "$HOME/maestro/bin" >> "$GITHUB_PATH"
46
+ - name: Build release APK
47
+ working-directory: android
48
+ run: ./gradlew assembleRelease --no-daemon
49
+ - name: Enable KVM (hardware acceleration for the emulator)
50
+ run: |
51
+ echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
52
+ sudo udevadm control --reload-rules
53
+ sudo udevadm trigger --name-match=kvm
54
+ - name: Run Maestro flows on an emulator
55
+ uses: ReactiveCircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
56
+ with:
57
+ api-level: 35
58
+ arch: x86_64
59
+ target: google_apis
60
+ profile: pixel_6
61
+ ram-size: 4096M
62
+ cores: 4
63
+ disable-animations: true
64
+ emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
65
+ script: sh scripts/ai/verify.sh android --label ci
66
+ - name: Upload screenshots and logs
67
+ if: always()
68
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
69
+ with:
70
+ name: e2e-evidence
71
+ path: .ai/evidence/
72
+ if-no-files-found: ignore
@@ -0,0 +1,43 @@
1
+ # agentic-mobile-kit iOS build check. macOS runners cost several times more than Linux,
2
+ # so this runs only when native code, dependencies or app config change.
3
+ name: ios
4
+
5
+ on:
6
+ pull_request:
7
+ paths: &ios-paths
8
+ - "ios/**"
9
+ - "package.json"
10
+ - "package-lock.json"
11
+ - "yarn.lock"
12
+ - "pnpm-lock.yaml"
13
+ - "app.json"
14
+ - "app.config.*"
15
+ - ".github/workflows/ios.yml"
16
+ push:
17
+ branches: [main]
18
+ paths: *ios-paths
19
+
20
+ concurrency:
21
+ group: ios-${{ github.ref }}
22
+ cancel-in-progress: true
23
+
24
+ permissions:
25
+ contents: read
26
+
27
+ jobs:
28
+ build:
29
+ runs-on: macos-latest
30
+ steps:
31
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
32
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
33
+ with:
34
+ node-version: 24
35
+ - run: sh scripts/ai/install-deps.sh
36
+ - name: Generate the native project (Expo apps without ios/)
37
+ if: hashFiles('ios/Podfile') == ''
38
+ run: npx expo prebuild --platform ios --no-install
39
+ - name: Install pods
40
+ working-directory: ios
41
+ run: pod install
42
+ - name: Build for the simulator (no signing)
43
+ run: sh scripts/ai/ios-build.sh
@@ -0,0 +1,12 @@
1
+ # gitleaks config (read by the pre-commit hook and CI). Default rules, minus files that
2
+ # hold checksums or vendored code rather than secrets.
3
+ [extend]
4
+ useDefault = true
5
+
6
+ [[allowlists]]
7
+ description = "Lockfiles and vendored package-manager releases contain hashes, not secrets"
8
+ paths = [
9
+ '''(^|/)Podfile\.lock$''',
10
+ '''(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lock)$''',
11
+ '''(^|/)\.yarn/releases/''',
12
+ ]
@@ -0,0 +1,8 @@
1
+ {
2
+ "version": 1,
3
+ "hooks": {
4
+ // no matcher: runs for every tool call; guard.js decides from the payload
5
+ "preToolUse": [{ "command": "node scripts/ai/guard.js" }],
6
+ "stop": [{ "command": "node scripts/ai/handoff-check.js" }]
7
+ }
8
+ }
@@ -0,0 +1,36 @@
1
+ // Per-tool permission rules, generated by rulesync. A second layer: git hooks and CI are the real backstop,
2
+ // and Phase 0 showed Codex and the Antigravity CLI can still read .env, so keep real secrets out of the repo.
3
+ {
4
+ "permission": {
5
+ "bash": {
6
+ "rm -rf*": "deny",
7
+ "git reset --hard*": "deny",
8
+ "git push --force*": "deny",
9
+ "git push -f*": "deny",
10
+ "git clean -f*": "deny",
11
+ "git commit --no-verify*": "deny",
12
+ "xcrun simctl erase*": "deny",
13
+ "npm install *": "ask",
14
+ "yarn add*": "ask",
15
+ "pnpm add*": "ask"
16
+ },
17
+ "read": {
18
+ ".env": "deny",
19
+ ".env.*": "deny",
20
+ "**/*.keystore": "deny",
21
+ "**/*.jks": "deny",
22
+ "**/*.p8": "deny",
23
+ "**/*.p12": "deny",
24
+ "**/*.mobileprovision": "deny"
25
+ },
26
+ "edit": {
27
+ "**/project.pbxproj": "deny",
28
+ "package.json": "ask",
29
+ "ios/Podfile": "ask",
30
+ "android/**/build.gradle": "ask",
31
+ "**/Info.plist": "ask",
32
+ "**/AndroidManifest.xml": "ask",
33
+ ".github/workflows/**": "ask"
34
+ }
35
+ }
36
+ }
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: m-reviewer
3
+ targets: ["*"]
4
+ description: Read-only code reviewer. Use when m-review asks for a review of the current branch.
5
+ claudecode:
6
+ tools: ["Read", "Grep", "Glob", "Bash"]
7
+ ---
8
+
9
+ You review code changes with fresh eyes. You never edit files. Use the shell only for read-only commands such as `git diff`, `git log` and `git show`.
10
+
11
+ 1. Get the changes: `git diff main...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`.
12
+ 2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, error and empty states, secrets, native file changes, and performance.
13
+ 3. Confirm each finding in the code before reporting it.
14
+ 4. Report each finding as: severity (blocker or should fix), file:line, the problem, and a suggested fix. No style nits.
15
+ 5. End with "Ready for PR" or "Not ready: N blockers".
@@ -0,0 +1,46 @@
1
+ <!-- KIT:START agentic-mobile-kit (edit outside these markers; the kit updates what's inside) -->
2
+ # {{APP_NAME}}: instructions for AI agents
3
+
4
+ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.
5
+
6
+ ## Project
7
+
8
+ - Bare React Native {{RN_VERSION}} (New Architecture), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
9
+ - What the app does: `docs/ai/product.md`. Stack and services: `docs/ai/tech.md`. Folders and layers: `docs/ai/structure.md`. Code style: `docs/ai/conventions.md`.
10
+
11
+ ## Commands
12
+
13
+ | Task | Command |
14
+ |---|---|
15
+ | Install dependencies | `sh scripts/ai/install-deps.sh` |
16
+ | Lint, typecheck, test | `{{PM_RUN}} lint`, `{{PM_RUN}} typecheck`, `{{PM_RUN}} test` |
17
+ | iOS pods (after native dependency changes) | `cd ios && pod install` |
18
+ | iOS build (simulator, no signing) | `sh scripts/ai/ios-build.sh` |
19
+ | Android build | `cd android && ./gradlew assembleDebug` |
20
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>` |
21
+
22
+ ## Definition of done
23
+
24
+ A task is done only when:
25
+ 1. lint, typecheck and tests pass, and you show the command output from this session;
26
+ 2. UI changes were checked with `sh scripts/ai/verify.sh all --spec <id>` on both iOS and Android, and you looked at the screenshots;
27
+ 3. the change stays inside the task's scope;
28
+ 4. `specs/<id>/progress.md` is updated, when working from a spec.
29
+
30
+ Never say a check passed unless you ran it in this session.
31
+
32
+ ## Rules
33
+
34
+ - Stay inside the task. Ask before touching unrelated files.
35
+ - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `Podfile`, `build.gradle`, `Info.plist`, `AndroidManifest.xml` or `.github/workflows/`.
36
+ - Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
37
+ - Never read, print or commit `.env` files, keystores or signing files. Secrets don't belong in this repo.
38
+ - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
39
+ - After 2 failed attempts at the same fix, stop and report what you found.
40
+ - Chat is not memory: write decisions into the spec or `docs/ai/decisions.md` straight away.
41
+ - Follow `docs/ai/react-native.md`. Before fixing a build error, check `docs/ai/known-issues.md`.
42
+
43
+ ## Skills
44
+
45
+ `react-native-best-practices`, `react-navigation`, `upgrading-react-native` (from Callstack, in `.agents/skills/`).
46
+ <!-- KIT:END agentic-mobile-kit -->
@@ -0,0 +1 @@
1
+ @AGENTS.md