agentic-mobile-kit 0.5.6 → 0.6.1

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 (62) hide show
  1. package/README.md +5 -1
  2. package/bin/cli.js +1 -1
  3. package/lib/doctor.js +1 -1
  4. package/lib/init.js +91 -39
  5. package/package.json +4 -2
  6. package/stacks/react-native/expo/.agents/skills/LICENSE-expo +21 -0
  7. package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +11 -0
  8. package/stacks/react-native/expo/.agents/skills/expo-module/SKILL.md +151 -0
  9. package/stacks/react-native/expo/.agents/skills/expo-module/agents/openai.yaml +4 -0
  10. package/stacks/react-native/expo/.agents/skills/expo-module/references/config-plugin.md +90 -0
  11. package/stacks/react-native/expo/.agents/skills/expo-module/references/create-expo-module.md +206 -0
  12. package/stacks/react-native/expo/.agents/skills/expo-module/references/lifecycle.md +127 -0
  13. package/stacks/react-native/expo/.agents/skills/expo-module/references/module-config.md +48 -0
  14. package/stacks/react-native/expo/.agents/skills/expo-module/references/native-module.md +286 -0
  15. package/stacks/react-native/expo/.agents/skills/expo-module/references/native-view.md +171 -0
  16. package/stacks/react-native/expo/.agents/skills/expo-router/SKILL.md +240 -0
  17. package/stacks/react-native/expo/.agents/skills/expo-router/agents/openai.yaml +4 -0
  18. package/stacks/react-native/expo/.agents/skills/expo-router/references/form-sheet.md +253 -0
  19. package/stacks/react-native/expo/.agents/skills/expo-router/references/route-structure.md +229 -0
  20. package/stacks/react-native/expo/.agents/skills/expo-router/references/search.md +248 -0
  21. package/stacks/react-native/expo/.agents/skills/expo-router/references/tabs.md +433 -0
  22. package/stacks/react-native/expo/.agents/skills/expo-router/references/toolbar-and-headers.md +284 -0
  23. package/stacks/react-native/expo/.agents/skills/expo-router/references/zoom-transitions.md +158 -0
  24. package/stacks/react-native/expo/.agents/skills/expo-upgrade/SKILL.md +150 -0
  25. package/stacks/react-native/expo/.agents/skills/expo-upgrade/agents/openai.yaml +4 -0
  26. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/expo-av-to-audio.md +132 -0
  27. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/expo-av-to-video.md +160 -0
  28. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/native-tabs.md +124 -0
  29. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/new-architecture.md +79 -0
  30. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-19.md +79 -0
  31. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-compiler.md +59 -0
  32. package/stacks/react-native/expo/.agents/skills/expo-upgrade/references/react-navigation-to-expo-router.md +61 -0
  33. package/stacks/react-native/expo/.rulesync/permissions.jsonc +40 -0
  34. package/stacks/react-native/expo/AGENTS.md +52 -0
  35. package/stacks/react-native/expo/docs/ai/expo.md +35 -0
  36. package/stacks/react-native/expo/docs/ai/known-issues.md +32 -0
  37. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +1 -1
  38. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
  39. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +2 -2
  40. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -5
  41. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +1 -1
  42. package/stacks/react-native/template/.githooks/pre-commit +5 -5
  43. package/stacks/react-native/template/.githooks/pre-push +3 -2
  44. package/stacks/react-native/template/.github/workflows/ci.yml +8 -3
  45. package/stacks/react-native/template/.github/workflows/e2e.yml +2 -0
  46. package/stacks/react-native/template/.github/workflows/ios.yml +2 -3
  47. package/stacks/react-native/template/AGENTS.md +3 -3
  48. package/stacks/react-native/template/codemagic.yaml +2 -1
  49. package/stacks/react-native/template/scripts/ai/baseline.js +201 -0
  50. package/stacks/react-native/template/scripts/ai/case-check.js +1 -1
  51. package/stacks/react-native/template/scripts/ai/guard.js +2 -1
  52. package/stacks/react-native/template/scripts/ai/ios-build.sh +9 -1
  53. package/stacks/react-native/template/scripts/ai/maestro-env.sh +20 -0
  54. package/stacks/react-native/template/scripts/ai/pm-run.sh +12 -0
  55. package/stacks/react-native/template/scripts/ai/prebuild.sh +28 -0
  56. package/stacks/react-native/template/scripts/ai/release-build.sh +6 -2
  57. package/stacks/react-native/template/scripts/ai/release-check.js +69 -15
  58. package/stacks/react-native/template/scripts/ai/set-version.sh +19 -1
  59. package/stacks/react-native/template/scripts/ai/{spec.js → specs.js} +5 -6
  60. package/stacks/react-native/template/scripts/ai/verify.sh +25 -7
  61. package/stacks/react-native/template/specs/_templates/flow.yaml +8 -0
  62. package/stacks/react-native/template/specs/current/README.md +2 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # agentic-mobile-kit
2
2
 
3
- One setup for AI-assisted development of bare React Native apps. Every AI tool on the team reads the same rules, project knowledge and workflows. Git hooks and CI check the work, whichever person or tool wrote it. A task started in one tool, or on one machine, carries on in another.
3
+ One setup for AI-assisted development of React Native apps, bare or Expo. Every AI tool on the team reads the same rules, project knowledge and workflows. Git hooks and CI check the work, whichever person or tool wrote it. A task started in one tool, or on one machine, carries on in another.
4
4
 
5
5
  Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, OpenCode and Kiro.
6
6
 
@@ -43,6 +43,10 @@ Invoke a skill with `/m-feature` in Claude Code and Antigravity, or `$m-feature`
43
43
 
44
44
  Apps that already use Superpowers, BMAD, proAgents or similar keep them as they are. The kit adds its section next to theirs and links its skills into an existing `.claude/skills` folder. A task started with an `m-` skill follows the kit's steps, and everything else keeps working as before.
45
45
 
46
+ ## Expo apps
47
+
48
+ `init` recognizes Expo apps that generate `ios/` and `android/` with `npx expo prebuild`. Agents get Expo's rules and skills, and never edit the generated folders. The kit's scripts generate them before each build, so device checks, release checks and signed builds work as they do in bare apps, with no Expo account. Teams that build with EAS run `eas build` and `eas submit` themselves. Expo apps that keep `ios/` and `android/` in git are set up like bare apps.
49
+
46
50
  ## Update or remove
47
51
 
48
52
  ```sh
package/bin/cli.js CHANGED
@@ -19,7 +19,7 @@ Usage:
19
19
  npx agentic-mobile-kit doctor
20
20
 
21
21
  Commands:
22
- init Install the kit into a bare React Native project (run in the app's root).
22
+ init Install the kit into a React Native or Expo app (run in the app's root).
23
23
  sync Update the kit's files to this version. Your own changes to them are merged in, not lost.
24
24
  uninstall Remove the kit's files and sections. Files you changed are kept and listed.
25
25
  doctor Check the project and this machine, with a fix for each problem.
package/lib/doctor.js CHANGED
@@ -66,7 +66,7 @@ function projectChecks(cwd, opts) {
66
66
  out.push(r.status === 0 ? ok('File names match git') : fail(`Renamed only in letter case, and git missed it:${lines.slice(1, -1).join(',')}`, lines.pop()));
67
67
  }
68
68
 
69
- const tracked = (run('git', ['ls-files'], { cwd }) || '').split('\n').filter(f => /(^|\/)\.env(\.(?!example$)[\w.-]+)?$/.test(f));
69
+ const tracked = (run('git', ['ls-files'], { cwd }) || '').split('\n').filter(f => /(^|\/)\.env(\.[\w.-]+)?$/.test(f) && !/\.(example|sample|template)$/.test(f));
70
70
  out.push(tracked.length ? fail(`Secret files tracked by git: ${tracked.join(', ')}`, 'git rm --cached them, rotate the secrets, keep them out of the repo') : ok('No .env files in git'));
71
71
 
72
72
  const claudeLink = path.join(cwd, '.claude/skills');
package/lib/init.js CHANGED
@@ -16,6 +16,9 @@ const FILLED = ['AGENTS.md', 'codemagic.yaml'];
16
16
  // docs each team rewrites for its app: sync replaces them only while they're untouched, and never merges into them
17
17
  const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/ai/${n}.md`);
18
18
  const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
19
+ // the app's own ESLint skips the kit's scripts: they follow the kit's style, not each app's rules
20
+ const ESLINT_IGNORE = 'scripts/ai/';
21
+ const ESLINT_NOTE = "# agentic-mobile-kit: its scripts follow the kit's style, not this app's lint rules";
19
22
  // optional parts, installed only when a project chooses them with --ci: not every app uses CI
20
23
  const CI = {
21
24
  github: rel => rel.startsWith('.github/'),
@@ -91,10 +94,33 @@ function checkProject(cwd) {
91
94
  const pkg = readJson(pkgFile);
92
95
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
93
96
  if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
94
- if (!fs.existsSync(path.join(cwd, 'ios')) || !fs.existsSync(path.join(cwd, 'android'))) {
95
- throw new InitError('No ios/ and android/ folders found. Only bare React Native projects are supported for now (Expo support comes later).');
97
+ const stack = detectStack(cwd, deps);
98
+ if (stack === 'bare' && (!fs.existsSync(path.join(cwd, 'ios')) || !fs.existsSync(path.join(cwd, 'android')))) {
99
+ throw new InitError('No ios/ and android/ folders found, and this isn\'t an Expo app. The kit supports bare React Native and Expo apps.');
96
100
  }
97
- return { pkg, deps };
101
+ return { pkg, deps, stack };
102
+ }
103
+
104
+ // Expo apps whose ios/ and android/ come from `expo prebuild` (Continuous Native Generation, not in git) get the
105
+ // Expo overlay. Expo apps that keep the native folders in git are set up like bare apps.
106
+ function detectStack(cwd, deps) {
107
+ return deps.expo && !git(cwd, 'ls-files', 'ios', 'android') ? 'expo' : 'bare';
108
+ }
109
+
110
+ // a stack's files, rel -> source: the template, and for Expo the overlay next to it, which replaces or adds files
111
+ const EXPO_LEAVES_OUT = ['docs/ai/react-native.md', '.agents/skills/upgrading-react-native/'];
112
+ function stackFiles(template, stack) {
113
+ const files = new Map(templateFiles(template).map(rel => [rel, path.join(template, rel)]));
114
+ if (stack !== 'expo') return files;
115
+ for (const rel of files.keys()) if (EXPO_LEAVES_OUT.some(f => (f.endsWith('/') ? rel.startsWith(f) : rel === f))) files.delete(rel);
116
+ const overlay = path.join(template, '..', 'expo');
117
+ if (fs.existsSync(overlay)) for (const rel of templateFiles(overlay)) files.set(rel, path.join(overlay, rel));
118
+ return files;
119
+ }
120
+
121
+ // app.json's expo section, for the values the kit fills in (app.config.* would need the Expo CLI to evaluate)
122
+ function expoConfig(cwd) {
123
+ try { return readJson(path.join(cwd, 'app.json')).expo || {}; } catch { return {}; }
98
124
  }
99
125
 
100
126
  // all files under dir, as relative paths with "/" on every OS (as git shows them), including dotfiles
@@ -124,15 +150,19 @@ function fillPlaceholders(text, values) {
124
150
  function architecture(cwd, rnVersion) {
125
151
  const [major, minor] = String(rnVersion).split('.').map(Number);
126
152
  if (!(major === 0 && minor < 82)) return 'New Architecture';
127
- const flag = ((readIf(path.join(cwd, 'android', 'gradle.properties')) || '').match(/^\s*newArchEnabled\s*=\s*(true|false)/m) || [])[1];
153
+ // Expo apps without native folders set it in app.json
154
+ const flag = ((readIf(path.join(cwd, 'android', 'gradle.properties')) || '').match(/^\s*newArchEnabled\s*=\s*(true|false)/m) || [])[1]
155
+ || (typeof expoConfig(cwd).newArchEnabled === 'boolean' ? String(expoConfig(cwd).newArchEnabled) : undefined);
128
156
  return (flag ? flag === 'true' : minor >= 76) ? 'New Architecture' : 'Old Architecture: newArchEnabled=false';
129
157
  }
130
158
 
131
- function projectValues(cwd, pkg, deps, pm, ci) {
159
+ function projectValues(cwd, pkg, deps, pm, ci, stack) {
132
160
  const rn = installedVersion(cwd, 'react-native', deps['react-native']);
133
161
  return {
134
162
  KIT_VERSION,
135
163
  KIT_CI: ci.join(',') || 'none',
164
+ KIT_STACK: stack,
165
+ EXPO_SDK: deps.expo ? installedVersion(cwd, 'expo', deps.expo).split('.')[0] : '',
136
166
  APP_NAME: pkg.name || path.basename(cwd),
137
167
  RN_VERSION: rn,
138
168
  RN_ARCH: architecture(cwd, rn),
@@ -141,13 +171,13 @@ function projectValues(cwd, pkg, deps, pm, ci) {
141
171
  NODE_VERSION: (pkg.engines && pkg.engines.node) || `${process.versions.node.split('.')[0]}`,
142
172
  PM: pm.name,
143
173
  PM_RUN: pm.run,
144
- IOS_BUNDLE_ID: iosBundleId(cwd),
174
+ IOS_BUNDLE_ID: stack === 'expo' ? (expoConfig(cwd).ios || {}).bundleIdentifier || 'com.example.app' : iosBundleId(cwd),
145
175
  };
146
176
  }
147
177
 
148
178
  // a template file's text as the kit writes it into this project
149
- function kitText(templateDir, rel, values, targets) {
150
- const text = fs.readFileSync(path.join(templateDir, rel), 'utf8');
179
+ function kitText(src, rel, values, targets) {
180
+ const text = fs.readFileSync(src, 'utf8');
151
181
  if (FILLED.includes(rel)) return fillPlaceholders(text, values);
152
182
  if (rel === 'rulesync.jsonc') return setTargets(text, targets);
153
183
  return text;
@@ -181,10 +211,10 @@ function installedTools(cwd) {
181
211
  return tools.length ? tools : TESTED;
182
212
  }
183
213
 
184
- // what the kit marker in AGENTS.md records: the kit version since 0.4.0, the CI choice since 0.5.0
214
+ // what the kit marker in AGENTS.md records: the kit version since 0.4.0, the CI choice since 0.5.0, the stack since 0.6.0
185
215
  function recorded(agents) {
186
- const m = (agents || '').match(/KIT:START agentic-mobile-kit (\d[^\s>]*)(?: ci=([\w,]+))?/);
187
- return { version: m ? m[1] : null, ci: m && m[2] ? m[2].split(',').filter(g => CI[g]) : null };
216
+ const m = (agents || '').match(/KIT:START agentic-mobile-kit (\d[^\s>]*)(?: ci=([\w,]+))?(?: stack=(\w+))?/);
217
+ return { version: m ? m[1] : null, ci: m && m[2] ? m[2].split(',').filter(g => CI[g]) : null, stack: m && m[3] ? m[3] : null };
188
218
  }
189
219
 
190
220
  // the CI parts a project has: as recorded, or (installs before 0.5.0 got them by default) recognized by the kit's own files
@@ -364,10 +394,10 @@ function dropHooksCmd(scripts) {
364
394
  }
365
395
 
366
396
  const SKILL_LINKS = [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']];
367
- const kitSkills = template => fs.readdirSync(path.join(template, '.agents', 'skills'), { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
397
+ const kitSkills = files => [...files.keys()].filter(rel => /^\.agents\/skills\/[^/]+\/SKILL\.md$/.test(rel)).map(rel => rel.split('/')[2]);
368
398
 
369
399
  // steps 2–6, shared by init and sync
370
- function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
400
+ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
371
401
  const done = { created: [], merged: [], skipped: [], warnings: [] };
372
402
  // Windows creates symbolic links only with Developer Mode on (or as admin)
373
403
  const link = (target, p, label) => {
@@ -389,7 +419,7 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
389
419
  }
390
420
  if (isLink(dest) || !fs.statSync(dest).isDirectory()) { done.skipped.push(linkPath); continue; }
391
421
  // the folder already holds another framework's skills: link each kit skill into it
392
- for (const name of kitSkills(template)) {
422
+ for (const name of kitSkills(files)) {
393
423
  const p = path.join(dest, name);
394
424
  const target = `../../.agents/skills/${name}`;
395
425
  if (isLink(p) && linkTarget(p) === target) continue;
@@ -402,9 +432,11 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
402
432
  // 3. .gitignore: keep secrets out of git
403
433
  const gi = path.join(cwd, '.gitignore');
404
434
  const giText = readIf(gi) || '';
405
- const missing = ['.env', '.env.*', '!.env.example', '.ai/'].filter(l => !giText.split('\n').includes(l));
435
+ // Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
436
+ const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.ai/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
437
+ const missing = ignored.filter(l => !giText.split('\n').includes(l));
406
438
  if (missing.length) {
407
- fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .ai/ holds local evidence (screenshots, logs)\n${missing.join('\n')}\n`);
439
+ fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .ai/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
408
440
  done.merged.push('.gitignore');
409
441
  }
410
442
 
@@ -417,6 +449,16 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
417
449
  done.merged.push('.gitattributes');
418
450
  }
419
451
 
452
+ // 3c. .eslintignore, for apps on ESLint's eslintrc config (ESLint 9's flat config doesn't read the file;
453
+ // the kit's scripts pass React Native's default rules, but stricter configs such as Airbnb's flag them)
454
+ const eslintrc = fs.readdirSync(cwd).some(f => /^\.eslintrc(\.\w+)?$/.test(f)) || Boolean(pkg.eslintConfig);
455
+ const ei = path.join(cwd, '.eslintignore');
456
+ const eiText = readIf(ei) || '';
457
+ if (eslintrc && !eiText.split('\n').includes(ESLINT_IGNORE)) {
458
+ fs.writeFileSync(ei, `${eiText.replace(/\n*$/, eiText ? '\n' : '')}${eiText ? '\n' : ''}${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`);
459
+ (eiText ? done.merged : done.created).push('.eslintignore');
460
+ }
461
+
420
462
  // 4. package.json scripts: typecheck, and hooks path on install (never overwrite existing scripts)
421
463
  const scripts = (pkg.scripts = pkg.scripts || {});
422
464
  let pkgChanged = false;
@@ -466,21 +508,21 @@ function init(cwd, opts = {}) {
466
508
  let prefix = '';
467
509
  try { prefix = git(cwd, 'rev-parse', '--show-prefix').replace(/\/$/, ''); } catch {}
468
510
  if (prefix) throw new InitError(`This app is in a subfolder of its git repository (${prefix}), as in a monorepo. The kit doesn't support that yet: git runs hooks from the repository root, and GitHub reads workflows only there.`);
469
- const { pkg, deps } = checkProject(cwd);
511
+ const { pkg, deps, stack } = checkProject(cwd);
470
512
  const pm = detectPm(cwd, opts.pm);
471
513
  const tools = opts.tools || TESTED;
472
514
  for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
473
- const template = opts.template || TEMPLATE;
515
+ const files = stackFiles(opts.template || TEMPLATE, stack);
474
516
  const ci = chooseCi(cwd, readIf(path.join(cwd, 'AGENTS.md')), opts.ci);
475
- const values = projectValues(cwd, pkg, deps, pm, ci);
517
+ const values = projectValues(cwd, pkg, deps, pm, ci, stack);
476
518
  const targets = tools.flatMap(t => TOOLS[t]);
477
519
  const report = { created: [], merged: [], skipped: [] };
478
520
 
479
521
  // 1. template files (never overwrite)
480
- for (const rel of templateFiles(template)) {
522
+ for (const [rel, src] of files) {
481
523
  if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
482
524
  const dest = path.join(cwd, rel);
483
- const text = kitText(template, rel, values, targets);
525
+ const text = kitText(src, rel, values, targets);
484
526
  const current = readIf(dest);
485
527
  if (current !== null && (rel === 'AGENTS.md' || rel === 'CLAUDE.md')) {
486
528
  const next = rel === 'AGENTS.md' ? mergeAgents(current, text) : mergeClaude(current);
@@ -492,32 +534,33 @@ function init(cwd, opts = {}) {
492
534
  report.created.push(rel);
493
535
  }
494
536
 
495
- const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
537
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files, stack, skipGenerate: opts.skipGenerate });
496
538
  for (const k of Object.keys(report)) report[k].push(...done[k]);
497
539
  return { report, warnings: done.warnings, values, tools, ci, generated, generateError };
498
540
  }
499
541
 
500
542
  function sync(cwd, opts = {}) {
501
- const { pkg, deps } = checkProject(cwd);
543
+ const { pkg, deps, stack: detected } = checkProject(cwd);
502
544
  const agents = readIf(path.join(cwd, 'AGENTS.md'));
503
545
  if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section). Run init instead.');
504
546
  const { from, dir: oldDir, exact } = oldTemplate(agents, opts);
505
- const template = opts.template || TEMPLATE;
547
+ // installs before 0.6.0 don't record it, and were all bare
548
+ const stack = recorded(agents).stack || detected;
506
549
  const ci = chooseCi(cwd, agents, opts.ci);
507
550
  // a CI part chosen just now was never installed, so its files are new rather than deleted by the team
508
551
  const hadCi = installedCi(cwd, agents);
509
552
  const wasInstalled = rel => !ciGroup(rel) || hadCi.includes(ciGroup(rel));
510
- const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci);
553
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci, stack);
511
554
  const tools = installedTools(cwd);
512
555
  const targets = tools.flatMap(t => TOOLS[t]);
513
556
  const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
514
- const newFiles = templateFiles(template);
515
- const oldFiles = new Set(templateFiles(oldDir));
557
+ const newFiles = stackFiles(opts.template || TEMPLATE, stack);
558
+ const oldFiles = stackFiles(oldDir, stack);
516
559
 
517
- for (const rel of newFiles) {
560
+ for (const [rel, src] of newFiles) {
518
561
  if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
519
- const kitNew = kitText(template, rel, values, targets);
520
- const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldDir, rel, values, targets) : null;
562
+ const kitNew = kitText(src, rel, values, targets);
563
+ const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldFiles.get(rel), rel, values, targets) : null;
521
564
  const current = projectText(cwd, rel, targets);
522
565
  if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
523
566
  const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, kitNew) : mergeClaude(current);
@@ -539,14 +582,14 @@ function sync(cwd, opts = {}) {
539
582
  (conflicts ? report.conflicts : report.merged).push(rel);
540
583
  }
541
584
  // files the kit no longer ships
542
- for (const rel of oldFiles) {
543
- if (newFiles.includes(rel) || !wasInstalled(rel)) continue;
585
+ for (const [rel, src] of oldFiles) {
586
+ if (newFiles.has(rel) || !wasInstalled(rel)) continue;
544
587
  const current = projectText(cwd, rel, targets);
545
588
  if (current === null) continue;
546
- if (current === kitText(oldDir, rel, values, targets)) { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); } else report.kept.push(`${rel} (the kit dropped it; you changed it)`);
589
+ if (current === kitText(src, rel, values, targets)) { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); } else report.kept.push(`${rel} (the kit dropped it; you changed it)`);
547
590
  }
548
591
 
549
- const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
592
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files: newFiles, stack, skipGenerate: opts.skipGenerate });
550
593
  report.added.push(...done.created);
551
594
  report.updated.push(...done.merged);
552
595
  return { report, warnings: done.warnings, from, to: KIT_VERSION, tools, generated, generateError };
@@ -566,18 +609,19 @@ function generatedFiles(cwd) {
566
609
  }
567
610
 
568
611
  function uninstall(cwd, opts = {}) {
569
- const { pkg, deps } = checkProject(cwd);
612
+ const { pkg, deps, stack: detected } = checkProject(cwd);
570
613
  const agents = readIf(path.join(cwd, 'AGENTS.md'));
571
614
  if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section).');
572
615
  const { from, dir: template } = oldTemplate(agents, opts);
573
- const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), installedCi(cwd, agents));
616
+ const stack = recorded(agents).stack || detected;
617
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), installedCi(cwd, agents), stack);
574
618
  const targets = installedTools(cwd).flatMap(t => TOOLS[t]);
575
619
  const report = { removed: [], kept: [], left: [] };
576
620
  const remove = rel => { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); };
577
621
  // listed before their sources are removed
578
622
  const generated = opts.skipGenerate ? [] : generatedFiles(cwd);
579
623
 
580
- for (const rel of templateFiles(template)) {
624
+ for (const [rel, src] of stackFiles(template, stack)) {
581
625
  const current = projectText(cwd, rel, targets);
582
626
  if (current === null) continue;
583
627
  if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
@@ -586,7 +630,7 @@ function uninstall(cwd, opts = {}) {
586
630
  else if (rest !== current) { fs.writeFileSync(path.join(cwd, rel), rest.replace(/\n+$/, '\n')); report.removed.push(`${rel} (the kit's part)`); }
587
631
  continue;
588
632
  }
589
- if (current === kitText(template, rel, values, targets)) remove(rel); else report.kept.push(rel);
633
+ if (current === kitText(src, rel, values, targets)) remove(rel); else report.kept.push(rel);
590
634
  }
591
635
  for (const [rel, text] of generated) {
592
636
  const current = readIf(path.join(cwd, rel));
@@ -618,13 +662,21 @@ function uninstall(cwd, opts = {}) {
618
662
  if (pkgChanged) fs.writeFileSync(path.join(cwd, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
619
663
  try { if (git(cwd, 'config', 'core.hooksPath') === '.githooks') git(cwd, 'config', '--unset', 'core.hooksPath'); } catch {}
620
664
 
665
+ // .eslintignore: the kit's lines, and the file if nothing else is in it
666
+ const eiText = readIf(path.join(cwd, '.eslintignore'));
667
+ if (eiText !== null && eiText.split('\n').includes(ESLINT_IGNORE)) {
668
+ const rest = eiText.split('\n').filter(l => l !== ESLINT_IGNORE && l !== ESLINT_NOTE).join('\n').replace(/\n{3,}/g, '\n\n');
669
+ if (!rest.trim()) fs.unlinkSync(path.join(cwd, '.eslintignore')); else fs.writeFileSync(path.join(cwd, '.eslintignore'), rest.replace(/\n*$/, '\n'));
670
+ report.removed.push('.eslintignore (the kit\'s lines)');
671
+ }
672
+
621
673
  report.left.push('.gitignore lines for .env files and .ai/ (they keep secrets and local evidence out of git)');
622
674
  if (scripts.typecheck === 'tsc --noEmit') report.left.push('the "typecheck" script in package.json');
623
675
  return { report, from };
624
676
  }
625
677
 
626
678
  function printSummary({ report, warnings = [], values, tools, ci, generated, generateError }, log = console.log) {
627
- log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
679
+ log(`agentic-mobile-kit installed for ${values.APP_NAME} (${values.KIT_STACK === 'expo' ? `Expo SDK ${values.EXPO_SDK}, ` : ''}React Native ${values.RN_VERSION}, ${values.PM}).`);
628
680
  log(`Tools: ${tools.join(', ')}${tools.some(t => !TESTED.includes(t)) ? ' (cursor, opencode and kiro are not tested yet)' : ''}`);
629
681
  log(`CI: ${ci.length ? ci.join(', ') : 'none (add it any time with --ci github,codemagic)'}`);
630
682
  log(` created: ${report.created.length} files`);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.5.6",
4
- "description": "One setup for AI-assisted development of bare React Native apps: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
3
+ "version": "0.6.1",
4
+ "description": "One setup for AI-assisted development of React Native apps, bare or Expo: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
7
7
  "repository": {
@@ -26,6 +26,8 @@
26
26
  "keywords": [
27
27
  "react-native",
28
28
  "bare-react-native",
29
+ "expo",
30
+ "expo-router",
29
31
  "mobile",
30
32
  "ios",
31
33
  "android",
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2025-present 650 Industries, Inc. (aka Expo)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,11 @@
1
+ # Third-party skills
2
+
3
+ | Skill | Source | Commit | License | Changes |
4
+ |---|---|---|---|---|
5
+ | expo-router | https://github.com/expo/skills | d4f484024fec15196bfd3c272e953e3f983972cf | MIT (`LICENSE-expo`) | Image files left out |
6
+ | expo-upgrade | same | same | MIT | Image files left out |
7
+ | expo-module | same | same | MIT | Image files left out |
8
+ | react-native-best-practices | https://github.com/callstackincubator/agent-skills | 61e6e7dfdf3a8ee862254c200d751fcb1fb863dc | MIT (`LICENSE-callstack`) | Image files left out |
9
+ | react-navigation | same | same | MIT | Image files left out |
10
+
11
+ Updated with `scripts/vendor-skills.sh` in the agentic-mobile-kit repo.
@@ -0,0 +1,151 @@
1
+ ---
2
+ name: expo-module
3
+ description: Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo. Not for migrating an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros; use expo-migrate-module (from the expo-experiments plugin) for that.
4
+ version: 1.0.0
5
+ license: MIT
6
+ ---
7
+
8
+ # Writing Expo Modules
9
+
10
+ Complete reference for building native modules and views using the Expo Modules API. Covers Swift (iOS), Kotlin (Android), and TypeScript.
11
+
12
+ ## When to Use
13
+
14
+ - Creating a new Expo native module or native view
15
+ - Adding native functionality (camera, sensors, system APIs) to an Expo app
16
+ - Wrapping platform SDKs for React Native consumption
17
+ - Building config plugins that modify native project files
18
+ - Adding Android, Apple, or web support to an existing Expo module
19
+ - Editing `expo-module.config.json`, config plugins, or lifecycle hooks
20
+
21
+ To migrate an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros (`@ExpoModule`, `@JS`, `@Event`), use the `expo-migrate-module` skill (from the `expo-experiments` plugin) instead.
22
+
23
+ ## References
24
+
25
+ Consult these resources as needed:
26
+
27
+ ```
28
+ references/
29
+ create-expo-module.md Scaffolding and add-platform-support workflow, defaults, and quirks
30
+ native-module.md Module definition DSL: Name, Function, AsyncFunction, Property, Constant, Events, type system, shared objects
31
+ native-view.md Native view components: View, Prop, EventDispatcher, view lifecycle, ref-based functions
32
+ lifecycle.md Lifecycle hooks: module, iOS app/AppDelegate, Android activity/application listeners
33
+ config-plugin.md Config plugins: modifying Info.plist, AndroidManifest.xml, reading values in native code
34
+ module-config.md expo-module.config.json fields, file placement, and autolinking behavior
35
+ ```
36
+
37
+ ## Quick Start
38
+
39
+ Prefer `create-expo-module` over manually creating native module files and directories. In practice, the best path is usually to create the scaffold first and then build on top of it. The scaffold sets up the expected layout, `expo-module.config.json`, podspec or Gradle files, TypeScript bindings, and the standalone example app flow.
40
+
41
+ If an existing Expo module only needs another platform, use `create-expo-module add-platform-support` instead of manually copying native directories.
42
+
43
+ See [references/create-expo-module.md](references/create-expo-module.md) before scaffolding or extending a module. It covers:
44
+
45
+ - local vs standalone modules
46
+ - `--platform`, `--features`, `--barrel`, `--package-manager`, and non-interactive mode
47
+ - `expo.autolinking.nativeModulesDir`
48
+ - `add-platform-support` behavior and quirks
49
+
50
+ ## Recommended Workflow
51
+
52
+ 1. Choose the scaffold type first:
53
+ - **Local module** for one app
54
+ - **Standalone module** for reuse, monorepos, or publishing
55
+ 2. Determine native `expo-module` features that you will need.
56
+ - Based on the user's instructions determine which feature scaffolding will be useful.
57
+ - Available features: `Constant`, `Function`, `AsyncFunction`, `Event`, `View`, `ViewEvent`, `SharedObject`
58
+ 3. Scaffold deliberately:
59
+ - pass an explicit slug or path
60
+ - choose `--platform` intentionally instead of relying on defaults
61
+ - use `--features` to choose code samples which you will modify in the next step to match the real implementation.
62
+ 4. Replace generated example code with the real implementation.
63
+ 5. If you add a new platform later, prefer `add-platform-support` over manual file copying.
64
+
65
+ ## Practical Scaffolding Rules
66
+
67
+ - Feature examples are **opt-in**. A newly scaffolded module may be minimal if no features were selected.
68
+ - `ViewEvent` implies `View`.
69
+ - Local modules do **not** generate an `index.ts` barrel by default. Use `--barrel` only if you want one.
70
+ - In non-interactive local scaffolding, pass the positional slug or path explicitly. `--name` changes the native class name, not the folder name.
71
+ - Local modules live in `expo.autolinking.nativeModulesDir` when configured, otherwise in `modules/`.
72
+ - Standalone modules have their own package metadata, scripts, and usually an example app. Local modules use the host app's tooling instead.
73
+
74
+ ## Core File Shapes
75
+
76
+ The Swift and Kotlin DSL share the same structure. Swift is usually the clearest primary example; consult the references for feature-specific details.
77
+
78
+ ## Module Structure Reference
79
+
80
+ The Swift and Kotlin DSL share the same structure. Both platforms are shown here for reference — in other reference files, Swift is shown as the primary language unless the Kotlin pattern meaningfully differs.
81
+
82
+ **Swift (iOS):**
83
+
84
+ ```swift
85
+ import ExpoModulesCore
86
+
87
+ public class MyModule: Module {
88
+ public func definition() -> ModuleDefinition {
89
+ Name("MyModule")
90
+
91
+ Function("hello") { (name: String) -> String in
92
+ return "Hello \(name)!"
93
+ }
94
+ }
95
+ }
96
+ ```
97
+
98
+ **Kotlin (Android):**
99
+
100
+ ```kotlin
101
+ package expo.modules.mymodule
102
+
103
+ import expo.modules.kotlin.modules.Module
104
+ import expo.modules.kotlin.modules.ModuleDefinition
105
+
106
+ class MyModule : Module() {
107
+ override fun definition() = ModuleDefinition {
108
+ Name("MyModule")
109
+
110
+ Function("hello") { name: String ->
111
+ "Hello $name!"
112
+ }
113
+ }
114
+ }
115
+ ```
116
+
117
+ **TypeScript:**
118
+
119
+ ```typescript
120
+ import { requireNativeModule } from "expo";
121
+
122
+ const MyModule = requireNativeModule("MyModule");
123
+
124
+ export function hello(name: string): string {
125
+ return MyModule.hello(name);
126
+ }
127
+ ```
128
+
129
+ ### expo-module.config.json
130
+
131
+ ```json
132
+ {
133
+ "platforms": ["android", "apple"],
134
+ "apple": {
135
+ "modules": ["MyModule"]
136
+ },
137
+ "android": {
138
+ "modules": ["expo.modules.mymodule.MyModule"]
139
+ }
140
+ }
141
+ ```
142
+
143
+ Note: iOS uses just the class name; Android uses the fully-qualified class name (package + class). See `references/module-config.md` for all fields.
144
+
145
+ ## Submitting Feedback
146
+ If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
147
+ ```bash
148
+ npx --yes submit-expo-feedback@latest --category skills --subject "expo-module" "<actionable feedback>"
149
+ ```
150
+ Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
151
+ If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Expo Module"
3
+ short_description: "Build Expo native modules and native views with Swift, Kotlin, TypeScript, autolinking, and config plugins"
4
+ default_prompt: "Use $expo-module to scaffold, implement, clean up, or review Expo native modules, native views, shared objects, lifecycle hooks, autolinking configuration, and config plugins."
@@ -0,0 +1,90 @@
1
+ # Config Plugins Reference
2
+
3
+ Config plugins customize native Android and iOS projects generated with `npx expo prebuild`. They are synchronous functions that accept an `ExpoConfig` and return a modified version.
4
+
5
+ ## Plugin Structure
6
+
7
+ ```
8
+ my-module/
9
+ plugin/
10
+ tsconfig.json
11
+ src/
12
+ index.ts
13
+ app.plugin.js # Entry: module.exports = require('./plugin/build');
14
+ ```
15
+
16
+ ## Writing a Plugin
17
+
18
+ Plugin functions follow the `with` prefix naming convention.
19
+
20
+ ```typescript
21
+ import {
22
+ ConfigPlugin,
23
+ withInfoPlist,
24
+ withAndroidManifest,
25
+ AndroidConfig,
26
+ } from "expo/config-plugins";
27
+
28
+ const withMyConfig: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
29
+ // iOS: modify Info.plist
30
+ config = withInfoPlist(config, (config) => {
31
+ config.modResults["MY_API_KEY"] = apiKey;
32
+ return config;
33
+ });
34
+
35
+ // Android: modify AndroidManifest.xml
36
+ config = withAndroidManifest(config, (config) => {
37
+ const mainApp =
38
+ AndroidConfig.Manifest.getMainApplicationOrThrow(config.modResults);
39
+ AndroidConfig.Manifest.addMetaDataItemToMainApplication(
40
+ mainApp,
41
+ "MY_API_KEY",
42
+ apiKey
43
+ );
44
+ return config;
45
+ });
46
+
47
+ return config;
48
+ };
49
+
50
+ export default withMyConfig;
51
+ ```
52
+
53
+ ## Using in app.json
54
+
55
+ ```json
56
+ {
57
+ "expo": {
58
+ "plugins": [["my-module", { "apiKey": "secret_key" }]]
59
+ }
60
+ }
61
+ ```
62
+
63
+ ## Reading Config Values in Native Code
64
+
65
+ **Swift:**
66
+
67
+ ```swift
68
+ Function("getApiKey") {
69
+ return Bundle.main.object(forInfoDictionaryKey: "MY_API_KEY") as? String
70
+ }
71
+ ```
72
+
73
+ **Kotlin:**
74
+
75
+ ```kotlin
76
+ Function("getApiKey") {
77
+ val appInfo = appContext?.reactContext?.packageManager?.getApplicationInfo(
78
+ appContext?.reactContext?.packageName.toString(),
79
+ PackageManager.GET_META_DATA
80
+ )
81
+ return@Function appInfo?.metaData?.getString("MY_API_KEY")
82
+ }
83
+ ```
84
+
85
+ ## Key Rules
86
+
87
+ - Plugins must be synchronous; return values must be serializable (except `mods`)
88
+ - `Mods` are async functions invoked during the prebuild "syncing" phase
89
+ - Use `npm run build plugin` to compile TypeScript plugins
90
+ - Test with `npx expo prebuild --clean`