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.
- package/README.md +3 -1
- package/lib/doctor.js +12 -7
- package/lib/init.js +60 -20
- package/package.json +1 -1
- package/stacks/react-native/expo/AGENTS.md +13 -13
- package/stacks/react-native/expo/docs/{ai → amk}/expo.md +1 -1
- package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +4 -4
- package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
- package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -2
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +5 -5
- package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +5 -5
- package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +60 -0
- package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -2
- package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -5
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +1 -1
- package/stacks/react-native/template/.githooks/pre-commit +5 -5
- package/stacks/react-native/template/.githooks/pre-push +3 -3
- package/stacks/react-native/template/.github/workflows/ci.yml +5 -5
- package/stacks/react-native/template/.github/workflows/e2e.yml +5 -5
- package/stacks/react-native/template/.github/workflows/ios.yml +4 -4
- package/stacks/react-native/template/.rulesync/hooks.jsonc +2 -2
- package/stacks/react-native/template/AGENTS.md +15 -15
- package/stacks/react-native/template/codemagic.yaml +6 -6
- package/stacks/react-native/template/docs/{ai → amk}/codemagic.md +1 -1
- package/stacks/react-native/template/docs/{ai → amk}/known-issues.md +2 -2
- package/stacks/react-native/template/docs/{ai → amk}/react-native.md +1 -1
- package/stacks/react-native/template/docs/{ai → amk}/team-process.md +2 -2
- package/stacks/react-native/template/scripts/{ai → amk}/baseline.js +7 -6
- package/stacks/react-native/template/scripts/{ai → amk}/guard.js +1 -1
- package/stacks/react-native/template/scripts/{ai → amk}/handoff-check.js +1 -1
- package/stacks/react-native/template/scripts/{ai → amk}/ios-build.sh +1 -1
- package/stacks/react-native/template/scripts/{ai → amk}/pm-run.sh +1 -1
- package/stacks/react-native/template/scripts/{ai → amk}/pod-install.sh +1 -1
- package/stacks/react-native/template/scripts/{ai → amk}/prebuild.sh +1 -1
- package/stacks/react-native/template/scripts/{ai → amk}/release-build.sh +10 -10
- package/stacks/react-native/template/scripts/{ai → amk}/release-check.js +3 -3
- package/stacks/react-native/template/scripts/{ai → amk}/set-version.sh +2 -2
- package/stacks/react-native/template/scripts/{ai → amk}/specs.js +3 -3
- package/stacks/react-native/template/scripts/{ai → amk}/verify.sh +13 -13
- package/stacks/react-native/template/specs/current/README.md +2 -2
- /package/stacks/react-native/expo/docs/{ai → amk}/known-issues.md +0 -0
- /package/stacks/react-native/template/docs/{ai → amk}/conventions.md +0 -0
- /package/stacks/react-native/template/docs/{ai → amk}/decisions.md +0 -0
- /package/stacks/react-native/template/docs/{ai → amk}/product.md +0 -0
- /package/stacks/react-native/template/docs/{ai → amk}/structure.md +0 -0
- /package/stacks/react-native/template/docs/{ai → amk}/tech.md +0 -0
- /package/stacks/react-native/template/scripts/{ai → amk}/android-flavors.js +0 -0
- /package/stacks/react-native/template/scripts/{ai → amk}/case-check.js +0 -0
- /package/stacks/react-native/template/scripts/{ai → amk}/install-deps.sh +0 -0
- /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.
|
|
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/
|
|
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/
|
|
64
|
-
const r = spawnSync(process.execPath, ['scripts/
|
|
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,
|
|
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(
|
|
95
|
-
: ok(
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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', '.
|
|
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; .
|
|
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
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
670
|
-
|
|
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
|
|
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.
|
|
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/
|
|
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.
|
|
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/
|
|
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}},
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
23
|
-
| Specs: progress, format check, fold a finished feature into the living spec | `node scripts/
|
|
24
|
-
| Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/
|
|
25
|
-
| Signed release builds (a person runs them: they use the signing keys) | `sh scripts/
|
|
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/
|
|
31
|
-
2. UI changes were checked with `sh scripts/
|
|
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/
|
|
47
|
-
- Follow `docs/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
25
|
-
9. **Commit** with a message
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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 `
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
17
|
-
2. A known error: add the error text, cause, fix and prevention to `docs/
|
|
18
|
-
3. Project knowledge: one line in the right `docs/
|
|
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)
|
|
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/
|
|
13
|
-
3. **Commit the work in progress** on the feature branch (never `main`): message `wip: <id> <short summary>`, ending with `
|
|
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/
|
|
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/
|
|
28
|
-
7. **Release PR:** commit as `chore(release): <version
|
|
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/
|
|
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/
|
|
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/
|
|
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)?
|