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
package/README.md CHANGED
@@ -1,16 +1,28 @@
1
1
  # agentic-mobile-kit
2
2
 
3
- One setup for AI-assisted mobile development that works the same in Claude Code, Codex, Cursor, OpenCode, Kiro and Antigravity.
3
+ One setup for AI-assisted mobile development that works the same in Claude Code, Codex and Antigravity (Cursor, OpenCode and Kiro next).
4
4
 
5
- > **Status: early development.** This version only reserves the package name. It has no commands yet.
5
+ > **Status: early development.** Bare React Native projects only for now; Expo comes next.
6
6
 
7
- ## What it will do
7
+ ## Install into a bare React Native app
8
8
 
9
- - Add a short `AGENTS.md` and shared Agent Skills (`feature`, `bugfix`, `continue`, `pause`, `review`, `release-notes`, `learn`) that every supported tool reads.
10
- - Enforce quality outside the AI: git hooks, CI checks for Android and iOS builds, secret scanning and PR size limits.
11
- - Require evidence before a task counts as done: test output plus simulator and emulator screenshots.
12
- - Keep task state in the repo, so work can continue in another tool or on another machine.
13
- - Support React Native (Expo and bare) first, with Flutter and native apps later.
9
+ Run in the app's root, on a clean git working tree:
10
+
11
+ ```sh
12
+ npx agentic-mobile-kit init
13
+ npx agentic-mobile-kit init --tools claude,codex,antigravity # choose your AI tools
14
+ ```
15
+
16
+ `init` never overwrites your files. It adds its section to an existing `AGENTS.md` between `KIT` markers, and it's safe to run again. Undo it with git.
17
+
18
+ ## What it adds
19
+
20
+ - **Context for every AI tool:** `AGENTS.md` (plus a one-line `CLAUDE.md`), `docs/ai/` (product, tech, structure, conventions, decisions, known issues, React Native rules) and spec templates in `specs/_templates/`.
21
+ - **Workflows:** the skills `m-feature`, `m-bugfix`, `m-continue`, `m-pause` and `m-review`. Invoke them with `/m-feature` in Claude Code and Antigravity, or `$m-feature` in Codex. Also Callstack's React Native skills.
22
+ - **Guardrails in each tool:** a guard hook that blocks destructive commands and secret files, a stop hook that asks for a handoff update, permission rules and a read-only `m-reviewer` subagent, generated with rulesync.
23
+ - **Checks no tool can skip:** git hooks (secrets, signing files, broken Xcode project files, lint, typecheck, tests) and GitHub Actions CI (lint, typecheck, tests, secret scan, PR size, Android and iOS builds).
24
+
25
+ Work continues across tools and machines through `specs/<id>/progress.md`: run `m-pause` in one tool, then `m-continue` in another.
14
26
 
15
27
  ## License
16
28
 
package/bin/cli.js CHANGED
@@ -1,11 +1,37 @@
1
1
  #!/usr/bin/env node
2
- // ponytail: placeholder that only reserves the name; the real init/sync/doctor/uninstall CLI comes later.
3
2
  const { version } = require('../package.json');
4
- const arg = process.argv[2];
3
+ const { init, printSummary, InitError, TOOLS } = require('../lib/init');
5
4
 
6
- if (arg === '--version' || arg === '-v') {
5
+ const [cmd, ...rest] = process.argv.slice(2);
6
+ const flag = name => {
7
+ const i = rest.indexOf(`--${name}`);
8
+ return i >= 0 ? rest[i + 1] : undefined;
9
+ };
10
+
11
+ const help = `agentic-mobile-kit ${version}
12
+
13
+ Usage:
14
+ npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--pm yarn|npm|pnpm|bun]
15
+
16
+ Commands:
17
+ init Install the kit into a bare React Native project (run in the app's root).
18
+
19
+ Options:
20
+ --tools AI tools your team uses: ${Object.keys(TOOLS).join(', ')} (default: claude,codex,antigravity)
21
+ --pm Package manager, if it can't be detected from the lockfile`;
22
+
23
+ if (cmd === '--version' || cmd === '-v') {
7
24
  console.log(version);
25
+ } else if (cmd === 'init') {
26
+ try {
27
+ const tools = flag('tools') ? flag('tools').split(',').map(s => s.trim()).filter(Boolean) : undefined;
28
+ printSummary(init(process.cwd(), { tools, pm: flag('pm') }));
29
+ } catch (e) {
30
+ if (!(e instanceof InitError)) throw e;
31
+ console.error(`init stopped: ${e.message}`);
32
+ process.exitCode = 1;
33
+ }
8
34
  } else {
9
- console.log(`agentic-mobile-kit ${version} is in early development and has no commands yet.`);
10
- if (arg) process.exitCode = 1;
35
+ console.log(help);
36
+ if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h') process.exitCode = 1;
11
37
  }
package/lib/init.js ADDED
@@ -0,0 +1,199 @@
1
+ 'use strict';
2
+ // `agentic-mobile-kit init`: installs the kit into a bare React Native project.
3
+ // Never overwrites existing files; merges AGENTS.md / CLAUDE.md; git is the backup (clean tree required).
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { execFileSync, spawnSync } = require('child_process');
7
+
8
+ const TEMPLATE = path.join(__dirname, '..', 'stacks', 'react-native', 'template');
9
+ const RULESYNC = 'rulesync@27.0.0';
10
+ const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
11
+
12
+ // tool name -> rulesync targets
13
+ const TOOLS = {
14
+ claude: ['claudecode'],
15
+ codex: ['codexcli'],
16
+ antigravity: ['antigravity-ide', 'antigravity-cli'],
17
+ cursor: ['cursor'],
18
+ opencode: ['opencode'],
19
+ kiro: ['kiro-ide', 'kiro-cli'],
20
+ };
21
+ const TESTED = ['claude', 'codex', 'antigravity'];
22
+
23
+ class InitError extends Error {}
24
+
25
+ function git(cwd, ...args) {
26
+ return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
27
+ }
28
+
29
+ function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
30
+
31
+ function installedVersion(cwd, pkg, declared) {
32
+ try { return readJson(path.join(cwd, 'node_modules', pkg, 'package.json')).version; } catch {}
33
+ return declared ? String(declared).replace(/^[\^~>=<\s]+/, '') : 'unknown';
34
+ }
35
+
36
+ function detectPm(cwd, forced) {
37
+ const pms = {
38
+ yarn: { name: 'Yarn', run: 'yarn', lock: 'yarn.lock' },
39
+ pnpm: { name: 'pnpm', run: 'pnpm', lock: 'pnpm-lock.yaml' },
40
+ bun: { name: 'Bun', run: 'bun run', lock: 'bun.lock' },
41
+ npm: { name: 'npm', run: 'npm run', lock: 'package-lock.json' },
42
+ };
43
+ if (forced) {
44
+ if (!pms[forced]) throw new InitError(`Unknown package manager "${forced}". Use npm, yarn, pnpm or bun.`);
45
+ return pms[forced];
46
+ }
47
+ for (const [, pm] of Object.entries(pms)) {
48
+ if (fs.existsSync(path.join(cwd, pm.lock)) || (pm.lock === 'bun.lock' && fs.existsSync(path.join(cwd, 'bun.lockb')))) return pm;
49
+ }
50
+ return pms.npm;
51
+ }
52
+
53
+ function checkProject(cwd) {
54
+ try { git(cwd, 'rev-parse', '--is-inside-work-tree'); } catch {
55
+ throw new InitError('This folder is not a git repository. Run "git init" and commit first; git is how init can be undone.');
56
+ }
57
+ if (git(cwd, 'status', '--porcelain')) {
58
+ throw new InitError('You have uncommitted changes. Commit or stash them first, so init can be undone with git.');
59
+ }
60
+ const pkgFile = path.join(cwd, 'package.json');
61
+ if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run init in the root of your React Native app.');
62
+ const pkg = readJson(pkgFile);
63
+ const deps = { ...pkg.dependencies, ...pkg.devDependencies };
64
+ if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
65
+ if (!fs.existsSync(path.join(cwd, 'ios')) || !fs.existsSync(path.join(cwd, 'android'))) {
66
+ throw new InitError('No ios/ and android/ folders found. Only bare React Native projects are supported for now (Expo support comes later).');
67
+ }
68
+ return { pkg, deps };
69
+ }
70
+
71
+ // all template files, relative paths, including dotfiles
72
+ function templateFiles(dir = TEMPLATE, base = '') {
73
+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => {
74
+ const rel = path.join(base, e.name);
75
+ return e.isDirectory() ? templateFiles(path.join(dir, e.name), rel) : [rel];
76
+ });
77
+ }
78
+
79
+ function fillPlaceholders(text, values) {
80
+ return text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in values ? values[k] : m));
81
+ }
82
+
83
+ function init(cwd, opts = {}) {
84
+ const { pkg, deps } = checkProject(cwd);
85
+ const pm = detectPm(cwd, opts.pm);
86
+ const tools = opts.tools || TESTED;
87
+ for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
88
+
89
+ const values = {
90
+ APP_NAME: pkg.name || path.basename(cwd),
91
+ RN_VERSION: installedVersion(cwd, 'react-native', deps['react-native']),
92
+ REACT_VERSION: installedVersion(cwd, 'react', deps.react),
93
+ TS_VERSION: installedVersion(cwd, 'typescript', deps.typescript),
94
+ NODE_VERSION: (pkg.engines && pkg.engines.node) || `${process.versions.node.split('.')[0]}`,
95
+ PM: pm.name,
96
+ PM_RUN: pm.run,
97
+ };
98
+ const report = { created: [], merged: [], skipped: [] };
99
+
100
+ // 1. template files (never overwrite)
101
+ for (const rel of templateFiles()) {
102
+ const src = path.join(TEMPLATE, rel);
103
+ const dest = path.join(cwd, rel);
104
+ const kitText = () => fillPlaceholders(fs.readFileSync(src, 'utf8'), values);
105
+
106
+ if (rel === 'AGENTS.md' && fs.existsSync(dest)) {
107
+ const current = fs.readFileSync(dest, 'utf8');
108
+ const section = kitText();
109
+ const next = MARKERS.test(current) ? current.replace(MARKERS, section) : `${current.replace(/\n*$/, '\n\n')}${section}`;
110
+ if (next !== current) { fs.writeFileSync(dest, next); report.merged.push(rel); } else report.skipped.push(rel);
111
+ continue;
112
+ }
113
+ if (rel === 'CLAUDE.md' && fs.existsSync(dest)) {
114
+ const current = fs.readFileSync(dest, 'utf8');
115
+ if (/^@AGENTS\.md\s*$/m.test(current)) report.skipped.push(rel);
116
+ else { fs.writeFileSync(dest, `${current.replace(/\n*$/, '\n\n')}@AGENTS.md\n`); report.merged.push(rel); }
117
+ continue;
118
+ }
119
+ if (fs.existsSync(dest)) { report.skipped.push(rel); continue; }
120
+
121
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
122
+ if (rel === 'AGENTS.md') fs.writeFileSync(dest, kitText());
123
+ else fs.copyFileSync(src, dest);
124
+ // npm doesn't always keep the executable bit, and git silently skips non-executable hooks
125
+ const executable = rel.startsWith(`.githooks${path.sep}`) || /\.(sh|js)$/.test(rel) && rel.startsWith(`scripts${path.sep}`);
126
+ fs.chmodSync(dest, executable ? 0o755 : 0o644);
127
+ report.created.push(rel);
128
+ }
129
+
130
+ // 2. skills folder links for tools that don't read .agents/skills
131
+ const links = [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']];
132
+ for (const [link, tool] of links) {
133
+ if (!tools.includes(tool)) continue;
134
+ const dest = path.join(cwd, link);
135
+ if (fs.existsSync(dest) || isLink(dest)) { report.skipped.push(link); continue; }
136
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
137
+ fs.symlinkSync('../.agents/skills', dest);
138
+ report.created.push(`${link} -> .agents/skills`);
139
+ }
140
+
141
+ // 3. .gitignore: keep secrets out of git
142
+ const gi = path.join(cwd, '.gitignore');
143
+ const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
144
+ const missing = ['.env', '.env.*', '!.env.example', '.ai/'].filter(l => !giText.split('\n').includes(l));
145
+ if (missing.length) {
146
+ 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`);
147
+ report.merged.push('.gitignore');
148
+ }
149
+
150
+ // 4. package.json scripts: typecheck, and hooks path on install (never overwrite existing scripts)
151
+ const pkgFile = path.join(cwd, 'package.json');
152
+ const scripts = (pkg.scripts = pkg.scripts || {});
153
+ let pkgChanged = false;
154
+ if (!scripts.typecheck && deps.typescript) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
155
+ const hooksCmd = 'git config core.hooksPath .githooks || true';
156
+ if (!(scripts.postinstall || '').includes('core.hooksPath')) {
157
+ scripts.postinstall = scripts.postinstall ? `${scripts.postinstall} && ${hooksCmd}` : hooksCmd;
158
+ pkgChanged = true;
159
+ }
160
+ if (pkgChanged) { fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`); report.merged.push('package.json (scripts)'); }
161
+
162
+ // 5. activate the git hooks now
163
+ git(cwd, 'config', 'core.hooksPath', '.githooks');
164
+
165
+ // 6. tool configs for the chosen tools (permissions, hooks, subagents)
166
+ const rsFile = path.join(cwd, 'rulesync.jsonc');
167
+ const rs = fs.readFileSync(rsFile, 'utf8');
168
+ const targets = tools.flatMap(t => TOOLS[t]);
169
+ fs.writeFileSync(rsFile, rs.replace(/"targets":\s*\[[^\]]*\]/, `"targets": ${JSON.stringify(targets)}`));
170
+ let generated = true;
171
+ let generateError = '';
172
+ if (!opts.skipGenerate) {
173
+ // when init itself runs under npx, npm_config_* variables (e.g. the outer --package) would leak into this npx
174
+ const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_(config|package|lifecycle)_/i.test(k)));
175
+ const r = spawnSync('npx', ['-y', RULESYNC, 'generate'], { cwd, env, encoding: 'utf8' });
176
+ generated = r.status === 0;
177
+ if (!generated) generateError = `${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').slice(-5).join('\n');
178
+ }
179
+
180
+ return { report, values, tools, generated, generateError };
181
+ }
182
+
183
+ function isLink(p) { try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; } }
184
+
185
+ function printSummary({ report, values, tools, generated, generateError }, log = console.log) {
186
+ log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
187
+ log(`Tools: ${tools.join(', ')}${tools.some(t => !TESTED.includes(t)) ? ' (cursor, opencode and kiro are not tested yet)' : ''}`);
188
+ log(` created: ${report.created.length} files`);
189
+ if (report.merged.length) log(` merged: ${report.merged.join(', ')}`);
190
+ if (report.skipped.length) log(` kept as they were (already existed): ${report.skipped.join(', ')}`);
191
+ if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
192
+ log('\nNext steps:');
193
+ log(' 1. Fill in docs/ai/product.md, tech.md, structure.md and conventions.md for this app.');
194
+ log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
195
+ log(' 3. Turn on branch protection for main: see docs/branch-protection.md in the kit repo.');
196
+ if (tools.includes('codex')) log(' 4. Codex users: open the project in Codex once and approve its hooks (they stay off until approved).');
197
+ }
198
+
199
+ module.exports = { init, printSummary, InitError, TOOLS };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.0.2",
3
+ "version": "0.2.0",
4
4
  "description": "One setup for AI-assisted mobile development that works the same in Claude Code, Codex, Cursor, OpenCode, Kiro and Antigravity. Early development.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -16,7 +16,9 @@
16
16
  "agentic-mobile-kit": "bin/cli.js"
17
17
  },
18
18
  "files": [
19
- "bin"
19
+ "bin",
20
+ "lib",
21
+ "stacks"
20
22
  ],
21
23
  "engines": {
22
24
  "node": ">=20"
@@ -34,5 +36,9 @@
34
36
  "opencode",
35
37
  "kiro",
36
38
  "antigravity"
37
- ]
39
+ ],
40
+ "scripts": {
41
+ "release": "sh scripts/release.sh",
42
+ "test": "node --test tests/*.test.js && sh tests/guard.test.sh"
43
+ }
38
44
  }
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Callstack Incubator
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,9 @@
1
+ # Third-party skills
2
+
3
+ | Skill | Source | Commit | License | Changes |
4
+ |---|---|---|---|---|
5
+ | react-native-best-practices | https://github.com/callstackincubator/agent-skills | 61e6e7dfdf3a8ee862254c200d751fcb1fb863dc | MIT (`LICENSE-callstack`) | Image files left out |
6
+ | react-navigation | same | same | MIT | Image files left out |
7
+ | upgrading-react-native | same | same | MIT | Image files left out |
8
+
9
+ Updated with `scripts/vendor-skills.sh` in the agentic-mobile-kit repo.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: m-bugfix
3
+ description: Fix a bug by finding its root cause, proving it with a failing test, and fixing it minimally. Run only when the user explicitly invokes m-bugfix.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-bugfix
8
+
9
+ Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, task link).
10
+
11
+ 1. **Check `docs/ai/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
12
+ 2. **Reproduce.** Write down the exact steps and the actual vs expected result. If you can't reproduce it, say so and ask for more details. Don't guess.
13
+ 3. **Write a failing test** that shows the bug, if it can be tested with Jest. Run it and show that it fails. (Native or device-only bugs: write the manual steps instead.)
14
+ 4. **Find the root cause before changing code.**
15
+ - Read the full error and stack trace.
16
+ - Trace the data back to where it goes wrong.
17
+ - Form one hypothesis, test it, and confirm or reject it. One at a time.
18
+ - Fix the cause, not the symptom: no try/catch that hides the error, no special case for the failing input.
19
+ 5. **Make the smallest fix.** Don't refactor or touch unrelated code.
20
+ 6. **Verify.** The new test passes, and lint, typecheck and all tests pass. Paste the output. For UI or native bugs, run `sh scripts/ai/verify.sh ios` and/or `android` and look at the screenshots.
21
+ 7. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
22
+ 8. **Record it.** If this kind of error could come back, add an entry to `docs/ai/known-issues.md` (error, cause, fix, prevention).
23
+ 9. **Commit** with a message ending in `Assisted-by: <tool>/<model>`. Ask the user before pushing, then open a PR with the evidence.
@@ -0,0 +1,3 @@
1
+ # Codex: run this skill only when invoked explicitly ($m-bugfix), never automatically.
2
+ policy:
3
+ allow_implicit_invocation: false
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: m-continue
3
+ description: Resume work that was started earlier, possibly in another AI tool or on another computer, from the files in specs/. Run only when the user explicitly invokes m-continue.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-continue
8
+
9
+ Input: $ARGUMENTS (a spec ID, or empty).
10
+
11
+ 1. **Check git first.** Run `git fetch` and `git status`.
12
+ - If the branch is behind its remote, say so and ask before pulling.
13
+ - If there are uncommitted changes, list them; they may be half-done work.
14
+ 2. **Find the spec.** Use the given ID; otherwise the `specs/*/progress.md` (not `_templates`) updated most recently. If unsure, ask.
15
+ 3. **Read** `requirements.md`, `design.md`, `tasks.md` and `progress.md` in that spec folder, plus `git log --oneline -15`.
16
+ 4. **Report back, in this order:**
17
+ 1. any open question or blocker from the handoff;
18
+ 2. the status (task N of M) and what's done;
19
+ 3. the exact next step.
20
+
21
+ Use only what the files and git say. If something isn't recorded, say it's unknown. Never fill gaps with guesses.
22
+ 5. **Wait for the user to confirm**, then continue with the next unchecked task, following step 4 of `m-feature` (one task at a time, real check output, commit, update `progress.md`).
@@ -0,0 +1,3 @@
1
+ # Codex: run this skill only when invoked explicitly ($m-continue), never automatically.
2
+ policy:
3
+ allow_implicit_invocation: false
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: m-feature
3
+ description: Build a feature from a requirement (pasted text, a file, or a task link), from spec to pull request. Run only when the user explicitly invokes m-feature.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-feature
8
+
9
+ Input: $ARGUMENTS (the requirement text, a file path, or a task link plus pasted details).
10
+
11
+ ## 1. Always use the full flow
12
+
13
+ The user chose `m-feature`, so follow every step below, however small the change looks. Never skip the spec or the approval stops on your own judgment. (Tiny changes don't need this skill; the user can just ask for them directly.)
14
+
15
+ If the input describes a bug rather than new behavior, suggest `m-bugfix` and stop.
16
+
17
+ ## 2. Requirements (then stop for approval)
18
+
19
+ 1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `specs/_templates/` to `specs/<id>/`.
20
+ 2. Fill `requirements.md`: goal, acceptance criteria as "WHEN … THE APP SHALL …", every edge-case line (or "n/a"), out of scope, open questions.
21
+ 3. If something is unclear, ask the user **one question at a time**. Don't fill gaps with guesses.
22
+ 4. Show the requirements and **stop until the user approves them**.
23
+
24
+ ## 3. Design and tasks (then stop for approval)
25
+
26
+ 1. **Search the codebase before designing.** List the components, hooks, API clients and helpers you'll reuse in `design.md` under "Existing code to reuse". Read `docs/ai/structure.md` and `docs/ai/conventions.md`.
27
+ 2. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
28
+ 3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each), each with its own check. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`), a Maestro flow that walks through the acceptance criteria, taps elements by `testID` and takes a screenshot per criterion.
29
+ 4. Show design and tasks and **stop until the user approves them**.
30
+
31
+ ## 4. Build, one task at a time
32
+
33
+ For each task:
34
+ 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after.
35
+ 2. Run `lint`, `typecheck` and `test` (see AGENTS.md). Paste the real output. If something fails, fix it; after 2 failed attempts, stop and report.
36
+ 3. Commit with a clear message ending in `Assisted-by: <tool>/<model>` and `Spec: specs/<id>`.
37
+ 4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
38
+
39
+ ## 5. Check against the spec
40
+
41
+ When all tasks are done:
42
+ 1. Run `sh scripts/ai/verify.sh all --spec <id>`. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its criterion. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
43
+ 2. Go through every acceptance criterion and note the evidence for it (test name, command output, or screen checked). If one isn't met, fix the code or ask whether the spec should change.
44
+
45
+ ## 6. Review and pull request
46
+
47
+ 1. Run `m-review` (or ask the `m-reviewer` subagent, if your tool has subagents). Fix real problems only; skip style nits.
48
+ 2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR using `.github/pull_request_template.md`, with the evidence filled in.
49
+
50
+ Never claim a check passed without running it in this session.
@@ -0,0 +1,3 @@
1
+ # Codex: run this skill only when invoked explicitly ($m-feature), never automatically.
2
+ policy:
3
+ allow_implicit_invocation: false
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: m-pause
3
+ description: Save the current state so the work can continue later in any AI tool or on another computer. Run only when the user explicitly invokes m-pause.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-pause
8
+
9
+ 1. **Update the handoff block** at the top of `specs/<id>/progress.md`: date and time, tool and model, branch, status (start the line with `not started`, `in progress — task N of M` or `done`, exactly), done, in progress (with file paths and what's half-done), the exact next step, decisions, open question, last check results, blockers, notes. Add a line to the log.
10
+ 2. **Move decisions out of the chat.** Anything decided in this conversation goes into `requirements.md`, `design.md` or `docs/ai/decisions.md` now. Chat history doesn't travel to other tools.
11
+ 3. **Commit the work in progress** on the feature branch (never `main`): message `wip: <id> <short summary>`, ending with `Assisted-by: <tool>/<model>` and `Spec: specs/<id>`.
12
+ - Never use `--no-verify`. If a git hook blocks the commit, fix the problem if it's quick. Otherwise say so, record it in the handoff under "Blocked", and stop.
13
+ 4. **Push the branch**: `git push -u origin <branch>`.
14
+ 5. **Tell the user** the branch name, and that they can continue anywhere with `git pull`, then `m-continue <id>`.
@@ -0,0 +1,3 @@
1
+ # Codex: run this skill only when invoked explicitly ($m-pause), never automatically.
2
+ policy:
3
+ allow_implicit_invocation: false
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: m-review
3
+ description: Review the current branch's changes for real problems before a pull request, and handle review feedback. Run only when the user explicitly invokes m-review.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-review
8
+
9
+ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it looks at the code with fresh eyes. Otherwise review it yourself, read-only.
10
+
11
+ ## Reviewing
12
+
13
+ 1. Get the changes: `git diff main...HEAD` and `git log main..HEAD --oneline`. If there's a spec, read its `requirements.md`.
14
+ 2. Check, in order:
15
+ - **Scope:** does the diff do what the spec asks, and nothing unrelated?
16
+ - **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
17
+ - **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
18
+ - **Errors and states:** offline, server errors, empty and loading states.
19
+ - **Security:** secrets, tokens, `.env` contents, logging of personal data.
20
+ - **Native:** `project.pbxproj`, `Podfile`, Gradle or manifest changes, and whether pods and builds were re-run.
21
+ - **Performance:** heavy work in render, list keys, needless re-renders.
22
+ 3. For each finding, check it in the code before reporting it. Report: severity (**blocker**, **should fix**), file and line, the problem, and a suggested fix. Leave out style nits; lint handles those.
23
+ 4. End with: "Ready for PR" or "Not ready: N blockers".
24
+
25
+ ## Receiving review feedback (from people or AI reviewers)
26
+
27
+ - Check each comment against the code before acting on it. Reviewers are sometimes wrong.
28
+ - Fix what's right; reply with the reason when you disagree.
29
+ - Don't add defensive code or abstractions only to satisfy a reviewer.
@@ -0,0 +1,3 @@
1
+ # Codex: run this skill only when invoked explicitly ($m-review), never automatically.
2
+ policy:
3
+ allow_implicit_invocation: false