agentic-mobile-kit 0.7.16 → 0.7.18

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 (24) hide show
  1. package/bin/cli.js +1 -1
  2. package/lib/init.js +122 -20
  3. package/package.json +1 -1
  4. package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +1 -1
  5. package/stacks/react-native/expo/AGENTS.md +6 -3
  6. package/stacks/react-native/expo/docs/amk/expo.md +60 -4
  7. package/stacks/react-native/new-app/ErrorBoundary.tsx +61 -0
  8. package/stacks/react-native/new-app/error-boundary.tsx +30 -0
  9. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +6 -5
  10. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +4 -3
  11. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +10 -6
  12. package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
  13. package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
  14. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +3 -3
  15. package/stacks/react-native/template/AGENTS.md +5 -2
  16. package/stacks/react-native/template/docs/amk/react-native.md +58 -3
  17. package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
  18. package/stacks/react-native/template/scripts/amk/release-check.js +149 -2
  19. package/stacks/react-native/template/scripts/amk/report.js +78 -0
  20. package/stacks/react-native/template/scripts/amk/rn-check.js +435 -0
  21. package/stacks/react-native/template/scripts/amk/verify.sh +139 -15
  22. package/stacks/react-native/template/specs/_templates/design.md +16 -0
  23. package/stacks/react-native/template/specs/_templates/flow.yaml +8 -0
  24. package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
package/bin/cli.js CHANGED
@@ -50,7 +50,7 @@ function main([cmd, ...rest]) {
50
50
  printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
51
51
  });
52
52
  } else if (cmd === 'sync') {
53
- run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
53
+ run('sync', () => { if (printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') }))) process.exitCode = 1; });
54
54
  } else if (cmd === 'uninstall') {
55
55
  run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
56
56
  } else if (cmd === 'doctor') {
package/lib/init.js CHANGED
@@ -173,7 +173,7 @@ function createApp(cwd, kind, { run = tool, log = console.log, pods = process.pl
173
173
  // the tools commit only in a repository they create; init needs everything committed
174
174
  commit(own ? 'Initial commit' : 'Add the files that were already in the folder');
175
175
  newAppDefaults(cwd, kind, { run, log });
176
- commit('Support tablets and landscape; stricter TypeScript with @/ imports');
176
+ commit('Support tablets and landscape; stricter TypeScript with @/ imports; an error boundary');
177
177
  // the first pod install changes the Xcode project and Info.plist: a commit of its own keeps that out of the first feature
178
178
  if (kind === 'bare' && pods) {
179
179
  log('Installing the iOS pods\n');
@@ -186,8 +186,9 @@ function createApp(cwd, kind, { run = tool, log = console.log, pods = process.pl
186
186
  }
187
187
 
188
188
  // What a new app starts with beyond the tool's template: iPad and every orientation (the React Native template locks
189
- // iPhones to portrait; Expo's locks everything to portrait and leaves iPad out), and stricter TypeScript with "@/"
190
- // imports for src/. Expo's template has the "@/" paths already, and Metro reads them; bare apps need a Babel plugin.
189
+ // iPhones to portrait; Expo's locks everything to portrait and leaves iPad out), stricter TypeScript with "@/"
190
+ // imports for src/, and an error boundary around the app (neither template has one, so a render error leaves a blank
191
+ // screen). Expo's template has the "@/" paths already, and Metro reads them; bare apps need a Babel plugin.
191
192
  const STRICTER = { noUncheckedIndexedAccess: true, noImplicitOverride: true, noImplicitReturns: true, noFallthroughCasesInSwitch: true };
192
193
  const ALIAS_PLUGIN = 'babel-plugin-module-resolver@5';
193
194
  const ADD_DEV = { npm: ['npm', 'install', '--save-dev'], Yarn: ['yarn', 'add', '--dev'], pnpm: ['pnpm', 'add', '--save-dev'], Bun: ['bun', 'add', '--dev'] };
@@ -197,6 +198,7 @@ function newAppDefaults(cwd, kind, { run, log }) {
197
198
  const next = text === null ? null : change(text);
198
199
  if (next !== null && next !== text) fs.writeFileSync(path.join(cwd, rel), next);
199
200
  };
201
+ errorBoundary(cwd, kind, edit, log);
200
202
  const json = text => { try { return JSON.parse(text); } catch { return null; } };
201
203
  // short lists stay on one line, as the templates write them
202
204
  const format = j => `${JSON.stringify(j, null, 2).replace(/\[\n\s*([^[\]{}]*?)\n\s*\]/g, (m, items) => `[${items.split(/,\n\s*/).join(', ')}]`)}\n`;
@@ -245,6 +247,45 @@ function newAppDefaults(cwd, kind, { run, log }) {
245
247
  edit('tsconfig.json', stricter(alias));
246
248
  }
247
249
 
250
+ // the error boundary: the component next to the app's others, used by the root layout (Expo Router shows an
251
+ // ErrorBoundary that a route exports) or around the root component index.js registers. Relative imports, which work
252
+ // whether or not the "@/" alias is set up
253
+ const NEW_APP_FILES = path.join(TEMPLATE, '..', 'new-app');
254
+ function errorBoundary(cwd, kind, edit, log) {
255
+ const place = (rel, source) => {
256
+ if (fs.existsSync(path.join(cwd, rel))) return false;
257
+ fs.mkdirSync(path.dirname(path.join(cwd, rel)), { recursive: true });
258
+ fs.copyFileSync(path.join(NEW_APP_FILES, source), path.join(cwd, rel));
259
+ return true;
260
+ };
261
+ const from = (file, target) => { const r = path.relative(path.dirname(file), target).split(path.sep).join('/'); return r.startsWith('.') ? r : `./${r}`; };
262
+ if (kind === 'expo') {
263
+ const layout = ['src/app/_layout.tsx', 'app/_layout.tsx'].find(f => fs.existsSync(path.join(cwd, f)));
264
+ if (!layout) { log('! No app/_layout.tsx or src/app/_layout.tsx, so no error boundary was added: export an ErrorBoundary from the root layout'); return; }
265
+ if (/\bErrorBoundary\b/.test(readIf(path.join(cwd, layout)))) return;
266
+ const component = `${layout.startsWith('src/') || fs.existsSync(path.join(cwd, 'src')) ? 'src/' : ''}components/error-boundary.tsx`;
267
+ if (!place(component, 'error-boundary.tsx')) { log(`! ${component} is already there, so no error boundary was added`); return; }
268
+ const line = `export { ErrorBoundary } from '${from(layout, component.replace(/\.tsx$/, ''))}';`;
269
+ // after the last import, which may span lines
270
+ edit(layout, text => {
271
+ const imports = [...text.matchAll(/^import\b[^;]*?(?:from\s*)?['"][^'"]+['"];?[ \t]*$/gm)];
272
+ const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
273
+ return at ? `${text.slice(0, at)}\n${line}${text.slice(at)}` : `${line}\n${text}`;
274
+ });
275
+ return;
276
+ }
277
+ const index = readIf(path.join(cwd, 'index.js'));
278
+ const register = /AppRegistry\.registerComponent\(\s*appName\s*,\s*\(\)\s*=>\s*App\s*\)/;
279
+ if (!index || !register.test(index) || !/^import App from '\.\/App';$/m.test(index)) {
280
+ log('! index.js doesn\'t register App the usual way, so no error boundary was added: wrap the app in one');
281
+ return;
282
+ }
283
+ if (!place('src/components/ErrorBoundary.tsx', 'ErrorBoundary.tsx')) { log('! src/components/ErrorBoundary.tsx is already there, so no error boundary was added'); return; }
284
+ edit('index.js', text => text
285
+ .replace(/^import App from '\.\/App';$/m, "import App from './App';\nimport { withErrorBoundary } from './src/components/ErrorBoundary';")
286
+ .replace(register, 'AppRegistry.registerComponent(appName, () => withErrorBoundary(App))'));
287
+ }
288
+
248
289
  // Expo apps whose ios/ and android/ come from `expo prebuild` (Continuous Native Generation, not in git) get the
249
290
  // Expo overlay. Expo apps that keep the native folders in git are set up like bare apps.
250
291
  function detectStack(cwd, deps) {
@@ -252,11 +293,14 @@ function detectStack(cwd, deps) {
252
293
  }
253
294
 
254
295
  // a stack's files, rel -> source: the template, and for Expo the overlay next to it, which replaces or adds files
296
+ // deps, when given, are the app's: an app on Expo Router doesn't get the react-navigation skill, as from SDK 56 it imports
297
+ // navigation from expo-router, which its own skill teaches (one on React Navigation itself still needs it)
255
298
  const EXPO_LEAVES_OUT = ['docs/amk/react-native.md', '.agents/skills/upgrading-react-native/'];
256
- function stackFiles(template, stack) {
299
+ function stackFiles(template, stack, deps = {}) {
257
300
  const files = new Map(templateFiles(template).map(rel => [rel, path.join(template, rel)]));
258
301
  if (stack !== 'expo') return files;
259
- for (const rel of files.keys()) if (EXPO_LEAVES_OUT.some(f => (f.endsWith('/') ? rel.startsWith(f) : rel === f))) files.delete(rel);
302
+ const out = [...EXPO_LEAVES_OUT, ...(deps['expo-router'] ? ['.agents/skills/react-navigation/'] : [])];
303
+ for (const rel of files.keys()) if (out.some(f => (f.endsWith('/') ? rel.startsWith(f) : rel === f))) files.delete(rel);
260
304
  const overlay = path.join(template, '..', 'expo');
261
305
  if (fs.existsSync(overlay)) for (const rel of templateFiles(overlay)) files.set(rel, path.join(overlay, rel));
262
306
  return files;
@@ -426,6 +470,34 @@ function merge3(current, base, kitNew, from) {
426
470
  return { text: r.stdout, conflicts: r.status };
427
471
  }
428
472
 
473
+ // AGENTS.md's kit section as the team left it, merged with the kit's new one: a team's edit inside it (the screens it
474
+ // builds for, say) stays. A line the kit fills in with what it finds (the versions, the package manager, the app's
475
+ // checks) is the kit's, whatever it says now: there the old version's line, filled in today, stands in for the team's.
476
+ // The screens are a team's decision, so a line with them counts as an edit. The marker lines are the kit's
477
+ function mergeSection(mine, rawOld, kitOld, kitNew, from) {
478
+ const lines = s => s.replace(/\n$/, '').split('\n');
479
+ const [raw, base, theirs] = [rawOld, kitOld, kitNew].map(lines);
480
+ const found = raw.length !== base.length ? [] : raw.map((l, i) => /\{\{\w+\}\}/.test(l) && !l.includes('{{SCREENS}}')
481
+ && [new RegExp(`^${l.split(/\{\{\w+\}\}/).map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`), base[i]]).filter(Boolean);
482
+ const ours = lines(mine).map(l => (base.includes(l) ? l : (found.find(([re]) => re.test(l)) || [null, l])[1]));
483
+ const inner = a => `${a.slice(1, -1).join('\n')}\n`;
484
+ const { text, conflicts } = merge3(inner(ours), inner(base), inner(theirs), from);
485
+ return { text: !conflicts && text === inner(theirs) ? kitNew : `${theirs[0]}\n${text}${theirs[theirs.length - 1]}\n`, conflicts };
486
+ }
487
+
488
+ // whether a merged script still parses (two edits can merge cleanly into one that doesn't): sh -n for shell scripts
489
+ // and git hooks, node --check for JavaScript. Without sh on the PATH (Windows without Git's), shell isn't checked
490
+ function parses(rel, text) {
491
+ const shell = rel.endsWith('.sh') || rel.startsWith('.githooks/');
492
+ if (!shell && !/\.[cm]?js$/.test(rel)) return true;
493
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-parse-'));
494
+ const file = path.join(dir, path.basename(rel));
495
+ fs.writeFileSync(file, text);
496
+ const r = spawnSync(shell ? 'sh' : process.execPath, [shell ? '-n' : '--check', file], { encoding: 'utf8' });
497
+ fs.rmSync(dir, { recursive: true, force: true });
498
+ return Boolean(r.error) || r.status === 0;
499
+ }
500
+
429
501
  // Git hook managers a project may already use. The kit's hooks then run from theirs and core.hooksPath stays theirs:
430
502
  // two tools setting it undo each other on every install (husky's prepare script runs after the kit's postinstall).
431
503
  const KIT_HOOKS = ['pre-commit', 'pre-push'];
@@ -445,7 +517,10 @@ const forwarder = h => `#!/bin/sh\n${FORWARD} .git/hooks/${h}, which core.hooksP
445
517
  const localHooksPath = cwd => {
446
518
  let v = '';
447
519
  try { v = git(cwd, 'config', '--local', 'core.hooksPath'); } catch {}
448
- return v && path.posix.normalize(v.replace(/\\/g, '/')).replace(/\/+$/, '');
520
+ v = v && path.posix.normalize(v.replace(/\\/g, '/')).replace(/\/+$/, '');
521
+ // the project's own .githooks as a full path (git config core.hooksPath "$PWD/.githooks") is the kit's folder too
522
+ const real = p => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
523
+ return v && path.isAbsolute(v) && real(v) === real(path.join(cwd, '.githooks')) ? '.githooks' : v;
449
524
  };
450
525
 
451
526
  function hookManager(cwd, pkg) {
@@ -618,10 +693,11 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
618
693
  const gi = path.join(cwd, '.gitignore');
619
694
  const giText = readIf(gi) || '';
620
695
  // Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
621
- const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
696
+ // .maestro/.amk-*: the copies of flows with view-tree steps that verify.sh runs on Android, there only while they run
697
+ const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', '.maestro/.amk-*', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
622
698
  const missing = ignored.filter(l => !giText.split('\n').includes(l));
623
699
  if (missing.length) {
624
- fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
700
+ fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs), .maestro/.amk-* the flows verify.sh is running${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
625
701
  done.merged.push('.gitignore');
626
702
  }
627
703
 
@@ -747,7 +823,7 @@ function init(cwd, opts = {}) {
747
823
  const pm = detectPm(cwd, opts.pm);
748
824
  const tools = opts.tools || TESTED;
749
825
  for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
750
- const files = stackFiles(opts.template || TEMPLATE, stack);
826
+ const files = stackFiles(opts.template || TEMPLATE, stack, deps);
751
827
  const ci = chooseCi(cwd, readIf(path.join(cwd, 'AGENTS.md')), opts.ci);
752
828
  const values = projectValues(cwd, pkg, deps, pm, ci, stack);
753
829
  const targets = tools.flatMap(t => TOOLS[t]);
@@ -790,10 +866,11 @@ function sync(cwd, opts = {}) {
790
866
  const oldValues = { ...values, ...ciTexts(hadCi) };
791
867
  const tools = installedTools(cwd);
792
868
  const targets = tools.flatMap(t => TOOLS[t]);
793
- const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
794
- const newFiles = stackFiles(opts.template || TEMPLATE, stack);
869
+ const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], byHand: [], removed: [], kept: [] };
870
+ const newFiles = stackFiles(opts.template || TEMPLATE, stack, deps);
795
871
  // an install from before 0.7.0: the kit's files move to the new folders first, so the team's edits come along.
796
872
  // Other files in the old folders may be the app's own, so they stay where they are.
873
+ // all the old version installed, whatever the app uses now: what this one leaves out goes
797
874
  const oldKit = stackFiles(oldDir, stack);
798
875
  const moved = [...oldKit.keys()].filter(rel => renamedPath(rel) !== rel
799
876
  && fs.existsSync(path.join(cwd, rel)) && !fs.existsSync(path.join(cwd, renamedPath(rel))));
@@ -817,8 +894,14 @@ function sync(cwd, opts = {}) {
817
894
  const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldFiles.get(rel), rel, oldValues, targets) : null;
818
895
  const current = projectText(cwd, rel, targets);
819
896
  if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
820
- const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, kitNew) : mergeClaude(current);
821
- if (next !== current) { fs.writeFileSync(path.join(cwd, rel), next); report.updated.push(rel); }
897
+ // the team's edits inside the kit's section stay, merged like any file's
898
+ const mine = rel === 'AGENTS.md' && exact && kitOld !== null && current !== null && (current.match(MARKERS) || [])[0];
899
+ const { text: section, conflicts } = mine ? mergeSection(mine, fs.readFileSync(oldFiles.get(rel), 'utf8'), kitOld, kitNew, from) : { text: kitNew, conflicts: 0 };
900
+ const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, section) : mergeClaude(current);
901
+ if (next === current) continue;
902
+ fs.writeFileSync(path.join(cwd, rel), next);
903
+ if (section === kitNew) report.updated.push(rel);
904
+ else (conflicts ? report.conflicts : report.merged).push(`${rel} (your edits inside the kit's section)`);
822
905
  continue;
823
906
  }
824
907
  if (current === null) {
@@ -834,6 +917,14 @@ function sync(cwd, opts = {}) {
834
917
  if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
835
918
  // without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
836
919
  const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
920
+ // markers, or a merge that no longer parses, would stop a script, a hook, a workflow or a config from working (and
921
+ // every check with it): those get the kit's version, and the team's goes beside it to bring its changes back
922
+ if (!rel.endsWith('.md') && (conflicts || !parses(rel, text))) {
923
+ fs.copyFileSync(path.join(cwd, rel), path.join(cwd, `${rel}.mine`));
924
+ writeKitFile(cwd, rel, kitNew);
925
+ report.byHand.push(rel);
926
+ continue;
927
+ }
837
928
  writeKitFile(cwd, rel, text);
838
929
  (conflicts ? report.conflicts : report.merged).push(rel);
839
930
  }
@@ -844,6 +935,7 @@ function sync(cwd, opts = {}) {
844
935
  if (current === null) continue;
845
936
  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)`);
846
937
  }
938
+ removeEmptyFolders(cwd, report.removed);
847
939
 
848
940
  const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files: newFiles, stack, skipGenerate: opts.skipGenerate });
849
941
  report.added.push(...done.created);
@@ -870,6 +962,14 @@ function generatedFiles(cwd) {
870
962
  return out;
871
963
  }
872
964
 
965
+ // the folders that removed files (paths from cwd, maybe followed by " (why)") left empty; rmdir refuses non-empty ones
966
+ function removeEmptyFolders(cwd, removed) {
967
+ const dirs = [...new Set(removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
968
+ for (let d of dirs) {
969
+ for (; d && d !== '.'; d = path.dirname(d)) { try { fs.rmdirSync(path.join(cwd, d)); } catch { break; } }
970
+ }
971
+ }
972
+
873
973
  function uninstall(cwd, opts = {}) {
874
974
  const { pkg, deps, stack: detected } = checkProject(cwd);
875
975
  const agents = readIf(path.join(cwd, 'AGENTS.md'));
@@ -910,11 +1010,7 @@ function uninstall(cwd, opts = {}) {
910
1010
  }
911
1011
  }
912
1012
  for (const h of OTHER_HOOKS) if ((readIf(path.join(cwd, '.githooks', h)) || '').includes(FORWARD)) remove(`.githooks/${h}`);
913
- // folders left empty (rmdir refuses non-empty ones)
914
- const dirs = [...new Set(report.removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
915
- for (let d of dirs) {
916
- for (; d && d !== '.'; d = path.dirname(d)) { try { fs.rmdirSync(path.join(cwd, d)); } catch { break; } }
917
- }
1013
+ removeEmptyFolders(cwd, report.removed);
918
1014
 
919
1015
  // git hooks: the kit's postinstall, or its lines in the project's hook manager (which would fail once .githooks is gone)
920
1016
  const scripts = pkg.scripts || {};
@@ -964,13 +1060,19 @@ function printSync({ report, warnings = [], from, to, changed, generated, genera
964
1060
  log(from === to ? `agentic-mobile-kit is already ${to}.` : `agentic-mobile-kit updated from ${from} to ${to}.`);
965
1061
  const lines = [
966
1062
  ['moved to the new folders', report.moved || []], ['updated', report.updated], ['added', report.added], ['removed', report.removed],
967
- ['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts], ['left alone', report.kept],
1063
+ ['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
1064
+ ['CONFLICTS where markers would stop the file from working, so the kit\'s version is in place: bring your changes back from <file>.mine, then delete it', report.byHand || []],
1065
+ ['left alone', report.kept],
968
1066
  ];
969
1067
  for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
970
1068
  if (!changed) log(' Nothing changed.');
971
1069
  for (const w of warnings) log(` ! ${w}`);
972
1070
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
973
- if (changed) log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
1071
+ // a conflict left is an update not finished: said last, and the command fails
1072
+ const open = report.conflicts.length + (report.byHand || []).length;
1073
+ if (open) log(`\nsync isn't finished: ${open === 1 ? 'a conflict' : `${open} conflicts`} to resolve (above). Then run the checks, and commit.`);
1074
+ else if (changed) log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
1075
+ return open;
974
1076
  }
975
1077
 
976
1078
  function printUninstall({ report }, log = console.log) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.7.16",
3
+ "version": "0.7.18",
4
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",
@@ -6,6 +6,6 @@
6
6
  | expo-upgrade | same | same | MIT | Image files left out |
7
7
  | expo-module | same | same | MIT | Image files left out |
8
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 |
9
+ | react-navigation | same | same | MIT | Image files left out; not in apps on Expo Router |
10
10
 
11
11
  Updated with `scripts/vendor-skills.sh` in the agentic-mobile-kit repo.
@@ -20,10 +20,11 @@ This project may also use other AI workflow frameworks (for example Superpowers,
20
20
  | Add a library (ask first) | `npx expo install <package>`: the version that matches the SDK |
21
21
  | Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/amk/pm-run.sh lint`, `sh scripts/amk/pm-run.sh typecheck`, `sh scripts/amk/pm-run.sh test` |
22
22
  | Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
23
- | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
23
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
24
24
  | Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
25
+ | React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
25
26
  | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
26
- | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/amk/release-check.js` |
27
+ | Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
27
28
  | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android`, `sh scripts/amk/release-build.sh ios` |
28
29
 
29
30
  ## Definition of done
@@ -39,16 +40,18 @@ Never say a check passed unless you ran it in this session.
39
40
  ## Rules
40
41
 
41
42
  - Stay inside the task. Ask before touching unrelated files.
43
+ - Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
42
44
  - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `app.json`, `app.config.*`, `eas.json` or `.github/workflows/`.
43
45
  - Never edit `ios/` or `android/`: the next prebuild overwrites them. Native settings go in `app.json` or `app.config.*`, through config plugins; native code goes in an Expo module (`expo-module` skill). Ask before adding a config plugin.
44
46
  - Never run `eas build`, `eas submit` or `eas update`: they build, ship or publish with the team's accounts, so a person runs them.
45
47
  - Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
46
48
  - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
49
+ - When `rn-check` (in `verify.sh quick`) reports a problem (✗), show it to the user and let them choose, for each one: fix it, or keep the line with `// amk-ok <today's date>: <their reason>`. Never add an `amk-ok` on your own. One kept over two weeks ago comes back when its file changes again: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
47
50
  - After 2 failed attempts at the same fix, stop and report what you found.
48
51
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
49
52
  - Follow `docs/amk/expo.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
50
53
 
51
54
  ## Skills
52
55
 
53
- `expo-router`, `expo-upgrade`, `expo-module` (from Expo), `react-native-best-practices`, `react-navigation` (from Callstack), in `.agents/skills/`.
56
+ `expo-router`, `expo-upgrade`, `expo-module` (from Expo), `react-native-best-practices`, and in an app on React Navigation without Expo Router, `react-navigation` (from Callstack), in `.agents/skills/`.
54
57
  <!-- KIT:END agentic-mobile-kit -->
@@ -1,6 +1,6 @@
1
1
  # Expo rules
2
2
 
3
- Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change, or from a bug agents keep making on screens.
3
+ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from a documented platform change, or from a bug agents keep making on screens. `node scripts/amk/rn-check.js`, which `verify.sh quick` runs, checks the lines a branch changes for some of them.
4
4
 
5
5
  ## Expo changes with every SDK
6
6
 
@@ -14,7 +14,8 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
14
14
  - `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git. Never edit them: the next prebuild overwrites the change.
15
15
  - Native settings (permissions and their texts, bundle ID, entitlements) go in `app.json` or `app.config.*`. Libraries with native setup bring a config plugin; add it to `plugins`.
16
16
  - Native code of the app's own goes in an Expo module (`expo-module` skill), not into the generated folders.
17
- - A library with native code needs a new native build: Expo Go doesn't include it. `sh scripts/amk/verify.sh` makes release builds with the current native code.
17
+ - Run the app in a development build, not Expo Go: Expo Go can't load native code the app adds, and the store version runs only one SDK. `sh scripts/amk/verify.sh` makes release builds with the current native code.
18
+ - Android release builds shrink the code with R8 (on by default from SDK 58). A crash only in release builds usually means a missing keep rule: add the rule; don't turn R8 off.
18
19
 
19
20
  ## Architecture
20
21
 
@@ -29,7 +30,7 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
29
30
  - With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
30
31
  - Lists that grow with the user's data scroll (`FlatList`, or the list component the app already uses), and so does any screen taller than a small phone.
31
32
  - At the largest system text size, text wraps instead of being cut off: no fixed heights on views that hold text. Don't turn off font scaling (`allowFontScaling={false}`) to make a layout fit.
32
- - Messages that appear after an action, such as a form error, are read out by screen readers: announce them with `AccessibilityInfo.announceForAccessibility`.
33
+ - Messages that appear after an action, such as a form error, are read out by screen readers. On Android, show the message in a view with `accessibilityLiveRegion="polite"`: Android 16 deprecated announcements. On iOS, announce it with `AccessibilityInfo.announceForAccessibility`.
33
34
  - Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
34
35
  - Give every interactive element a `testID` (kebab-case, for example `dark-mode-switch`). End-to-end tools tap by `testID`. On iOS, React Native exposes a label and its control as duplicate accessibility elements, so tapping by text can hit the label: nothing happens, yet the tool reports success.
35
36
  - Give every interactive element an `accessibilityLabel` that says what it does and an `accessibilityRole` (`button`, `link`, `switch`, …), so screen readers can use it. Icon-only buttons need it most; screen readers don't read `testID`.
@@ -43,9 +44,64 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
43
44
  - Lay out by window width: under 600 points (dp on Android), the phone layout; from 600, the tablet layout, with more columns, and a list beside its detail where that helps. Text-heavy content and forms keep a readable width (about 600 to 700 points) instead of stretching edge to edge.
44
45
  - Sizes: when the app already has a way to size things (a scaling helper, or sizes in its theme), use it everywhere and don't mix in another. A new app takes sizes from its theme: spacing and a few text sizes step up from 600 points, and text follows the system font size. Judge the tablet and landscape screenshots like the phone's: each should look made for that screen, not stretched or tiny.
45
46
  - Landscape leaves little height: screens scroll, the keyboard covers more, and the safe-area insets include the left and right edges (the notch or Dynamic Island side).
46
- - Apps targeting Android 16 (API 36) can't lock the orientation or size on tablets and foldables (600 dp wide and up): the system ignores the lock there. So on Android tablets every screen has to work turned, whatever the app's settings say.
47
+ - Android ignores orientation and size locks on tablets and foldables (600 dp wide and up) for apps targeting Android 16 (API 36), and from Android 17 (API 37) apps can't opt out. Apple deprecated `UIRequiresFullScreen` with iPadOS 26, so iPad windows resize too, and on iOS 27 `ScreenOrientation.lockAsync` may do nothing. Every screen has to work at any window size and turned, whatever the app's settings say.
47
48
  - Don't lock the orientation in code to avoid layout work. Which orientations the app supports is a product decision, set in `app.json`: `orientation` (`default` turns, `portrait` or `landscape` locks) and `ios.supportsTablet` for the iPad app.
48
49
 
50
+ ## Current Expo, React Native and React
51
+
52
+ These changed after most AI training data was written: check them instead of writing from memory.
53
+
54
+ - Navigation (SDK 56 and later): import from Expo Router's own entry points, such as `expo-router/react-navigation`, never from `@react-navigation/*`, which no longer works alongside it (`expo-router` skill; the `expo-upgrade` skill's codemod moves old imports).
55
+ - `expo-av` isn't maintained any more: use `expo-audio` and `expo-video`. `@expo/vector-icons` is deprecated from SDK 56: use `@react-native-vector-icons/*`. In `expo-file-system`, `File` and `Directory`'s `copy` and `move` (SDK 56) and `File.write` (SDK 58) are async; the `…Sync` versions aren't.
56
+ - iOS: from SDK 58, prebuild generates `SceneDelegate.swift`, as apps built with Xcode 27 don't launch without the UIScene life cycle. Config plugins that change the app delegate's window or URL handling have to change the scene delegate instead.
57
+ - Removed from React Native: `InteractionManager` (0.87; use `requestIdleCallback`), the `StatusBar` props `backgroundColor` and `translucent` (0.87), `Modal`'s `animated` (0.87; `animationType`), a boolean `keyboardShouldPersistTaps` (0.87; `"handled"`) and `StyleSheet.absoluteFillObject` (0.85; `StyleSheet.absoluteFill`).
58
+ - Deprecated, so not in new code: `ImageBackground` (a `View` with an absolutely positioned image), `InputAccessoryView` (`KeyboardStickyView` from `react-native-keyboard-controller`) and `AccessibilityInfo.setAccessibilityFocus` (`sendAccessibilityEvent`).
59
+ - Import from `react-native` itself. `react-native/Libraries/…` is private, and a type error from React Native 0.87; don't add the `react-native-legacy-deep-imports` opt-out to hide it.
60
+ - React 19: pass `ref` as a prop instead of `forwardRef`, render `<SomeContext value={…}>` instead of `<SomeContext.Provider>`, and use `useEffectEvent` (19.2) instead of turning off `react-hooks/exhaustive-deps`.
61
+ - With the React Compiler on (`experiments.reactCompiler` in `app.json`), it memoizes: don't add `memo`, `useMemo` or `useCallback` to new code, and don't remove the ones there as a side task.
62
+ - Android: Google Play takes only apps targeting Android 16 (API 36) or higher (from 31 August 2026). Don't lower the target SDK to get out of edge to edge, back handling or orientation changes.
63
+
64
+ ## Errors, storage and effects
65
+
66
+ - Wrap the app in an error boundary, so a render error shows a screen to recover from instead of a blank or closed app: export an `ErrorBoundary` from the root layout (Expo Router), or use the crash reporter's.
67
+ - Every failure reaches the user or the crash reporter: no empty `catch`, and an action started from a button catches its error and shows it, with a way to retry, so a spinner never stays up.
68
+ - Tokens, passwords and keys go in `expo-secure-store`, never in AsyncStorage or other plain storage. Anything in the JavaScript bundle, `EXPO_PUBLIC_` variables included, can be read by anyone who has the app: no secret keys there.
69
+ - Session replay and analytics mask what users type, and logs leave out tokens and personal data.
70
+ - Effects clean up what they start: timers (`clearTimeout`, `clearInterval`), listeners and subscriptions (return their `remove`), and async work that can finish after the screen closes (an `AbortController`, or a flag the cleanup sets).
71
+ - List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
72
+ - Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
73
+ - Component tests use React Native Testing Library (`@testing-library/react-native`) and find elements as users and screen readers do, by role, label or text (`getByRole('button', { name: 'Save' })`), rather than relying on snapshots.
74
+
75
+ ## Platform guidelines and accessibility
76
+
77
+ From Apple's Human Interface Guidelines, Android's design and app quality guidelines, and WCAG 2.2.
78
+
79
+ - Touch targets: every button, link and control is at least 44×44 points on iOS and 48×48 dp on Android (`minWidth`/`minHeight: 48` covers both): pad a small icon instead of sizing the button to it. `hitSlop` doesn't reach past the parent's bounds, so use it only where the layout can't grow.
80
+ - Text: no `fontSize` under 11, and don't cap scaling below 2× (`maxFontSizeMultiplier`, or `Text.defaultProps`).
81
+ - Contrast, in both light and dark: text 4.5:1 against its background (3:1 from 18 points, or 14 bold), and input borders, focus rings and icons that carry meaning 3:1. Colors come from the theme, whose pairs are checked once; a grey like `#999` on white is only 2.8:1.
82
+ - Screen readers: controls show their state in `accessibilityState` (`checked`, `selected`, `expanded`, `disabled`), and screen and section titles have `accessibilityRole="header"`. A label names the action ("Delete photo"), without the role ("button") the reader already says. Put `accessible` on a row that reads as one item, never on one that holds its own buttons. Meaningful images get a label; decorative ones need nothing.
83
+ - Every swipe, drag or long-press action also has a visible button or menu item, and is in `accessibilityActions`. Color is never the only signal: an error shows text, and a state adds an icon or a word.
84
+ - Back: keep swipe back on iOS and the system back on Android. To ask before leaving unsaved changes, use `usePreventRemove` (from `expo-router/react-navigation`), not `gestureEnabled: false`. A `hardwareBackPress` listener returns `true` only while it closes something on screen; apps don't quit themselves (`BackHandler.exitApp`). Every `Modal` has `onRequestClose`, which Android's back button calls; forms open as sheets (a route with `presentation: 'formSheet'`, or `presentationStyle="pageSheet"`).
85
+ - Permissions: ask when the user starts the feature that needs it, never at launch or when a screen opens; first say in the app why. When it's denied, say what's unavailable and keep the rest working. When the system won't ask again (`canAskAgain` is false), the feature's button explains that and offers `Linking.openSettings()`. Ask for notifications after an action they serve, not on launch; on Android 13 and later, `expo-notifications` shows the prompt only once a notification channel exists, so create it first.
86
+ - Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `Switch`); a custom one gets the same role, state and size.
87
+ - Dark mode: `userInterfaceStyle: "automatic"` in `app.json` (Android also needs `expo-system-ui`), and colors from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
88
+ - Data screens have loading, empty (why, and what to do next), error (what failed, with Retry) and content states. A message the user has to read doesn't vanish on a timer, and screen readers announce it.
89
+ - Reduce Motion: with it on, nothing loops or moves for decoration. Don't pass `ReduceMotion.Never` to Reanimated for decoration; with `Animated` or Lottie, read `AccessibilityInfo.isReduceMotionEnabled()` and the `reduceMotionChanged` event, and fade or stop instead.
90
+ - iOS 26: use native headers and tab bars (Expo Router's `Stack` and native tabs), which iOS draws in its current style; don't draw imitation glass behind content, or opt out with `UIDesignRequiresCompatibility` (builds with the iOS 27 SDK ignore it). Nothing the user needs sits under a floating tab bar, button or footer: scroll content gets bottom padding for it.
91
+ - Haptics only for success, error or a selection, never as the only feedback, with `expo-haptics`; not `Vibration.vibrate`.
92
+
93
+ ## Store review
94
+
95
+ What App Store review and Google Play reject. `node scripts/amk/release-check.js` checks the app config for some of it.
96
+
97
+ - Apps where people can create an account let them start deleting it in the app: a full deletion, not deactivation; a direct link to a web page that finishes it is fine (Apple 5.1.1(v)). Google Play also needs that web link in the Data safety form.
98
+ - A third-party or social login (Google, Facebook) as the main sign-in also needs an equivalent private one, usually Sign in with Apple (`expo-apple-authentication`, 4.8); an app that signs in only with the company's own accounts doesn't.
99
+ - Digital content and subscriptions are sold with in-app purchase (3.1.1); physical goods and services aren't. Links to buy elsewhere follow the storefront's current rules.
100
+ - Permission texts (in each library's plugin options, or `ios.infoPlist`) say what the app does with the data and why, for each use; ask only for what the app uses.
101
+ - The privacy manifest (`ios.privacyManifests` in `app.json`) and App Store Connect's privacy details list the data the app and its SDKs collect (analytics, crash reporting, session replay). Tracking needs the App Tracking Transparency prompt first (`expo-tracking-transparency`).
102
+ - Google Play restricts these permissions to apps whose core feature needs them, with a declaration in Play Console: photos and videos (`READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`: others use the Android photo picker), `QUERY_ALL_PACKAGES`, `MANAGE_EXTERNAL_STORAGE`, SMS and call log, `USE_EXACT_ALARM`, and background location (also a video and an in-app disclosure first). A library can add one: list it in `android.blockedPermissions` when the app doesn't need it.
103
+ - Android foreground services declare their type and its `FOREGROUND_SERVICE_<TYPE>` permission (the library's config plugin usually does), and each type is declared in Play Console.
104
+
49
105
  ## TypeScript
50
106
 
51
107
  - Keep the checks `tsconfig.json` has. Don't loosen them, or get past one with `any`, `@ts-ignore` or a non-null `!`.
@@ -0,0 +1,61 @@
1
+ // The app's error boundary. index.js registers withErrorBoundary(App), so a render error anywhere in the app shows this
2
+ // screen, with a way to try again, instead of a blank screen or a closed app. Once the app has a crash reporter, report
3
+ // the error in componentDidCatch (or use the reporter's own boundary).
4
+ import React from 'react';
5
+ import { Pressable, StyleSheet, Text, useColorScheme, View } from 'react-native';
6
+
7
+ type Props = { children: React.ReactNode };
8
+ type State = { error: Error | null };
9
+
10
+ export class ErrorBoundary extends React.Component<Props, State> {
11
+ override state: State = { error: null };
12
+
13
+ static getDerivedStateFromError(error: Error): State {
14
+ return { error };
15
+ }
16
+
17
+ override componentDidCatch(error: Error, info: React.ErrorInfo) {
18
+ console.error(error, info.componentStack);
19
+ }
20
+
21
+ override render() {
22
+ if (!this.state.error) return this.props.children;
23
+ return <Fallback error={this.state.error} retry={() => this.setState({ error: null })} />;
24
+ }
25
+ }
26
+
27
+ function Fallback({ error, retry }: { error: Error; retry: () => void }) {
28
+ const dark = useColorScheme() === 'dark';
29
+ return (
30
+ <View style={[styles.screen, dark && styles.screenDark]} accessibilityLiveRegion="assertive">
31
+ <Text style={[styles.title, dark && styles.textDark]} accessibilityRole="header">
32
+ Something went wrong
33
+ </Text>
34
+ {__DEV__ ? <Text style={[styles.detail, dark && styles.textDark]}>{error.message}</Text> : null}
35
+ <Pressable onPress={retry} style={styles.button} accessibilityRole="button" accessibilityLabel="Try again" testID="error-try-again">
36
+ <Text style={styles.buttonText}>Try again</Text>
37
+ </Pressable>
38
+ </View>
39
+ );
40
+ }
41
+
42
+ // the app's root component inside the boundary
43
+ export function withErrorBoundary<P extends object>(Component: React.ComponentType<P>) {
44
+ return function WithErrorBoundary(props: P) {
45
+ return (
46
+ <ErrorBoundary>
47
+ <Component {...props} />
48
+ </ErrorBoundary>
49
+ );
50
+ };
51
+ }
52
+
53
+ const styles = StyleSheet.create({
54
+ screen: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24, gap: 16, backgroundColor: '#fff' },
55
+ screenDark: { backgroundColor: '#000' },
56
+ title: { fontSize: 20, fontWeight: '600', textAlign: 'center', color: '#000' },
57
+ detail: { fontSize: 14, textAlign: 'center', color: '#000' },
58
+ textDark: { color: '#fff' },
59
+ button: { paddingVertical: 12, paddingHorizontal: 24, borderRadius: 8, backgroundColor: '#007AFF' },
60
+ buttonText: { fontSize: 16, fontWeight: '600', color: '#fff' },
61
+ });
@@ -0,0 +1,30 @@
1
+ // The app's error boundary. The root layout exports it, so Expo Router shows it, with a way to try again, when a screen
2
+ // throws while rendering, instead of a blank screen or a closed app. A route can export its own ErrorBoundary for its
3
+ // screens. Once the app has a crash reporter, report the error here.
4
+ import { type ErrorBoundaryProps } from 'expo-router';
5
+ import { Pressable, StyleSheet, Text, useColorScheme, View } from 'react-native';
6
+
7
+ export function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
8
+ const dark = useColorScheme() === 'dark';
9
+ return (
10
+ <View style={[styles.screen, dark && styles.screenDark]} accessibilityLiveRegion="assertive">
11
+ <Text style={[styles.title, dark && styles.textDark]} accessibilityRole="header">
12
+ Something went wrong
13
+ </Text>
14
+ {__DEV__ ? <Text style={[styles.detail, dark && styles.textDark]}>{error.message}</Text> : null}
15
+ <Pressable onPress={retry} style={styles.button} accessibilityRole="button" accessibilityLabel="Try again" testID="error-try-again">
16
+ <Text style={styles.buttonText}>Try again</Text>
17
+ </Pressable>
18
+ </View>
19
+ );
20
+ }
21
+
22
+ const styles = StyleSheet.create({
23
+ screen: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24, gap: 16, backgroundColor: '#fff' },
24
+ screenDark: { backgroundColor: '#000' },
25
+ title: { fontSize: 20, fontWeight: '600', textAlign: 'center', color: '#000' },
26
+ detail: { fontSize: 14, textAlign: 'center', color: '#000' },
27
+ textDark: { color: '#fff' },
28
+ button: { paddingVertical: 12, paddingHorizontal: 24, borderRadius: 8, backgroundColor: '#007AFF' },
29
+ buttonText: { fontSize: 16, fontWeight: '600', color: '#fff' },
30
+ });
@@ -35,17 +35,18 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
35
35
 
36
36
  ## 3. Design and tasks (then stop for approval)
37
37
 
38
- 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/amk/structure.md` and `docs/amk/conventions.md`.
39
- 2. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
40
- 3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each). Each task names the requirement it serves and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with one step and screenshot per scenario, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short.
41
- 4. Show design and tasks and **stop until the user approves them**. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
38
+ 1. **Ask for the UI/UX level first, when the feature has screens.** As one question, ask which level its screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends; it takes longer). `specs/_templates/design.md` describes each. Offer as the default the level a prototype settled (under `## Decisions` in `requirements.md`), otherwise the one the app's other screens have (an earlier spec's `design.md`), otherwise Simple. Don't design until the user has answered. Write the answer and the date under "UI/UX level" in `design.md` (n/a for a feature without screens).
39
+ 2. **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/amk/structure.md` and `docs/amk/conventions.md`.
40
+ 3. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
41
+ 4. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each). Each task names the requirement it serves and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with a `# Scenario <n>: <name>` comment above each scenario's steps, an assertion for its THEN and a screenshot, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short.
42
+ 5. Show design and tasks and **stop until the user approves them**. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
42
43
 
43
44
  From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
44
45
 
45
46
  ## 4. Build, one task at a time
46
47
 
47
48
  For each task:
48
- 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
49
+ 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the UI/UX level in `design.md`, and to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
49
50
  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.
50
51
  3. Commit with a clear message ending in `Spec: specs/<id>`.
51
52
  4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
@@ -16,9 +16,10 @@ A prototype answers questions before the real build: what the client wants, how
16
16
 
17
17
  1. Read the requirement, `docs/amk/product.md`, `structure.md` and `conventions.md`, the living spec for the area in `specs/current/`, and the screens around where this would live: their components, theme and navigation.
18
18
  2. Ask who the demo is for (the client or the team) and what it must show, one question at a time.
19
- 3. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
20
- 4. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way.
21
- 5. Decide which case this is:
19
+ 3. Ask which UI/UX level the screens should have: Simple (clean, minimal and functional; the default), Mixed (simple, with modern touches) or Premium (polished, following current design trends). `specs/_templates/design.md` describes each; offer the level the app's other screens have, if an earlier spec's `design.md` records one. The concepts and the prototype are made at that level. Don't start them until the user has answered.
20
+ 4. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
21
+ 5. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way, starting with the UI/UX level and the date.
22
+ 6. Decide which case this is:
22
23
  - **What to show is clear** (the screens and the flow are known): go to step 3.
23
24
  - **How it should work or look is still open:** go to step 2.
24
25