agentic-mobile-kit 0.6.2 → 0.7.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 (50) hide show
  1. package/README.md +3 -1
  2. package/lib/doctor.js +12 -7
  3. package/lib/init.js +60 -20
  4. package/package.json +1 -1
  5. package/stacks/react-native/expo/AGENTS.md +13 -13
  6. package/stacks/react-native/expo/docs/{ai → amk}/expo.md +1 -1
  7. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +4 -4
  8. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
  9. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -2
  10. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +5 -5
  11. package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +5 -5
  12. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +60 -0
  13. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -2
  14. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -5
  15. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +1 -1
  16. package/stacks/react-native/template/.githooks/pre-commit +5 -5
  17. package/stacks/react-native/template/.githooks/pre-push +3 -3
  18. package/stacks/react-native/template/.github/workflows/ci.yml +5 -5
  19. package/stacks/react-native/template/.github/workflows/e2e.yml +5 -5
  20. package/stacks/react-native/template/.github/workflows/ios.yml +4 -4
  21. package/stacks/react-native/template/.rulesync/hooks.jsonc +2 -2
  22. package/stacks/react-native/template/AGENTS.md +15 -15
  23. package/stacks/react-native/template/codemagic.yaml +6 -6
  24. package/stacks/react-native/template/docs/{ai → amk}/codemagic.md +1 -1
  25. package/stacks/react-native/template/docs/{ai → amk}/known-issues.md +2 -2
  26. package/stacks/react-native/template/docs/{ai → amk}/react-native.md +1 -1
  27. package/stacks/react-native/template/docs/{ai → amk}/team-process.md +2 -2
  28. package/stacks/react-native/template/scripts/{ai → amk}/baseline.js +7 -6
  29. package/stacks/react-native/template/scripts/{ai → amk}/guard.js +1 -1
  30. package/stacks/react-native/template/scripts/{ai → amk}/handoff-check.js +1 -1
  31. package/stacks/react-native/template/scripts/{ai → amk}/ios-build.sh +1 -1
  32. package/stacks/react-native/template/scripts/{ai → amk}/pm-run.sh +1 -1
  33. package/stacks/react-native/template/scripts/{ai → amk}/pod-install.sh +1 -1
  34. package/stacks/react-native/template/scripts/{ai → amk}/prebuild.sh +1 -1
  35. package/stacks/react-native/template/scripts/{ai → amk}/release-build.sh +10 -10
  36. package/stacks/react-native/template/scripts/{ai → amk}/release-check.js +3 -3
  37. package/stacks/react-native/template/scripts/{ai → amk}/set-version.sh +2 -2
  38. package/stacks/react-native/template/scripts/{ai → amk}/specs.js +3 -3
  39. package/stacks/react-native/template/scripts/{ai → amk}/verify.sh +13 -13
  40. package/stacks/react-native/template/specs/current/README.md +2 -2
  41. /package/stacks/react-native/expo/docs/{ai → amk}/known-issues.md +0 -0
  42. /package/stacks/react-native/template/docs/{ai → amk}/conventions.md +0 -0
  43. /package/stacks/react-native/template/docs/{ai → amk}/decisions.md +0 -0
  44. /package/stacks/react-native/template/docs/{ai → amk}/product.md +0 -0
  45. /package/stacks/react-native/template/docs/{ai → amk}/structure.md +0 -0
  46. /package/stacks/react-native/template/docs/{ai → amk}/tech.md +0 -0
  47. /package/stacks/react-native/template/scripts/{ai → amk}/android-flavors.js +0 -0
  48. /package/stacks/react-native/template/scripts/{ai → amk}/case-check.js +0 -0
  49. /package/stacks/react-native/template/scripts/{ai → amk}/install-deps.sh +0 -0
  50. /package/stacks/react-native/template/scripts/{ai → amk}/maestro-env.sh +0 -0
package/README.md CHANGED
@@ -16,7 +16,7 @@ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, O
16
16
 
17
17
  2. Run it again and choose **Check this project and machine**. It lists each problem with its fix.
18
18
 
19
- 3. Fill in `docs/ai/product.md`, `tech.md`, `structure.md` and `conventions.md`, then commit and open a PR.
19
+ 3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md` and `conventions.md`, asks what the code can't show, and writes them once you approve. Then commit and open a PR.
20
20
 
21
21
  Each choice prints the command it runs, for scripts and CI: `init` (with `--ci github`, `--ci codemagic` or `--tools claude,codex,antigravity`), `sync`, `doctor` and `uninstall`. `--help` lists every option.
22
22
 
@@ -26,6 +26,7 @@ Each choice prints the command it runs, for scripts and CI: `init` (with `--ci g
26
26
 
27
27
  | You want to | Run | What happens |
28
28
  |---|---|---|
29
+ | Describe the app for agents | `m-onboard` | Reads the whole project, drafts the product, tech, structure and conventions files in `docs/amk/`, asks what the code can't show, and writes them once you approve. Run it after installing, and again after big changes. |
29
30
  | 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. |
30
31
  | 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 |
31
32
  | Fix a bug | `m-bugfix` | Reproduces the bug, proves it with a failing test, finds the root cause, then makes the smallest fix |
@@ -58,6 +59,7 @@ Both need a clean working tree and leave the result for you to review with `git
58
59
  - **Report:** `sync` lists what it updated, added, removed and merged.
59
60
  - **Your docs:** the product, tech, structure and conventions files your team filled in are never changed.
60
61
  - **Adding CI later:** `sync --ci github` or `--ci codemagic` does it.
62
+ - **From 0.6 or earlier:** the update moves the kit's files from `docs/ai/` and `scripts/ai/` to `docs/amk/` and `scripts/amk/`, with your edits. Your own files in the old folders stay where they are, and it lists any of your files that still use the old paths.
61
63
 
62
64
  ## Requirements
63
65
 
package/lib/doctor.js CHANGED
@@ -33,12 +33,16 @@ function projectChecks(cwd, opts) {
33
33
  return out; // the rest needs the kit
34
34
  }
35
35
  out.push(ok('Kit installed'));
36
+ // installs from before 0.7.0, until sync moves them
37
+ if (fs.existsSync(path.join(cwd, 'scripts/ai/verify.sh')) && !fs.existsSync(path.join(cwd, 'scripts/amk'))) {
38
+ out.push(warn('The kit\'s folders have their old names (docs/ai, scripts/ai)', 'update the kit: run npx agentic-mobile-kit and choose Update'));
39
+ }
36
40
 
37
41
  const lines = agents.split('\n').length;
38
42
  const bytes = Buffer.byteLength(agents);
39
43
  out.push(lines <= 150 && bytes <= 8192
40
44
  ? ok('AGENTS.md size', `${lines} lines`)
41
- : warn(`AGENTS.md is ${lines} lines / ${bytes} bytes`, 'keep it under 150 lines and 8 KB; tools truncate or ignore long files. Move details to docs/ai/'));
45
+ : warn(`AGENTS.md is ${lines} lines / ${bytes} bytes`, 'keep it under 150 lines and 8 KB; tools truncate or ignore long files. Move details to docs/amk/'));
42
46
 
43
47
  let pkg = {};
44
48
  try { pkg = JSON.parse(read(cwd, 'package.json') || '{}'); } catch {}
@@ -60,8 +64,8 @@ function projectChecks(cwd, opts) {
60
64
  : fail(`${manager.name} isn't set up on this clone, so no git hooks run`, 'run your package manager\'s install'));
61
65
  }
62
66
 
63
- if (fs.existsSync(path.join(cwd, 'scripts/ai/case-check.js'))) {
64
- const r = spawnSync(process.execPath, ['scripts/ai/case-check.js'], { cwd, encoding: 'utf8' });
67
+ if (fs.existsSync(path.join(cwd, 'scripts/amk/case-check.js'))) {
68
+ const r = spawnSync(process.execPath, ['scripts/amk/case-check.js'], { cwd, encoding: 'utf8' });
65
69
  const lines = (r.stderr || '').trim().split('\n');
66
70
  out.push(r.status === 0 ? ok('File names match git') : fail(`Renamed only in letter case, and git missed it:${lines.slice(1, -1).join(',')}`, lines.pop()));
67
71
  }
@@ -86,13 +90,14 @@ function projectChecks(cwd, opts) {
86
90
  : warn('Tool configs out of date with .rulesync/', `run: npx -y ${RULESYNC} generate, then commit`));
87
91
  }
88
92
 
93
+ const docs = fs.existsSync(path.join(cwd, 'docs/amk')) ? 'docs/amk' : 'docs/ai';
89
94
  const unfilled = ['product', 'tech', 'structure', 'conventions'].filter(n => {
90
- const t = read(cwd, `docs/ai/${n}.md`);
95
+ const t = read(cwd, `${docs}/${n}.md`);
91
96
  return t !== null && t.replace(/<!--[\s\S]*?-->/g, '').replace(/^#.*$/gm, '').trim() === '';
92
97
  });
93
98
  out.push(unfilled.length
94
- ? warn(`docs/ai not filled in: ${unfilled.join(', ')}`, 'describe the app there; agents build better with it')
95
- : ok('docs/ai filled in'));
99
+ ? warn(`${docs} not filled in: ${unfilled.join(', ')}`, 'run the m-onboard skill in your AI tool: it drafts them from the code')
100
+ : ok(`${docs} filled in`));
96
101
  return out;
97
102
  }
98
103
 
@@ -103,7 +108,7 @@ function machineChecks(cwd) {
103
108
 
104
109
  const pm = fs.existsSync(path.join(cwd, 'yarn.lock')) ? 'yarn' : fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
105
110
  out.push(run(pm, ['--version'], { cwd }) ? ok(`Package manager (${pm})`) : fail(`${pm} not found`, pm === 'npm' ? 'install Node' : 'run: corepack enable'));
106
- out.push(fs.existsSync(path.join(cwd, 'node_modules')) ? ok('Dependencies installed') : fail('Dependencies not installed', 'run: sh scripts/ai/install-deps.sh'));
111
+ out.push(fs.existsSync(path.join(cwd, 'node_modules')) ? ok('Dependencies installed') : fail('Dependencies not installed', 'run: sh scripts/amk/install-deps.sh'));
107
112
 
108
113
  // iOS (macOS only)
109
114
  if (process.platform === 'darwin') {
package/lib/init.js CHANGED
@@ -14,17 +14,23 @@ const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
14
14
  // files with {{PLACEHOLDERS}} filled in from the project
15
15
  const FILLED = ['AGENTS.md', 'codemagic.yaml'];
16
16
  // docs each team rewrites for its app: sync replaces them only while they're untouched, and never merges into them
17
- const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/ai/${n}.md`);
17
+ const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/amk/${n}.md`);
18
18
  const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
19
19
  // the app's own ESLint skips the kit's scripts: they follow the kit's style, not each app's rules
20
- const ESLINT_IGNORE = 'scripts/ai/';
20
+ const ESLINT_IGNORE = 'scripts/amk/';
21
21
  const ESLINT_NOTE = "# agentic-mobile-kit: its scripts follow the kit's style, not this app's lint rules";
22
22
  // optional parts, installed only when a project chooses them with --ci: not every app uses CI
23
23
  const CI = {
24
24
  github: rel => rel.startsWith('.github/'),
25
- codemagic: rel => rel === 'codemagic.yaml' || rel === 'docs/ai/codemagic.md',
25
+ codemagic: rel => rel === 'codemagic.yaml' || rel === 'docs/amk/codemagic.md',
26
26
  };
27
27
  const ciGroup = rel => Object.keys(CI).find(g => CI[g](rel));
28
+ // 0.7.0 renamed the kit's folders from "ai", which apps may already use for their own AI features
29
+ const RENAMED = [['docs/ai/', 'docs/amk/'], ['scripts/ai/', 'scripts/amk/']];
30
+ const renamedPath = rel => {
31
+ const r = RENAMED.find(([from]) => rel.startsWith(from));
32
+ return r ? r[1] + rel.slice(r[0].length) : rel;
33
+ };
28
34
 
29
35
  // tool name -> rulesync targets
30
36
  const TOOLS = {
@@ -109,7 +115,7 @@ function detectStack(cwd, deps) {
109
115
  }
110
116
 
111
117
  // a stack's files, rel -> source: the template, and for Expo the overlay next to it, which replaces or adds files
112
- const EXPO_LEAVES_OUT = ['docs/ai/react-native.md', '.agents/skills/upgrading-react-native/'];
118
+ const EXPO_LEAVES_OUT = ['docs/amk/react-native.md', '.agents/skills/upgrading-react-native/'];
113
119
  function stackFiles(template, stack) {
114
120
  const files = new Map(templateFiles(template).map(rel => [rel, path.join(template, rel)]));
115
121
  if (stack !== 'expo') return files;
@@ -157,8 +163,14 @@ function architecture(cwd, rnVersion) {
157
163
  return (flag ? flag === 'true' : minor >= 76) ? 'New Architecture' : 'Old Architecture: newArchEnabled=false';
158
164
  }
159
165
 
166
+ // TypeScript files, not just the typescript package: the React Native template installs it in JavaScript apps too
167
+ const usesTs = cwd => git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
168
+
160
169
  function projectValues(cwd, pkg, deps, pm, ci, stack) {
161
170
  const rn = installedVersion(cwd, 'react-native', deps['react-native']);
171
+ const ts = usesTs(cwd);
172
+ // the checks agents can run: the app's own scripts, and the typecheck script init adds to TypeScript apps
173
+ const checks = ['lint', 'typecheck', 'test'].filter(s => (pkg.scripts || {})[s] || (s === 'typecheck' && ts && deps.typescript));
162
174
  return {
163
175
  KIT_VERSION,
164
176
  KIT_CI: ci.join(',') || 'none',
@@ -169,6 +181,9 @@ function projectValues(cwd, pkg, deps, pm, ci, stack) {
169
181
  RN_ARCH: architecture(cwd, rn),
170
182
  REACT_VERSION: installedVersion(cwd, 'react', deps.react),
171
183
  TS_VERSION: installedVersion(cwd, 'typescript', deps.typescript),
184
+ LANGUAGE: ts ? `TypeScript${deps.typescript ? ` ${installedVersion(cwd, 'typescript', deps.typescript)}` : ''}` : 'JavaScript',
185
+ CHECK_TASKS: checks.length ? checks.join(', ').replace(/^./, c => c.toUpperCase()) : 'Lint, typecheck, test',
186
+ CHECK_COMMANDS: checks.map(s => `\`${pm.run} ${s}\``).join(', ') || 'none in `package.json` yet',
172
187
  NODE_VERSION: (pkg.engines && pkg.engines.node) || `${process.versions.node.split('.')[0]}`,
173
188
  PM: pm.name,
174
189
  PM_RUN: pm.run,
@@ -434,10 +449,10 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
434
449
  const gi = path.join(cwd, '.gitignore');
435
450
  const giText = readIf(gi) || '';
436
451
  // Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
437
- const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.ai/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
452
+ const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
438
453
  const missing = ignored.filter(l => !giText.split('\n').includes(l));
439
454
  if (missing.length) {
440
- fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .ai/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
455
+ 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`);
441
456
  done.merged.push('.gitignore');
442
457
  }
443
458
 
@@ -454,18 +469,20 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
454
469
  // the kit's scripts pass React Native's default rules, but stricter configs such as Airbnb's flag them)
455
470
  const eslintrc = fs.readdirSync(cwd).some(f => /^\.eslintrc(\.\w+)?$/.test(f)) || Boolean(pkg.eslintConfig);
456
471
  const ei = path.join(cwd, '.eslintignore');
457
- const eiText = readIf(ei) || '';
458
- if (eslintrc && !eiText.split('\n').includes(ESLINT_IGNORE)) {
459
- fs.writeFileSync(ei, `${eiText.replace(/\n*$/, eiText ? '\n' : '')}${eiText ? '\n' : ''}${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`);
460
- (eiText ? done.merged : done.created).push('.eslintignore');
472
+ const eiOld = readIf(ei) || '';
473
+ // before 0.7.0 the kit's line named scripts/ai/
474
+ let eiText = eiOld.replace(`${ESLINT_NOTE}\nscripts/ai/\n`, `${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`);
475
+ if (eslintrc && !eiText.split('\n').includes(ESLINT_IGNORE)) eiText = `${eiText.replace(/\n*$/, eiText ? '\n' : '')}${eiText ? '\n' : ''}${ESLINT_NOTE}\n${ESLINT_IGNORE}\n`;
476
+ if (eiText !== eiOld) {
477
+ fs.writeFileSync(ei, eiText);
478
+ (eiOld ? done.merged : done.created).push('.eslintignore');
461
479
  }
462
480
 
463
481
  // 4. package.json scripts: typecheck, and hooks path on install (never overwrite existing scripts)
464
482
  const scripts = (pkg.scripts = pkg.scripts || {});
465
483
  let pkgChanged = false;
466
484
  // only TypeScript projects get typecheck: tsc fails ("no inputs") in JavaScript apps that merely have typescript installed
467
- const hasTs = git(cwd, 'ls-files', '*.ts', '*.tsx').split('\n').some(f => f && !f.endsWith('.d.ts'));
468
- if (!scripts.typecheck && deps.typescript && hasTs) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
485
+ if (!scripts.typecheck && deps.typescript && usesTs(cwd)) { scripts.typecheck = 'tsc --noEmit'; pkgChanged = true; }
469
486
  const manager = hookManager(cwd, pkg);
470
487
  if (manager) {
471
488
  // the project's hook manager runs the kit's hooks; drop the postinstall earlier kit versions added, which fought it
@@ -553,9 +570,26 @@ function sync(cwd, opts = {}) {
553
570
  const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci, stack);
554
571
  const tools = installedTools(cwd);
555
572
  const targets = tools.flatMap(t => TOOLS[t]);
556
- const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
573
+ const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
557
574
  const newFiles = stackFiles(opts.template || TEMPLATE, stack);
558
- const oldFiles = stackFiles(oldDir, stack);
575
+ // an install from before 0.7.0: the kit's files move to the new folders first, so the team's edits come along.
576
+ // Other files in the old folders may be the app's own, so they stay where they are.
577
+ const oldKit = stackFiles(oldDir, stack);
578
+ const moved = [...oldKit.keys()].filter(rel => renamedPath(rel) !== rel
579
+ && fs.existsSync(path.join(cwd, rel)) && !fs.existsSync(path.join(cwd, renamedPath(rel))));
580
+ for (const rel of moved) {
581
+ fs.mkdirSync(path.dirname(path.join(cwd, renamedPath(rel))), { recursive: true });
582
+ fs.renameSync(path.join(cwd, rel), path.join(cwd, renamedPath(rel)));
583
+ }
584
+ for (const [from, to] of RENAMED) {
585
+ const n = moved.filter(rel => rel.startsWith(from)).length;
586
+ if (!n) continue;
587
+ report.moved.push(`${from} to ${to} (${n} files)`);
588
+ const left = templateFiles(path.join(cwd, from));
589
+ if (left.length) report.kept.push(`${left.map(f => from + f).join(', ')} (not the kit's; its files moved to ${to})`);
590
+ else fs.rmSync(path.join(cwd, from), { recursive: true, force: true });
591
+ }
592
+ const oldFiles = new Map([...oldKit].map(([rel, src]) => [renamedPath(rel), src]));
559
593
 
560
594
  for (const [rel, src] of newFiles) {
561
595
  if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
@@ -592,6 +626,10 @@ function sync(cwd, opts = {}) {
592
626
  const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, files: newFiles, stack, skipGenerate: opts.skipGenerate });
593
627
  report.added.push(...done.created);
594
628
  report.updated.push(...done.merged);
629
+ // the team's own files that still name a moved file: scripts in package.json, other CI, their docs
630
+ let stale = '';
631
+ try { if (moved.length) stale = git(cwd, 'grep', '-l', '--untracked', '-F', ...moved.flatMap(rel => ['-e', rel])); } catch {}
632
+ if (stale) done.warnings.push(`still pointing to the kit's old folders: ${stale.split('\n').join(', ')}. Change docs/ai/ to docs/amk/ and scripts/ai/ to scripts/amk/ there.`);
595
633
  // it started from a clean working tree, so git shows everything it changed (tool configs too)
596
634
  const changed = git(cwd, 'status', '--porcelain') !== '';
597
635
  return { report, warnings: done.warnings, from, to: KIT_VERSION, tools, changed, generated, generateError };
@@ -666,13 +704,15 @@ function uninstall(cwd, opts = {}) {
666
704
 
667
705
  // .eslintignore: the kit's lines, and the file if nothing else is in it
668
706
  const eiText = readIf(path.join(cwd, '.eslintignore'));
669
- if (eiText !== null && eiText.split('\n').includes(ESLINT_IGNORE)) {
670
- const rest = eiText.split('\n').filter(l => l !== ESLINT_IGNORE && l !== ESLINT_NOTE).join('\n').replace(/\n{3,}/g, '\n\n');
707
+ // installs from before 0.7.0 have scripts/ai/ under the kit's note
708
+ const ours = l => l === ESLINT_NOTE || l === ESLINT_IGNORE || (l === 'scripts/ai/' && eiText.includes(ESLINT_NOTE));
709
+ if (eiText !== null && eiText.split('\n').some(l => l !== ESLINT_NOTE && ours(l))) {
710
+ const rest = eiText.split('\n').filter(l => !ours(l)).join('\n').replace(/\n{3,}/g, '\n\n');
671
711
  if (!rest.trim()) fs.unlinkSync(path.join(cwd, '.eslintignore')); else fs.writeFileSync(path.join(cwd, '.eslintignore'), rest.replace(/\n*$/, '\n'));
672
712
  report.removed.push('.eslintignore (the kit\'s lines)');
673
713
  }
674
714
 
675
- report.left.push('.gitignore lines for .env files and .ai/ (they keep secrets and local evidence out of git)');
715
+ report.left.push('the kit\'s .gitignore lines (they keep .env files and local evidence out of git)');
676
716
  if (scripts.typecheck === 'tsc --noEmit') report.left.push('the "typecheck" script in package.json');
677
717
  return { report, from };
678
718
  }
@@ -687,11 +727,11 @@ function printSummary({ report, warnings = [], values, tools, ci, generated, gen
687
727
  for (const w of warnings) log(` ! ${w}`);
688
728
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
689
729
  log('\nNext steps:');
690
- log(' 1. Fill in docs/ai/product.md, tech.md, structure.md and conventions.md for this app.');
730
+ log(' 1. In your AI tool, run m-onboard (/m-onboard, or $m-onboard in Codex). It drafts docs/amk/product.md, tech.md,\n structure.md and conventions.md from the code, asks what the code can\'t show, and writes them once you approve.');
691
731
  log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
692
732
  const more = [
693
733
  ci.includes('github') && 'Turn on branch protection for main: see docs/branch-protection.md in the kit repo.',
694
- ci.includes('codemagic') && 'Signed store builds on Codemagic: one-time setup in docs/ai/codemagic.md.',
734
+ ci.includes('codemagic') && 'Signed store builds on Codemagic: one-time setup in docs/amk/codemagic.md.',
695
735
  tools.includes('codex') && 'Codex users: open the project in Codex once and approve its hooks (they stay off until approved).',
696
736
  ].filter(Boolean);
697
737
  more.forEach((m, i) => log(` ${i + 3}. ${m}`));
@@ -700,7 +740,7 @@ function printSummary({ report, warnings = [], values, tools, ci, generated, gen
700
740
  function printSync({ report, warnings = [], from, to, changed, generated, generateError }, log = console.log) {
701
741
  log(from === to ? `agentic-mobile-kit is already ${to}.` : `agentic-mobile-kit updated from ${from} to ${to}.`);
702
742
  const lines = [
703
- ['updated', report.updated], ['added', report.added], ['removed', report.removed],
743
+ ['moved to the new folders', report.moved || []], ['updated', report.updated], ['added', report.added], ['removed', report.removed],
704
744
  ['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts], ['left alone', report.kept],
705
745
  ];
706
746
  for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.6.2",
3
+ "version": "0.7.0",
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",
@@ -1,34 +1,34 @@
1
1
  <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} stack={{KIT_STACK}} (edit outside these markers; the kit updates what's inside) -->
2
2
  # {{APP_NAME}}: instructions for AI agents
3
3
 
4
- Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.
4
+ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/amk/`.
5
5
 
6
6
  This project may also use other AI workflow frameworks (for example Superpowers, BMAD or proAgents). They keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
7
7
 
8
8
  ## Project
9
9
 
10
- - Expo SDK {{EXPO_SDK}}, React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
10
+ - Expo SDK {{EXPO_SDK}}, React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, {{LANGUAGE}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
11
11
  - `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git (Continuous Native Generation). The kit's scripts generate them when they need them.
12
- - What the app does: `docs/ai/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/ai/tech.md`. Folders and layers: `docs/ai/structure.md`. Code style: `docs/ai/conventions.md`.
12
+ - What the app does: `docs/amk/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/amk/tech.md`. Folders and layers: `docs/amk/structure.md`. Code style: `docs/amk/conventions.md`.
13
13
 
14
14
  ## Commands
15
15
 
16
16
  | Task | Command |
17
17
  |---|---|
18
- | Install dependencies | `sh scripts/ai/install-deps.sh` |
18
+ | Install dependencies | `sh scripts/amk/install-deps.sh` |
19
19
  | Add a library (ask first) | `npx expo install <package>`: the version that matches the SDK |
20
- | Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/ai/pm-run.sh lint`, `sh scripts/ai/pm-run.sh typecheck`, `sh scripts/ai/pm-run.sh test` |
20
+ | 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` |
21
21
  | Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
22
- | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>` |
23
- | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/ai/specs.js status`, `node scripts/ai/specs.js check`, `node scripts/ai/specs.js merge <id>` |
24
- | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/ai/release-check.js` |
25
- | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/ai/release-build.sh android`, `sh scripts/ai/release-build.sh ios` |
22
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>` |
23
+ | 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>` |
24
+ | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/amk/release-check.js` |
25
+ | 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` |
26
26
 
27
27
  ## Definition of done
28
28
 
29
29
  A task is done only when:
30
- 1. `sh scripts/ai/verify.sh quick` passes (lint, typecheck, tests) and you show its output from this session. In an app whose base branch already fails some of them, it passes when your change adds no new failure, and lists the old ones: leave those alone unless the task is to fix them;
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;
30
+ 1. `sh scripts/amk/verify.sh quick` passes (lint, typecheck, tests) and you show its output from this session. In an app whose base branch already fails some of them, it passes when your change adds no new failure, and lists the old ones: leave those alone unless the task is to fix them;
31
+ 2. UI changes were checked with `sh scripts/amk/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
 
@@ -43,8 +43,8 @@ Never say a check passed unless you ran it in this session.
43
43
  - Never read, print or commit `.env` files, keystores or signing files. Secrets don't belong in this repo.
44
44
  - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
45
45
  - After 2 failed attempts at the same fix, stop and report what you found.
46
- - Chat is not memory: write decisions into the spec or `docs/ai/decisions.md` straight away.
47
- - Follow `docs/ai/expo.md`. Before fixing a build error, check `docs/ai/known-issues.md`.
46
+ - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
47
+ - Follow `docs/amk/expo.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
48
48
 
49
49
  ## Skills
50
50
 
@@ -14,7 +14,7 @@ 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/ai/verify.sh` makes release builds with the current native code.
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.
18
18
 
19
19
  ## Architecture
20
20
 
@@ -10,7 +10,7 @@ The user chose this workflow: follow its steps for this task, even where other w
10
10
 
11
11
  Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, task link).
12
12
 
13
- 1. **Check `docs/ai/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
13
+ 1. **Check `docs/amk/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
14
14
  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.
15
15
  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.)
16
16
  4. **Find the root cause before changing code.**
@@ -19,7 +19,7 @@ Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, ta
19
19
  - Form one hypothesis, test it, and confirm or reject it. One at a time.
20
20
  - Fix the cause, not the symptom: no try/catch that hides the error, no special case for the failing input.
21
21
  5. **Make the smallest fix.** Don't refactor or touch unrelated code.
22
- 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.
22
+ 6. **Verify.** The new test passes, and lint, typecheck and all tests pass. Paste the output. For UI or native bugs, run `sh scripts/amk/verify.sh ios` and/or `android` and look at the screenshots.
23
23
  7. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
24
- 8. **Record it.** If this kind of error could come back, add an entry to `docs/ai/known-issues.md` (error, cause, fix, prevention). If the fix changes what the app is meant to do, not just makes it work as specified, update that requirement in `specs/current/<area>.md` in the same format, and run `node scripts/ai/specs.js check`.
25
- 9. **Commit** with a message ending in `Assisted-by: <tool>/<model>`. Ask the user before pushing, then open a PR with the evidence.
24
+ 8. **Record it.** If this kind of error could come back, add an entry to `docs/amk/known-issues.md` (error, cause, fix, prevention). If the fix changes what the app is meant to do, not just makes it work as specified, update that requirement in `specs/current/<area>.md` in the same format, and run `node scripts/amk/specs.js check`.
25
+ 9. **Commit** with a clear message. Ask the user before pushing, then open a PR with the evidence.
@@ -13,7 +13,7 @@ Input: $ARGUMENTS (a spec ID, or empty).
13
13
  1. **Check git first.** Run `git fetch` and `git status`.
14
14
  - If the branch is behind its remote, say so and ask before pulling.
15
15
  - If there are uncommitted changes, list them; they may be half-done work.
16
- 2. **Find the spec.** Use the given ID; otherwise run `node scripts/ai/specs.js status` and take the spec in progress that was updated most recently. If unsure, ask.
16
+ 2. **Find the spec.** Use the given ID; otherwise run `node scripts/amk/specs.js status` and take the spec in progress that was updated most recently. If unsure, ask.
17
17
  3. **Read** `requirements.md`, `design.md`, `tasks.md` and `progress.md` in that spec folder, plus `git log --oneline -15`.
18
18
  4. **Report back, in this order:**
19
19
  1. any open question or blocker from the handoff;
@@ -10,8 +10,8 @@ The user chose this workflow: follow its steps for this task, even where other w
10
10
 
11
11
  Input: $ARGUMENTS (a problem, a question about how something works, or an idea to check).
12
12
 
13
- 1. **Read before answering.** Start with `specs/current/` and `docs/ai/` for the area, then the code itself. Back each claim with the file and line it comes from. Don't guess; say what you couldn't find.
13
+ 1. **Read before answering.** Start with `specs/current/` and `docs/amk/` for the area, then the code itself. Back each claim with the file and line it comes from. Don't guess; say what you couldn't find.
14
14
  2. **Explain what's there today:** the screens, state, API calls and native parts involved, and where iOS and Android differ.
15
15
  3. **When there's a choice, lay out options:** two or three, each with its trade-offs (effort, risk, both platforms, native changes, store review, what it leaves unsolved). Say which one you'd pick and why. Diagrams help when the flow is complicated.
16
- 4. **Change nothing.** Exploring never edits code, config or project files. Write notes only when the user asks: a draft in `specs/<id>/requirements.md` for `m-feature`, or a decision in `docs/ai/decisions.md`.
16
+ 4. **Change nothing.** Exploring never edits code, config or project files. Write notes only when the user asks: a draft in `specs/<id>/requirements.md` for `m-feature`, or a decision in `docs/amk/decisions.md`.
17
17
  5. **Hand off when it's clear.** Suggest the next step: `m-feature <one-line summary>` or `m-bugfix <one-line summary>`, carrying over what you found. If the idea turns out not to be worth doing, say so; learning that cheaply is a good outcome.
@@ -21,7 +21,7 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
21
21
  1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `specs/_templates/` to `specs/<id>/`.
22
22
  2. Read `specs/current/<area>.md` for each area this touches: it says what the app does now. In an area with no living spec yet, read the code that implements it.
23
23
  3. **One intent.** The feature should be one thing you can say in a sentence. If it needs "and also", suggest splitting it into separate features, and ask.
24
- 4. Fill `requirements.md`: the goal; the requirements under `## ADDED`, `## MODIFIED` and `## REMOVED Requirements: <area>` (the format is in `specs/current/README.md`), with one SHALL per requirement and scenarios for the cases that matter; every edge-case line (or "n/a"); out of scope; open questions. Then run `node scripts/ai/specs.js check specs/<id>/requirements.md`.
24
+ 4. Fill `requirements.md`: the goal; the requirements under `## ADDED`, `## MODIFIED` and `## REMOVED Requirements: <area>` (the format is in `specs/current/README.md`), with one SHALL per requirement and scenarios for the cases that matter; every edge-case line (or "n/a"); out of scope; open questions. Then run `node scripts/amk/specs.js check specs/<id>/requirements.md`.
25
25
  5. If something is unclear, ask the user **one question at a time**. Don't fill gaps with guesses.
26
26
  6. Show the requirements and **stop until the user approves them**. Give the user these questions to check them against:
27
27
  - Is this the problem you asked me to solve, with nothing extra in scope?
@@ -30,7 +30,7 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
30
30
 
31
31
  ## 3. Design and tasks (then stop for approval)
32
32
 
33
- 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`.
33
+ 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`.
34
34
  2. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
35
35
  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`.
36
36
  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.
@@ -42,7 +42,7 @@ From here the plan lives in files, so the building can also run in a fresh sessi
42
42
  For each task:
43
43
  1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after.
44
44
  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.
45
- 3. Commit with a clear message ending in `Assisted-by: <tool>/<model>` and `Spec: specs/<id>`.
45
+ 3. Commit with a clear message ending in `Spec: specs/<id>`.
46
46
  4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
47
47
 
48
48
  If building shows the plan is wrong: when the intent is the same, update `requirements.md`, `design.md` or `tasks.md`, tell the user what changed, and ask again before going on if a requirement changed. When the intent itself changed, or the scope grew into different work, stop and suggest finishing this feature small and starting a new one.
@@ -50,12 +50,12 @@ 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>`. 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.
53
+ 1. Run `sh scripts/amk/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 `.amk/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
57
57
 
58
- Run `node scripts/ai/specs.js merge <id>`. It applies the ADDED, MODIFIED and REMOVED requirements to `specs/current/` and notes the source of each. If it refuses, the reason is usually that a requirement listed as ADDED already exists, or one listed as MODIFIED doesn't. Fix `requirements.md` and run it again. Commit `specs/current/` with the feature, so reviewers see the change in behavior.
58
+ Run `node scripts/amk/specs.js merge <id>`. It applies the ADDED, MODIFIED and REMOVED requirements to `specs/current/` and notes the source of each. If it refuses, the reason is usually that a requirement listed as ADDED already exists, or one listed as MODIFIED doesn't. Fix `requirements.md` and run it again. Commit `specs/current/` with the feature, so reviewers see the change in behavior.
59
59
 
60
60
  ## 7. Review and pull request
61
61
 
@@ -11,11 +11,11 @@ The user chose this workflow: follow its steps for this task, even where other w
11
11
  Input: $ARGUMENTS (what went wrong or what the user had to correct; the error text, PR comment or session transcript if there is one).
12
12
 
13
13
  1. **State the lesson in one sentence:** what happened, what should have happened, and why. The usual causes are missing context, an ignored rule, the wrong command, or a gap in the rules. Quote the evidence, and don't guess what an earlier session did. If the cause isn't clear, ask.
14
- 2. **Check whether it's already covered.** Search `AGENTS.md`, `docs/ai/` and `.agents/skills/`. If a rule exists and was ignored, writing it again won't help; enforce it instead (step 3.1).
14
+ 2. **Check whether it's already covered.** Search `AGENTS.md`, `docs/amk/` and `.agents/skills/`. If a rule exists and was ignored, writing it again won't help; enforce it instead (step 3.1).
15
15
  3. **Pick the strongest small fix**, in this order:
16
- 1. A check that runs without anyone remembering it: a lint rule, a test, a git hook, a CI step, a pattern in `scripts/ai/guard.js`, or a rule in `scripts/ai/release-check.js`.
17
- 2. A known error: add the error text, cause, fix and prevention to `docs/ai/known-issues.md`.
18
- 3. Project knowledge: one line in the right `docs/ai/` file. Use `conventions.md`, `react-native.md` or `tech.md`, or `decisions.md` with the date and the reason.
16
+ 1. A check that runs without anyone remembering it: a lint rule, a test, a git hook, a CI step, a pattern in `scripts/amk/guard.js`, or a rule in `scripts/amk/release-check.js`.
17
+ 2. A known error: add the error text, cause, fix and prevention to `docs/amk/known-issues.md`.
18
+ 3. Project knowledge: one line in the right `docs/amk/` file. Use `conventions.md`, `react-native.md` or `tech.md`, or `decisions.md` with the date and the reason.
19
19
  4. A workflow step: edit the skill that should have caught it.
20
20
  5. `AGENTS.md`: only for a rule every task needs, and keep the file under 150 lines.
21
21
 
@@ -25,4 +25,4 @@ Input: $ARGUMENTS (what went wrong or what the user had to correct; the error te
25
25
  - For a check: show it failing on the old mistake and passing on the fixed code.
26
26
  - For docs or a skill: show the diff, and name the task that would have gone differently.
27
27
  6. **This project or every project?** If the lesson applies to any React Native app, say so and draft an issue for the agentic-mobile-kit repo, so every project gets the fix. Ask before opening it.
28
- 7. **Commit** with a message that starts with `chore(learn):` and ends with `Assisted-by: <tool>/<model>`. That prefix keeps it out of the changelog and easy to find with `git log --grep 'chore(learn)'` in the monthly review. Ask before pushing.
28
+ 7. **Commit** with a message that starts with `chore(learn):`. That prefix keeps it out of the changelog and easy to find with `git log --grep 'chore(learn)'` in the monthly review. Ask before pushing.
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: m-onboard
3
+ description: Describe the app for AI agents - read the whole project, draft docs/amk/product.md, tech.md, structure.md and conventions.md, ask only what the code can't show, and write them once the user approves. Run it after installing the kit, and again after big changes. Run only when the user explicitly invokes m-onboard.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-onboard
8
+
9
+ The user chose this workflow: follow its steps for this task, even where other workflow instructions in this project (Superpowers, BMAD, proAgents or similar) say otherwise.
10
+
11
+ Input: $ARGUMENTS (optional: which files to work on, for example `tech structure`; all four by default).
12
+
13
+ Every agent reads these four files before it works on this app, so they must be true, short and specific: facts with the files they come from, not advice. Write only what you found in the project or what the user told you.
14
+
15
+ ## 1. See what's there
16
+
17
+ Read `AGENTS.md` and the four files in `docs/amk/`. A file that holds only its heading and the `<!-- … -->` outline is empty: you'll draft it. A file with content is the team's: you'll suggest changes to it, never rewrite it.
18
+
19
+ ## 2. Read the project
20
+
21
+ Change nothing in this step. List the project's files with `git ls-files` (it leaves out `node_modules`, Pods and build output), then read in this order:
22
+
23
+ - **What the app is:** the README, `package.json` (name, scripts, dependencies), `app.json` or `app.config.*` in Expo apps, the display name and bundle IDs, and store texts if there are any (`fastlane/metadata/`, `release-notes/`).
24
+ - **Screens and journeys:** the entry point (`index.js`, `App.tsx`, or the `app/` folder with Expo Router), the navigation setup and the list of screens. The key user journeys come from these: sign-in, the main flows, payments, settings.
25
+ - **Tech:** for each dependency that matters, what the app uses it for and where it's set up: state, navigation, the API client, storage, forms, i18n, analytics, push, crash reporting, payments, maps. Also the backend APIs and where their contracts live, and the environments: config files, `.env.example`, build flavors and schemes. Never open `.env` files, keystores or signing files.
26
+ - **Structure:** the folder map, two or three levels into the app's code; where shared components, the theme and helpers live; custom native code under `ios/` and `android/` (native modules, extensions, widgets), or config plugins and local modules in Expo apps.
27
+ - **Conventions:** a few files from each layer (a screen, a component, a hook, an API call, a test) and what they have in common: naming, file layout, styling, error, loading and empty states, how tests mock the API. Also the lint and formatter configs, and `git log --oneline -30` for the style of commit messages and branch names. A convention is a pattern you saw in several files; a single file is an example, not a rule.
28
+
29
+ In a large app, sample: a few files per layer are enough. Keep a note of the files each finding comes from.
30
+
31
+ ## 3. Draft
32
+
33
+ Draft each file you're working on from its outline, and keep it short: `product.md` under 40 lines, the others under about 60.
34
+
35
+ - `product.md`: what the app does in two sentences, who uses it, the 3 to 5 key journeys, and what must never break.
36
+ - `tech.md`: what the app uses today, one line each with the library and where it's set up; the backend APIs and their contracts; the environments and how the app switches between them; third-party services. Describe what's there; don't recommend new tools.
37
+ - `structure.md`: the folder map, one line per folder; where shared UI, the theme and helpers live, so agents reuse them instead of writing new ones; custom native code.
38
+ - `conventions.md`: the patterns you found, each with a file that shows it.
39
+
40
+ Use the app's own names for screens, modules and services. Where the project doesn't answer something, write down a question for step 4 instead of guessing.
41
+
42
+ For a file that's already filled in, compare it with what you found and list what's missing, out of date or wrong, with the file that shows it. Leave what's still true alone.
43
+
44
+ ## 4. Ask what the code can't show
45
+
46
+ Ask the user in one message, usually five questions or fewer, about what you couldn't find:
47
+ - who uses the app (customers, staff, a market or age group);
48
+ - what must never break (payments, data sync, sign-in, …);
49
+ - whether the key journeys you found are right and complete;
50
+ - which of two conflicting things is current: two API clients, two styling approaches, two state libraries.
51
+
52
+ ## 5. Show, then write
53
+
54
+ Show the drafts, and the suggested changes for files that are already filled in. **Stop until the user approves them.** Then write only what they approved. A decision the user made in their answers, such as which of two libraries is current, also gets a dated line in `docs/amk/decisions.md`. Change nothing else: no code, no `AGENTS.md`, no other docs.
55
+
56
+ ## 6. Commit
57
+
58
+ On the main branch, suggest a new branch first. Commit the files with a message that starts with `docs(amk):`, which keeps it out of the changelog. Ask before pushing.
59
+
60
+ Suggest running `m-onboard` again after big changes: a new module, a new state or navigation library, a new backend. In a new app that's still close to its template, also suggest settling the stack choices the team hasn't made yet with `m-explore` before the first feature, for example `m-explore which navigation and state libraries should we use`.
@@ -9,8 +9,8 @@ disable-model-invocation: true
9
9
  The user chose this workflow: follow its steps for this task, even where other workflow instructions in this project (Superpowers, BMAD, proAgents or similar) say otherwise.
10
10
 
11
11
  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.
12
- 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.
13
- 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
+ 2. **Move decisions out of the chat.** Anything decided in this conversation goes into `requirements.md`, `design.md` or `docs/amk/decisions.md` now. Chat history doesn't travel to other tools.
13
+ 3. **Commit the work in progress** on the feature branch (never `main`): message `wip: <id> <short summary>`, ending with `Spec: specs/<id>`.
14
14
  - 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.
15
15
  4. **Push the branch**: `git push -u origin <branch>`.
16
16
  5. **Tell the user** the branch name, and that they can continue anywhere with `git pull`, then `m-continue <id>`.
@@ -21,12 +21,12 @@ Input: $ARGUMENTS (the new version such as 1.4.0, or patch, minor or major; whic
21
21
  - `client.md`: for the client or product owner. Cover what's new, what's fixed, what they should test or do, and known issues.
22
22
 
23
23
  Show all three files to the user and wait for their approval.
24
- 5. **Version and build numbers:** `sh scripts/ai/set-version.sh <version>` sets the iOS and Android version names; in Expo apps without native folders, `expo.version` in `app.json`. If the script stops because the project ships several apps, or computes its config in `app.config.*`, ask the user how to set each version, and set them after they confirm.
24
+ 5. **Version and build numbers:** `sh scripts/amk/set-version.sh <version>` sets the iOS and Android version names; in Expo apps without native folders, `expo.version` in `app.json`. If the script stops because the project ships several apps, or computes its config in `app.config.*`, ask the user how to set each version, and set them after they confirm.
25
25
  - When CI, fastlane or EAS sets the build numbers at build time (`release-check.js` in step 6 says so), leave them alone.
26
26
  - Otherwise every store upload needs a higher build number. Ask before changing native files. Then raise Android's `versionCode` in `android/app/build.gradle`, and set iOS with `cd ios && agvtool new-version -all <number>`. Never edit `project.pbxproj` by hand. In Expo apps without native folders, raise `expo.ios.buildNumber` and `expo.android.versionCode` in `app.json` instead. iOS may keep its build number when the version name changes, if that's how the team works.
27
- 6. **Release check:** `node scripts/ai/release-check.js`. Show the output. Fix each ✗, asking first when the fix touches native config. List each ! for the user to decide.
28
- 7. **Release PR:** commit as `chore(release): <version>` (so the next changelog leaves it out), with `Assisted-by: <tool>/<model>`. Ask before pushing. Open a PR titled `Release <version>` with the changelog and the release-check output.
27
+ 6. **Release check:** `node scripts/amk/release-check.js`. Show the output. Fix each ✗, asking first when the fix touches native config. List each ! for the user to decide.
28
+ 7. **Release PR:** commit as `chore(release): <version>`, so the next changelog leaves it out. Ask before pushing. Open a PR titled `Release <version>` with the changelog and the release-check output.
29
29
  8. **Tag and build, after the merge.** Once the PR is merged, ask the user before tagging. Then run `git switch main && git pull && git tag v<version> && git push origin v<version>`.
30
- - With Codemagic (`codemagic.yaml`; see `docs/ai/codemagic.md`), the tag starts the signed builds.
30
+ - With Codemagic (`codemagic.yaml`; see `docs/amk/codemagic.md`), the tag starts the signed builds.
31
31
  - With the team's own release tooling (fastlane lanes in `fastlane/`, `ios/fastlane/` or `android/fastlane/`, EAS builds set up in `eas.json`, or release scripts in `package.json`), the user runs the lane, `eas build` and `eas submit`, or the script that builds and uploads the release, instead of `release-build.sh`. Tell them which one; if it isn't clear, ask.
32
- - Without CI, the user builds signed apps on their Mac, because signing keys stay with people. Tell them to run `sh scripts/ai/release-build.sh android [flavor]` and `sh scripts/ai/release-build.sh ios [scheme]`, and to upload the results from `.ai/release/` (Play Console, and Xcode's Organizer or Transporter). In Expo apps the script generates the native projects first, and iOS signing needs the Apple team in `app.json` (`expo.ios.appleTeamId`). Never run these yourself or ask for the keys.
32
+ - Without CI, the user builds signed apps on their Mac, because signing keys stay with people. Tell them to run `sh scripts/amk/release-build.sh android [flavor]` and `sh scripts/amk/release-build.sh ios [scheme]`, and to upload the results from `.amk/release/` (Play Console, and Xcode's Organizer or Transporter). In Expo apps the script generates the native projects first, and iOS signing needs the Apple team in `app.json` (`expo.ios.appleTeamId`). Never run these yourself or ask for the keys.
@@ -17,7 +17,7 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
17
17
  - **Against the spec**, when there is one:
18
18
  - *Complete:* every task is ticked, every requirement is implemented, and every scenario has evidence (a test or a screenshot).
19
19
  - *Correct:* the code does what each requirement says, edge cases included, and nothing outside the agreed scope.
20
- - *Coherent:* the decisions in `design.md` show up in the code, and `specs/current/` was updated (`node scripts/ai/specs.js merge <id>`) if behavior changed.
20
+ - *Coherent:* the decisions in `design.md` show up in the code, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
21
21
  - **No spec:** does the diff do what was asked, and nothing unrelated?
22
22
  - **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
23
23
  - **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?