agentic-mobile-kit 0.7.18 → 0.7.19

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 (27) hide show
  1. package/README.md +3 -3
  2. package/lib/init.js +2 -2
  3. package/package.json +1 -1
  4. package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
  5. package/stacks/react-native/expo/AGENTS.md +4 -1
  6. package/stacks/react-native/expo/docs/amk/expo.md +11 -0
  7. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +10 -11
  8. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
  9. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +1 -1
  10. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +13 -9
  11. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +8 -5
  12. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +7 -8
  13. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +4 -1
  14. package/stacks/react-native/template/.github/pull_request_template.md +3 -1
  15. package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
  16. package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
  17. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +1 -1
  18. package/stacks/react-native/template/AGENTS.md +4 -1
  19. package/stacks/react-native/template/docs/amk/design-system.md +15 -0
  20. package/stacks/react-native/template/docs/amk/glossary.md +12 -0
  21. package/stacks/react-native/template/docs/amk/react-native.md +11 -0
  22. package/stacks/react-native/template/scripts/amk/guard.js +22 -1
  23. package/stacks/react-native/template/scripts/amk/rn-check.js +9 -0
  24. package/stacks/react-native/template/specs/_templates/design.md +3 -3
  25. package/stacks/react-native/template/specs/_templates/flow.yaml +3 -0
  26. package/stacks/react-native/template/specs/_templates/questions.md +29 -0
  27. package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
package/README.md CHANGED
@@ -18,7 +18,7 @@ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, O
18
18
 
19
19
  2. Run it again and choose **Check this project and machine**. It lists each problem with its fix.
20
20
 
21
- 3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md` and `conventions.md`, asks what the code can't show, and writes them once you approve. Then commit and open a PR.
21
+ 3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md`, `conventions.md`, `glossary.md` and `design-system.md`, asks what the code can't show, and writes them once you approve. Then commit and open a PR.
22
22
 
23
23
  Each choice prints the command it runs, for scripts and CI: `init` (with `--ci github`, `--ci codemagic` or `--tools claude,codex,antigravity`, and `--new bare` or `--new expo` to create the app first), `sync`, `doctor` and `uninstall`. `--help` lists every option.
24
24
 
@@ -28,12 +28,12 @@ Each choice prints the command it runs, for scripts and CI: `init` (with `--ci g
28
28
 
29
29
  | You want to | Run | What happens |
30
30
  |---|---|---|
31
- | Describe the app for agents | `m-onboard` | Reads the whole project, drafts the product, tech, structure and conventions files in `docs/amk/`, asks what the code can't show, and writes them once you approve. Run it after installing, and again after big changes. |
31
+ | Describe the app for agents | `m-onboard` | Reads the whole project, drafts the product, tech, structure, conventions, glossary and design-system files in `docs/amk/`, asks what the code can't show, and writes them once you approve. Run it after installing, and again after big changes. |
32
32
  | Think a problem through | `m-explore` | The agent reads the code, explains how it works today and lays out options with trade-offs. It never edits code. |
33
33
  | Agree on an idea before building it | `m-prototype` | Concepts as clickable HTML mocks when how it should work is still open, then real screens with mock data on a throwaway branch, with screenshots and a video for the demo. The agreed requirements go to `m-feature` |
34
34
  | Build a feature | `m-feature` | Requirements → you approve → design and tasks → you approve → one task at a time with tests → device checks with screenshots → living spec updated → review → PR |
35
35
  | Make a small change | `m-change` | Checks it's small, then shows the code, living-spec and docs changes for one approval, makes them together and runs the checks |
36
- | Fix a bug | `m-bugfix` | Reproduces the bug, proves it with a failing test, finds the root cause, then makes the smallest fix |
36
+ | Fix a bug | `m-bugfix` | Makes the bug fail on demand (a test, or a Maestro flow on the device), lists the likely causes, finds the root cause, then makes the smallest fix |
37
37
  | Stop, or switch tool or machine | `m-pause` | Writes a handoff in the spec, commits and pushes |
38
38
  | Carry on anywhere | `m-continue` | Reads the spec and handoff, then picks up at the next step |
39
39
  | Review a branch | `m-review` | Checks the work against the spec (complete, correct, coherent) and covers both platforms, error states, security and native changes |
package/lib/init.js CHANGED
@@ -15,7 +15,7 @@ const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
15
15
  // files with {{PLACEHOLDERS}} filled in from the project (the last three say what the CI chosen does, or that none does)
16
16
  const FILLED = ['AGENTS.md', 'codemagic.yaml', 'scripts/amk/set-version.sh', 'docs/amk/team-process.md', '.githooks/pre-commit'];
17
17
  // docs each team rewrites for its app: sync replaces them only while they're untouched, and never merges into them
18
- const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/amk/${n}.md`);
18
+ const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions', 'glossary', 'design-system'].map(n => `docs/amk/${n}.md`);
19
19
  const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
20
20
  // the app's own ESLint skips the kit's scripts: they follow the kit's style, not each app's rules
21
21
  const ESLINT_IGNORE = 'scripts/amk/';
@@ -1046,7 +1046,7 @@ function printSummary({ report, warnings = [], values, tools, ci, generated, gen
1046
1046
  for (const w of warnings) log(` ! ${w}`);
1047
1047
  if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
1048
1048
  log('\nNext steps:');
1049
- log(' 1. In your AI tool, run m-onboard (/m-onboard, or $m-onboard in Codex). It drafts docs/amk/product.md, tech.md,\n structure.md and conventions.md from the code, asks what the code can\'t show, and writes them once you approve.');
1049
+ log(' 1. In your AI tool, run m-onboard (/m-onboard, or $m-onboard in Codex). It drafts docs/amk/product.md, tech.md,\n structure.md, conventions.md, glossary.md and design-system.md from the code, asks what the code can\'t show, and writes them once you approve.');
1050
1050
  log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
1051
1051
  const more = [
1052
1052
  ci.includes('github') && 'Turn on branch protection for main: see docs/branch-protection.md in the kit repo.',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.7.18",
3
+ "version": "0.7.19",
4
4
  "description": "One setup for AI-assisted development of React Native apps, bare or Expo: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -9,6 +9,12 @@
9
9
  "git push --force*": "deny",
10
10
  "git push -f*": "deny",
11
11
  "git clean -f*": "deny",
12
+ "git checkout .": "deny",
13
+ "git checkout -- .": "deny",
14
+ "git restore .": "deny",
15
+ "git stash drop*": "deny",
16
+ "git stash clear*": "deny",
17
+ "git branch -D*": "deny",
12
18
  "git commit --no-verify*": "deny",
13
19
  "xcrun simctl erase*": "deny",
14
20
  "npm install *": "ask",
@@ -11,6 +11,8 @@ This project may also use other AI workflow frameworks (for example Superpowers,
11
11
  - `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git (Continuous Native Generation). The kit's scripts generate them when they need them.
12
12
  - Screens: {{SCREENS}}. Build every screen for each of them (`docs/amk/expo.md`, Tablets and landscape); `verify.sh` checks each one.
13
13
  - 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`.
14
+ - The app's own words, to use in names, specs and messages: `docs/amk/glossary.md`.
15
+ - How the app looks, which new screens follow (colours, type, spacing, controls): `docs/amk/design-system.md`.
14
16
 
15
17
  ## Commands
16
18
 
@@ -40,12 +42,13 @@ Never say a check passed unless you ran it in this session.
40
42
  ## Rules
41
43
 
42
44
  - Stay inside the task. Ask before touching unrelated files.
45
+ - Ask the user in rounds: every question you can ask now (its answer doesn't wait on another open question), numbered, each with the answer you recommend and worded so "yes" takes it. A "yes" answers that round and nothing more: an approval is asked for on its own. 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`, from `specs/_templates/questions.md`, for the user to send; go on with the rest.
43
46
  - 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
47
  - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `app.json`, `app.config.*`, `eas.json` or `.github/workflows/`.
45
48
  - Never edit `ios/` or `android/`: the next prebuild overwrites them. Native settings go in `app.json` or `app.config.*`, through config plugins; native code goes in an Expo module (`expo-module` skill). Ask before adding a config plugin.
46
49
  - Never run `eas build`, `eas submit` or `eas update`: they build, ship or publish with the team's accounts, so a person runs them.
47
50
  - Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
48
- - Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`.
51
+ - 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>`.
49
52
  - 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.
50
53
  - After 2 failed attempts at the same fix, stop and report what you found.
51
54
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
@@ -28,6 +28,11 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
28
28
  - Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
29
29
  - For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS.
30
30
  - With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
31
+ - 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.
32
+ - Every field has a visible label; a placeholder only shows the format (`DD/MM/YYYY`), never the label, which disappears once the user types.
33
+ - 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.
34
+ - 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.
35
+ - 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.
31
36
  - 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.
32
37
  - 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.
33
38
  - 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`.
@@ -71,6 +76,10 @@ These changed after most AI training data was written: check them instead of wri
71
76
  - List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
72
77
  - Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
73
78
  - 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.
79
+ - 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.
80
+ - 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.
81
+ - 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.
82
+ - A bug fix comes with a test that failed before the fix.
74
83
 
75
84
  ## Platform guidelines and accessibility
76
85
 
@@ -86,6 +95,8 @@ From Apple's Human Interface Guidelines, Android's design and app quality guidel
86
95
  - Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `Switch`); a custom one gets the same role, state and size.
87
96
  - Dark mode: `userInterfaceStyle: "automatic"` in `app.json` (Android also needs `expo-system-ui`), and colors from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
88
97
  - 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.
98
+ - 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.
99
+ - 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.
89
100
  - 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.
90
101
  - iOS 26: use native headers and tab bars (Expo Router's `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.
91
102
  - Haptics only for success, error or a selection, never as the only feedback, with `expo-haptics`; not `Vibration.vibrate`.
@@ -11,15 +11,14 @@ The user chose this workflow: follow its steps for this task, even where other w
11
11
  Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, task link).
12
12
 
13
13
  1. **Check `docs/amk/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
14
- 2. **Reproduce.** Write down the exact steps and the actual vs expected result. If you can't reproduce it, say so and ask for more details. Don't guess.
15
- 3. **Write a failing test** that shows the bug, if it can be tested with Jest. Run it and show that it fails. (Native or device-only bugs: write the manual steps instead.)
16
- 4. **Find the root cause before changing code.**
17
- - Read the full error and stack trace.
18
- - Trace the data back to where it goes wrong.
19
- - Form one hypothesis, test it, and confirm or reject it. One at a time.
14
+ 2. **Make it fail on demand.** Before looking for the cause, build one check that shows the bug and that you can run again: a failing Jest test where the logic can be tested; for a bug that shows on the device, a Maestro flow in `.maestro/` (from `specs/_templates/flow.yaml`) that goes where the user did and asserts what should be there, run with `sh scripts/amk/verify.sh ios --flow <path>` or `android`. Run it and show that it fails the way the user described, not with some other error. If you can't make it fail, say what you tried and ask for what would help (the exact steps, a screen recording, logs, the device and OS version). Don't guess.
15
+ 3. **Find the root cause before changing code.**
16
+ - Read the full error and stack trace, and trace the data back to where it goes wrong.
17
+ - List three to five possible causes, most likely first, each with what it predicts ("if X is the cause, then changing Y fixes it"). Show the list to the user, who may know which one it is.
18
+ - Test them in that order, one change at a time. Tag every log you add while debugging with `[amk-debug]`, and remove them all before committing: `git grep amk-debug` finds them.
20
19
  - Fix the cause, not the symptom: no try/catch that hides the error, no special case for the failing input.
21
- 5. **Make the smallest fix.** Don't refactor or touch unrelated code.
22
- 6. **Verify.** The new test passes, and lint, typecheck and all tests pass. Paste the output. For UI or native bugs, run `sh scripts/amk/verify.sh ios` and/or `android` and look at the screenshots; `--screens` limits it to the screens the bug is on (for example `--screens tablet-landscape`).
23
- 7. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
24
- 8. **Record it.** If this kind of error could come back, add an entry to `docs/amk/known-issues.md` (error, cause, fix, prevention). If the fix changes what the app is meant to do, not just makes it work as specified, update that requirement in `specs/current/<area>.md` in the same format, and run `node scripts/amk/specs.js check`.
25
- 9. **Commit** with a clear message. Ask the user before pushing, then open a PR with the evidence.
20
+ 4. **Make the smallest fix.** Don't refactor or touch unrelated code.
21
+ 5. **Verify.** The check from step 2 passes now, and stays in the project so the bug can't come back unnoticed. Lint, typecheck and all tests pass too. Paste the output. For UI or native bugs, run `sh scripts/amk/verify.sh ios` and/or `android` and look at the screenshots; `--screens` limits it to the screens the bug is on (for example `--screens tablet-landscape`).
22
+ 6. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
23
+ 7. **Record it.** If this kind of error could come back, add an entry to `docs/amk/known-issues.md` (error, cause, fix, prevention). If the fix changes what the app is meant to do, not just makes it work as specified, update that requirement in `specs/current/<area>.md` in the same format, and run `node scripts/amk/specs.js check`.
24
+ 8. **Commit** with a message that names the cause you confirmed, so the next person debugging learns from it. Ask the user before pushing, then open a PR with the evidence.
@@ -21,4 +21,4 @@ Input: $ARGUMENTS (a spec ID, or empty).
21
21
  3. the exact next step.
22
22
 
23
23
  Use only what the files and git say. If something isn't recorded, say it's unknown. Never fill gaps with guesses.
24
- 5. **Wait for the user to confirm**, then continue with the next unchecked task, following step 4 of `m-feature` (one task at a time, real check output, commit, update `progress.md`).
24
+ 5. **Wait for the user to confirm**, then continue with the next unchecked task (one with `after:` only once those tasks are ticked; one without, in list order), following step 4 of `m-feature` (one task at a time, real check output, commit, update `progress.md`).
@@ -14,5 +14,5 @@ Input: $ARGUMENTS (a problem, a question about how something works, or an idea t
14
14
  2. **Explain what's there today:** the screens, state, API calls and native parts involved, and where iOS and Android differ.
15
15
  3. **When there's a choice, lay out options:** two or three, each with its trade-offs (effort, risk, both platforms, native changes, store review, what it leaves unsolved). Say which one you'd pick and why. Diagrams help when the flow is complicated.
16
16
  4. **Change nothing.** Exploring never edits code, config or project files. Write notes only when the user asks: a draft in `specs/<id>/requirements.md` for `m-feature`, or a decision in `docs/amk/decisions.md`.
17
- 5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document. Then offer to commit those files on their own, so the next feature's branch starts from them instead of carrying them along uncommitted.
17
+ 5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. A word the exploration settled (what the app calls a thing) goes into `docs/amk/glossary.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document. Then offer to commit those files on their own, so the next feature's branch starts from them instead of carrying them along uncommitted.
18
18
  6. **Hand off when it's clear.** Suggest the next step: `m-feature <one-line summary>`, `m-change <one-line summary>` for a small change, `m-prototype <one-line summary>` when it needs a demo or a design before it's built, or `m-bugfix <one-line summary>`, carrying over what you found. If the idea turns out not to be worth doing, say so; learning that cheaply is a good outcome.
@@ -23,34 +23,36 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
23
23
 
24
24
  ## 2. Requirements (then stop for approval)
25
25
 
26
- 1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `specs/_templates/` to `specs/<id>/`. If `specs/<id>/` already has a draft from `m-explore` or `m-prototype`, keep it and copy only the missing files.
26
+ 1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `requirements.md`, `design.md`, `tasks.md` and `progress.md` from `specs/_templates/` to `specs/<id>/`. If `specs/<id>/` already has a draft from `m-explore` or `m-prototype`, keep it and copy only the missing files.
27
27
  2. Read `specs/current/<area>.md` for each area this touches: it says what the app does now. In an area with no living spec yet, read the code that implements it.
28
28
  3. **One intent.** The feature should be one thing you can say in a sentence. If it needs "and also", suggest splitting it into separate features, and ask.
29
- 4. Fill `requirements.md`: the goal; the requirements under `## ADDED`, `## MODIFIED` and `## REMOVED Requirements: <area>` (the format is in `specs/current/README.md`), with one SHALL per requirement and scenarios for the cases that matter; every edge-case line (or "n/a"); out of scope; open questions. Then run `node scripts/amk/specs.js check specs/<id>/requirements.md`.
30
- 5. If something is unclear, ask the user **one question at a time**. Don't fill gaps with guesses.
31
- 6. Show the requirements and **stop until the user approves them**. Give the user these questions to check them against:
29
+ 4. Fill `requirements.md`: the goal; the requirements under `## ADDED`, `## MODIFIED` and `## REMOVED Requirements: <area>` (the format is in `specs/current/README.md`), with one SHALL per requirement and scenarios for the cases that matter; every edge-case line (or "n/a"); out of scope; open questions. Use the app's words from `docs/amk/glossary.md`; a new word, or one used two ways, gets settled with the user and added there. Then run `node scripts/amk/specs.js check specs/<id>/requirements.md`.
30
+ 5. If something is unclear, ask the user in rounds (`AGENTS.md`): every question you can ask now, numbered, each with the answer you recommend. Don't fill gaps with guesses.
31
+ 6. Show the requirements, with the answers worked in, and **stop until the user approves them**. Answers to a round aren't that approval: ask for it on its own. Give the user these questions to check them against:
32
32
  - Is this the problem you asked me to solve, with nothing extra in scope?
33
33
  - Could someone test each requirement without reading the code?
34
34
  - Does a scenario cover the case you care about most?
35
35
 
36
36
  ## 3. Design and tasks (then stop for approval)
37
37
 
38
- 1. **Ask for the UI/UX level first, when the feature has screens.** As one question, ask which level its screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends; it takes longer). `specs/_templates/design.md` describes each. Offer as the default the level a prototype settled (under `## Decisions` in `requirements.md`), otherwise the one the app's other screens have (an earlier spec's `design.md`), otherwise Simple. Don't design until the user has answered. Write the answer and the date under "UI/UX level" in `design.md` (n/a for a feature without screens).
38
+ 1. **Ask for the UI/UX level first, when the feature has screens**, in one round with any other open design question: which level its screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends; it takes longer). `specs/_templates/design.md` describes each. Offer as the default the level a prototype settled (under `## Decisions` in `requirements.md`), otherwise the one the app's other screens have (an earlier spec's `design.md`), otherwise Simple. Don't design until the user has answered. Write the answer and the date under "UI/UX level" in `design.md` (n/a for a feature without screens).
39
39
  2. **Search the codebase before designing.** List the components, hooks, API clients and helpers you'll reuse in `design.md` under "Existing code to reuse". Read `docs/amk/structure.md` and `docs/amk/conventions.md`.
40
40
  3. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
41
- 4. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each). Each task names the requirement it serves and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with a `# Scenario <n>: <name>` comment above each scenario's steps, an assertion for its THEN and a screenshot, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short.
41
+ 4. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each), each a thin slice through every layer it needs (screen, state, API call, test) that works and can be checked on its own, rather than one layer at a time. Changes that make the feature easy to add (moving or renaming code that's there) come first, as their own task. Each task names the requirement it serves, the tasks it waits on (`after:`) and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with a `# Scenario <n>: <name>` comment above each scenario's steps, an assertion for its THEN and a screenshot, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short. A screen that loads data gets a scenario and a screenshot for its empty and error states too, where a flow can reach them (cleared data, or an account without any, for empty; `setAirplaneMode: enabled` for no network). When the feature adds screens, the task for its main screen comes first among them and ends with a look check: the start of `.maestro/<id>.yaml` opens that screen and takes its screenshot, run with `sh scripts/amk/verify.sh ios --flow .maestro/<id>.yaml --screens phone` (or `android`).
42
42
  5. Show design and tasks and **stop until the user approves them**. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
43
43
 
44
44
  From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
45
45
 
46
46
  ## 4. Build, one task at a time
47
47
 
48
- For each task:
49
- 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the UI/UX level in `design.md`, and to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
48
+ For each task, in order (a task with `after:` once those tasks are ticked; one without, as listed):
49
+ 1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the UI/UX level in `design.md`, from the colours, type, spacing and controls in `docs/amk/design-system.md`, and to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
50
50
  2. Run `lint`, `typecheck` and `test` (see AGENTS.md). Paste the real output. If something fails, fix it; after 2 failed attempts, stop and report.
51
51
  3. Commit with a clear message ending in `Spec: specs/<id>`.
52
52
  4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
53
53
 
54
+ After the main screen's task, show the user its screenshot and **stop until they OK the look**: a wrong look then costs one screen, not five.
55
+
54
56
  If building shows the plan is wrong: when the intent is the same, update `requirements.md`, `design.md` or `tasks.md`, tell the user what changed, and ask again before going on if a requirement changed. When the intent itself changed, or the scope grew into different work, stop and suggest finishing this feature small and starting a new one.
55
57
 
56
58
  ## 5. Check against the spec
@@ -60,6 +62,8 @@ When all tasks are done:
60
62
  - **One command** (`verify.sh all --spec <id>`): run it. Then **open the screenshots** in `.amk/evidence/<id>/` and check each one against its scenario, in every screen's folder (phone, landscape, tablet).
61
63
  - **A plan, and your tool has subagents:** run its `quick` and `build` commands as printed (nothing added: the plain commands are the ones people allow), then, round by round, start one `m-device-checker` subagent per device command of the round, all at once, and wait for their reports before the next round; each runs its device (or its part of the flows), checks its screenshots and hands back a report. When all are back, check them yourself: every flow passed, every screen has screenshots in its folder, or in each `part-k/` folder when its flows ran in parts (list them), and open every screenshot a report flags plus at least one per screen. A report alone isn't evidence. Without subagents, run `verify.sh all --spec <id>` instead.
62
64
 
65
+ Then **the design review**: give the screenshot folders to the `m-design-reviewer` subagent, which sees only them, `docs/amk/design-system.md` and the UI/UX level in `design.md` (without subagents, check the same yourself). Fix what it finds, or tell the user why one stays.
66
+
63
67
  Off a Mac it checks Android only: record in `progress.md` that iOS still needs `verify.sh ios --spec <id>` on a Mac, and say so in the PR. A turned screen's screenshots are landscape; a portrait one means the app didn't turn. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
64
68
  2. Go through every scenario and note its evidence: a test name, command output, or the screen checked. Where the code and the spec disagree, fix whichever is wrong, asking first if it's the spec. The spec must describe what ships.
65
69
 
@@ -72,6 +76,6 @@ Then update the `docs/amk/` files the feature made untrue: a new key journey in
72
76
  ## 7. Review and pull request
73
77
 
74
78
  1. Run `m-review` (or ask the `m-reviewer` subagent, if your tool has subagents). Fix real problems only; skip style nits.
75
- 2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR. Start the description with the requirements this adds, changes and removes, so reviewers read what should be true before the code. Then add the evidence: lint, typecheck and test output, and the screenshot for each scenario. Use `.github/pull_request_template.md` if the repo has one.
79
+ 2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR. Start the description with the requirements this adds, changes and removes, so reviewers read what should be true before the code. Then add the evidence: lint, typecheck and test output, and the screenshot for each scenario. Then the risk: whether it can be undone once a store build ships (native changes, data saved in a new format, and API changes that installed versions still rely on can't be; JavaScript can be fixed in the next release), and what else it could break. Use `.github/pull_request_template.md` if the repo has one.
76
80
 
77
81
  Never claim a check passed without running it in this session.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: m-onboard
3
- description: Describe the app for AI agents - read the whole project, draft docs/amk/product.md, tech.md, structure.md and conventions.md, ask only what the code can't show, and write them once the user approves. Run it after installing the kit, and again after big changes. Run only when the user explicitly invokes m-onboard.
3
+ description: Describe the app for AI agents - read the whole project, draft docs/amk/product.md, tech.md, structure.md, conventions.md, glossary.md and design-system.md, ask only what the code can't show, and write them once the user approves. Run it after installing the kit, and again after big changes. Run only when the user explicitly invokes m-onboard.
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
@@ -8,13 +8,13 @@ disable-model-invocation: true
8
8
 
9
9
  The user chose this workflow: follow its steps for this task, even where other workflow instructions in this project (Superpowers, BMAD, proAgents or similar) say otherwise.
10
10
 
11
- Input: $ARGUMENTS (optional: which files to work on, for example `tech structure`; all four by default).
11
+ Input: $ARGUMENTS (optional: which files to work on, for example `tech structure`; all six by default).
12
12
 
13
- Every agent reads these four files before it works on this app, so they must be true, short and specific: facts with the files they come from, not advice. Write only what you found in the project or what the user told you.
13
+ Every agent reads these six files before it works on this app, so they must be true, short and specific: facts with the files they come from, not advice. Write only what you found in the project or what the user told you.
14
14
 
15
15
  ## 1. See what's there
16
16
 
17
- Read `AGENTS.md` and the four files in `docs/amk/`. A file that holds only its heading and the `<!-- … -->` outline is empty: you'll draft it. A file with content is the team's: you'll suggest changes to it, never rewrite it.
17
+ Read `AGENTS.md` and the six files in `docs/amk/` (`product.md`, `tech.md`, `structure.md`, `conventions.md`, `glossary.md`, `design-system.md`). A file that holds only its heading and the `<!-- … -->` outline is empty: you'll draft it. A file with content is the team's: you'll suggest changes to it, never rewrite it.
18
18
 
19
19
  ## 2. Read the project
20
20
 
@@ -24,6 +24,7 @@ Change nothing in this step. List the project's files with `git ls-files` (it le
24
24
  - **Screens and journeys:** the entry point (`index.js`, `App.tsx`, or the `app/` folder with Expo Router), the navigation setup and the list of screens. The key user journeys come from these: sign-in, the main flows, payments, settings.
25
25
  - **Tech:** for each dependency that matters, what the app uses it for and where it's set up: state, navigation, the API client, storage, forms, i18n, analytics, push, crash reporting, payments, maps. Also the backend APIs and where their contracts live, and the environments: config files, `.env.example`, build flavors and schemes. Never open `.env` files, keystores or signing files.
26
26
  - **Structure:** the folder map, two or three levels into the app's code; where shared components, the theme and helpers live; custom native code under `ios/` and `android/` (native modules, extensions, widgets), or config plugins and local modules in Expo apps.
27
+ - **Look:** the theme (colours, fonts, spacing, radius, dark mode), the shared components that draw buttons, fields and rows, the icon library, and what the texts on screen sound like.
27
28
  - **Conventions:** a few files from each layer (a screen, a component, a hook, an API call, a test) and what they have in common: naming, file layout, styling, error, loading and empty states, how tests mock the API. Also the lint and formatter configs, and `git log --oneline -30` for the style of commit messages and branch names. A convention is a pattern you saw in several files; a single file is an example, not a rule.
28
29
 
29
30
  In a large app, sample: a few files per layer are enough. Keep a note of the files each finding comes from.
@@ -36,6 +37,8 @@ Draft each file you're working on from its outline, and keep it short.
36
37
  - `tech.md`: what the app uses today, 1-2 lines each with the library and where it's set up; the backend APIs and their contracts; the environments and how the app switches between them; third-party services. Describe what's there; don't recommend new tools.
37
38
  - `structure.md`: the folder map, 1-2 lines per folder; where shared UI, the theme and helpers live, so agents reuse them instead of writing new ones; custom native code.
38
39
  - `conventions.md`: the patterns you found, each with a file that shows it.
40
+ - `glossary.md`: the app's own words, from its screens, data types, API and store texts (an Order, a Visit), one or two lines each, with the other words used for the same thing listed as not to use (leave that line out when you found none).
41
+ - `design-system.md`: how the app looks, from its theme and shared components, each with the file it comes from: colours by role, the type size and weight of each text role, spacing steps, radius, the buttons, fields and rows, the icon set, motion, and the voice of its texts. In an app without a theme, write what the screens use most, and say so.
39
42
 
40
43
  Use the app's own names for screens, modules and services. Where the project doesn't answer something, write down a question for step 4 instead of guessing.
41
44
 
@@ -43,7 +46,7 @@ For a file that's already filled in, compare it with what you found and list wha
43
46
 
44
47
  ## 4. Ask what the code can't show
45
48
 
46
- Ask the user in one message, usually five questions or fewer, about what you couldn't find:
49
+ Ask the user in one round (`AGENTS.md`), usually five questions or fewer, each with the answer the code suggests, about what you couldn't find:
47
50
  - who uses the app (customers, staff, a market or age group);
48
51
  - what must never break (payments, data sync, sign-in, …);
49
52
  - whether the key journeys you found are right and complete;
@@ -15,23 +15,22 @@ A prototype answers questions before the real build: what the client wants, how
15
15
  ## 1. Understand
16
16
 
17
17
  1. Read the requirement, `docs/amk/product.md`, `structure.md` and `conventions.md`, the living spec for the area in `specs/current/`, and the screens around where this would live: their components, theme and navigation.
18
- 2. Ask who the demo is for (the client or the team) and what it must show, one question at a time.
19
- 3. Ask which UI/UX level the screens should have: Simple (clean, minimal and functional; the default), Mixed (simple, with modern touches) or Premium (polished, following current design trends). `specs/_templates/design.md` describes each; offer the level the app's other screens have, if an earlier spec's `design.md` records one. The concepts and the prototype are made at that level. Don't start them until the user has answered.
20
- 4. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
21
- 5. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way, starting with the UI/UX level and the date.
22
- 6. Decide which case this is:
18
+ 2. Ask in one round (`AGENTS.md`): who the demo is for (the client or the team), what it must show, and which UI/UX level the screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends). `specs/_templates/design.md` describes each; recommend the level the app's other screens have, if an earlier spec's `design.md` records one, otherwise Simple. The concepts and the prototype are made at that level: don't start them until the user has answered.
19
+ 3. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
20
+ 4. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way, starting with the UI/UX level and the date.
21
+ 5. Decide which case this is:
23
22
  - **What to show is clear** (the screens and the flow are known): go to step 3.
24
23
  - **How it should work or look is still open:** go to step 2.
25
24
 
26
25
  ## 2. Concepts
27
26
 
28
27
  1. Work out two or three genuinely different ways it could work: different flows or layouts, not colour variants. For each, note the user flow step by step, the key screens, and the trade-offs: effort, iOS and Android differences, native or backend work.
29
- 2. Make one HTML file per concept in `specs/<id>/concepts/`: the key screens as phone-sized frames side by side, with the app's colours, fonts and spacing taken from its theme, real texts where they're known, and links between the frames so it can be clicked through. Each is a single file of plain HTML and CSS, with nothing to install or build and nothing loaded from the internet, so it opens in any browser.
28
+ 2. Make one HTML file per concept in `specs/<id>/concepts/`: the key screens as phone-sized frames side by side, with the app's colours, fonts and spacing taken from `docs/amk/design-system.md` (its theme), real texts where they're known, and links between the frames so it can be clicked through. Each is a single file of plain HTML and CSS, with nothing to install or build and nothing loaded from the internet, so it opens in any browser.
30
29
  3. Show the concepts with your recommendation. **Stop until the user picks one or combines them.** Write the choice and why under `## Decisions`, and commit.
31
30
 
32
31
  ## 3. Build the prototype in the app
33
32
 
34
- 1. Build the screens with the app's own components, theme and navigation, so it looks and feels like the app. Keep the mock data in one file next to the screens.
33
+ 1. Build the screens with the app's own components, theme and navigation, as `docs/amk/design-system.md` describes them, so it looks and feels like the app. Keep the mock data in one file next to the screens.
35
34
  2. No API calls, no native files and no new dependencies. If one seems unavoidable, ask.
36
35
  3. Make it easy to reach in a demo: a temporary entry where the feature would live, or the app's first screen when that's simpler.
37
36
  4. Skip tests: the prototype is thrown away. It only has to build and run.
@@ -41,7 +40,7 @@ A prototype answers questions before the real build: what the client wants, how
41
40
 
42
41
  1. Write `.maestro/<id>-prototype.yaml` from `specs/_templates/flow.yaml`: walk through the prototype the way the demo would, with a `takeScreenshot` on every screen, and `startRecording: <id>-prototype` after the launch and `stopRecording` at the end for a video.
43
42
  2. Run `sh scripts/amk/verify.sh all --flow .maestro/<id>-prototype.yaml --label <id>-prototype`. Off a Mac it covers Android only.
44
- 3. Open every screenshot and check that it shows what the demo needs. Give the user the folder `.amk/evidence/<id>-prototype/`, which has the screenshots and a video per platform, and the concept files if there are any. For a live demo, run the app from this branch on a phone or simulator.
43
+ 3. Open every screenshot and check that it shows what the demo needs. Then ask the `m-design-reviewer` subagent for a design review of them (without subagents, check the same yourself), and fix what it finds before the demo. Give the user the folder `.amk/evidence/<id>-prototype/`, which has the screenshots and a video per platform, and the concept files if there are any. For a live demo, run the app from this branch on a phone or simulator.
45
44
 
46
45
  ## 5. Take in the feedback
47
46
 
@@ -19,10 +19,13 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
19
19
  - *Correct:* the code does what each requirement says, edge cases included, and nothing outside the agreed scope.
20
20
  - *Coherent:* the decisions in `design.md` show up in the code, its UI/UX level in the screens, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
21
21
  - **No spec:** does the diff do what was asked, and nothing unrelated?
22
- - **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
22
+ - **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened? Do they check behavior through the public interface, mock only what the app doesn't own, and take expected values from the spec rather than recompute them (the React Native rules file)?
23
23
  - **TypeScript:** any new `any`, `@ts-ignore` or non-null `!` to get past a check, or a loosened `tsconfig.json`?
24
24
  - **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
25
25
  - **Screens:** with the keyboard open, do the field and its button stay visible? Does anything sit under the status bar, home indicator or gesture bar? Do lists that grow with the user's data scroll? Does text wrap at the largest text size?
26
+ - **Design system:** new screens use the colours, type, spacing and controls in `docs/amk/design-system.md`; nothing new (a hex colour, a one-off button style) that it doesn't have.
27
+ - **Forms and buttons:** a visible label on every field, not the placeholder; the right keyboard and autofill; errors under their field; a request that can't be sent twice; no success message when nothing was saved; a destructive action that asks first.
28
+ - **Nothing invented:** no made-up figures, ratings, reviews or placeholder names on a screen; a missing text is a placeholder the PR lists.
26
29
  - **Tablets and landscape** (the screens `AGENTS.md` lists): does each layout adapt to the window width (`useWindowDimensions`), rather than stretching or centering the phone layout? Do turned screens scroll, with the left and right insets handled? Are sizes done the app's existing way?
27
30
  - **Accessibility:** does every new button or other touchable have an `accessibilityLabel` and an `accessibilityRole`, and checkboxes, switches and tabs their `accessibilityState`? Are messages that appear after an action, such as form errors, announced to screen readers? Text contrast 4.5:1 in both themes, nothing under 11 points, swipe and long-press actions reachable another way?
28
31
  - **Platform guidelines:** tap areas of at least 44×44 pt (48×48 dp on Android); swipe back and the Android back button still work, and every `Modal` closes with back; permissions asked when the user starts the feature, with a way to Settings once blocked; native controls; dark mode from the theme; Reduce Motion respected.
@@ -10,7 +10,9 @@
10
10
 
11
11
  ## Risk
12
12
 
13
- <!-- What could break, and how to roll back -->
13
+ <!-- Can it be undone? JavaScript can be fixed in the next release, but a store build can't be called back:
14
+ native changes, data saved in a new format, and API changes that installed versions still rely on need care.
15
+ And what else could it break, beyond the feature? -->
14
16
 
15
17
  ## AI use
16
18
 
@@ -8,6 +8,12 @@
8
8
  "git push --force*": "deny",
9
9
  "git push -f*": "deny",
10
10
  "git clean -f*": "deny",
11
+ "git checkout .": "deny",
12
+ "git checkout -- .": "deny",
13
+ "git restore .": "deny",
14
+ "git stash drop*": "deny",
15
+ "git stash clear*": "deny",
16
+ "git branch -D*": "deny",
11
17
  "git commit --no-verify*": "deny",
12
18
  "xcrun simctl erase*": "deny",
13
19
  "npm install *": "ask",
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: m-design-reviewer
3
+ targets: ["*"]
4
+ description: Read-only review of how screens look, from their device screenshots alone. Use when m-feature or m-prototype asks for a design review of a check's screenshots.
5
+ claudecode:
6
+ tools: ["Read", "Glob"]
7
+ ---
8
+
9
+ You review how screens look, from their screenshots alone. You didn't build them and aren't told why anything is the way it is: judge what's on the screen. You never edit files.
10
+
11
+ Your inputs, and nothing else: the screenshot folders you're given (`.amk/evidence/<id>/<screen>/`, one per phone, tablet and orientation), `docs/amk/design-system.md`, and the UI/UX level in `specs/<id>/design.md`.
12
+
13
+ 1. Open every screenshot in every folder.
14
+ 2. Check each one:
15
+ - **The app's look:** colours, type sizes, spacing, corner radius, buttons and fields as `design-system.md` describes them; nothing that looks like it came from another app.
16
+ - **Care:** edges line up, spacing is even, one primary action per screen, nothing crowded against an edge or the system bars, no text cut off, overlapping or wrapping badly, on every screen size and orientation.
17
+ - **Every state:** loading, empty and error screens look as finished as the full one, and say what to do next.
18
+ - **Not generic:** no card inside a card, rows of identical icon-and-title tiles, decorative gradients, emoji used as icons, filler text (Lorem ipsum, Jane Doe) or figures that look made up.
19
+ - **Its level:** a Simple screen carrying decoration it doesn't need, or a Mixed or Premium one that looks unfinished.
20
+ 3. Start your report with one word: **ship** (nothing owed), **fix** (findings follow) or **recapture** (a screenshot is missing, blank or shows the wrong screen: name it, then review the rest). A screen that may be empty on purpose is also judged as an empty state: does it say what belongs there and what to do?
21
+ 4. Then at most eight findings, the costliest first, one line each: the screenshot, what's wrong, and what you'd change.
22
+ 5. End with one line: what must not be lost while fixing it.
@@ -9,7 +9,7 @@ claudecode:
9
9
  You review code changes with fresh eyes. You never edit files. Use the shell only for read-only commands such as `git diff`, `git log`, `git show`, `node scripts/amk/baseline.js base` and `node scripts/amk/rn-check.js`.
10
10
 
11
11
  1. Get the changes since the base branch the kit's checks use: `node scripts/amk/baseline.js base` prints it, then `git diff <base>...HEAD`. If a spec exists in `specs/<id>/`, read its `requirements.md`. Run `node scripts/amk/rn-check.js`: what it reports is a finding, and each `// amk-ok: <reason>` it lists needs a reason that holds.
12
- 2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, screens (the keyboard covering a field or button, content under the system bars, lists that don't scroll, text cut off at large sizes), tablets and landscape for the screens AGENTS.md lists (layouts that adapt to the window width, turned screens that scroll), accessibility (labels and roles, state on checkboxes, switches and tabs, contrast, text sizes, messages announced to screen readers), platform guidelines (44/48 tap areas, back gestures and the back button, permissions asked in context, native controls, dark mode, Reduce Motion), store review (account deletion, Sign in with Apple next to a social login, in-app purchase for digital goods, permission texts, restricted Android permissions), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), removed or deprecated React Native APIs, errors (an error boundary, no empty `catch`, failed actions shown), error and empty states, effects that don't clean up, secrets and tokens in plain storage, native file changes, and performance.
12
+ 2. Check scope, tests (added, deleted, weakened), iOS vs Android differences, the design system (`docs/amk/design-system.md`: no colours, sizes or controls outside it), forms (labels, keyboard and autofill, errors under fields, no double submit), nothing invented on screens (figures, ratings, placeholder names), screens (the keyboard covering a field or button, content under the system bars, lists that don't scroll, text cut off at large sizes), tablets and landscape for the screens AGENTS.md lists (layouts that adapt to the window width, turned screens that scroll), accessibility (labels and roles, state on checkboxes, switches and tabs, contrast, text sizes, messages announced to screen readers), platform guidelines (44/48 tap areas, back gestures and the back button, permissions asked in context, native controls, dark mode, Reduce Motion), store review (account deletion, Sign in with Apple next to a social login, in-app purchase for digital goods, permission texts, restricted Android permissions), TypeScript (new `any` or `@ts-ignore`, a loosened tsconfig), removed or deprecated React Native APIs, errors (an error boundary, no empty `catch`, failed actions shown), error and empty states, effects that don't clean up, secrets and tokens in plain storage, native file changes, and performance.
13
13
  3. Confirm each finding in the code before reporting it.
14
14
  4. Report each finding as: severity (blocker or should fix), file:line, the problem, and a suggested fix. No style nits.
15
15
  5. End with "Ready for PR" or "Not ready: N blockers".
@@ -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
 
@@ -40,11 +42,12 @@ Never say a check passed unless you ran it in this session.
40
42
  ## Rules
41
43
 
42
44
  - Stay inside the task. Ask before touching unrelated files.
45
+ - Ask the user in rounds: every question you can ask now (its answer doesn't wait on another open question), numbered, each with the answer you recommend and worded so "yes" takes it. A "yes" answers that round and nothing more: an approval is asked for on its own. 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`, from `specs/_templates/questions.md`, for the user to send; go on with the rest.
43
46
  - 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
47
  - Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `Podfile`, `build.gradle`, `Info.plist`, `AndroidManifest.xml` or `.github/workflows/`.
45
48
  - Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
46
49
  - 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`.
50
+ - 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>`.
48
51
  - 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.
49
52
  - After 2 failed attempts at the same fix, stop and report what you found.
50
53
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
@@ -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`.
@@ -56,6 +61,10 @@ 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.
59
68
 
60
69
  ## Platform guidelines and accessibility
61
70
 
@@ -71,6 +80,8 @@ From Apple's Human Interface Guidelines, Android's design and app quality guidel
71
80
  - 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
81
  - 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
82
  - 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.
83
+ - 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.
84
+ - 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
85
  - 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
86
  - 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
87
  - Haptics only for success, error or a selection, never as the only feedback, through the app's haptics library; not `Vibration.vibrate`.
@@ -27,6 +27,22 @@ const paths = [];
27
27
  // rm with a recursive flag and a force flag anywhere before the next ; & | (-rf, -Rf, -r -f, --recursive --force);
28
28
  // a push with --force, -f or a +refspec
29
29
  const destructive = /\brm(?=[^;&|\n]*\s(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\b)(?=[^;&|\n]*\s(-[a-zA-Z]*f[a-zA-Z]*|--force)\b)|git\s+reset\s+--hard|git\s+push\s+(.*\s)?((--force|-f)\b|\+\S)|git\s+clean\s+-[a-z]*f|--no-verify|xcrun\s+simctl\s+erase/;
30
+ // git commands that throw away work for good: every uncommitted change (a checkout or restore of the whole tree, a forced
31
+ // checkout or switch), saved stashes, a branch with commits merged nowhere. Undoing one file's edit stays allowed
32
+ const discards = c => c.split(/&&|\|\||[;&|\n]/).some(s => {
33
+ const m = /\bgit\s+(checkout|restore|switch|stash|branch)\b(.*)/.exec(s);
34
+ if (!m) return false;
35
+ const args = m[2].trim().split(/\s+/).filter(Boolean);
36
+ const short = args.filter(a => /^-[a-zA-Z]+$/.test(a)).join('');
37
+ const has = (letter, long) => short.includes(letter) || args.includes(long);
38
+ const everything = args.some(a => /^['"]?(\.|\.\/|:\/|\*)['"]?$/.test(a));
39
+ if (m[1] === 'checkout') return everything || has('f', '--force');
40
+ // --staged alone only unstages: the changes stay
41
+ if (m[1] === 'restore') return everything && (!has('S', '--staged') || has('W', '--worktree'));
42
+ if (m[1] === 'switch') return has('f', '--force') || args.includes('--discard-changes');
43
+ if (m[1] === 'stash') return args[0] === 'drop' || args[0] === 'clear';
44
+ return short.includes('D') || (has('d', '--delete') && has('f', '--force'));
45
+ });
30
46
  // example files (.env.example, .env.local.example, .env.sample, .env.template) aren't secrets
31
47
  const secretFile = /(^|[\s/'"=])\.env(?![\w.-]*\.(?:example|sample|template)(?=$|[\s'";|&)]))(\.[\w.-]+)?(?=$|[\s'";|&)])|\.(keystore|jks|p8|p12|mobileprovision)\b/;
32
48
  // the project's own secret files: .amk-secrets lists them, one path from the project root per line (a folder ends in /)
@@ -37,7 +53,12 @@ const secret = s => secretFile.test(s) || listed.some(p => s.includes(p));
37
53
  const block = reason => { process.stderr.write(`Blocked by scripts/amk/guard.js: ${reason}\n`); process.exit(2); };
38
54
  for (const c of commands) {
39
55
  // a command that only mentions one, in a commit message, is blocked too: the message can come from a file instead
40
- if (destructive.test(c)) block(`destructive command: ${c}${/git\s+commit\b/.test(c) ? '\n(Only in the commit message? Write it to a file and use git commit -F <file>.)' : ''}`);
56
+ const inMessage = /git\s+commit\b/.test(c) ? '\n(Only in the commit message? Write it to a file and use git commit -F <file>.)' : '';
57
+ if (destructive.test(c)) block(`destructive command: ${c}${inMessage}`);
58
+ if (discards(c)) {
59
+ block(`this throws away work that can't be brought back (uncommitted changes, stashes or unmerged commits): ${c}\n`
60
+ + `Ask the user first, or keep the work: git stash, or a commit. To undo your own edit to a file: git checkout -- <that file>.${inMessage}`);
61
+ }
41
62
  if (secret(c)) block(`shell access to a secret file: ${c}`);
42
63
  }
43
64
  for (const p of paths) {
@@ -211,6 +211,15 @@ function check(file, text) {
211
211
  if (l && !/\breturn\b/.test(body)) add('!', m.index, close, `${l[1]} in an effect that returns no cleanup: return a function that removes it`, lineAt(code, open + l.index));
212
212
  });
213
213
  each(/\bconsole\s*\.\s*log\s*\(/g, m => add('!', m.index, null, 'console.log left in: remove it, or use the app\'s logger'));
214
+ // the generated look: marketing filler for copy, placeholder text and names, emoji in place of the app's icons
215
+ each(/\b(seamless(?:ly)?|effortless(?:ly)?|supercharge[ds]?|revolutioni[sz](?:e|es|ed|ing)|revolutionary|cutting-edge|next-level|game-?chang(?:er|ing)|unleash(?:es|ed)?|elevate your|empower your|unlock your (?:full )?potential)\b/gi,
216
+ m => add('!', m.index, null, `"${m[0]}" reads as generated copy: say what it does, in the app's words (docs/amk/glossary.md)`));
217
+ each(/\b(lorem ipsum|(?:john|jane) doe|acme)\b/gi, m => add('!', m.index, null, `"${m[0]}" is filler: the real text, or a placeholder the PR lists`));
218
+ // not in translation files: an emoji there is part of a message ("Welcome 👋"), not an icon
219
+ if (!/(^|\/)(i18n?|locales?|translations?|lang)\//i.test(file)) {
220
+ each(/\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F/gu,
221
+ m => add('!', m.index, null, 'an emoji in the app: an icon from its icon set (docs/amk/design-system.md), unless it\'s content'));
222
+ }
214
223
  each(/\bmask(AllTextInputs|AllText|AllInputs|TextInputs)\s*:\s*false\b/g, m => add('!', m.index, null, 'session replay that records what users type: mask text inputs'));
215
224
  each(/\bAccessibilityInfo\s*\.\s*setAccessibilityFocus\s*\(/g, m => add('!', m.index, null, 'AccessibilityInfo.setAccessibilityFocus is deprecated: use sendAccessibilityEvent'));
216
225
  // platform guidelines: text, back, screen readers, tap areas, permissions, motion
@@ -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.
@@ -2,6 +2,9 @@
2
2
  # Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
3
3
  # Each scenario of specs/<id>/requirements.md gets a "# Scenario <n>: <name>" comment above its steps, an assertion for
4
4
  # its THEN and a screenshot: rn-check (in verify.sh quick) checks that, and Maestro's syntax, before any build.
5
+ # A screen that loads data also gets its empty and error states, each a scenario with a screenshot, where a flow can
6
+ # reach them: cleared data (launchApp: { clearState: true }) or an account without any for empty, and for no network
7
+ # "- setAirplaneMode: enabled" before the step and "disabled" after it (and in onFlowComplete, so a failure can't leave it on).
5
8
  # Steps several flows share (logging in, skipping onboarding, a permission prompt) and resetting test data go in
6
9
  # .maestro/subflows/ (specs/_templates/subflow.yaml), run with "- runFlow: subflows/<name>.yaml".
7
10
  # Test logins: ${MAESTRO_EMAIL}, ${MAESTRO_PASSWORD} and the like, set in .maestro/.env.local, which isn't committed.
@@ -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,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.