agentic-mobile-kit 0.7.18 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +20 -5
  2. package/bin/cli.js +5 -3
  3. package/lib/doctor.js +31 -5
  4. package/lib/init.js +19 -24
  5. package/lib/menu.js +3 -3
  6. package/package.json +1 -1
  7. package/stacks/react-native/expo/.eas/workflows/pr-preview.yml +54 -0
  8. package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
  9. package/stacks/react-native/expo/AGENTS.md +33 -17
  10. package/stacks/react-native/expo/docs/amk/expo.md +22 -1
  11. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +14 -12
  12. package/stacks/react-native/template/.agents/skills/m-change/SKILL.md +3 -2
  13. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +6 -4
  14. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -2
  15. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +34 -27
  16. package/stacks/react-native/template/.agents/skills/m-feature/build.md +35 -0
  17. package/stacks/react-native/template/.agents/skills/m-feature/plan.md +43 -0
  18. package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +3 -1
  19. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +10 -5
  20. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -0
  21. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +8 -9
  22. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -4
  23. package/stacks/react-native/template/.agents/skills/m-report/SKILL.md +25 -0
  24. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +8 -4
  25. package/stacks/react-native/template/.agents/skills/m-test/SKILL.md +24 -0
  26. package/stacks/react-native/template/.agents/skills/m-test/agents/openai.yaml +3 -0
  27. package/stacks/react-native/template/.githooks/pre-commit +12 -0
  28. package/stacks/react-native/template/.github/pull_request_template.md +7 -1
  29. package/stacks/react-native/template/.github/workflows/amk-ai-deps.yml +90 -0
  30. package/stacks/react-native/template/.github/workflows/amk-ai-review.yml +82 -0
  31. package/stacks/react-native/template/.github/workflows/amk-kit-update.yml +95 -0
  32. package/stacks/react-native/template/.github/workflows/amk-ready.yml +39 -0
  33. package/stacks/react-native/template/.github/workflows/ci.yml +79 -13
  34. package/stacks/react-native/template/.github/workflows/e2e.yml +10 -1
  35. package/stacks/react-native/template/.rulesync/hooks.jsonc +3 -1
  36. package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
  37. package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
  38. package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -1
  39. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +4 -2
  40. package/stacks/react-native/template/.rulesync/subagents/m-spec-writer.md +15 -0
  41. package/stacks/react-native/template/.rulesync/subagents/m-tester.md +23 -0
  42. package/stacks/react-native/template/AGENTS.md +26 -10
  43. package/stacks/react-native/template/codemagic.yaml +82 -1
  44. package/stacks/react-native/template/docs/amk/codemagic.md +8 -0
  45. package/stacks/react-native/template/docs/amk/design-system.md +15 -0
  46. package/stacks/react-native/template/docs/amk/glossary.md +12 -0
  47. package/stacks/react-native/template/docs/amk/react-native.md +22 -1
  48. package/stacks/react-native/template/docs/amk/team-process.md +33 -1
  49. package/stacks/react-native/template/rulesync.jsonc +1 -1
  50. package/stacks/react-native/template/scripts/amk/ai-job.js +106 -0
  51. package/stacks/react-native/template/scripts/amk/autopilot.js +837 -0
  52. package/stacks/react-native/template/scripts/amk/baseline.js +19 -7
  53. package/stacks/react-native/template/scripts/amk/ci-scope.js +59 -0
  54. package/stacks/react-native/template/scripts/amk/coverage.js +111 -0
  55. package/stacks/react-native/template/scripts/amk/guard.js +64 -1
  56. package/stacks/react-native/template/scripts/amk/handoff-check.js +87 -14
  57. package/stacks/react-native/template/scripts/amk/issue.js +31 -0
  58. package/stacks/react-native/template/scripts/amk/metrics.js +164 -0
  59. package/stacks/react-native/template/scripts/amk/pr.js +244 -0
  60. package/stacks/react-native/template/scripts/amk/redact.js +57 -0
  61. package/stacks/react-native/template/scripts/amk/release-build.sh +14 -0
  62. package/stacks/react-native/template/scripts/amk/report.js +48 -11
  63. package/stacks/react-native/template/scripts/amk/rn-check.js +204 -47
  64. package/stacks/react-native/template/scripts/amk/shots.js +131 -0
  65. package/stacks/react-native/template/scripts/amk/specs.js +717 -34
  66. package/stacks/react-native/template/scripts/amk/tool-configs.js +41 -0
  67. package/stacks/react-native/template/scripts/amk/verify.sh +127 -23
  68. package/stacks/react-native/template/specs/_templates/design.md +25 -3
  69. package/stacks/react-native/template/specs/_templates/flow.yaml +5 -1
  70. package/stacks/react-native/template/specs/_templates/plan.md +54 -0
  71. package/stacks/react-native/template/specs/_templates/progress.md +1 -1
  72. package/stacks/react-native/template/specs/_templates/questions.md +29 -0
  73. package/stacks/react-native/template/specs/_templates/requirements.md +40 -0
  74. package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
  75. package/stacks/react-native/template/specs/_templates/test-report.md +25 -0
  76. package/stacks/react-native/template/.github/workflows/ios.yml +0 -41
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env node
2
+ // Finishes the tool configs rulesync generates from .rulesync/, as the kit needs them. Run it after
3
+ // `npx -y rulesync@27.0.0 generate`: init and sync do, and so do CI's and doctor's checks that the configs match .rulesync/.
4
+ // - Antigravity's Stop hooks become a plain list of handlers: rulesync before 40 writes them in the matcher shape, which
5
+ // Antigravity rejects, dropping the whole hook set, the guard included
6
+ // - Codex asks with options to pick from (request_user_input) in every mode, not only in plan mode: rulesync writes no
7
+ // [features] table, and Codex reads it from the project's config once the folder is trusted
8
+ // Usage: node scripts/amk/tool-configs.js (in the project's folder)
9
+ 'use strict';
10
+ const fs = require('fs');
11
+ const path = require('path');
12
+
13
+ const read = f => { try { return fs.readFileSync(f, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; } };
14
+
15
+ function flattenAntigravityStop(dir) {
16
+ const file = path.join(dir, '.agents/hooks.json');
17
+ let hooks;
18
+ try { hooks = JSON.parse(read(file)); } catch { return; }
19
+ let changed = false;
20
+ for (const set of Object.values(hooks || {})) {
21
+ if (!set || !Array.isArray(set.Stop) || !set.Stop.some(e => e && Array.isArray(e.hooks) && !e.command)) continue;
22
+ set.Stop = set.Stop.flatMap(e => (e && Array.isArray(e.hooks) && !e.command ? e.hooks : [e]));
23
+ changed = true;
24
+ }
25
+ if (changed) fs.writeFileSync(file, `${JSON.stringify(hooks, null, 2)}\n`);
26
+ }
27
+
28
+ function codexQuestions(dir) {
29
+ const file = path.join(dir, '.codex/config.toml');
30
+ const text = read(file);
31
+ if (text === null || /^\s*default_mode_request_user_input\s*=/m.test(text)) return;
32
+ const on = 'default_mode_request_user_input = true';
33
+ fs.writeFileSync(file, /^\[features\][ \t]*$/m.test(text) ? text.replace(/^\[features\][ \t]*$/m, `[features]\n${on}`)
34
+ : `${text.replace(/\n*$/, '\n')}\n# agentic-mobile-kit: questions as options to pick from, in every mode\n[features]\n${on}\n`);
35
+ }
36
+
37
+ const afterGenerate = dir => { flattenAntigravityStop(dir); codexQuestions(dir); };
38
+
39
+ module.exports = { afterGenerate, flattenAntigravityStop, codexQuestions };
40
+
41
+ if (require.main === module) afterGenerate(process.cwd());
@@ -3,15 +3,20 @@
3
3
  # and Android emulator, running Maestro flows and saving screenshots as evidence. Apps that support tablets or
4
4
  # landscape (scripts/amk/screens.js) are checked on each: an iPad simulator and a tablet emulator, and turned.
5
5
  #
6
- # Usage: sh scripts/amk/verify.sh [quick|ios|android|all|build|plan] [--spec <id>] [--flow <file>] [--label <name>]
7
- # [--flavor <name>] [--scheme <name>] [--screens <list>] [--no-build]
6
+ # Usage: sh scripts/amk/verify.sh [quick|ios|android|all|build|plan|approve] [--spec <ids>] [--flow <file>] [--label <name>]
7
+ # [--flavor <name>] [--scheme <name>] [--screens <list>] [--no-build] [--related] [--mock]
8
8
  # quick lint, typecheck, tests
9
+ # --related quick: only the Jest tests related to the files this branch changed, for each task while building
10
+ # (without it, the whole suite)
9
11
  # ios|android release build, install, run flows, screenshots
10
12
  # all everything (default)
11
13
  # build the release builds only, iOS and Android at the same time, for --no-build checks after it
12
14
  # plan how many devices this machine's memory can check at the same time, and the commands to run:
13
15
  # one per device, in rounds when they don't all fit, the flows split into parts when there's room
14
- # --spec <id> run .maestro/<id>*.yaml and save evidence in .amk/evidence/<id>/
16
+ # approve the last check's screenshots (of --spec or --label) become the approved ones, in .amk/approved/:
17
+ # after each device check, the screenshots that differ from them are listed, for a look
18
+ # --spec <ids> run .maestro/<id>*.yaml and save evidence in .amk/evidence/<id>/. Several, comma-separated, run the
19
+ # flows of each (a flow's name prefix works too: offline-sync runs offline-sync-1.yaml) and need --label
15
20
  # --flow <file> run only this flow: a path in the project, or anywhere (an absolute path)
16
21
  # --tags <list> only the flows with one of these tags in their header (tags: [smoke]), comma-separated
17
22
  # --label <n> evidence folder name (default: the spec id, or no-spec)
@@ -19,11 +24,17 @@
19
24
  # --scheme <name> iOS scheme to check (default: the one named like the workspace)
20
25
  # --screens <l> only these of the screens the app supports, comma-separated: phone, tablet, portrait,
21
26
  # landscape, or one such as tablet-landscape
22
- # --no-build check the last build instead of building again (after `build`)
27
+ # --no-build check the last build instead of building again (after `build`), when it has the same API (--mock)
28
+ # --mock build with the app's mock API on: the variables in .amk-mock (a NAME=value line each) switch it on, the
29
+ # way the app reads its other settings. Its evidence goes in <label>-mock/, and its report says so
23
30
  # --part <k/n> only part k of the flows split in n (every n-th, from the k-th), with its evidence in
24
31
  # <screen>/part-k/: part 1 on the usual device, the others on a temporary copy of it (the same kind of
25
32
  # simulator, or an emulator with the same settings), deleted afterwards. plan prints these
26
33
  # (no flows found: a smoke check that launches the app and takes a screenshot)
34
+ # A flow that fails runs once more: one that passes then is flaky, which doesn't fail the check but is reported, with
35
+ # the first try's log and screen kept in maestro-logs/<screen>-<flow>-first-try/
36
+ # Before a build it stops when the disk has under 5 GB free, or 8 GB before a first iOS build (not in CI), as a build that
37
+ # runs out halfway wastes the run
27
38
  # Evidence per screen: ios/ and android/ (phone, portrait), then -landscape/, -tablet/ and -tablet-landscape/, each
28
39
  # with its latest run only (the device's own log only for a flow that failed); the newest 5 evidence folders stay,
29
40
  # and every prototype's
@@ -58,6 +69,8 @@ label=""
58
69
  flavor=${AMK_ANDROID_FLAVOR:-}
59
70
  only=${AMK_SCREENS:-}
60
71
  no_build=0
72
+ mock=0
73
+ related=0
61
74
  build_only=0
62
75
  part=""
63
76
  while [ $# -gt 0 ]; do
@@ -70,6 +83,8 @@ while [ $# -gt 0 ]; do
70
83
  --scheme) AMK_IOS_SCHEME=$2; export AMK_IOS_SCHEME; shift 2 ;;
71
84
  --screens) only=$2; shift 2 ;;
72
85
  --no-build) no_build=1; shift ;;
86
+ --mock) mock=1; shift ;;
87
+ --related) related=1; shift ;;
73
88
  --part) part=$2; shift 2 ;;
74
89
  *) echo "verify: unknown option $1"; exit 2 ;;
75
90
  esac
@@ -82,15 +97,37 @@ if [ -n "$part" ]; then
82
97
  [ "$part_k" -ge 1 ] && [ "$part_k" -le "$part_n" ] || { echo "verify: --part takes k/n, such as 2/3"; exit 2; }
83
98
  fi
84
99
 
100
+ # several specs' flows go in one evidence folder, which the cleanup below keeps by its name
101
+ case $spec in *,*) [ -n "$label" ] || { echo "verify: --spec $spec runs several specs' flows: name their evidence folder with --label <name>"; exit 2; } ;; esac
102
+
85
103
  root=$(pwd)
86
104
  # --flow: a path in the project, or an absolute one (C:/… on Windows too); a Windows path's backslashes become slashes
87
105
  case $flow in *\\*) flow=$(printf '%s' "$flow" | tr '\\' /) ;; esac
88
106
  case $flow in "" | /* | [A-Za-z]:/*) ;; *) flow=$root/$flow ;; esac
89
107
  [ -z "$flow" ] || [ -f "$flow" ] || { echo "verify: no flow file $flow"; exit 2; }
90
108
  . scripts/amk/maestro-env.sh
109
+ # --mock: the app's mock API, switched on by the variables .amk-mock lists, with its evidence apart and Metro's cache
110
+ # apart from the real builds', so neither build reuses the other's JavaScript
111
+ api=real
112
+ if [ "$mock" = 1 ]; then
113
+ [ -f .amk-mock ] || { echo "verify: --mock needs .amk-mock: the variables that switch this app's mock API on, a NAME=value line each (m-feature adds them with the mock mode)"; exit 2; }
114
+ while IFS= read -r line || [ -n "$line" ]; do
115
+ line=$(printf '%s' "$line" | tr -d '\r')
116
+ case $line in '' | '#'*) continue ;; esac
117
+ name=${line%%=*}
118
+ case $name in "$line" | '' | [!A-Za-z_]* | *[!A-Za-z0-9_]*) echo "verify: .amk-mock: not a NAME=value line: $line"; exit 2 ;; esac
119
+ export "$name=${line#*=}"
120
+ done < .amk-mock
121
+ api=mock
122
+ label="${label:-${spec:-no-spec}}-mock"
123
+ TMPDIR="$root/.amk/metro-mock"
124
+ export TMPDIR
125
+ mkdir -p "$TMPDIR"
126
+ fi
91
127
  # runs without a spec or a label (verify.sh quick, mostly) share one folder, so they don't push out a feature's
92
128
  evidence="$root/.amk/evidence/${label:-${spec:-no-spec}}"
93
129
  mkdir -p "$evidence"
130
+ if [ "$mock" = 1 ]; then : > "$evidence/.mock"; fi
94
131
  # Evidence stays on this machine (.amk/ is out of git): the newest AMK_EVIDENCE_KEEP folders stay, this one among
95
132
  # them, and older ones go (5; 0 keeps them all). A prototype's folder (<id>-prototype, material for a demo) and those
96
133
  # of a spec in progress (its progress.md isn't done: its evidence table points there) always stay and aren't counted.
@@ -116,10 +153,21 @@ if [ "$keep" -gt 0 ] 2> /dev/null; then
116
153
  fi
117
154
  status=0
118
155
 
156
+ # a check of the last build (--no-build) needs one with the same API, mock or real; each build records its own
157
+ same_api() {
158
+ [ "$no_build" = 1 ] || return 0
159
+ last=$(cat "$root/.amk/last-build-$1" 2> /dev/null || echo real)
160
+ [ "$last" = "$api" ] && return 0
161
+ echo "$1: the last build has the $last API, and this check is for the $api one: build again, without --no-build"
162
+ return 1
163
+ }
164
+ built_api() { echo "$api" > "$root/.amk/last-build-$1"; }
165
+
119
166
  flow_files() {
120
167
  {
121
168
  if [ -n "$flow" ]; then echo "$flow"
122
- elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" ! -name '.amk-*' 2>/dev/null | sort
169
+ elif [ -n "$spec" ]; then
170
+ for s in $(echo "$spec" | tr ',' ' '); do find "$root/.maestro" -maxdepth 1 -iname "$s*.yaml" ! -name '.amk-*' 2>/dev/null; done | sort -u
123
171
  else find "$root/.maestro" -maxdepth 1 -name '*.yaml' ! -name '.amk-*' 2>/dev/null | sort
124
172
  fi
125
173
  } | with_tags | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
@@ -129,15 +177,10 @@ with_tags() {
129
177
  if [ -z "$tags" ]; then cat; return; fi
130
178
  TAGS=$tags node -e '
131
179
  const fs = require("fs");
180
+ const { tagsOf } = require("./scripts/amk/specs.js");
132
181
  const want = process.env.TAGS.split(",").map(s => s.trim()).filter(Boolean);
133
182
  for (const f of fs.readFileSync(0, "utf8").split("\n").filter(Boolean)) {
134
- const head = fs.readFileSync(f, "utf8").split(/^---\s*$/m)[0].split("\n");
135
- const at = head.findIndex(l => /^tags\s*:/.test(l));
136
- if (at < 0) continue;
137
- const inline = head[at].replace(/^tags\s*:/, "").trim();
138
- const below = [];
139
- for (let i = at + 1; i < head.length && /^\s+-\s*\S/.test(head[i]); i++) below.push(head[i].replace(/^\s+-\s*/, ""));
140
- const tags = (inline ? inline.replace(/^\[|\]$/g, "").split(",") : below).map(s => s.trim().replace(/^["\x27]|["\x27]$/g, ""));
183
+ const tags = tagsOf(fs.readFileSync(f, "utf8"));
141
184
  if (tags.some(s => want.includes(s))) console.log(f);
142
185
  }'
143
186
  }
@@ -286,7 +329,9 @@ run_flow() { # screen device app_id file name orientation
286
329
  tree_flow=""
287
330
  # Maestro named the flow's folder after the copy, a hidden name: the flow's own, as on iOS
288
331
  [ ! -d "$debug/.amk-$1-$5" ] || [ -e "$debug/$5" ] || mv "$debug/.amk-$1-$5" "$debug/$5"
289
- node scripts/amk/a11y.js "$debug" "$density" "$5" >> "$out/.a11y" 2> /dev/null || true
332
+ # a flow run again replaces its lines from the earlier try
333
+ { awk -F '\t' -v f="$5" '$1 != f' "$out/.a11y"; node scripts/amk/a11y.js "$debug" "$density" "$5" 2> /dev/null || true; } > "$out/.a11y.new"
334
+ mv "$out/.a11y.new" "$out/.a11y"
290
335
  fi
291
336
  return $rc
292
337
  }
@@ -373,10 +418,13 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
373
418
  fi
374
419
  passed=0
375
420
  total=0
421
+ flakies=0
376
422
  for f in $files; do
377
423
  total=$((total + 1))
378
424
  name=$(basename "$f" .yaml)
379
- ok=0 why="" shot=""
425
+ ok=0 why="" shot="" first=""
426
+ # an earlier run's first try, when the flow was flaky then
427
+ [ ! -d "$evidence/maestro-logs/$1-$name-first-try" ] || rm -r "$evidence/maestro-logs/$1-$name-first-try"
380
428
  : > "$out/.flow-started"
381
429
  run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
382
430
  # Maestro now and then stops before a flow starts (it printed nothing), and an emulator sometimes drops its adb
@@ -402,11 +450,35 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
402
450
  sleep 15
403
451
  ok=0
404
452
  run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
453
+ elif [ "$ok" != 0 ] && ! is_real "$2" && ! grep -qE '\.\.\. *(COMPLETED|FAILED|SKIPPED|WARNED)' "$out/$name.log"; then
454
+ # nor did it get to the flow's first step when its driver didn't start on the device (a stack trace, and no step)
455
+ echo " $1: Maestro stopped before flow $name started; running it once more"
456
+ ok=0
457
+ run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
458
+ elif [ "$ok" != 0 ]; then
459
+ # one that failed at one of its steps runs once more, to tell a flaky flow from a failing one. The first try's logs
460
+ # and screen stay as the evidence of a flaky one
461
+ why=$(why_failed "$2" "$name" | tr '\t' ' ')
462
+ shot=$(failure_shot "$2")
463
+ first=$debug-first-try
464
+ [ ! -d "$first" ] || rm -r "$first"
465
+ mv "$debug" "$first"
466
+ mv "$out/$name.log" "$first/flow.log"
467
+ [ -z "$shot" ] || shot=$first${shot#"$debug"}
468
+ echo " $1: flow $name failed; running it once more, to tell a flaky flow from a failing one"
469
+ ok=0
470
+ run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
471
+ if [ "$ok" != 0 ]; then rm -r "$first"; first="" why="" shot=""; fi
405
472
  fi
406
473
  if [ "$ok" = 0 ]; then
407
474
  passed=$((passed + 1))
408
475
  # the device's own log (the simulator's or the emulator's, up to 25 MB a run) helps only with a failure
409
476
  find "$debug" -path '*/logs/device-*' -type f -exec rm -f {} +
477
+ if [ -n "$first" ]; then
478
+ flakies=$((flakies + 1))
479
+ echo " $1: flow $name is flaky: it failed${why:+ $why}, then passed. Not a failure, but fix it (a race, or a wait too short);"
480
+ echo " the first try's logs and screen are in ${first#"$root"/}/"
481
+ fi
410
482
  elif is_real "$2"; then
411
483
  echo " $1: flow $name failed, see ${out#"$root"/}/$name.log and maestro-runner's own log ${debug#"$root"/}/maestro-runner.log"
412
484
  status=1
@@ -423,10 +495,11 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
423
495
  [ -z "$why" ] || echo " failed $why"
424
496
  [ -z "$shot" ] || echo " the screen when it failed: ${shot#"$root"/}"
425
497
  fi
426
- # for the report: the flow, its result, why it failed, the screenshots it took, and the screen when it failed
427
- printf '%s\t%s\t%s\t%s\t%s\n' "$name" "$([ "$ok" = 0 ] && echo passed || echo failed)" "$why" \
498
+ # for the report: the flow, its result, why it failed, the screenshots it took, the screen when it failed, and a
499
+ # flaky one's first log
500
+ printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$name" "$([ "$ok" != 0 ] && echo failed || { [ -n "$first" ] && echo flaky; } || echo passed)" "$why" \
428
501
  "$(find "$out" -name '*.png' -newer "$out/.flow-started" | sed "s|^$evidence/||" | sort | tr '\n' ',' | sed 's/,$//')" \
429
- "${shot#"$evidence"/}" >> "$out/.flows"
502
+ "${shot#"$evidence"/}" "${first:+${first#"$evidence"/}/flow.log}" >> "$out/.flows"
430
503
  done
431
504
  # iOS saves a turned screen's screenshots at the device's upright size, with a tag that tells viewers to turn them,
432
505
  # and some viewers ignore it: save them turned (through BMP, which keeps no tag), so every viewer shows the screen
@@ -455,7 +528,7 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
455
528
  return
456
529
  fi
457
530
  shots=$(find "$out" -name '*.png' | wc -l | tr -d ' ')
458
- echo "$1: flows $passed/$total passed, $shots screenshots in ${out#"$root"/}"
531
+ echo "$1: flows $passed/$total passed$([ "$flakies" = 0 ] || echo " ($flakies flaky)"), $shots screenshots in ${out#"$root"/}"
459
532
  a11y=$(grep -c . "$out/.a11y" 2> /dev/null || true)
460
533
  [ "${a11y:-0}" = 0 ] || echo " $1: $a11y accessibility warning$([ "$a11y" = 1 ] || echo s) on the flows' screens (controls without a label, tap areas under 48 dp): see the report"
461
534
  if [ "$shots" = 0 ]; then
@@ -514,8 +587,8 @@ quick() {
514
587
  # each one passes when the app's script passes, or when all its failures were already on the base branch
515
588
  if node scripts/amk/baseline.js lint > "$evidence/lint.log" 2>&1 &&
516
589
  node scripts/amk/baseline.js typecheck > "$evidence/typecheck.log" 2>&1 &&
517
- node scripts/amk/baseline.js test > "$evidence/test.log" 2>&1; then
518
- echo "quick: lint, typecheck and tests passed"
590
+ node scripts/amk/baseline.js test $([ "$related" = 0 ] || echo --related) > "$evidence/test.log" 2>&1; then
591
+ if [ "$related" = 0 ]; then echo "quick: lint, typecheck and tests passed"; else echo "quick: lint, typecheck and the tests related to this branch's changes passed"; fi
519
592
  # what didn't run (no such script, or an Expo app without ESLint yet), and failures the base branch already had
520
593
  cat "$evidence/lint.log" "$evidence/typecheck.log" "$evidence/test.log" |
521
594
  sed -n -E -e 's/^skip: / skipped: /p' -e 's/^(lint|typecheck|test): / \1: /p'
@@ -539,6 +612,7 @@ ios() {
539
612
  return
540
613
  fi
541
614
  [ "$build_only" = 1 ] || command -v maestro > /dev/null || { echo "ios: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
615
+ same_api ios || { status=1; return; }
542
616
  if [ "$no_build" = 0 ]; then
543
617
  # Expo apps without native folders in git: generate ios/ first
544
618
  if ! sh scripts/amk/prebuild.sh ios > "$evidence/prebuild-ios.log" 2>&1; then
@@ -600,6 +674,7 @@ ios() {
600
674
  echo "ios: release build for $d FAILED, see ${evidence#"$root"/}/ios-device-build.log"; status=1; return
601
675
  fi
602
676
  done
677
+ built_api ios
603
678
  fi
604
679
  unclaim "build-ios-$project"
605
680
  [ "$build_only" = 0 ] || { echo "ios: release build done"; return; }
@@ -889,6 +964,7 @@ android_ready() {
889
964
 
890
965
  android() {
891
966
  [ "$build_only" = 1 ] || command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
967
+ same_api android || { status=1; return; }
892
968
  case $(uname -s) in # where Android Studio puts the SDK by default
893
969
  Darwin) default_sdk=$HOME/Library/Android/sdk ;;
894
970
  MINGW* | MSYS* | CYGWIN*) default_sdk=${LOCALAPPDATA:-$HOME/AppData/Local}/Android/Sdk ;;
@@ -975,9 +1051,16 @@ android() {
975
1051
  fi
976
1052
  # a check build isn't a release: its mapping files and debug symbols stay off the crash reporters
977
1053
  set -- "$@" --init-script "$(cd scripts/amk && { pwd -W 2> /dev/null || pwd; })/no-symbol-upload.gradle"
1054
+ # Gradle would count the JavaScript bundled for the other API (mock or real) as up to date: it's bundled again
1055
+ # (React Native's Gradle plugin puts it in generated/*/react/<variant>/, before 0.71 in createBundle<Variant>JsAndAssets/)
1056
+ if [ "$(cat "$root/.amk/last-build-android" 2> /dev/null || echo real)" != "$api" ]; then
1057
+ rm -rf android/app/build/generated/assets/react android/app/build/generated/res/react \
1058
+ android/app/build/generated/assets/createBundle* android/app/build/generated/res/createBundle*
1059
+ fi
978
1060
  if ! (cd android && SENTRY_DISABLE_AUTO_UPLOAD=true ./gradlew "assemble${variant}Release" --no-daemon -q "$@") > "$evidence/android-build.log" 2>&1; then
979
1061
  echo "android: release build FAILED, see ${evidence#"$root"/}/android-build.log"; status=1; return
980
1062
  fi
1063
+ built_api android
981
1064
  fi
982
1065
  unclaim "build-android-$project"
983
1066
  [ "$build_only" = 0 ] || { echo "android: release build done"; return; }
@@ -1122,6 +1205,24 @@ if [ -n "$part" ] && [ -z "$(flow_files)" ]; then
1122
1205
  case $mode in ios | android | all) echo "verify: part $part has no flows: there are fewer flows than parts"; exit 0 ;; esac
1123
1206
  fi
1124
1207
 
1208
+ # a build that runs out of disk halfway (Xcode, Gradle and simulators fill disks) wastes the whole run: stop before it.
1209
+ # Not in CI, where a machine lasts one run
1210
+ case $mode in ios | android | all | build)
1211
+ if [ "$no_build" = 0 ] && [ -z "${CI:-}" ]; then
1212
+ free=$(node -e 'const s = require("fs").statfsSync("."); console.log(Math.floor(s.bavail * s.bsize / 2 ** 30))')
1213
+ case ${AMK_DISK_GB:-x} in *[!0-9]*) ;; *) free=$AMK_DISK_GB ;; esac
1214
+ need=5 what="a release build needs about 5"
1215
+ # a first iOS build (no pods or no build folder yet) downloads pods and Hermes and boots a simulator: about 6 GB measured
1216
+ if [ "$mode" != android ] && [ "$(uname -s)" = Darwin ] && { [ ! -d ios/Pods ] || [ ! -d ios/DerivedData ]; }; then
1217
+ need=8 what="a first iOS build (pods, Hermes and a simulator) needs about 8"
1218
+ fi
1219
+ if [ "$free" -lt "$need" ]; then
1220
+ echo "verify: only $free GB of disk is free here, and $what. Free some (Xcode's DerivedData, simulators and emulators you don't use, Gradle's caches), then run it again"
1221
+ exit 1
1222
+ fi
1223
+ fi ;;
1224
+ esac
1225
+
1125
1226
  case $mode in
1126
1227
  quick) quick ;;
1127
1228
  ios) ios ;;
@@ -1129,12 +1230,15 @@ case $mode in
1129
1230
  all) quick; ios; android ;;
1130
1231
  build) build ;;
1131
1232
  plan) plan; exit 0 ;;
1132
- *) echo "verify: unknown mode $mode (quick, ios, android, all, build or plan)"; exit 2 ;;
1233
+ approve) node scripts/amk/shots.js approve "$evidence"; exit $? ;;
1234
+ *) echo "verify: unknown mode $mode (quick, ios, android, all, build, plan or approve)"; exit 2 ;;
1133
1235
  esac
1134
1236
 
1135
- # the run's report, from every screen checked so far: other devices, parts and rounds add theirs
1237
+ # the run's report, from every screen checked so far: other devices, parts and rounds add theirs. First, the screenshots
1238
+ # that differ from the approved ones, which the report lists too
1136
1239
  case $mode in
1137
- ios | android | all) if [ -n "$(find "$evidence" -name .flows 2> /dev/null | head -n 1)" ] && node scripts/amk/report.js "$evidence" > /dev/null 2>&1; then
1240
+ ios | android | all) [ -z "$(find "$evidence" -name .flows 2> /dev/null | head -n 1)" ] || node scripts/amk/shots.js compare "$evidence" || true
1241
+ if [ -n "$(find "$evidence" -name .flows 2> /dev/null | head -n 1)" ] && node scripts/amk/report.js "$evidence" > /dev/null 2>&1; then
1138
1242
  echo "Report: ${evidence#"$root"/}/report.md (each flow's result, why one failed, and its screenshots)"
1139
1243
  fi ;;
1140
1244
  esac
@@ -3,9 +3,9 @@
3
3
  ## UI/UX level
4
4
 
5
5
  <!-- For a feature with screens: the level the user confirmed before the design, and the date (n/a without screens).
6
- Simple (the default): clean, minimal and functional. The app's own components and theme, or the platform's
7
- standard ones; a clear hierarchy with room around it; standard navigation, lists and forms; motion only where
8
- the platform gives it (screen transitions, pressed states).
6
+ Simple (the default): clean, minimal and functional. The app's own components and theme
7
+ (`docs/amk/design-system.md`), or the platform's standard ones; a clear hierarchy with room around it; standard
8
+ navigation, lists and forms; motion only where the platform gives it (screen transitions, pressed states).
9
9
  Mixed: Simple, with modern touches where they help: cards with rounded corners and soft shadows, an accent colour
10
10
  and icons, subtle transitions and feedback when something changes, skeletons while loading, friendly empty and
11
11
  error states.
@@ -24,8 +24,30 @@
24
24
 
25
25
  <!-- Screens, components, state, API calls, native changes (if any). Keep it to what the task needs. -->
26
26
 
27
+ ## API contract
28
+
29
+ <!-- Only for calls this feature needs that the backend doesn't have yet (n/a otherwise): the backend's OpenAPI file (its
30
+ path), or for each call its method, path and an example response (status and JSON). The typed client comes from it
31
+ (the project's generator, or types written from the examples), and the app's mock mode answers with the examples:
32
+ the variables in `.amk-mock` switch it on, the way the app reads its other settings, and `verify.sh --mock` builds
33
+ with them. An app without a mock mode gets one, approved with this design. A scenario checked only that way is
34
+ "passed (mock API)" until it runs against the backend. -->
35
+
27
36
  ## Files to change
28
37
 
38
+ ## Tests
39
+
40
+ <!-- How each scenario is checked, approved with the design. `node scripts/amk/specs.js tests <id>` lists what tests the
41
+ areas this touches. A Jest test is named after its scenario; a flow block is "# Scenario <n>: <name>" in .maestro/<id>.yaml;
42
+ manual steps only for what a flow can't do (a payment sheet, a push notification). -->
43
+
44
+ | Scenario | Check |
45
+ |---|---|
46
+ | <name> | <Jest: file "it() title", a flow block, or manual: steps> |
47
+
48
+ - To change or retire: <what checks a requirement this modifies or removes, and what happens to it>, or none
49
+ - Regression: <the command specs.js tests prints, with the flows no spec links to that this touches>
50
+
29
51
  ## Risks
30
52
 
31
53
  <!-- What could break; anything that needs a native rebuild or pod install. -->
@@ -1,7 +1,11 @@
1
- # Copy to .maestro/<id>.yaml. verify.sh runs it on iOS and Android and keeps the screenshots as evidence.
1
+ # `node scripts/amk/specs.js flow <id>` writes .maestro/<id>.yaml from this, with a block for each scenario. verify.sh
2
+ # runs it on iOS and Android and keeps the screenshots as evidence.
2
3
  # Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
3
4
  # Each scenario of specs/<id>/requirements.md gets a "# Scenario <n>: <name>" comment above its steps, an assertion for
4
5
  # its THEN and a screenshot: rn-check (in verify.sh quick) checks that, and Maestro's syntax, before any build.
6
+ # A screen that loads data also gets its empty and error states, each a scenario with a screenshot, where a flow can
7
+ # reach them: cleared data (launchApp: { clearState: true }) or an account without any for empty, and for no network
8
+ # "- setAirplaneMode: enabled" before the step and "disabled" after it (and in onFlowComplete, so a failure can't leave it on).
5
9
  # Steps several flows share (logging in, skipping onboarding, a permission prompt) and resetting test data go in
6
10
  # .maestro/subflows/ (specs/_templates/subflow.yaml), run with "- runFlow: subflows/<name>.yaml".
7
11
  # Test logins: ${MAESTRO_EMAIL}, ${MAESTRO_PASSWORD} and the like, set in .maestro/.env.local, which isn't committed.
@@ -0,0 +1,54 @@
1
+ # Plan
2
+
3
+ <!-- The features to plan all, then build. Only the planning session writes this file, on the `plan` branch, which is
4
+ never merged: each feature's spec reaches main with that feature's PR. `/m-feature build` reads it from there.
5
+ Approvals come in three layers, each a stop: this feature map; the stories, use cases and shared design; then the
6
+ detail, a batch at a time. `node scripts/amk/specs.js check --plan` checks it; `specs.js status` shows where each
7
+ feature stands and adds up the sizes. -->
8
+
9
+ Approved: <the layers approved so far, with their dates: feature map; stories and shared design>
10
+
11
+ ## Features
12
+
13
+ <!-- One row per feature, in build order.
14
+ Feature: its spec id (YYYYMMDD-<slug>, or the task's id). Goal: one line, what the user can do.
15
+ Depends on: the features it needs built first (planned, or already built), comma-separated, or none. A feature that
16
+ MODIFIES a requirement another planned feature ADDS depends on it.
17
+ Batch: about two or three days of building each, never before a feature it depends on.
18
+ Size: hours, rough (~6) until its tasks are written; then specs.js status counts them (a task is about an hour).
19
+ Status: drafting, questions open, ready for approval, approved, changes requested: <what>, or held: <waiting on
20
+ whom or what>. The build takes only approved features. -->
21
+
22
+ | # | Feature | Goal | Depends on | Batch | Size | Status |
23
+ |---|---|---|---|---|---|---|
24
+ | 1 | <id> | <what the user can do> | none | 1 | ~6 | drafting |
25
+
26
+ ## Shared design
27
+
28
+ <!-- What several features share, approved with the stories. In an app with features built already, only what's new.
29
+ Words the plan adds go here, not in docs/amk/glossary.md: docs on the plan branch never reach main, and the build
30
+ adds them to the glossary with the first feature that uses them. Same format: **<Term>**: what it is. _Not:_ <other words>. -->
31
+
32
+ - Data model:
33
+ - Navigation:
34
+ - Shared components:
35
+ - UI/UX level: <Simple, Mixed or Premium, as in specs/_templates/design.md>
36
+ - Dependencies to add:
37
+ - New words:
38
+
39
+ ## Approved up front
40
+
41
+ <!-- What the build does without asking, approved with the stories and shared design. -->
42
+
43
+ - Pushing a `feature/<id>` branch and opening a pull request for each feature
44
+ - Adding the dependencies the shared design lists
45
+ - The look: <the prototype's screenshots, or docs/amk/design-system.md>
46
+
47
+ ## Summaries
48
+
49
+ <!-- One per feature, for reviewing the plan without reading every spec: what the counts don't show. -->
50
+
51
+ ### <id>
52
+ - Assumptions: <what the spec assumes that nobody confirmed, or none>
53
+ - Risk: <low, medium or high, and why>
54
+ - Waiting on: <none, or whom, with specs/<id>/questions-<who>.md: until it's none, the feature is held, and the build won't take it>
@@ -6,7 +6,7 @@ Next step: <the very next action>
6
6
  Decisions: <decisions made in chat, and where they were written down>
7
7
  Open question: <anything waiting for an answer>
8
8
  Last verify: <lint / typecheck / test / iOS / Android results>
9
- Blocked: <none, or what's blocking>
9
+ Blocked: <none, or what's blocking and what would unblock it (Status keeps its words)>
10
10
  Notes: <anything the next session must know>
11
11
 
12
12
  ## Log
@@ -0,0 +1,29 @@
1
+ # <ID>: questions for <who>
2
+
3
+ **Why we ask:** <the decision these answers settle, and what waits on them>
4
+ **From:** <name>. **To:** <name and role>. **Answers by:** <date, if there is one>
5
+
6
+ ## Context
7
+
8
+ <!-- One short paragraph for someone who wasn't in the conversation: enough to answer well, not the whole story. -->
9
+
10
+ ## How to answer
11
+
12
+ Write your answer under each question. "I don't know" and partial answers help too: say what you're unsure of rather
13
+ than skipping it.
14
+
15
+ ## <Theme>
16
+
17
+ <!-- The most important question first: there may be only one reply. One question each, never two in one. A "why it
18
+ matters" line only where the question could be misread or answered too lightly. Group them under themes once there are
19
+ more than a handful. -->
20
+
21
+ ### 1. <Question>
22
+
23
+ _Why it matters: <what the answer decides>_
24
+
25
+ >
26
+
27
+ ## Anything else we should know?
28
+
29
+ >
@@ -1,12 +1,42 @@
1
1
  # <ID>: <title>
2
2
 
3
3
  Source: <link to the task in Excel, Trello or the task platform>
4
+ Mode: feature-by-feature
5
+
6
+ <!-- Mode: feature-by-feature (m-feature's approval stops), or plan-all for a feature of specs/plan.md, approved in
7
+ the plan and built by /m-feature build. -->
4
8
 
5
9
  ## Goal
6
10
 
7
11
  <!-- One or two sentences: what the user can do after this change, and why.
8
12
  One intent you can say in a sentence: if it needs "and also", it's two features. -->
9
13
 
14
+ ## User stories
15
+
16
+ <!-- Who it's for and why: a story for each kind of user or need (one is often enough). Its acceptance criteria are its
17
+ requirements' scenarios, so it names those rather than repeating them. Add Priority (must, should or could),
18
+ Depends on (another story, spec, API or permission) or Notes only when they say something the Goal doesn't. -->
19
+
20
+ ### US-1: <short title>
21
+ As a <kind of user, in the glossary's words>, I want <capability>, so that <benefit>.
22
+ - Requirements: <requirement names below>
23
+
24
+ ## Use cases
25
+
26
+ <!-- The journey step by step, and what can go differently. Each alternative flow and exception names the scenario that
27
+ tests it, and business rules name requirements. A one-screen feature has one short use case ("Alternative flows: none"). -->
28
+
29
+ ### UC-1: <the user's goal>
30
+ - Actors: <primary>; <others: another user, the backend, a payment provider, the OS>
31
+ - Stories: US-1
32
+ - Preconditions: <what's true before>
33
+ - Trigger: <what starts it>
34
+ - Main flow: 1. … 2. … 3. …
35
+ - Alternative flows: 2a. <variation> → Scenario: <name>
36
+ - Exceptions: 3a. <offline, a denied permission, a server error> → Scenario: <name>
37
+ - Postconditions: <what's true after, on success and on failure>
38
+ - Business rules: <requirement names>
39
+
10
40
  ## ADDED Requirements: <area>
11
41
 
12
42
  <!-- <area> names the living spec file specs/current/<area>.md (for example login or tasks); read it first.
@@ -50,3 +80,13 @@ The app SHALL <behavior>.
50
80
  ## Open questions
51
81
 
52
82
  <!-- The agent stops for answers before design starts. -->
83
+
84
+ ## Changes after approval
85
+
86
+ <!-- Empty until the requirements are approved (the commit "docs(spec): <id> approved"). Each change after that gets an
87
+ entry here and waits for the user's approval, as the requirements did:
88
+ ### <date>: <requirement name>
89
+ - Before → after: <the change, or `git diff <approval commit> -- specs/<id>/`>
90
+ - Why: <the reason>
91
+ - Impact: <the stories, scenarios, tasks, tests and flows that change, and what else could break>
92
+ - Approved: <who, and when> -->
@@ -1,6 +1,6 @@
1
1
  # <ID>: tasks
2
2
 
3
- Each task: about an hour of work, under ~300 changed lines, one commit. Each one names the requirement it serves and how it's checked. Its tests are written in the same task, not in a catch-up task at the end.
3
+ Each task: about an hour of work, under ~300 changed lines, one commit. Each is a thin slice through every layer it needs (screen, state, API call, test) that works and can be checked on its own, not one layer at a time; moving or renaming code that's there, to make the feature easy to add, comes first. Each names the requirement it serves, the tasks it waits on, and how it's checked. Its tests are written in the same task, not in a catch-up task at the end.
4
4
 
5
- - [ ] 1. <task> — for: <requirement name> — files: <paths> — check: <test, command or screen>
5
+ - [ ] 1. <task> — for: <requirement name> — after: <task numbers, or none> — files: <paths> — check: <test, command or screen>
6
6
  - [ ] 2.
@@ -0,0 +1,25 @@
1
+ # <ID, or "release <version>">: test report
2
+
3
+ Run: <date> · branch <branch> at <commit> · evidence in `.amk/evidence/<label>/` · <the verify.sh commands run>
4
+
5
+ **Verdict:** <Ready | Not ready: N blockers>
6
+
7
+ ## Scenarios
8
+
9
+ | Area › requirement › scenario | Status | Evidence |
10
+ |---|---|---|
11
+ | <area> › <requirement> › <scenario> | <passed, passed (mock API), failed, flaky, blocked, not run or no check> | <the test's name, the flow block and its screenshot, or why> |
12
+
13
+ ## Failures
14
+
15
+ <!-- Each one: steps to reproduce, expected (the THEN), actual (Maestro's message and the screen, or the test's error),
16
+ severity (blocker or should fix), and the evidence path. "None" when there are none. -->
17
+
18
+ ## Not run or blocked
19
+
20
+ <!-- Each with its reason. In a release, the user's acceptance of each too: who, and when. -->
21
+
22
+ ## Coverage gaps and tests to add
23
+
24
+ <!-- Scenarios with no check, changed logic without a test, old tests not changed or retired, tests deleted or
25
+ weakened, coverage under its floors; and the tests that would close each gap. -->