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
@@ -1,7 +1,7 @@
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/amk/`.
4
+ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity; 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
 
@@ -10,6 +10,8 @@ This project may also use other AI workflow frameworks (for example Superpowers,
10
10
  - Bare React Native {{RN_VERSION}} ({{RN_ARCH}}), React {{REACT_VERSION}}, {{LANGUAGE}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
11
11
  - Screens: {{SCREENS}}. Build every screen for each of them (`docs/amk/react-native.md`, Tablets and landscape); `verify.sh` checks each one.
12
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
+ - The app's own words, to use in names, specs and messages: `docs/amk/glossary.md`.
14
+ - How the app looks, which new screens follow (colours, type, spacing, controls): `docs/amk/design-system.md`.
13
15
 
14
16
  ## Commands
15
17
 
@@ -20,36 +22,50 @@ This project may also use other AI workflow frameworks (for example Superpowers,
20
22
  | iOS pods (after native dependency changes) | `sh scripts/amk/pod-install.sh` |
21
23
  | iOS build (simulator, no signing) | `sh scripts/amk/ios-build.sh` |
22
24
  | Android build | `cd android && ./gradlew assembleDebug` |
23
- | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
24
- | Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
25
- | React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
26
- | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
27
- | Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
25
+ | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); smoke flows only: `--tags smoke`; with the app's mock API: `--mock`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
26
+ | Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` prints a command per device, each for an `m-device-checker` subagent |
27
+ | After each task: lint, typecheck and the tests of the changed files | `sh scripts/amk/verify.sh quick --related` |
28
+ | React Native mistakes, flow problems and oversized files or functions in this branch's changes (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
29
+ | Specs and the plan: progress, checks, the tests of the areas a spec touches, flows, the living spec, planning | `node scripts/amk/specs.js status` (or `check`, `tests <id>`, `flow <id>`, `merge <id>`, `check --plan`, `plan-folder`, `import <file>`, `start [<id>]`) |
30
+ | Unattended (a person starts it; never skipping permission prompts): its PRs' review fixes, `amk-fix` bugs, then approved features | `node scripts/amk/autopilot.js [--reviews \| --bugs \| --features]`; first `node scripts/amk/autopilot.js check` |
31
+ | A feature's PR: checks (with a failure's log), review comments, auto-merge, main merged into stacked branches | `node scripts/amk/pr.js checks` (or `comments`, `automerge`, `forward`) |
32
+ | Check a release before tagging it (versions, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
28
33
  | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android [flavor]`, `sh scripts/amk/release-build.sh ios [scheme]` |
29
34
 
30
35
  ## Definition of done
31
36
 
32
37
  A task is done only when:
33
38
  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;
34
- 2. UI changes were checked with `sh scripts/amk/verify.sh all --spec <id>` on both iOS and Android, on each screen listed above, 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;
39
+ 2. UI changes were checked with `sh scripts/amk/verify.sh all --spec <id>` on iOS and Android, on each screen listed above, and you looked at the screenshots. Off a Mac it covers Android only: say in `progress.md` and the PR that iOS still needs a Mac, for a teammate to check before merging;
35
40
  3. the change stays inside the task's scope;
36
- 4. `specs/<id>/progress.md` is updated, when working from a spec.
41
+ 4. `specs/<id>/progress.md` is updated, when working from a spec;
42
+ 5. tests are assessed (added, changed or retired, or why none), the flows of the areas it touches ran, and what didn't run is listed with its reason, in `specs/<id>/test-report.md` (`m-test`).
37
43
 
38
44
  Never say a check passed unless you ran it in this session.
39
45
 
40
46
  ## Rules
41
47
 
42
48
  - Stay inside the task. Ask before touching unrelated files.
49
+ - Ask the user in rounds: every question you can ask now, each with the answer you recommend. With a question tool (`AskUserQuestion`, `request_user_input`, `question`), give each 2 to 4 options, the recommended one first and marked "(Recommended)", multiple choice where several can apply; suggestions too. Without one, number them, each worded so "yes" takes it. An approval is always a question of its own, never part of a round. The answers can open the next round. Look facts up in the code yourself; ask only for decisions. A question only someone else can answer (the client, a designer, the backend team) goes into `specs/<id>/questions-<who>.md` for the user to send; go on with the rest.
43
50
  - Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
44
51
  - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `Podfile`, `build.gradle`, `Info.plist`, `AndroidManifest.xml` or `.github/workflows/`.
45
52
  - Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
46
53
  - Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
47
- - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
48
- - When `rn-check` (in `verify.sh quick`) reports a problem (✗), show it to the user and let them choose, for each one: fix it, or keep the line with `// amk-ok <today's date>: <their reason>`. Never add an `amk-ok` on your own. One kept over two weeks ago comes back when its file changes again: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
54
+ - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`, and never throw away work that can't be brought back (uncommitted changes with `git checkout .` or `git restore .`, stashes with `git stash drop` or `clear`, unmerged commits with `git branch -D`): ask first. To undo your own edit to a file, `git checkout -- <that file>`.
55
+ - When `rn-check` (in `verify.sh quick`) reports a problem (✗), show it to the user and let them choose, for each one: fix it, or keep the line with `// amk-ok <today's date>: <their reason>`. Never add an `amk-ok`, or a cap in `.amk-size-caps`, on your own. One kept over two weeks ago comes back when its file changes: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
56
+ - Run shell commands one at a time, as the skills write them, not joined with `&&` or `;`: a tool asks about a joined line, or refuses it, as a whole. When one is refused, run its parts on their own before deciding anything is blocked.
49
57
  - After 2 failed attempts at the same fix, stop and report what you found.
50
58
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
51
59
  - Follow `docs/amk/react-native.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
52
60
 
61
+ ## Review guidelines
62
+
63
+ Reviews, AI reviewers' too, check these first (more in `m-review`):
64
+ - No secrets or personal data in code, logs or analytics; tokens only in the Keychain or Keystore.
65
+ - Nothing lost: older saved data still loads, and typed input survives errors, going offline and a restart.
66
+ - The code does what its spec says, on both platforms and each screen listed above, and its tests changed with it.
67
+ <!-- This app's own, a line each. -->
68
+
53
69
  ## Skills
54
70
 
55
71
  `react-native-best-practices`, `react-navigation`, `upgrading-react-native` (from Callstack, in `.agents/skills/`).
@@ -1,5 +1,7 @@
1
1
  # Signed release builds on Codemagic (codemagic.io). One-time setup for each app: docs/amk/codemagic.md
2
- # Both workflows start when a version tag is pushed (git push origin v1.2.0); you can also start them in Codemagic.
2
+ # Both release workflows start when a version tag is pushed (git push origin v1.2.0); you can also start them in Codemagic.
3
+ # The two test workflows give testers a build of main (Firebase App Distribution, TestFlight's internal testing): they
4
+ # start only from Codemagic until you turn on their triggering, below, for each merge to main (macOS minutes cost).
3
5
  # Build numbers are set on the build machine only (one more than the store's latest), so the repo never needs a bump for them.
4
6
  workflows:
5
7
  android-release:
@@ -87,3 +89,82 @@ workflows:
87
89
  app_store_connect:
88
90
  auth: integration
89
91
  submit_to_testflight: true
92
+
93
+ android-test:
94
+ name: Android test build (Firebase App Distribution)
95
+ instance_type: mac_mini_m2
96
+ max_build_duration: 60
97
+ # for a build of each merge to main, uncomment:
98
+ # triggering:
99
+ # events:
100
+ # - push
101
+ # branch_patterns:
102
+ # - pattern: main
103
+ # include: true
104
+ # source: true
105
+ # cancel_previous_builds: true
106
+ environment:
107
+ android_signing:
108
+ - upload_keystore
109
+ groups:
110
+ - firebase_credentials # FIREBASE_SERVICE_ACCOUNT: a service account with the Firebase App Distribution Admin role
111
+ node: 24
112
+ java: 17
113
+ scripts:
114
+ - name: Install dependencies
115
+ script: sh scripts/amk/install-deps.sh
116
+ - name: Build the signed APK
117
+ script: |
118
+ sh scripts/amk/prebuild.sh android # Expo apps without android/ in git
119
+ echo "sdk.dir=$ANDROID_SDK_ROOT" > android/local.properties
120
+ sed -i '' -E "s/versionCode( =)? [0-9]+/versionCode\1 $BUILD_NUMBER/" android/app/build.gradle*
121
+ cd android && ./gradlew assembleRelease \
122
+ -Pandroid.injected.signing.store.file="$CM_KEYSTORE_PATH" \
123
+ -Pandroid.injected.signing.store.password="$CM_KEYSTORE_PASSWORD" \
124
+ -Pandroid.injected.signing.key.alias="$CM_KEY_ALIAS" \
125
+ -Pandroid.injected.signing.key.password="$CM_KEY_PASSWORD"
126
+ artifacts:
127
+ - android/app/build/outputs/apk/release/*.apk
128
+ publishing:
129
+ firebase:
130
+ firebase_service_account: $FIREBASE_SERVICE_ACCOUNT
131
+ android:
132
+ app_id: 1:000000000000:android:0000000000000000 # Firebase console > Project settings > your Android app's App ID
133
+ groups:
134
+ - testers
135
+ artifact_type: apk
136
+
137
+ ios-test:
138
+ name: iOS test build (TestFlight, internal testing)
139
+ instance_type: mac_mini_m2
140
+ max_build_duration: 60
141
+ # for a build of each merge to main, uncomment the same triggering as android-test
142
+ integrations:
143
+ app_store_connect: codemagic
144
+ environment:
145
+ ios_signing:
146
+ distribution_type: app_store # Firebase for iOS takes ad_hoc builds instead, for registered devices only
147
+ bundle_identifier: {{IOS_BUNDLE_ID}}
148
+ vars:
149
+ APP_STORE_APPLE_ID: 0 # App Store Connect > the app > App Information > Apple ID
150
+ node: 24
151
+ xcode: latest
152
+ cocoapods: default
153
+ scripts:
154
+ - name: Install dependencies
155
+ script: sh scripts/amk/install-deps.sh && sh scripts/amk/prebuild.sh ios && sh scripts/amk/pod-install.sh
156
+ - name: Use the signing files, for internal testers only
157
+ script: |
158
+ xcode-project use-profiles --custom-export-options='{"testFlightInternalTestingOnly": true}'
159
+ - name: Build the signed ipa
160
+ script: |
161
+ if last=$(app-store-connect get-latest-build-number "$APP_STORE_APPLE_ID") && [ -n "$last" ]; then build=$((last + 1)); else build=$BUILD_NUMBER; fi
162
+ (cd ios && agvtool new-version -all "$build")
163
+ workspace=$(ls -d ios/*.xcworkspace | head -1)
164
+ xcode-project build-ipa --workspace "$workspace" --scheme "$(basename "$workspace" .xcworkspace)"
165
+ artifacts:
166
+ - build/ios/ipa/*.ipa
167
+ publishing:
168
+ app_store_connect:
169
+ auth: integration
170
+ submit_to_testflight: true
@@ -30,6 +30,14 @@ You need admin rights in the Codemagic team (or your personal account). Menus ar
30
30
 
31
31
  Then start `android-release` by hand and check that the signed `.aab` appears in the build's artifacts. Do the same for `ios-release`.
32
32
 
33
+ ## Test builds for testers
34
+
35
+ `android-test` builds a signed APK and sends it to Firebase App Distribution; `ios-test` builds a signed ipa for TestFlight's internal testing. They start only by hand until you uncomment their `triggering` (a build of each merge to `main`, which costs macOS minutes). Once, for Android:
36
+ 1. In the Firebase console, add the Android app (its package name) if it isn't there, and copy its App ID (Project settings) into `app_id` in `codemagic.yaml`. Under App Distribution, make a group of testers named `testers`, or change `groups` to yours.
37
+ 2. In Google Cloud, a service account with the **Firebase App Distribution Admin** role, its JSON key in a Codemagic variable `FIREBASE_SERVICE_ACCOUNT`, in a group named `firebase_credentials`, marked Secret.
38
+
39
+ iOS uses the same key and App Store profile as `ios-release`; the build reaches TestFlight's internal testers only. For Firebase on iOS instead, it needs an ad hoc profile with each tester's device registered: `distribution_type: ad_hoc`, and a `firebase: ios:` block beside Android's.
40
+
33
41
  ## Apps with more than one target
34
42
 
35
43
  When one repo ships several apps (for example a main app and a kiosk app, or product flavors), copy the workflow once per app. In each copy, set the bundle ID, the scheme (iOS) and the Gradle task and package (Android).
@@ -0,0 +1,15 @@
1
+ # Design system
2
+
3
+ <!-- How the app looks, so every new screen matches the ones it has. Facts from the app's theme and shared components,
4
+ each with the file it comes from, not advice. m-onboard drafts it; something new (a colour, a component) is added here
5
+ and to the theme before a screen uses it.
6
+ - Theme: the file(s) holding colours, type and spacing (`src/theme/…`), and how a screen reads them (a hook, an import).
7
+ - Colours, by role: background, surface (cards, sheets), text, muted text, primary (the main action), error, success,
8
+ border. Dark mode's too, if the app has it.
9
+ - Type: the font(s), and the size and weight of each role in use (title, heading, body, caption, button).
10
+ - Spacing and shape: the spacing steps (4, 8, 16, …), corner radius, shadows.
11
+ - Controls: the primary and secondary button, text field, list row, and the shared components that draw them.
12
+ - Icons: the set (library) and its sizes; images and illustrations, if the app has them.
13
+ - Motion: what animates and for how long, and what happens with Reduce Motion on.
14
+ - Voice: how the app's texts speak (formal or casual, "you") and the words its buttons use (Save, Done, …).
15
+ -->
@@ -0,0 +1,12 @@
1
+ # Glossary
2
+
3
+ <!-- The app's own words: what its users and its business talk about (an Order, a Visit, a Plan), so agents and people
4
+ name things the same way in code, specs, flows and messages, and say in one word what would take a sentence.
5
+ - One entry per term: the word, what it is in one or two sentences (what it is, not how the code does it), and the other
6
+ words people use for it that this app doesn't, when there are any (no "not" line otherwise).
7
+ - Only the app's own concepts: not general programming terms (a cache, a hook, a retry).
8
+ - When two words mean the same thing, pick one and list the other under "not".
9
+
10
+ **<Term>**: what it is, in one or two sentences.
11
+ _Not:_ <the other words used for it>.
12
+ -->
@@ -14,6 +14,11 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
14
14
  - Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
15
15
  - For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS, or `OnBackPressedDispatcher` in native code.
16
16
  - With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
17
+ - New screens use the app's design system (`docs/amk/design-system.md`): its colours, type sizes, spacing, radius and shared controls. Something it doesn't have (a colour, a component) goes into it and the theme first, not into one screen.
18
+ - Every field has a visible label; a placeholder only shows the format (`DD/MM/YYYY`), never the label, which disappears once the user types.
19
+ - The keyboard and autofill fit the field: `keyboardType` (`email-address`, `number-pad`, `phone-pad`), `autoComplete` (`email`, `password`, `one-time-code`, `postal-code`, …) and on iOS `textContentType`, `autoCapitalize="none"` for emails and codes, `secureTextEntry` for passwords, and `returnKeyType` with `onSubmitEditing` going to the next field.
20
+ - A field is checked when the user leaves it, then as they type; its error shows under it and says what to do. The submit button is disabled only while the request runs.
21
+ - A button that starts a request shows it's working without changing size, ignores a second tap until the request ends, then shows the result or the error: never a success message when nothing was saved. A destructive action asks first, or can be undone.
17
22
  - Lists that grow with the user's data scroll (`FlatList`, or the list component the app already uses), and so does any screen taller than a small phone.
18
23
  - At the largest system text size, text wraps instead of being cut off: no fixed heights on views that hold text. Don't turn off font scaling (`allowFontScaling={false}`) to make a layout fit.
19
24
  - Messages that appear after an action, such as a form error, are read out by screen readers. On Android, show the message in a view with `accessibilityLiveRegion="polite"`: Android 16 deprecated announcements. On iOS, announce it with `AccessibilityInfo.announceForAccessibility`.
@@ -23,7 +28,7 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
23
28
 
24
29
  ## Tablets and landscape
25
30
 
26
- `AGENTS.md` lists the screens this app supports: phones and tablets, portrait and landscape. Build every screen for each of them, and skip what isn't listed. `verify.sh` checks each one.
31
+ `AGENTS.md` lists which screens this app supports, out of phones and tablets, portrait and landscape. Build every screen for each one it lists, and skip the others. `verify.sh` checks each one.
27
32
 
28
33
  - One set of screens for every device: layouts adapt to the window. No separate tablet copies of screens, and no phone-width column centered on a tablet.
29
34
  - Read the window size with `useWindowDimensions()`, which updates on rotation, split view and resizable windows. `Dimensions.get` read once at startup goes stale.
@@ -56,6 +61,11 @@ These changed after most AI training data was written: check them instead of wri
56
61
  - List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
57
62
  - Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
58
63
  - Component tests use React Native Testing Library (`@testing-library/react-native`) and find elements as users and screen readers do, by role, label or text (`getByRole('button', { name: 'Save' })`), rather than relying on snapshots.
64
+ - A test checks what a user or a caller sees, through the public interface (rendered text and roles, a hook's result, a function's return), so a refactor that keeps the behavior keeps the test passing.
65
+ - Mock only what the app doesn't own: the network, storage, native modules, time and randomness. Not the app's own components, hooks or modules: a test of mocks passes whatever the code does.
66
+ - Expected values come from the spec or a worked example (`expect(total([10, 5])).toBe(15)`), never computed the way the code computes them, or the test can't fail.
67
+ - A bug fix comes with a test that failed before the fix.
68
+ - A test that checks a spec's scenario is named after it, word for word (`it('Rejects an expired code', …)`), so `specs.js tests` and reviews can tell what checks each scenario.
59
69
 
60
70
  ## Platform guidelines and accessibility
61
71
 
@@ -71,6 +81,8 @@ From Apple's Human Interface Guidelines, Android's design and app quality guidel
71
81
  - Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `ActionSheetIOS`, `Switch`); a custom one gets the same role, state and size.
72
82
  - Dark mode: colors come from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
73
83
  - Data screens have loading, empty (why, and what to do next), error (what failed, with Retry) and content states. A message the user has to read doesn't vanish on a timer, and screen readers announce it.
84
+ - Nothing on a screen is invented: texts, numbers, ratings, reviews, user counts and images come from the spec, the app's data or the client. Where one is missing, a placeholder the PR lists (and `specs/<id>/questions-<who>.md` asks for), never a made-up figure, quote or rating. Brand colours, fonts and logos come from the project or the client, never from memory. A prototype's mock data stays in its mock-data file.
85
+ - Texts say what things do, in the app's words (`docs/amk/glossary.md`), not marketing filler (seamless, effortless, unlock your potential); icons come from the app's icon set, not emoji.
74
86
  - Reduce Motion: with it on, nothing loops or moves for decoration. Don't pass `ReduceMotion.Never` to Reanimated for decoration; with `Animated` or Lottie, read `AccessibilityInfo.isReduceMotionEnabled()` and the `reduceMotionChanged` event, and fade or stop instead.
75
87
  - iOS 26: use native headers and tab bars (React Navigation's native stack and native tabs), which iOS draws in its current style; don't draw imitation glass behind content, or opt out with `UIDesignRequiresCompatibility` (builds with the iOS 27 SDK ignore it). Nothing the user needs sits under a floating tab bar, button or footer: scroll content gets bottom padding for it.
76
88
  - Haptics only for success, error or a selection, never as the only feedback, through the app's haptics library; not `Vibration.vibrate`.
@@ -88,6 +100,15 @@ What App Store review and Google Play reject. `node scripts/amk/release-check.js
88
100
  - Android foreground services declare their type (`android:foregroundServiceType`) and its `FOREGROUND_SERVICE_<TYPE>` permission, and each type is declared in Play Console.
89
101
  - From 1 February 2027, Google Play takes updates to apps targeting Android 15 or later only with 16 KB page size support, which React Native has from 0.77.
90
102
 
103
+ ## Texts in several languages
104
+
105
+ In an app with language files (JSON under `i18n/`, `locales/`, `translations/` or `lang/`), every text a change adds or changes goes into each language's file, under the same key:
106
+ - the source language as written;
107
+ - each other language as a machine translation, listed in `specs/<id>/translations.md` (the key, the language, the text) for a translator to review, and marked there once reviewed. `m-release` lists those still waiting;
108
+ - where a translation service (Lokalise, Crowdin, Phrase and the like) syncs the language files, change only the source language, and list the new keys in `translations.md` for the service instead.
109
+
110
+ `rn-check` warns about a key the branch left out of one language's file.
111
+
91
112
  ## TypeScript
92
113
 
93
114
  - Keep the checks `tsconfig.json` has. Don't loosen them, or get past one with `any`, `@ts-ignore` or a non-null `!`.
@@ -6,4 +6,36 @@
6
6
  - Run at most 2 or 3 agents in parallel per person.
7
7
  - Don't use "skip permissions", "YOLO" or auto-run modes in any tool.
8
8
  - Keep secrets out of the repo folder; inject them at run time.
9
- - Review the metrics and the `m-learn` changes (`git log --grep 'chore(learn)'`) once a month. Re-check `AGENTS.md` and `docs/amk/` after every React Native, Xcode or Android Gradle Plugin upgrade, and after switching AI models.
9
+ - Review the metrics (`node scripts/amk/metrics.js`) and the `m-learn` changes (`git log --grep 'chore(learn)'`) once a month, and run `m-learn review` for what reviews keep finding. Re-check `AGENTS.md` and `docs/amk/` after every React Native, Xcode or Android Gradle Plugin upgrade, and after switching AI models.
10
+
11
+ ## Settings for the agents
12
+
13
+ - Feature mode: ask
14
+ <!-- What /m-feature does, given no task, when docs/amk/product.md plans several features without a spec: ask (offer
15
+ both), feature-by-feature (each with its own approvals), or plan-all (plan every feature first, approved in
16
+ batches, then /m-feature build). -->
17
+ - Reviewers: team
18
+ <!-- team: another person approves each pull request, and the build turns on auto-merge (pr.js automerge), so it
19
+ merges once approved and green; only where main requires an approval, else a person merges it. solo: GitHub doesn't let you approve your own pull request, so you review it and
20
+ add the amk-ready label, which turns on auto-merge (.github/workflows/amk-ready.yml); a new commit takes the
21
+ label off again. Create the label once: gh label create amk-ready. Branch protection: docs/branch-protection.md in
22
+ the kit. -->
23
+ - Merge method:
24
+ <!-- merge, squash or rebase, for auto-merge; empty: the first the repository allows, in that order. -->
25
+ - Open PRs before the build waits: 5
26
+ <!-- node scripts/amk/autopilot.js starts no new planned feature while this many of the plan's pull requests wait for
27
+ review. -->
28
+ - First PR review: off
29
+ <!-- on: once the plan's first pull request is open, autopilot.js builds nothing new until a person approves or merges it,
30
+ so a wrong pattern doesn't spread over every feature. -->
31
+ - Blocked questions as issues: off
32
+ <!-- on: a feature the unattended build blocks gets a GitHub issue "Blocked: <id>" with its question, and m-continue
33
+ reads the answer there. Off by default: clients often watch their private repositories, and agents don't message
34
+ clients. -->
35
+ - Sentry adds amk-fix: off
36
+ <!-- on: an issue Sentry's GitHub integration labels amk-fix (an alert rule can) joins the overnight bug queue
37
+ (autopilot.js), like one a team member labels. Off: only people who can label issues queue bugs. -->
38
+ - Variables for unattended runs: none
39
+ <!-- autopilot.js gives each session only PATH, HOME, the tool's sign-in, GH_TOKEN, what builds need (LANG, JAVA_HOME,
40
+ ANDROID_HOME, SSH_AUTH_SOCK, a package registry token, proxies) and the AMK_ settings. Names of other variables
41
+ the app's build needs, comma-separated (autopilot.js check shows a build failing without them). -->
@@ -1,4 +1,4 @@
1
- // Generates per-tool permissions, hooks and subagents from .rulesync/. Run: npx -y rulesync@27.0.0 generate
1
+ // Generates per-tool permissions, hooks and subagents from .rulesync/. Run: npx -y rulesync@27.0.0 generate && node scripts/amk/tool-configs.js
2
2
  // Commit the generated files. Rules and skills don't go through rulesync (AGENTS.md and .agents/skills are shared).
3
3
  {
4
4
  "targets": ["claudecode", "codexcli", "antigravity-ide", "antigravity-cli"],
@@ -0,0 +1,106 @@
1
+ #!/usr/bin/env node
2
+ // The AI jobs in CI (.github/workflows/amk-ai-review.yml and amk-ai-deps.yml, added with --ci github,ai): who may start
3
+ // one, and when it stops. GitHub's own variables (GITHUB_EVENT_PATH, GITHUB_REPOSITORY, GITHUB_WORKFLOW_REF, …) and gh
4
+ // (GH_TOKEN) tell it the rest.
5
+ // node scripts/amk/ai-job.js gate <job> go=true or go=false, as a GitHub Actions output, and why:
6
+ // - only a person with write access to the repository starts one; for the dependency job (deps), Dependabot or
7
+ // Renovate too. Never the AI jobs' own app or another bot, and never a commit an AI job's fix made (its
8
+ // "AMK-Agent-Fix: <job>" trailer)
9
+ // - not while the job is paused: an open issue "AI job paused: <job>" (close it to resume the job)
10
+ // - the loop guard: not after 3 of its fix commits in a row on the branch, nor after 6 runs in the last hour; the
11
+ // dependency job once per failed CI run
12
+ // - nothing when docs/amk/team-process.md, where its settings are, can't be read
13
+ // node scripts/amk/ai-job.js after <job> <result> after a run that went: a third failure in a row (a timeout or a
14
+ // cancel counts; a run that didn't go doesn't) pauses the job, opening that issue
15
+ 'use strict';
16
+ const fs = require('fs');
17
+ const path = require('path');
18
+ const { spawnSync } = require('child_process');
19
+
20
+ const ROOT = path.join(__dirname, '..', '..');
21
+ const BOTS = { deps: ['dependabot[bot]', 'renovate[bot]'] };
22
+ const IN_A_ROW = 3;
23
+ const PER_HOUR = 6;
24
+ const trailer = job => new RegExp(`^AMK-Agent-Fix: ${job}\\b`, 'm');
25
+ const paused = job => `AI job paused: ${job}`;
26
+
27
+ // gh, as JSON or text; a test passes its own
28
+ const ghReal = args => {
29
+ const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 2 ** 26, timeout: 60000 });
30
+ if (r.status !== 0) return null;
31
+ try { return JSON.parse(r.stdout); } catch { return r.stdout.trim(); }
32
+ };
33
+ function context(env = process.env, gh = ghReal) {
34
+ let event = {};
35
+ try { event = JSON.parse(fs.readFileSync(env.GITHUB_EVENT_PATH, 'utf8')); } catch {}
36
+ return { event, gh, env, repo: env.GITHUB_REPOSITORY, workflow: path.basename(String(env.GITHUB_WORKFLOW_REF || '').split('@')[0]), now: Date.now(),
37
+ settings: fs.existsSync(path.join(ROOT, 'docs/amk/team-process.md')) };
38
+ }
39
+
40
+ function gate(job, c) {
41
+ const no = why => ({ go: false, why });
42
+ if (!c.settings) return no('docs/amk/team-process.md can\'t be read, so the job does nothing');
43
+ const open = c.gh(['issue', 'list', '--repo', c.repo, '--state', 'open', '--search', `"${paused(job)}" in:title`, '--json', 'title']);
44
+ if (!Array.isArray(open)) return no('its state can\'t be read (gh), so the job does nothing');
45
+ if (open.some(i => i.title === paused(job))) return no(`paused: close the issue "${paused(job)}" to resume it`);
46
+ // who started it, and on which branch and commit
47
+ const run = c.event.workflow_run;
48
+ const pr = c.event.pull_request || {};
49
+ const who = run ? (run.triggering_actor || run.actor || {}).login : (c.event.sender || {}).login;
50
+ const branch = run ? run.head_branch : (pr.head || {}).ref;
51
+ const sha = run ? run.head_sha : (pr.head || {}).sha;
52
+ if (!who) return no('nobody started it');
53
+ if (run && (run.head_repository || {}).full_name !== c.repo) return no('a change from another repository');
54
+ if (/\[bot\]$/.test(who) && !(BOTS[job] || []).includes(who)) return no(`started by ${who}, a bot`);
55
+ if (!/\[bot\]$/.test(who)) {
56
+ const p = c.gh(['api', `repos/${c.repo}/collaborators/${encodeURIComponent(who)}/permission`, '--jq', '.permission']);
57
+ if (!['admin', 'maintain', 'write'].includes(p)) return no(`${who} doesn't have write access to the repository`);
58
+ }
59
+ if (job === 'deps' && !(BOTS.deps || []).includes(who)) return no(`not a dependency update (started by ${who})`);
60
+ // the branch's latest commits: an AI fix's own commit doesn't start a job, and 3 in a row stop it
61
+ const commits = (sha && c.gh(['api', `repos/${c.repo}/commits?sha=${sha}&per_page=${IN_A_ROW + 1}`, '--jq', '[.[].commit.message]'])) || [];
62
+ if (commits.length && trailer('[a-z-]+').test(commits[0]) && job !== 'deps') return no('the latest commit is an AI job\'s fix');
63
+ let row = 0;
64
+ while (row < commits.length && trailer(job).test(commits[row])) row++;
65
+ if (row >= IN_A_ROW) return no(`${row} of its fix commits in a row on ${branch}: a person takes it from here`);
66
+ if (job === 'deps' && commits.some(m => m.includes(`(CI run ${run.id})`))) return no(`CI run ${run.id} was fixed once already`);
67
+ const since = new Date(c.now - 3600e3).toISOString();
68
+ const recent = c.gh(['run', 'list', '--repo', c.repo, '--workflow', c.workflow, '--created', `>=${since}`, '--json', 'databaseId', '--limit', '50']) || [];
69
+ if (recent.length > PER_HOUR) return no(`${recent.length} runs in the last hour: it waits`);
70
+ return { go: true, why: `started by ${who} on ${branch}` };
71
+ }
72
+
73
+ // after a run that went: a third failure in a row (runs that didn't go left out) pauses the job
74
+ function after(job, result, c) {
75
+ if (result === 'success') return { paused: false };
76
+ const runs = c.gh(['run', 'list', '--repo', c.repo, '--workflow', c.workflow, '--status', 'completed', '--json', 'databaseId', '--limit', '10']) || [];
77
+ const results = [];
78
+ for (const r of runs) {
79
+ if (String(r.databaseId) === String(c.env.GITHUB_RUN_ID)) continue;
80
+ const jobs = (c.gh(['run', 'view', String(r.databaseId), '--repo', c.repo, '--json', 'jobs']) || {}).jobs || [];
81
+ const j = jobs.find(x => x.name === job);
82
+ if (!j || j.conclusion === 'skipped') continue;
83
+ results.push(j.conclusion);
84
+ if (results.length >= IN_A_ROW - 1) break;
85
+ }
86
+ if (results.length < IN_A_ROW - 1 || results.some(r => r === 'success')) return { paused: false };
87
+ const body = `The AI job "${job}" failed ${IN_A_ROW} times in a row (the last one: ${result}), so it paused itself: it starts no run until this issue is closed. Look at its runs (the Actions tab, workflow ${c.workflow}), fix what fails, then close this issue to resume it.`;
88
+ c.gh(['issue', 'create', '--repo', c.repo, '--title', paused(job), '--body', body]);
89
+ return { paused: true };
90
+ }
91
+
92
+ module.exports = { gate, after, context, IN_A_ROW, PER_HOUR };
93
+
94
+ if (require.main === module) {
95
+ const [cmd, job, result] = process.argv.slice(2);
96
+ if (!['gate', 'after'].includes(cmd) || !job) { console.error('usage: node scripts/amk/ai-job.js gate <job> | after <job> <result>'); process.exit(2); }
97
+ const c = context();
98
+ if (cmd === 'gate') {
99
+ const g = gate(job, c);
100
+ console.error(`${job}: ${g.go ? 'goes' : 'does nothing'}: ${g.why}`);
101
+ console.log(`go=${g.go}`);
102
+ } else {
103
+ const a = after(job, result || 'failure', c);
104
+ console.log(a.paused ? `${job} paused itself after ${IN_A_ROW} failures in a row: an issue says so` : `${job}: ${result}`);
105
+ }
106
+ }