agentic-mobile-kit 0.5.1 → 0.5.3

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.
package/README.md CHANGED
@@ -1,51 +1,87 @@
1
1
  # agentic-mobile-kit
2
2
 
3
- One setup for AI-assisted mobile development that works the same in Claude Code, Codex and Antigravity (Cursor, OpenCode and Kiro next).
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.
4
4
 
5
- > **Status: early development.** Bare React Native projects only for now; Expo comes next.
5
+ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, OpenCode and Kiro.
6
6
 
7
- ## Install into a bare React Native app
7
+ ## Install
8
8
 
9
- Run in the app's root, on a clean git working tree:
9
+ 1. In your app's root folder, on a clean git branch, run:
10
10
 
11
- ```sh
12
- npx agentic-mobile-kit init
13
- npx agentic-mobile-kit init --tools claude,codex,antigravity # choose your AI tools
14
- npx agentic-mobile-kit init --ci github,codemagic # only if the app uses that CI
15
- ```
11
+ ```sh
12
+ npx agentic-mobile-kit init
13
+ ```
16
14
 
17
- Then check the project and your machine, with a fix for each problem:
15
+ If the app uses CI, add `--ci github`, `--ci codemagic` or both. To pick AI tools, add `--tools claude,codex,antigravity`, which is the default. `--help` lists every option.
18
16
 
19
- ```sh
20
- npx agentic-mobile-kit doctor
21
- ```
17
+ 2. Check the project and your machine. `doctor` lists each problem with its fix:
18
+
19
+ ```sh
20
+ npx agentic-mobile-kit doctor
21
+ ```
22
+
23
+ 3. Fill in `docs/ai/product.md`, `tech.md`, `structure.md` and `conventions.md`, then commit and open a PR.
24
+
25
+ `init` never overwrites your files, is safe to run again, and can be undone with git. The [team guide](docs/team-guide.md#setup) lists everything it changes.
26
+
27
+ ## How work flows
22
28
 
23
- `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.
29
+ | You want to | Run | What happens |
30
+ |---|---|---|
31
+ | Think a problem through | `m-explore` | The agent reads the code, explains how it works today and lays out options with trade-offs. It never edits code. |
32
+ | Build a feature | `m-feature` | Requirements → you approve → design and tasks → you approve → one task at a time with tests → device checks with screenshots → living spec updated → review → PR |
33
+ | Fix a bug | `m-bugfix` | Reproduces the bug, proves it with a failing test, finds the root cause, then makes the smallest fix |
34
+ | Stop, or switch tool or machine | `m-pause` | Writes a handoff in the spec, commits and pushes |
35
+ | Carry on anywhere | `m-continue` | Reads the spec and handoff, then picks up at the next step |
36
+ | Review a branch | `m-review` | Checks the work against the spec (complete, correct, coherent) and covers both platforms, error states, security and native changes |
37
+ | Ship a release | `m-release` | Changelog from real commits, store and client notes, versions, release check, release PR, tag, signed builds |
38
+ | Stop a mistake repeating | `m-learn` | Turns a correction into a lasting check, a known-issues entry or a rule |
24
39
 
25
- ## Update or remove it
40
+ Invoke a skill with `/m-feature` in Claude Code and Antigravity, or `$m-feature` in Codex. The skills are set to run only when you invoke them.
41
+
42
+ ## What it adds to the app
43
+
44
+ | Area | What you get |
45
+ |---|---|
46
+ | Project knowledge | `AGENTS.md` (with a one-line `CLAUDE.md`): commands, the definition of done and the rules. `docs/ai/`: product, tech stack, structure, conventions, decisions, known issues, React Native rules and team process. Callstack's React Native skills. |
47
+ | Specs | `specs/<id>/` for each feature: requirements, design, tasks, a Maestro flow and a handoff file. A living spec of what the app does now, in `specs/current/`. `spec.js`: `check`, `merge`, `status`. |
48
+ | Device checks | `verify.sh`: lint and tests, release builds on an iPhone simulator and an Android emulator, the feature's Maestro flow, and screenshots in `.ai/evidence/<id>/` |
49
+ | Releases | `release-check.js` catches what store review would reject. Changelog and store notes come from commits (git-cliff). `set-version.sh` sets versions. Signed builds come from `release-build.sh` or Codemagic (`--ci codemagic`). |
50
+ | Guardrails in AI tools | Hooks that block destructive commands and secret files and remind the agent about the handoff, permission rules, and a read-only reviewer, generated with rulesync |
51
+ | Git hooks | Before a commit: secrets, signing files, Xcode project files, ESLint, spec format. Before a push: typecheck and tests. |
52
+ | CI (`--ci github`) | Lint, typecheck, tests, a secret scan, a tool-config check, a 600-line PR limit (`large-pr` label), Android and iOS builds, nightly end-to-end tests (`e2e` label), and a PR template |
53
+ | Everyday scripts | `install-deps.sh`, `pm-run.sh`, `ios-build.sh` |
54
+
55
+ All scripts are in `scripts/ai/`. The [team guide](docs/team-guide.md) has the details.
56
+
57
+ ## Alongside other AI workflows
58
+
59
+ 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.
60
+
61
+ ## Update or remove
26
62
 
27
63
  ```sh
28
- npx agentic-mobile-kit@latest sync # update the kit's files; your own changes to them are merged in
64
+ npx agentic-mobile-kit@latest sync # update the kit's files, merging in your own changes
29
65
  npx agentic-mobile-kit uninstall # remove the kit; files you changed are kept and listed
30
66
  ```
31
67
 
32
- Both need a clean working tree, and both leave the result for you to review with `git diff`.
33
-
34
- `sync` reports what it updated, added, removed and merged. If you and the kit changed the same lines, the file gets `<<<<<<<` conflict markers to resolve. The docs your team filled in (`docs/ai/product.md`, `tech.md`, `structure.md`, `conventions.md`) are never changed.
35
-
36
- Installs older than 0.4.0 don't record which kit version made them, so their first `sync` or `uninstall` needs `--from <version>`, for example `--from 0.3.0`. That version can only be a guess, so `sync` doesn't merge on top of it: every file that matches neither version gets conflict markers instead.
68
+ Both need a clean working tree and leave the result for you to review with `git diff`.
69
+ - **Report:** `sync` lists what it updated, added, removed and merged.
70
+ - **Your docs:** the product, tech, structure and conventions files your team filled in are never changed.
71
+ - **Adding CI later:** `sync --ci github` or `--ci codemagic` does it.
37
72
 
38
- ## What it adds
73
+ ## Requirements
39
74
 
40
- - **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), spec templates in `specs/_templates/`, and a living spec in `specs/current/` that says what the app does now, one area at a time. Each feature lists the requirements it adds, changes and removes, and `scripts/ai/spec.js` folds them into the living spec and checks the format.
41
- - **Workflows:** the skills `m-explore`, `m-feature`, `m-bugfix`, `m-continue`, `m-pause`, `m-review`, `m-release` and `m-learn`. Invoke them with `/m-feature` in Claude Code and Antigravity, or `$m-feature` in Codex. Also Callstack's React Native skills.
42
- - **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.
43
- - **Releases:** `m-release` writes each release's changelog from real commits with git-cliff, plus store and client notes, all in `release-notes/<version>/`. It then runs `scripts/ai/release-check.js`, which catches what store review would reject. Signed builds come from `scripts/ai/release-build.sh` on a Mac: an app bundle signed with your upload key, and an `.ipa` signed through Xcode's account. With `--ci codemagic`, a version tag starts them on Codemagic instead (`codemagic.yaml`, one-time setup in `docs/ai/codemagic.md`).
44
- - **Checks no tool can skip:** git hooks (secrets, signing files, broken Xcode project files, lint, typecheck, tests) and, with `--ci github`, GitHub Actions CI (lint, typecheck, tests, secret scan, PR size, Android and iOS builds, nightly Android end-to-end tests).
75
+ - Git and Node.js 20 or later, on macOS, Windows or Linux. The kit's tests run on all three for every change.
76
+ - Android work needs the Android SDK and Java. iOS work needs a Mac with Xcode and CocoaPods. `doctor` checks the rest.
77
+ - On Windows, turn on Developer Mode (Settings > System > For developers) and run `git config --global core.symlinks true`. Then `init` can link the Claude Code skills folder, and clones keep the link.
45
78
 
46
- Work continues across tools and machines through `specs/<id>/progress.md`: run `m-pause` in one tool, then `m-continue` in another.
79
+ ## More
47
80
 
48
- For the day-to-day workflow, what's enforced, and a 1-hour training plan, see the [team guide](docs/team-guide.md).
81
+ - [Team guide](docs/team-guide.md): day-to-day use, what's enforced, troubleshooting and a 1-hour training plan.
82
+ - [Branch protection](docs/branch-protection.md): the GitHub settings that make the CI checks required.
83
+ - [Tool matrix](docs/tool-matrix.md): how the kit was tested in each AI tool and on a real app.
84
+ - Published from GitHub Actions with npm provenance.
49
85
 
50
86
  ## License
51
87
 
package/lib/doctor.js CHANGED
@@ -3,14 +3,20 @@
3
3
  const fs = require('fs');
4
4
  const os = require('os');
5
5
  const path = require('path');
6
- const { execFileSync, spawnSync } = require('child_process');
6
+ const { spawnSync } = require('child_process');
7
+ const { tool } = require('./init');
7
8
 
8
9
  const RULESYNC = 'rulesync@27.0.0';
9
10
 
10
11
  // run a command; return trimmed stdout, or null if it isn't installed or fails
11
12
  function run(cmd, args, opts = {}) {
12
- try { return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 60000, ...opts }).trim(); } catch { return null; }
13
+ const r = tool(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 60000, ...opts });
14
+ return r.status === 0 ? (r.stdout || '').trim() : null;
13
15
  }
16
+ const WIN = process.platform === 'win32';
17
+ // where Android Studio puts the SDK by default on each OS
18
+ const defaultSdk = () => (WIN ? path.join(process.env.LOCALAPPDATA || os.homedir(), 'Android', 'Sdk')
19
+ : process.platform === 'darwin' ? path.join(os.homedir(), 'Library/Android/sdk') : path.join(os.homedir(), 'Android/Sdk'));
14
20
  const version = s => (String(s || '').match(/(\d+)\.(\d+)(?:\.(\d+))?/) || []).slice(1).map(n => Number(n || 0));
15
21
  const atLeast = (v, min) => { for (let i = 0; i < 3; i++) { if ((v[i] || 0) !== min[i]) return (v[i] || 0) > min[i]; } return true; };
16
22
  const read = (cwd, f) => { try { return fs.readFileSync(path.join(cwd, f), 'utf8'); } catch { return null; } };
@@ -46,12 +52,14 @@ function projectChecks(cwd, opts) {
46
52
  if (fs.existsSync(path.join(cwd, '.claude/settings.json'))) {
47
53
  out.push(fs.existsSync(path.join(claudeLink, 'm-feature/SKILL.md'))
48
54
  ? ok('Claude Code skills link')
49
- : fail('.claude/skills link missing or broken', 'run: ln -sfn ../.agents/skills .claude/skills (on Windows, enable git symlinks)'));
55
+ : fail('.claude/skills link missing or broken', WIN
56
+ ? 'turn on Developer Mode (Settings > System > For developers), run "git config core.symlinks true", then "npx agentic-mobile-kit init" again'
57
+ : 'run: ln -sfn ../.agents/skills .claude/skills'));
50
58
  }
51
59
 
52
60
  if (!opts.skipNetwork && fs.existsSync(path.join(cwd, 'rulesync.jsonc'))) {
53
61
  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_(config|package|lifecycle)_/i.test(k)));
54
- const r = spawnSync('npx', ['-y', RULESYNC, 'generate', '--check'], { cwd, env, encoding: 'utf8', timeout: 120000 });
62
+ const r = tool('npx', ['-y', RULESYNC, 'generate', '--check'], { cwd, env, encoding: 'utf8', timeout: 120000 });
55
63
  out.push(r.status === 0
56
64
  ? ok('Tool configs match .rulesync/')
57
65
  : warn('Tool configs out of date with .rulesync/', `run: npx -y ${RULESYNC} generate, then commit`));
@@ -89,8 +97,8 @@ function machineChecks(cwd) {
89
97
  }
90
98
 
91
99
  // Android
92
- const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || path.join(os.homedir(), 'Library/Android/sdk');
93
- const adb = path.join(sdk, 'platform-tools/adb');
100
+ const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || defaultSdk();
101
+ const adb = path.join(sdk, 'platform-tools', WIN ? 'adb.exe' : 'adb');
94
102
  out.push(fs.existsSync(adb) ? ok('Android SDK', sdk) : fail('Android SDK not found', 'install Android Studio, or set ANDROID_HOME'));
95
103
  const avds = run(path.join(sdk, 'emulator/emulator'), ['-list-avds']);
96
104
  out.push(avds ? ok('Android emulator', avds.split('\n')[0]) : warn('No Android emulator', 'create one in Android Studio > Device Manager'));
package/lib/init.js CHANGED
@@ -18,8 +18,8 @@ const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `d
18
18
  const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
19
19
  // optional parts, installed only when a project chooses them with --ci: not every app uses CI
20
20
  const CI = {
21
- github: rel => rel.startsWith(`.github${path.sep}`),
22
- codemagic: rel => rel === 'codemagic.yaml' || rel === path.join('docs', 'ai', 'codemagic.md'),
21
+ github: rel => rel.startsWith('.github/'),
22
+ codemagic: rel => rel === 'codemagic.yaml' || rel === 'docs/ai/codemagic.md',
23
23
  };
24
24
  const ciGroup = rel => Object.keys(CI).find(g => CI[g](rel));
25
25
 
@@ -41,8 +41,18 @@ function git(cwd, ...args) {
41
41
  }
42
42
 
43
43
  function readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }
44
- const readIf = file => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
44
+ // Windows line endings (git's autocrlf) read as plain newlines, so a Windows clone compares equal to the kit's files
45
+ const readIf = file => { try { return fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; } };
46
+ const WIN = process.platform === 'win32';
47
+ // npm, npx and yarn are .cmd files on Windows, which Node can only start through a shell.
48
+ // Only arguments with spaces get quotes: a quoted .cmd name found on PATH can't locate its own folder (%~dp0).
49
+ const quote = a => (/[\s"]/.test(a) ? `"${a}"` : a);
50
+ const tool = (cmd, args, opts = {}) => (WIN
51
+ ? spawnSync([cmd, ...args].map(quote).join(' '), { ...opts, shell: true })
52
+ : spawnSync(cmd, args, opts));
45
53
  function isLink(p) { try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; } }
54
+ // a link's target with "/" (Windows reports it with backslashes)
55
+ const linkTarget = p => fs.readlinkSync(p).replace(/\\/g, '/');
46
56
 
47
57
  // when the kit runs under npx, npm_config_* variables (e.g. the outer --package) would leak into the npx/npm it starts
48
58
  const cleanEnv = () => Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_(config|package|lifecycle)_/i.test(k)));
@@ -87,10 +97,10 @@ function checkProject(cwd) {
87
97
  return { pkg, deps };
88
98
  }
89
99
 
90
- // all files under dir, as relative paths, including dotfiles
100
+ // all files under dir, as relative paths with "/" on every OS (as git shows them), including dotfiles
91
101
  function templateFiles(dir = TEMPLATE, base = '') {
92
102
  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => {
93
- const rel = path.join(base, e.name);
103
+ const rel = base ? `${base}/${e.name}` : e.name;
94
104
  return e.isDirectory() ? templateFiles(path.join(dir, e.name), rel) : [rel];
95
105
  });
96
106
  }
@@ -147,7 +157,7 @@ function writeKitFile(cwd, rel, text) {
147
157
  fs.mkdirSync(path.dirname(dest), { recursive: true });
148
158
  fs.writeFileSync(dest, text);
149
159
  // npm doesn't always keep the executable bit, and git silently skips non-executable hooks
150
- const executable = rel.startsWith(`.githooks${path.sep}`) || /\.(sh|js)$/.test(rel) && rel.startsWith(`scripts${path.sep}`);
160
+ const executable = rel.startsWith('.githooks/') || /\.(sh|js)$/.test(rel) && rel.startsWith('scripts/');
151
161
  fs.chmodSync(dest, executable ? 0o755 : 0o644);
152
162
  }
153
163
 
@@ -196,7 +206,7 @@ function oldTemplate(agents, opts) {
196
206
  function fetchTemplate(version) {
197
207
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-kit-'));
198
208
  process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true }));
199
- const r = spawnSync('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--silent'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
209
+ const r = tool('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--silent'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
200
210
  if (r.status !== 0) throw new InitError(`Couldn't download agentic-mobile-kit@${version} from npm: ${(r.stderr || '').trim().split('\n').pop()}`);
201
211
  execFileSync('tar', ['-xzf', path.join(dir, r.stdout.trim().split('\n').pop()), '-C', dir]);
202
212
  return path.join(dir, 'package', 'stacks', 'react-native', 'template');
@@ -217,27 +227,34 @@ const kitSkills = template => fs.readdirSync(path.join(template, '.agents', 'ski
217
227
 
218
228
  // steps 2–6, shared by init and sync
219
229
  function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
220
- const done = { created: [], merged: [], skipped: [] };
230
+ const done = { created: [], merged: [], skipped: [], warnings: [] };
231
+ // Windows creates symbolic links only with Developer Mode on (or as admin)
232
+ const link = (target, p, label) => {
233
+ try { fs.symlinkSync(target, p); return true; } catch (e) {
234
+ if (!['EPERM', 'EACCES'].includes(e.code)) throw e;
235
+ done.warnings.push(`couldn't create the ${label} link (${e.code}). On Windows, turn on Developer Mode (Settings > System > For developers), run "git config core.symlinks true", then run this again. Codex and Antigravity read .agents/skills directly and don't need it.`);
236
+ return false;
237
+ }
238
+ };
221
239
 
222
240
  // 2. skills links for tools that don't read .agents/skills
223
- for (const [link, tool] of SKILL_LINKS) {
224
- if (!tools.includes(tool)) continue;
225
- const dest = path.join(cwd, link);
241
+ for (const [linkPath, forTool] of SKILL_LINKS) {
242
+ if (!tools.includes(forTool)) continue;
243
+ const dest = path.join(cwd, linkPath);
226
244
  if (!fs.existsSync(dest) && !isLink(dest)) {
227
245
  fs.mkdirSync(path.dirname(dest), { recursive: true });
228
- fs.symlinkSync('../.agents/skills', dest);
229
- done.created.push(`${link} -> .agents/skills`);
246
+ if (link('../.agents/skills', dest, linkPath)) done.created.push(`${linkPath} -> .agents/skills`);
230
247
  continue;
231
248
  }
232
- if (isLink(dest) || !fs.statSync(dest).isDirectory()) { done.skipped.push(link); continue; }
249
+ if (isLink(dest) || !fs.statSync(dest).isDirectory()) { done.skipped.push(linkPath); continue; }
233
250
  // the folder already holds another framework's skills: link each kit skill into it
234
251
  for (const name of kitSkills(template)) {
235
252
  const p = path.join(dest, name);
236
253
  const target = `../../.agents/skills/${name}`;
237
- if (isLink(p) && fs.readlinkSync(p) === target) continue;
238
- if (fs.existsSync(p) || isLink(p)) { done.skipped.push(`${link}/${name} (another skill has this name)`); continue; }
239
- fs.symlinkSync(target, p);
240
- done.created.push(`${link}/${name} -> .agents/skills/${name}`);
254
+ if (isLink(p) && linkTarget(p) === target) continue;
255
+ if (fs.existsSync(p) || isLink(p)) { done.skipped.push(`${linkPath}/${name} (another skill has this name)`); continue; }
256
+ if (!link(target, p, `${linkPath}/${name}`)) break;
257
+ done.created.push(`${linkPath}/${name} -> .agents/skills/${name}`);
241
258
  }
242
259
  }
243
260
 
@@ -250,6 +267,15 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
250
267
  done.merged.push('.gitignore');
251
268
  }
252
269
 
270
+ // 3b. .gitattributes: shell scripts keep Unix line endings, or they fail on Windows checkouts (autocrlf)
271
+ const ga = path.join(cwd, '.gitattributes');
272
+ const gaText = readIf(ga) || '';
273
+ const gaMissing = ['.githooks/* text eol=lf', '*.sh text eol=lf'].filter(l => !gaText.split('\n').includes(l));
274
+ if (gaMissing.length) {
275
+ fs.writeFileSync(ga, `${gaText.replace(/\n*$/, gaText ? '\n' : '')}${gaText ? '\n' : ''}# agentic-mobile-kit: shell scripts keep LF line endings, so they run on Windows too\n${gaMissing.join('\n')}\n`);
276
+ done.merged.push('.gitattributes');
277
+ }
278
+
253
279
  // 4. package.json scripts: typecheck, and hooks path on install (never overwrite existing scripts)
254
280
  const scripts = (pkg.scripts = pkg.scripts || {});
255
281
  let pkgChanged = false;
@@ -265,6 +291,10 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
265
291
 
266
292
  // 5. activate the git hooks now
267
293
  git(cwd, 'config', 'core.hooksPath', '.githooks');
294
+ // Windows files have no executable bit, and git skips non-executable hooks on Mac and Linux clones:
295
+ // stage the hooks as executable so the commit carries it
296
+ const hooks = ['.githooks/pre-commit', '.githooks/pre-push'].filter(h => fs.existsSync(path.join(cwd, h)));
297
+ if (WIN && hooks.length) git(cwd, 'add', '--chmod=+x', '--', ...hooks);
268
298
 
269
299
  // 6. tool configs for the chosen tools (permissions, hooks, subagents)
270
300
  const rsFile = path.join(cwd, 'rulesync.jsonc');
@@ -272,9 +302,9 @@ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
272
302
  let generated = true;
273
303
  let generateError = '';
274
304
  if (!skipGenerate) {
275
- const r = spawnSync('npx', ['-y', RULESYNC, 'generate'], { cwd, env: cleanEnv(), encoding: 'utf8' });
305
+ const r = tool('npx', ['-y', RULESYNC, 'generate'], { cwd, env: cleanEnv(), encoding: 'utf8' });
276
306
  generated = r.status === 0;
277
- if (!generated) generateError = `${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').slice(-5).join('\n');
307
+ if (!generated) generateError = `${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').slice(-12).join('\n');
278
308
  }
279
309
  return { done, generated, generateError };
280
310
  }
@@ -308,7 +338,7 @@ function init(cwd, opts = {}) {
308
338
 
309
339
  const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
310
340
  for (const k of Object.keys(report)) report[k].push(...done[k]);
311
- return { report, values, tools, ci, generated, generateError };
341
+ return { report, warnings: done.warnings, values, tools, ci, generated, generateError };
312
342
  }
313
343
 
314
344
  function sync(cwd, opts = {}) {
@@ -363,7 +393,7 @@ function sync(cwd, opts = {}) {
363
393
  const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
364
394
  report.added.push(...done.created);
365
395
  report.updated.push(...done.merged);
366
- return { report, from, to: KIT_VERSION, tools, generated, generateError };
396
+ return { report, warnings: done.warnings, from, to: KIT_VERSION, tools, generated, generateError };
367
397
  }
368
398
 
369
399
  // what rulesync generates from the project's kit sources, regenerated in an empty folder: [[path, text]]
@@ -371,9 +401,9 @@ function generatedFiles(cwd) {
371
401
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-gen-'));
372
402
  fs.cpSync(path.join(cwd, '.rulesync'), path.join(dir, '.rulesync'), { recursive: true });
373
403
  fs.copyFileSync(path.join(cwd, 'rulesync.jsonc'), path.join(dir, 'rulesync.jsonc'));
374
- const r = spawnSync('npx', ['-y', RULESYNC, 'generate'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
404
+ const r = tool('npx', ['-y', RULESYNC, 'generate'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
375
405
  if (r.status !== 0) throw new InitError(`Couldn't work out which tool configs rulesync generated: ${`${r.stderr}${r.stdout}`.trim().split('\n').pop()}`);
376
- const files = templateFiles(dir).filter(f => !f.startsWith(`.rulesync${path.sep}`) && !['rulesync.jsonc', '.gitignore'].includes(f));
406
+ const files = templateFiles(dir).filter(f => !f.startsWith('.rulesync/') && !['rulesync.jsonc', '.gitignore'].includes(f));
377
407
  const out = files.map(f => [f, fs.readFileSync(path.join(dir, f), 'utf8')]);
378
408
  fs.rmSync(dir, { recursive: true, force: true });
379
409
  return out;
@@ -409,12 +439,12 @@ function uninstall(cwd, opts = {}) {
409
439
  }
410
440
  for (const [link] of SKILL_LINKS) {
411
441
  const p = path.join(cwd, link);
412
- if (isLink(p) && fs.readlinkSync(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); continue; }
442
+ if (isLink(p) && linkTarget(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); continue; }
413
443
  // per-skill links inside another framework's skills folder
414
444
  if (!fs.existsSync(p) || isLink(p)) continue;
415
445
  for (const name of fs.readdirSync(p)) {
416
446
  const q = path.join(p, name);
417
- if (isLink(q) && fs.readlinkSync(q) === `../../.agents/skills/${name}`) { fs.unlinkSync(q); report.removed.push(path.join(link, name)); }
447
+ if (isLink(q) && linkTarget(q) === `../../.agents/skills/${name}`) { fs.unlinkSync(q); report.removed.push(`${link}/${name}`); }
418
448
  }
419
449
  }
420
450
  // folders left empty (rmdir refuses non-empty ones)
@@ -438,13 +468,14 @@ function uninstall(cwd, opts = {}) {
438
468
  return { report, from };
439
469
  }
440
470
 
441
- function printSummary({ report, values, tools, ci, generated, generateError }, log = console.log) {
471
+ function printSummary({ report, warnings = [], values, tools, ci, generated, generateError }, log = console.log) {
442
472
  log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
443
473
  log(`Tools: ${tools.join(', ')}${tools.some(t => !TESTED.includes(t)) ? ' (cursor, opencode and kiro are not tested yet)' : ''}`);
444
474
  log(`CI: ${ci.length ? ci.join(', ') : 'none (add it any time with --ci github,codemagic)'}`);
445
475
  log(` created: ${report.created.length} files`);
446
476
  if (report.merged.length) log(` merged: ${report.merged.join(', ')}`);
447
477
  if (report.skipped.length) log(` kept as they were (already existed): ${report.skipped.join(', ')}`);
478
+ for (const w of warnings) log(` ! ${w}`);
448
479
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
449
480
  log('\nNext steps:');
450
481
  log(' 1. Fill in docs/ai/product.md, tech.md, structure.md and conventions.md for this app.');
@@ -457,7 +488,7 @@ function printSummary({ report, values, tools, ci, generated, generateError }, l
457
488
  more.forEach((m, i) => log(` ${i + 3}. ${m}`));
458
489
  }
459
490
 
460
- function printSync({ report, from, to, generated, generateError }, log = console.log) {
491
+ function printSync({ report, warnings = [], from, to, generated, generateError }, log = console.log) {
461
492
  log(`agentic-mobile-kit updated from ${from} to ${to}.`);
462
493
  const lines = [
463
494
  ['updated', report.updated], ['added', report.added], ['removed', report.removed],
@@ -465,6 +496,7 @@ function printSync({ report, from, to, generated, generateError }, log = console
465
496
  ];
466
497
  for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
467
498
  if (!Object.values(report).some(a => a.length)) log(' Nothing to change.');
499
+ for (const w of warnings) log(` ! ${w}`);
468
500
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
469
501
  log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
470
502
  }
@@ -476,4 +508,4 @@ function printUninstall({ report }, log = console.log) {
476
508
  log('\nReview it with "git status" and "git diff", then commit. Undo it with git if you change your mind.');
477
509
  }
478
510
 
479
- module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION };
511
+ module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION, tool };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
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",
@@ -50,7 +50,7 @@ If building shows the plan is wrong: when the intent is the same, update `requir
50
50
  ## 5. Check against the spec
51
51
 
52
52
  When all tasks are done:
53
- 1. Run `sh scripts/ai/verify.sh all --spec <id>`. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its scenario. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
53
+ 1. Run `sh scripts/ai/verify.sh all --spec <id>`. Off a Mac it checks Android only: record in `progress.md` that iOS still needs `verify.sh ios --spec <id>` on a Mac, and say so in the PR. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its scenario. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
54
54
  2. Go through every scenario and note its evidence: a test name, command output, or the screen checked. Where the code and the spec disagree, fix whichever is wrong, asking first if it's the spec. The spec must describe what ships.
55
55
 
56
56
  ## 6. Update the living spec
@@ -28,7 +28,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
28
28
 
29
29
  A task is done only when:
30
30
  1. lint, typecheck and tests pass, and you show the command output from this session;
31
- 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;
31
+ 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. On Windows or Linux, that covers Android only: write in `progress.md` and the PR that iOS still needs checking on a Mac, and the PR isn't merged until a teammate with a Mac has done it;
32
32
  3. the change stays inside the task's scope;
33
33
  4. `specs/<id>/progress.md` is updated, when working from a spec.
34
34
 
@@ -2,10 +2,10 @@
2
2
  # Installs JS dependencies exactly as locked, with the project's package manager.
3
3
  set -eu
4
4
  if [ -f yarn.lock ]; then
5
- corepack enable
5
+ corepack enable 2> /dev/null || true # needs admin rights on some Windows setups; yarn/pnpm may already be installed
6
6
  if [ -f .yarnrc.yml ]; then yarn install --immutable; else yarn install --frozen-lockfile; fi
7
7
  elif [ -f pnpm-lock.yaml ]; then
8
- corepack enable
8
+ corepack enable 2> /dev/null || true # needs admin rights on some Windows setups; yarn/pnpm may already be installed
9
9
  pnpm install --frozen-lockfile
10
10
  elif [ -f bun.lock ] || [ -f bun.lockb ]; then
11
11
  bun install --frozen-lockfile # ponytail: CI needs a setup-bun step for this branch
@@ -12,9 +12,10 @@ gradle=$(ls android/app/build.gradle android/app/build.gradle.kts 2>/dev/null |
12
12
  [ -z "$(grep -oE 'MARKETING_VERSION = [^;]+' "$pbx" | sort -u | sed -n 2p)" ] || { echo "$pbx has several app versions; set each one in Xcode" >&2; exit 1; }
13
13
  [ -z "$(grep -oE 'versionName( =)? "[^"]+"' "$gradle" | sort -u | sed -n 2p)" ] || { echo "$gradle has several versionName values; set each one by hand" >&2; exit 1; }
14
14
 
15
- sed -i '' -E "s/MARKETING_VERSION = [^;]+;/MARKETING_VERSION = $v;/" "$pbx"
16
- sed -i '' -E "s/versionName( =)? \"[^\"]+\"/versionName\1 \"$v\"/" "$gradle"
15
+ # -i.bak works with both macOS and GNU sed (Linux, Git Bash on Windows)
16
+ sed -i.bak -E "s/MARKETING_VERSION = [^;]+;/MARKETING_VERSION = $v;/" "$pbx" && rm -f "$pbx.bak"
17
+ sed -i.bak -E "s/versionName( =)? \"[^\"]+\"/versionName\1 \"$v\"/" "$gradle" && rm -f "$gradle.bak"
17
18
  grep -q "MARKETING_VERSION = $v;" "$pbx" || { echo "No MARKETING_VERSION in $pbx; set the version in Xcode" >&2; exit 1; }
18
19
  grep -qE "versionName( =)? \"$v\"" "$gradle" || { echo "No versionName in $gradle; set it by hand" >&2; exit 1; }
19
- plutil -lint -s "$pbx"
20
+ ! command -v plutil > /dev/null || plutil -lint -s "$pbx"
20
21
  echo "Version $v set in $pbx and $gradle."
@@ -12,7 +12,7 @@ const fs = require('fs');
12
12
  const path = require('path');
13
13
 
14
14
  const [cmd, ...args] = process.argv.slice(2);
15
- const read = f => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
15
+ const read = f => { try { return fs.readFileSync(f, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; } };
16
16
  const key = name => name.trim().toLowerCase();
17
17
  const isRequirement = l => /^### Requirement:/.test(l);
18
18
 
@@ -79,6 +79,12 @@ quick() {
79
79
  }
80
80
 
81
81
  ios() {
82
+ # iOS builds need Xcode, so off a Mac "all" checks Android and says who has to check iOS
83
+ if [ "$(uname -s)" != Darwin ]; then
84
+ echo "ios: not checked here: iOS builds need a Mac with Xcode. A teammate with a Mac runs: sh scripts/ai/verify.sh ios${spec:+ --spec $spec}"
85
+ [ "$mode" = ios ] && status=1
86
+ return
87
+ fi
82
88
  command -v maestro > /dev/null || { echo "ios: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
83
89
  # pod install also generates React Native codegen files into ios/build/generated
84
90
  if [ ! -d ios/Pods ] || [ ! -d ios/build/generated ]; then (cd ios && pod install > "$evidence/pod-install.log" 2>&1); fi
@@ -104,7 +110,12 @@ ios() {
104
110
 
105
111
  android() {
106
112
  command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
107
- sdk=${ANDROID_HOME:-$HOME/Library/Android/sdk}
113
+ case $(uname -s) in # where Android Studio puts the SDK by default
114
+ Darwin) default_sdk=$HOME/Library/Android/sdk ;;
115
+ MINGW* | MSYS* | CYGWIN*) default_sdk=${LOCALAPPDATA:-$HOME/AppData/Local}/Android/Sdk ;;
116
+ *) default_sdk=$HOME/Android/Sdk ;;
117
+ esac
118
+ sdk=${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$default_sdk}}
108
119
  adb="$sdk/platform-tools/adb"
109
120
  if ! (cd android && ./gradlew assembleRelease --no-daemon -q) > "$evidence/android-build.log" 2>&1; then
110
121
  echo "android: release build FAILED, see ${evidence#"$root"/}/android-build.log"; status=1; return