agentic-mobile-kit 0.4.0 → 0.5.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 CHANGED
@@ -11,6 +11,7 @@ Run in the app's root, on a clean git working tree:
11
11
  ```sh
12
12
  npx agentic-mobile-kit init
13
13
  npx agentic-mobile-kit init --tools claude,codex,antigravity # choose your AI tools
14
+ npx agentic-mobile-kit init --ci github,codemagic # only if the app uses that CI
14
15
  ```
15
16
 
16
17
  Then check the project and your machine, with a fix for each problem:
@@ -39,8 +40,8 @@ Installs older than 0.4.0 don't record which kit version made them, so their fir
39
40
  - **Context for every AI tool:** `AGENTS.md` (plus a one-line `CLAUDE.md`), `docs/ai/` (product, tech, structure, conventions, decisions, known issues, React Native rules) and spec templates in `specs/_templates/`.
40
41
  - **Workflows:** the skills `m-feature`, `m-bugfix`, `m-continue`, `m-pause`, `m-review`, `m-release` and `m-learn`. Invoke them with `/m-feature` in Claude Code and Antigravity, or `$m-feature` in Codex. Also Callstack's React Native skills.
41
42
  - **Guardrails in each tool:** a guard hook that blocks destructive commands and secret files, a stop hook that asks for a handoff update, permission rules and a read-only `m-reviewer` subagent, generated with rulesync.
42
- - **Releases:** `m-release` writes `CHANGELOG.md` from real commits with git-cliff, plus store and client notes, then runs `scripts/ai/release-check.js`, which catches what store review would reject. A version tag starts signed builds on Codemagic (`codemagic.yaml`, one-time setup in `docs/ai/codemagic.md`).
43
- - **Checks no tool can skip:** git hooks (secrets, signing files, broken Xcode project files, lint, typecheck, tests) and GitHub Actions CI (lint, typecheck, tests, secret scan, PR size, Android and iOS builds).
43
+ - **Releases:** `m-release` writes each release's changelog from real commits with git-cliff, plus store and client notes, all in `release-notes/<version>/`. It then runs `scripts/ai/release-check.js`, which catches what store review would reject. Signed builds come from `scripts/ai/release-build.sh` on a Mac: an app bundle signed with your upload key, and an `.ipa` signed through Xcode's account. With `--ci codemagic`, a version tag starts them on Codemagic instead (`codemagic.yaml`, one-time setup in `docs/ai/codemagic.md`).
44
+ - **Checks no tool can skip:** git hooks (secrets, signing files, broken Xcode project files, lint, typecheck, tests) and, with `--ci github`, GitHub Actions CI (lint, typecheck, tests, secret scan, PR size, Android and iOS builds, nightly Android end-to-end tests).
44
45
 
45
46
  Work continues across tools and machines through `specs/<id>/progress.md`: run `m-pause` in one tool, then `m-continue` in another.
46
47
 
package/bin/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  const { version } = require('../package.json');
3
- const { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS } = require('../lib/init');
3
+ const { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI } = require('../lib/init');
4
4
  const { doctor, printDoctor } = require('../lib/doctor');
5
5
 
6
6
  const [cmd, ...rest] = process.argv.slice(2);
@@ -8,12 +8,13 @@ const flag = name => {
8
8
  const i = rest.indexOf(`--${name}`);
9
9
  return i >= 0 ? rest[i + 1] : undefined;
10
10
  };
11
+ const list = name => (flag(name) ? flag(name).split(',').map(s => s.trim()).filter(Boolean) : undefined);
11
12
 
12
13
  const help = `agentic-mobile-kit ${version}
13
14
 
14
15
  Usage:
15
- npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--pm yarn|npm|pnpm|bun]
16
- npx agentic-mobile-kit sync [--from <version>]
16
+ npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--ci github,codemagic] [--pm yarn|npm|pnpm|bun]
17
+ npx agentic-mobile-kit sync [--ci github,codemagic] [--from <version>]
17
18
  npx agentic-mobile-kit uninstall [--from <version>]
18
19
  npx agentic-mobile-kit doctor
19
20
 
@@ -25,6 +26,7 @@ Commands:
25
26
 
26
27
  Options:
27
28
  --tools AI tools your team uses: ${Object.keys(TOOLS).join(', ')} (default: claude,codex,antigravity)
29
+ --ci CI to set up, only if the app uses it: ${Object.keys(CI).join(', ')} (GitHub Actions checks, Codemagic signed builds; default: none)
28
30
  --pm Package manager, if it can't be detected from the lockfile
29
31
  --from The kit version that installed the project; needed only for installs made before 0.4.0`;
30
32
 
@@ -41,11 +43,10 @@ if (cmd === '--version' || cmd === '-v') {
41
43
  console.log(version);
42
44
  } else if (cmd === 'init') {
43
45
  run('init', () => {
44
- const tools = flag('tools') ? flag('tools').split(',').map(s => s.trim()).filter(Boolean) : undefined;
45
- printSummary(init(process.cwd(), { tools, pm: flag('pm') }));
46
+ printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
46
47
  });
47
48
  } else if (cmd === 'sync') {
48
- run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), pm: flag('pm') })));
49
+ run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
49
50
  } else if (cmd === 'uninstall') {
50
51
  run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
51
52
  } else if (cmd === 'doctor') {
package/lib/init.js CHANGED
@@ -16,6 +16,12 @@ 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
17
  const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/ai/${n}.md`);
18
18
  const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
19
+ // optional parts, installed only when a project chooses them with --ci: not every app uses CI
20
+ const CI = {
21
+ github: rel => rel.startsWith(`.github${path.sep}`),
22
+ codemagic: rel => rel === 'codemagic.yaml' || rel === path.join('docs', 'ai', 'codemagic.md'),
23
+ };
24
+ const ciGroup = rel => Object.keys(CI).find(g => CI[g](rel));
19
25
 
20
26
  // tool name -> rulesync targets
21
27
  const TOOLS = {
@@ -103,9 +109,10 @@ function fillPlaceholders(text, values) {
103
109
  return text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in values ? values[k] : m));
104
110
  }
105
111
 
106
- function projectValues(cwd, pkg, deps, pm) {
112
+ function projectValues(cwd, pkg, deps, pm, ci) {
107
113
  return {
108
114
  KIT_VERSION,
115
+ KIT_CI: ci.join(',') || 'none',
109
116
  APP_NAME: pkg.name || path.basename(cwd),
110
117
  RN_VERSION: installedVersion(cwd, 'react-native', deps['react-native']),
111
118
  REACT_VERSION: installedVersion(cwd, 'react', deps.react),
@@ -153,11 +160,29 @@ function installedTools(cwd) {
153
160
  return tools.length ? tools : TESTED;
154
161
  }
155
162
 
163
+ // what the kit marker in AGENTS.md records: the kit version since 0.4.0, the CI choice since 0.5.0
164
+ function recorded(agents) {
165
+ const m = (agents || '').match(/KIT:START agentic-mobile-kit (\d[^\s>]*)(?: ci=([\w,]+))?/);
166
+ return { version: m ? m[1] : null, ci: m && m[2] ? m[2].split(',').filter(g => CI[g]) : null };
167
+ }
168
+
169
+ // the CI parts a project has: as recorded, or (installs before 0.5.0 got them by default) recognized by the kit's own files
170
+ function installedCi(cwd, agents) {
171
+ return recorded(agents).ci || Object.keys(CI).filter(g => (g === 'github'
172
+ ? /agentic-mobile-kit/.test(readIf(path.join(cwd, '.github', 'workflows', 'ci.yml')) || '')
173
+ : fs.existsSync(path.join(cwd, 'docs', 'ai', 'codemagic.md'))));
174
+ }
175
+
176
+ function chooseCi(cwd, agents, wanted = []) {
177
+ for (const g of wanted) if (!CI[g]) throw new InitError(`Unknown CI "${g}". Choose from: ${Object.keys(CI).join(', ')}.`);
178
+ return Object.keys(CI).filter(g => wanted.includes(g) || installedCi(cwd, agents).includes(g));
179
+ }
180
+
156
181
  // the kit version that installed the project: recorded in AGENTS.md since 0.4.0, or given with --from.
157
182
  // A --from version is a guess (installs may predate it), so it isn't trusted as a merge base.
158
183
  function oldTemplate(agents, opts) {
159
184
  if (opts.fromDir) return { from: opts.from || 'old', dir: opts.fromDir, exact: !opts.from };
160
- const from = opts.from || (agents.match(/KIT:START agentic-mobile-kit (\d[^\s>]*)/) || [])[1];
185
+ const from = opts.from || recorded(agents).version;
161
186
  if (!from) {
162
187
  throw new InitError('This project doesn\'t record which kit version installed it (versions before 0.4.0 didn\'t). '
163
188
  + 'Pass it with --from, for example --from 0.3.0; the commit that added or last updated the kit usually says.');
@@ -186,18 +211,33 @@ function merge3(current, base, kitNew, from) {
186
211
  return { text: r.stdout, conflicts: r.status };
187
212
  }
188
213
 
214
+ const SKILL_LINKS = [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']];
215
+ const kitSkills = template => fs.readdirSync(path.join(template, '.agents', 'skills'), { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
216
+
189
217
  // steps 2–6, shared by init and sync
190
- function finish(cwd, { pkg, deps, tools, skipGenerate }) {
218
+ function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
191
219
  const done = { created: [], merged: [], skipped: [] };
192
220
 
193
- // 2. skills folder links for tools that don't read .agents/skills
194
- for (const [link, tool] of [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']]) {
221
+ // 2. skills links for tools that don't read .agents/skills
222
+ for (const [link, tool] of SKILL_LINKS) {
195
223
  if (!tools.includes(tool)) continue;
196
224
  const dest = path.join(cwd, link);
197
- if (fs.existsSync(dest) || isLink(dest)) { done.skipped.push(link); continue; }
198
- fs.mkdirSync(path.dirname(dest), { recursive: true });
199
- fs.symlinkSync('../.agents/skills', dest);
200
- done.created.push(`${link} -> .agents/skills`);
225
+ if (!fs.existsSync(dest) && !isLink(dest)) {
226
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
227
+ fs.symlinkSync('../.agents/skills', dest);
228
+ done.created.push(`${link} -> .agents/skills`);
229
+ continue;
230
+ }
231
+ if (isLink(dest) || !fs.statSync(dest).isDirectory()) { done.skipped.push(link); continue; }
232
+ // the folder already holds another framework's skills: link each kit skill into it
233
+ for (const name of kitSkills(template)) {
234
+ const p = path.join(dest, name);
235
+ const target = `../../.agents/skills/${name}`;
236
+ if (isLink(p) && fs.readlinkSync(p) === target) continue;
237
+ if (fs.existsSync(p) || isLink(p)) { done.skipped.push(`${link}/${name} (another skill has this name)`); continue; }
238
+ fs.symlinkSync(target, p);
239
+ done.created.push(`${link}/${name} -> .agents/skills/${name}`);
240
+ }
201
241
  }
202
242
 
203
243
  // 3. .gitignore: keep secrets out of git
@@ -244,12 +284,14 @@ function init(cwd, opts = {}) {
244
284
  const tools = opts.tools || TESTED;
245
285
  for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
246
286
  const template = opts.template || TEMPLATE;
247
- const values = projectValues(cwd, pkg, deps, pm);
287
+ const ci = chooseCi(cwd, readIf(path.join(cwd, 'AGENTS.md')), opts.ci);
288
+ const values = projectValues(cwd, pkg, deps, pm, ci);
248
289
  const targets = tools.flatMap(t => TOOLS[t]);
249
290
  const report = { created: [], merged: [], skipped: [] };
250
291
 
251
292
  // 1. template files (never overwrite)
252
293
  for (const rel of templateFiles(template)) {
294
+ if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
253
295
  const dest = path.join(cwd, rel);
254
296
  const text = kitText(template, rel, values, targets);
255
297
  const current = readIf(dest);
@@ -263,9 +305,9 @@ function init(cwd, opts = {}) {
263
305
  report.created.push(rel);
264
306
  }
265
307
 
266
- const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, skipGenerate: opts.skipGenerate });
308
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
267
309
  for (const k of Object.keys(report)) report[k].push(...done[k]);
268
- return { report, values, tools, generated, generateError };
310
+ return { report, values, tools, ci, generated, generateError };
269
311
  }
270
312
 
271
313
  function sync(cwd, opts = {}) {
@@ -274,7 +316,11 @@ function sync(cwd, opts = {}) {
274
316
  if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section). Run init instead.');
275
317
  const { from, dir: oldDir, exact } = oldTemplate(agents, opts);
276
318
  const template = opts.template || TEMPLATE;
277
- const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm));
319
+ const ci = chooseCi(cwd, agents, opts.ci);
320
+ // a CI part chosen just now was never installed, so its files are new rather than deleted by the team
321
+ const hadCi = installedCi(cwd, agents);
322
+ const wasInstalled = rel => !ciGroup(rel) || hadCi.includes(ciGroup(rel));
323
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci);
278
324
  const tools = installedTools(cwd);
279
325
  const targets = tools.flatMap(t => TOOLS[t]);
280
326
  const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
@@ -282,8 +328,9 @@ function sync(cwd, opts = {}) {
282
328
  const oldFiles = new Set(templateFiles(oldDir));
283
329
 
284
330
  for (const rel of newFiles) {
331
+ if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
285
332
  const kitNew = kitText(template, rel, values, targets);
286
- const kitOld = oldFiles.has(rel) ? kitText(oldDir, rel, values, targets) : null;
333
+ const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldDir, rel, values, targets) : null;
287
334
  const current = projectText(cwd, rel, targets);
288
335
  if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
289
336
  const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, kitNew) : mergeClaude(current);
@@ -305,13 +352,13 @@ function sync(cwd, opts = {}) {
305
352
  }
306
353
  // files the kit no longer ships
307
354
  for (const rel of oldFiles) {
308
- if (newFiles.includes(rel)) continue;
355
+ if (newFiles.includes(rel) || !wasInstalled(rel)) continue;
309
356
  const current = projectText(cwd, rel, targets);
310
357
  if (current === null) continue;
311
358
  if (current === kitText(oldDir, rel, values, targets)) { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); } else report.kept.push(`${rel} (the kit dropped it; you changed it)`);
312
359
  }
313
360
 
314
- const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, skipGenerate: opts.skipGenerate });
361
+ const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
315
362
  report.added.push(...done.created);
316
363
  report.updated.push(...done.merged);
317
364
  return { report, from, to: KIT_VERSION, tools, generated, generateError };
@@ -335,7 +382,7 @@ function uninstall(cwd, opts = {}) {
335
382
  const agents = readIf(path.join(cwd, 'AGENTS.md'));
336
383
  if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section).');
337
384
  const { from, dir: template } = oldTemplate(agents, opts);
338
- const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm));
385
+ const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), installedCi(cwd, agents));
339
386
  const targets = installedTools(cwd).flatMap(t => TOOLS[t]);
340
387
  const report = { removed: [], kept: [], left: [] };
341
388
  const remove = rel => { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); };
@@ -358,9 +405,15 @@ function uninstall(cwd, opts = {}) {
358
405
  if (current === null) continue;
359
406
  if (current === text) remove(rel); else report.kept.push(`${rel} (also has your own settings; remove the kit's entries by hand)`);
360
407
  }
361
- for (const link of ['.claude/skills', '.kiro/skills']) {
408
+ for (const [link] of SKILL_LINKS) {
362
409
  const p = path.join(cwd, link);
363
- if (isLink(p) && fs.readlinkSync(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); }
410
+ if (isLink(p) && fs.readlinkSync(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); continue; }
411
+ // per-skill links inside another framework's skills folder
412
+ if (!fs.existsSync(p) || isLink(p)) continue;
413
+ for (const name of fs.readdirSync(p)) {
414
+ const q = path.join(p, name);
415
+ if (isLink(q) && fs.readlinkSync(q) === `../../.agents/skills/${name}`) { fs.unlinkSync(q); report.removed.push(path.join(link, name)); }
416
+ }
364
417
  }
365
418
  // folders left empty (rmdir refuses non-empty ones)
366
419
  const dirs = [...new Set(report.removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
@@ -383,9 +436,10 @@ function uninstall(cwd, opts = {}) {
383
436
  return { report, from };
384
437
  }
385
438
 
386
- function printSummary({ report, values, tools, generated, generateError }, log = console.log) {
439
+ function printSummary({ report, values, tools, ci, generated, generateError }, log = console.log) {
387
440
  log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
388
441
  log(`Tools: ${tools.join(', ')}${tools.some(t => !TESTED.includes(t)) ? ' (cursor, opencode and kiro are not tested yet)' : ''}`);
442
+ log(`CI: ${ci.length ? ci.join(', ') : 'none (add it any time with --ci github,codemagic)'}`);
389
443
  log(` created: ${report.created.length} files`);
390
444
  if (report.merged.length) log(` merged: ${report.merged.join(', ')}`);
391
445
  if (report.skipped.length) log(` kept as they were (already existed): ${report.skipped.join(', ')}`);
@@ -393,9 +447,12 @@ function printSummary({ report, values, tools, generated, generateError }, log =
393
447
  log('\nNext steps:');
394
448
  log(' 1. Fill in docs/ai/product.md, tech.md, structure.md and conventions.md for this app.');
395
449
  log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
396
- log(' 3. Turn on branch protection for main: see docs/branch-protection.md in the kit repo.');
397
- log(' 4. Signed store builds on Codemagic: one-time setup in docs/ai/codemagic.md.');
398
- if (tools.includes('codex')) log(' 5. Codex users: open the project in Codex once and approve its hooks (they stay off until approved).');
450
+ const more = [
451
+ ci.includes('github') && 'Turn on branch protection for main: see docs/branch-protection.md in the kit repo.',
452
+ ci.includes('codemagic') && 'Signed store builds on Codemagic: one-time setup in docs/ai/codemagic.md.',
453
+ tools.includes('codex') && 'Codex users: open the project in Codex once and approve its hooks (they stay off until approved).',
454
+ ].filter(Boolean);
455
+ more.forEach((m, i) => log(` ${i + 3}. ${m}`));
399
456
  }
400
457
 
401
458
  function printSync({ report, from, to, generated, generateError }, log = console.log) {
@@ -417,4 +474,4 @@ function printUninstall({ report }, log = console.log) {
417
474
  log('\nReview it with "git status" and "git diff", then commit. Undo it with git if you change your mind.');
418
475
  }
419
476
 
420
- module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, KIT_VERSION };
477
+ module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "One setup for AI-assisted mobile development that works the same in Claude Code, Codex, Cursor, OpenCode, Kiro and Antigravity. Early development.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -6,6 +6,8 @@ disable-model-invocation: true
6
6
 
7
7
  # m-bugfix
8
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
+
9
11
  Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, task link).
10
12
 
11
13
  1. **Check `docs/ai/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
@@ -6,6 +6,8 @@ disable-model-invocation: true
6
6
 
7
7
  # m-continue
8
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
+
9
11
  Input: $ARGUMENTS (a spec ID, or empty).
10
12
 
11
13
  1. **Check git first.** Run `git fetch` and `git status`.
@@ -6,6 +6,8 @@ disable-model-invocation: true
6
6
 
7
7
  # m-feature
8
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
+
9
11
  Input: $ARGUMENTS (the requirement text, a file path, or a task link plus pasted details).
10
12
 
11
13
  ## 1. Always use the full flow
@@ -6,6 +6,8 @@ disable-model-invocation: true
6
6
 
7
7
  # m-learn
8
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
+
9
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).
10
12
 
11
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.
@@ -6,6 +6,8 @@ disable-model-invocation: true
6
6
 
7
7
  # m-pause
8
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
+
9
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.
10
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.
11
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>`.
@@ -1,23 +1,31 @@
1
1
  ---
2
2
  name: m-release
3
- description: Prepare a store release - version, changelog and store notes from real commits, release check, release PR, then the tag that starts the signed builds. Run only when the user explicitly invokes m-release.
3
+ description: Prepare a store release - version, changelog and store notes from real commits, release check, release PR, then the tag and the signed builds. Run only when the user explicitly invokes m-release.
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
7
  # m-release
8
8
 
9
- Input: $ARGUMENTS (the new version such as 1.4.0, or patch, minor or major; anything the client should hear about).
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
- 1. **Start clean:** `main`, pulled, with a clean working tree. Find the last release with `git describe --tags --abbrev=0 --match 'v*'`. If there's none, this is the first release.
11
+ Input: $ARGUMENTS (the new version such as 1.4.0, or patch, minor or major; which app, if the project ships several; anything the client should hear about).
12
+
13
+ 1. **Start clean:** `main`, pulled, with a clean working tree. Find the last release with `git describe --tags --abbrev=0 --match 'v*'`.
14
+ - No tag, but the app is already in the stores: ask the user which commit was the last store release (or its date and version), and tag it locally as `v<that version>`. The changelog then starts there instead of at the first commit.
15
+ - No tag and never released: this is the first release.
12
16
  2. **Choose the version.** Show the commits since the last release (`git log --oneline <last tag>..HEAD`). Suggest minor if there's anything new for users, patch for fixes only, and major only if the user asks. Get the user's confirmation, then create the branch `release/v<version>`.
13
- 3. **Changelog from real commits:** `npx -y git-cliff@2.14.2 --unreleased --tag v<version> --prepend CHANGELOG.md`. If `CHANGELOG.md` doesn't exist yet, use `-o CHANGELOG.md` instead of `--prepend CHANGELOG.md`. Don't add, merge or reword entries by hand. A misleading commit message gets fixed in the notes below, not in the changelog.
14
- 4. **Store and client notes** go in `release-notes/<version>/`. Write them only from the new changelog section, so every line traces back to an entry. Leave out internal changes (refactors, CI, dependency bumps) unless users notice them.
17
+ 3. **Changelog from real commits:** `npx -y git-cliff@2.14.2 --unreleased --tag v<version> -o release-notes/<version>/CHANGELOG.md`. If the repo tracks a root `CHANGELOG.md` (`git ls-files CHANGELOG.md`), also add the section there with `--prepend CHANGELOG.md`. Leave the root file alone if `.gitignore` ignores it, because another tool may own it. Don't add, merge or reword entries by hand. A misleading commit message gets fixed in the notes below, not in the changelog.
18
+ 4. **Store and client notes** go in `release-notes/<version>/` too. Write them only from that changelog, so every line traces back to an entry. Leave out internal changes (refactors, CI, dependency bumps) unless users notice them.
15
19
  - `play-store.txt`: plain text for users, at most 500 characters.
16
20
  - `app-store.txt`: plain text for users, at most 4000 characters, with no `<` or `>`.
17
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.
18
22
 
19
23
  Show all three files to the user and wait for their approval.
20
- 5. **Version name:** `sh scripts/ai/set-version.sh <version>` sets the iOS and Android version names. Leave build numbers alone when `codemagic.yaml` sets them; otherwise ask whether to bump them. If the script stops because the project ships several apps, ask the user which version each app gets.
24
+ 5. **Version and build numbers:** `sh scripts/ai/set-version.sh <version>` sets the iOS and Android version names. If the script stops because the project ships several apps, ask the user which version each app gets, and set them after they confirm.
25
+ - When `codemagic.yaml` sets build numbers, leave them alone.
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. iOS may keep its build number when the version name changes, if that's how the team works.
21
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.
22
- 7. **Release PR:** commit as `Release <version>` with `Assisted-by: <tool>/<model>`. Ask before pushing. Open a PR titled `Release <version>` with the new changelog section and the release-check output.
23
- 8. **Tag 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>`. With Codemagic set up (`docs/ai/codemagic.md`), the tag starts the signed builds, which go to TestFlight and Play's internal track.
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.
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.
31
+ - 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). Never run these yourself or ask for the keys.
@@ -6,6 +6,8 @@ disable-model-invocation: true
6
6
 
7
7
  # m-review
8
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
+
9
11
  If your tool has subagents, hand the review to the `m-reviewer` subagent, so it looks at the code with fresh eyes. Otherwise review it yourself, read-only.
10
12
 
11
13
  ## Reviewing
@@ -1,8 +1,10 @@
1
- <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} (edit outside these markers; the kit updates what's inside) -->
1
+ <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} (edit outside these markers; the kit updates what's inside) -->
2
2
  # {{APP_NAME}}: instructions for AI agents
3
3
 
4
4
  Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.
5
5
 
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
+
6
8
  ## Project
7
9
 
8
10
  - Bare React Native {{RN_VERSION}} (New Architecture), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
@@ -19,6 +21,7 @@ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antig
19
21
  | Android build | `cd android && ./gradlew assembleDebug` |
20
22
  | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>` |
21
23
  | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/ai/release-check.js` |
24
+ | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/ai/release-build.sh android [flavor]`, `sh scripts/ai/release-build.sh ios [scheme]` |
22
25
 
23
26
  ## Definition of done
24
27
 
@@ -0,0 +1,87 @@
1
+ #!/bin/sh
2
+ # Builds signed release apps on this Mac: for apps without CI, or to check a release by hand.
3
+ # A person runs it, because it uses the signing keys, which agents must never handle.
4
+ #
5
+ # sh scripts/ai/release-build.sh android [flavor] signed app bundle (.aab) for Google Play
6
+ # sh scripts/ai/release-build.sh ios [scheme] signed .ipa for App Store Connect (TestFlight)
7
+ #
8
+ # Android signs with your upload key. Set its path in your shell, never in the repo:
9
+ # export AMK_UPLOAD_KEYSTORE=~/keys/myapp-upload.jks AMK_UPLOAD_KEY_ALIAS=upload
10
+ # The passwords are asked for, unless AMK_UPLOAD_STORE_PASSWORD and AMK_UPLOAD_KEY_PASSWORD are set.
11
+ # Without AMK_UPLOAD_KEYSTORE it uses the app's own signing setup, and stops if that's the debug key.
12
+ # iOS signs with the Apple account in Xcode (Settings > Accounts) and automatic signing; Xcode may
13
+ # create a distribution certificate or profile in that team if one is missing.
14
+ # Version and build numbers come from the repo, so set them first (the m-release skill does).
15
+ # Output: .ai/release/
16
+ set -eu
17
+ platform=${1:-}
18
+ target=${2:-}
19
+ out=.ai/release
20
+ mkdir -p "$out"
21
+
22
+ # secret VAR "question": read it without echo, unless it's already set
23
+ secret() {
24
+ eval "[ -n \"\${$1:-}\" ]" && return 0
25
+ [ -t 0 ] || { echo "Set $1 in your shell, or run this in a terminal to be asked." >&2; exit 1; }
26
+ printf '%s: ' "$2" >&2; stty -echo; read -r value; stty echo; echo >&2
27
+ eval "$1=\$value"
28
+ }
29
+
30
+ case "$platform" in
31
+ android)
32
+ flavor=$(printf %s "$target" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
33
+ if [ -n "${AMK_UPLOAD_KEYSTORE:-}" ]; then
34
+ secret AMK_UPLOAD_STORE_PASSWORD 'Keystore password'
35
+ secret AMK_UPLOAD_KEY_PASSWORD 'Key password'
36
+ # injected signing (as Android Studio's "Generate Signed Bundle" does): build.gradle stays as it is
37
+ set -- -Pandroid.injected.signing.store.file="$AMK_UPLOAD_KEYSTORE" \
38
+ -Pandroid.injected.signing.store.password="$AMK_UPLOAD_STORE_PASSWORD" \
39
+ -Pandroid.injected.signing.key.alias="${AMK_UPLOAD_KEY_ALIAS:-upload}" \
40
+ -Pandroid.injected.signing.key.password="$AMK_UPLOAD_KEY_PASSWORD"
41
+ else
42
+ set --
43
+ fi
44
+ (cd android && ./gradlew "bundle${flavor}Release" "$@")
45
+ dir=android/app/build/outputs/bundle/${target:-release}${target:+Release}
46
+ for aab in "$dir"/*.aab; do
47
+ signer=$(keytool -printcert -jarfile "$aab" | sed -n 's/^Owner: //p' | head -n 1)
48
+ case "$signer" in
49
+ ''|*'Android Debug'*) echo "$aab is signed with the debug key. Set AMK_UPLOAD_KEYSTORE (see the top of this script)." >&2; exit 1 ;;
50
+ esac
51
+ cp "$aab" "$out/"
52
+ echo "Signed by: $signer"
53
+ echo "$out/$(basename "$aab")"
54
+ done
55
+ ;;
56
+ ios)
57
+ workspace=$(ls -d ios/*.xcworkspace | head -n 1)
58
+ scheme=${target:-$(basename "$workspace" .xcworkspace)}
59
+ [ -d ios/Pods ] || (cd ios && pod install)
60
+ log="$out/$scheme-ios.log"
61
+ echo "Archiving $scheme (several minutes; log: $log)"
62
+ xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration Release -destination 'generic/platform=iOS' \
63
+ -archivePath "$out/$scheme.xcarchive" -allowProvisioningUpdates archive > "$log" 2>&1 \
64
+ || { grep -E 'error:|BUILD FAILED|ARCHIVE FAILED' "$log" | head -n 20; exit 1; }
65
+ cat > "$out/ExportOptions.plist" <<'PLIST'
66
+ <?xml version="1.0" encoding="UTF-8"?>
67
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
68
+ <plist version="1.0"><dict>
69
+ <key>method</key><string>app-store-connect</string>
70
+ <key>destination</key><string>export</string>
71
+ <key>signingStyle</key><string>automatic</string>
72
+ </dict></plist>
73
+ PLIST
74
+ xcodebuild -exportArchive -archivePath "$out/$scheme.xcarchive" -exportPath "$out/$scheme" \
75
+ -exportOptionsPlist "$out/ExportOptions.plist" -allowProvisioningUpdates >> "$log" 2>&1 \
76
+ || { grep -E 'error:|EXPORT FAILED' "$log" | head -n 20; exit 1; }
77
+ ipa=$(ls "$out/$scheme"/*.ipa | head -n 1)
78
+ # the export re-signs for distribution, so check the app inside the .ipa, not the archive
79
+ unzip -oq "$ipa" -d "$out/$scheme/unzipped"
80
+ echo "Signed by: $(codesign -dvv "$out/$scheme/unzipped"/Payload/*.app 2>&1 | sed -n 's/^Authority=//p' | head -n 1)"
81
+ echo "$ipa"
82
+ ;;
83
+ *)
84
+ sed -n '2,16p' "$0"
85
+ exit 1
86
+ ;;
87
+ esac
@@ -49,7 +49,7 @@ const iosBuilds = t => all(/CURRENT_PROJECT_VERSION = ([^;]+);/g, t);
49
49
  const androidVersions = t => all(/versionName\s*=?\s*"([^"]+)"/g, stripComments(t));
50
50
  const androidBuilds = t => all(/versionCode\s*=?\s*(\d+)/g, stripComments(t));
51
51
 
52
- function compare(platform, now, before, kind) {
52
+ function compare(platform, now, before, kind, versionChanged) {
53
53
  if (kind === 'build number' && ciBuildNumber[platform]) { info(`${platform} build number: set by Codemagic at build time`); return; }
54
54
  if (!now.length) { warn(`${platform} ${kind}: couldn't read it`, 'check it by hand before you ship'); return; }
55
55
  if (!before) { info(`${platform} ${kind}: ${now.join(', ')}`); return; }
@@ -57,6 +57,9 @@ function compare(platform, now, before, kind) {
57
57
  if (kind === 'build number' && before.length && maxNum(now) < maxNum(before)) {
58
58
  fail(`${platform} build number went down (${before.join(', ')} → ${now.join(', ')})`, 'stores reject a build number lower than the last upload');
59
59
  } else ok(`${platform} ${kind}`, `${before.join(', ') || '?'} → ${now.join(', ')}`);
60
+ } else if (kind === 'build number' && platform === 'iOS' && versionChanged) {
61
+ // the App Store needs a new build number only within a version, so 1 again for a new version is fine
62
+ ok(`${platform} build number (${now.join(', ')} again, for a new version)`);
60
63
  } else if (kind === 'build number') {
61
64
  warn(`${platform} build number unchanged since ${since} (${now.join(', ')})`, 'bump it, unless your CI sets it (for example Codemagic); stores reject a repeated build number');
62
65
  } else {
@@ -66,8 +69,9 @@ function compare(platform, now, before, kind) {
66
69
 
67
70
  if (!since) info('No previous release found (no git tag)', 'tag each release, e.g. v1.4.0, or pass --since <ref>, so the next check can compare');
68
71
  if (pbx) {
69
- compare('iOS', iosVersions(pbx), since && iosVersions(readAt(since, pbxPath)), 'version');
70
- compare('iOS', iosBuilds(pbx), since && iosBuilds(readAt(since, pbxPath)), 'build number');
72
+ const [now, before] = [iosVersions(pbx), since && iosVersions(readAt(since, pbxPath))];
73
+ compare('iOS', now, before, 'version');
74
+ compare('iOS', iosBuilds(pbx), since && iosBuilds(readAt(since, pbxPath)), 'build number', before && now.join() !== before.join());
71
75
  }
72
76
  if (gradle) {
73
77
  compare('Android', androidVersions(gradle), since && androidVersions(readAt(since, gradlePath)), 'version');
@@ -76,7 +80,7 @@ if (gradle) {
76
80
  if (pbx && gradle) {
77
81
  const a = iosVersions(pbx), b = androidVersions(gradle);
78
82
  if (a.length && b.length && !a.some(v => b.includes(v))) {
79
- warn(`iOS shows version ${a.join(', ')}, Android shows ${b.join(', ')}`, 'users and support see different numbers; align them unless that\'s intended');
83
+ info(`iOS shows version ${a.join(', ')}, Android shows ${b.join(', ')}`, 'users and support see different numbers; fine if your team numbers the platforms separately');
80
84
  }
81
85
  }
82
86
 
@@ -168,7 +172,8 @@ const releaseBlock = block(block(gradle, 'buildTypes'), 'release');
168
172
  if (/debuggable\s*=?\s*true/.test(releaseBlock)) fail('Android release build is debuggable', 'remove "debuggable true" from buildTypes.release; Play rejects debuggable apps');
169
173
  if (/android\.injected\.signing/.test(codemagic)) ok('Android release signing', 'Codemagic signs with the upload key');
170
174
  else if (/signingConfig\s*=?\s*signingConfigs\.debug/.test(releaseBlock)) {
171
- warn('Android release build is signed with the debug key', 'fine only if your release pipeline (for example Codemagic) re-signs it; Play rejects debug-signed uploads');
175
+ // the kit's release-build.sh (and Codemagic) sign with the upload key, and Play rejects debug-signed uploads anyway
176
+ info('build.gradle signs release builds with the debug key', 'build store releases with sh scripts/ai/release-build.sh android, which signs with your upload key');
172
177
  }
173
178
  if (/android:usesCleartextTraffic="true"/.test(readNow(manifestPath) || '')) {
174
179
  warn('Android allows cleartext (HTTP) traffic', 'allow only the domains that need it (network security config)');