agentic-mobile-kit 0.14.1 → 0.15.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 (23) hide show
  1. package/lib/init.js +26 -4
  2. package/package.json +1 -1
  3. package/stacks/react-native/expo/docs/amk/expo.md +1 -0
  4. package/stacks/react-native/expo/docs/amk/known-issues.md +5 -0
  5. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +1 -1
  6. package/stacks/react-native/template/.agents/skills/m-change/SKILL.md +1 -1
  7. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +3 -3
  8. package/stacks/react-native/template/.agents/skills/m-test/SKILL.md +3 -3
  9. package/stacks/react-native/template/.githooks/pre-commit +1 -1
  10. package/stacks/react-native/template/.github/workflows/ci.yml +3 -1
  11. package/stacks/react-native/template/.rulesync/hooks.jsonc +4 -0
  12. package/stacks/react-native/template/docs/amk/known-issues.md +5 -0
  13. package/stacks/react-native/template/docs/amk/react-native.md +1 -0
  14. package/stacks/react-native/template/scripts/amk/autopilot.js +1 -1
  15. package/stacks/react-native/template/scripts/amk/guard.js +1 -1
  16. package/stacks/react-native/template/scripts/amk/handoff-check.js +12 -5
  17. package/stacks/react-native/template/scripts/amk/notify.js +85 -0
  18. package/stacks/react-native/template/scripts/amk/pr.js +10 -8
  19. package/stacks/react-native/template/scripts/amk/screens.js +30 -8
  20. package/stacks/react-native/template/scripts/amk/specs.js +63 -4
  21. package/stacks/react-native/template/scripts/amk/verify.sh +26 -8
  22. package/stacks/react-native/template/specs/_templates/flow.yaml +9 -2
  23. package/stacks/react-native/template/specs/_templates/subflow.yaml +2 -1
package/lib/init.js CHANGED
@@ -464,12 +464,28 @@ function oldTemplate(agents, opts) {
464
464
  function fetchTemplate(version) {
465
465
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-kit-'));
466
466
  process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true }));
467
- const r = tool('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--silent'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
468
- if (r.status !== 0) throw new InitError(`Couldn't download agentic-mobile-kit@${version} from npm: ${(r.stderr || '').trim().split('\n').pop()}`);
467
+ // errors only: --silent hid npm's reason too (a version npm hasn't got, no network)
468
+ const r = tool('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--loglevel=error'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
469
+ if (r.status !== 0) {
470
+ const why = (r.stderr || '').split('\n').map(l => l.replace(/^npm (?:error|ERR!)\s*/, '').replace(/^(?:notarget|network)\s+/, '').trim())
471
+ .find(l => l && !/^(?:code|errno|syscall)\b/.test(l)) || `npm exited with ${r.status}`;
472
+ throw new InitError(`Couldn't download agentic-mobile-kit@${version} from npm: ${why}`);
473
+ }
469
474
  execFileSync('tar', ['-xzf', path.join(dir, r.stdout.trim().split('\n').pop()), '-C', dir]);
470
475
  return path.join(dir, 'package', 'stacks', 'react-native', 'template');
471
476
  }
472
477
 
478
+ // a list's entries: each "### " heading with its lines, up to the next heading
479
+ const entries = text => text.match(/^### [^\n]*\n[\s\S]*?(?=^#{2,3} |(?![\s\S]))/gm) || [];
480
+ // the team's list with the entries the kit added since the old version (not those the team has too), after its heading
481
+ function withNewEntries(current, kitOld, kitNew) {
482
+ const heads = text => new Set(entries(text).map(e => e.split('\n')[0].trim()));
483
+ const known = new Set([...heads(kitOld), ...heads(current)]);
484
+ const added = entries(kitNew).filter(e => !known.has(e.split('\n')[0].trim()));
485
+ if (!/^## Entries\n\n/m.test(current)) return null;
486
+ return current.replace(/^## Entries\n\n/m, m => `${m}${added.map(e => `${e.replace(/\n*$/, '')}\n\n`).join('')}`);
487
+ }
488
+
473
489
  // three-way merge: your changes and the kit's changes since the old version, both kept
474
490
  function merge3(current, base, kitNew, from) {
475
491
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-merge-'));
@@ -704,10 +720,12 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
704
720
  const giText = readIf(gi) || '';
705
721
  // Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
706
722
  // .maestro/.amk-*: the copies of flows with view-tree steps that verify.sh runs on Android, there only while they run
707
- const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', '.maestro/.amk-*', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
723
+ // node_modules without the slash: a git worktree often links the project's node_modules, and node_modules/ matches
724
+ // only a folder, so git add -A would commit the link
725
+ const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', '.maestro/.amk-*', 'node_modules', '.claude/worktrees/', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
708
726
  const missing = ignored.filter(l => !giText.split('\n').includes(l));
709
727
  if (missing.length) {
710
- fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs), .maestro/.amk-* the flows verify.sh is running${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
728
+ fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs), .maestro/.amk-* the flows verify.sh is running; node_modules also as a link (a worktree's); .claude/worktrees/ Claude Code's worktrees${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
711
729
  done.merged.push('.gitignore');
712
730
  }
713
731
 
@@ -912,6 +930,10 @@ function sync(cwd, opts = {}) {
912
930
  if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
913
931
  // without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
914
932
  const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
933
+ // the known issues are the team's list too: when both added entries in one place, the team's file gets the kit's
934
+ // new entries, by heading, at the top of the list, rather than conflict markers
935
+ const listed = conflicts && rel === 'docs/amk/known-issues.md' && withNewEntries(current, kitOld, kitNew);
936
+ if (listed) { writeKitFile(cwd, rel, listed); report.merged.push(rel); continue; }
915
937
  // markers, or a merge that no longer parses, would stop a script, a hook, a workflow or a config from working (and
916
938
  // every check with it): those get the kit's version, and the team's goes beside it to bring its changes back
917
939
  if (!rel.endsWith('.md') && (conflicts || !parses(rel, text))) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.14.1",
3
+ "version": "0.15.0",
4
4
  "description": "One setup for AI-assisted development of React Native apps, bare or Expo: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -51,6 +51,7 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
51
51
  - Landscape leaves little height: screens scroll, the keyboard covers more, and the safe-area insets include the left and right edges (the notch or Dynamic Island side).
52
52
  - Android ignores orientation and size locks on tablets and foldables (600 dp wide and up) for apps targeting Android 16 (API 36), and from Android 17 (API 37) apps can't opt out. Apple deprecated `UIRequiresFullScreen` with iPadOS 26, so iPad windows resize too, and on iOS 27 `ScreenOrientation.lockAsync` may do nothing. Every screen has to work at any window size and turned, whatever the app's settings say.
53
53
  - Don't lock the orientation in code to avoid layout work. Which orientations the app supports is a product decision, set in `app.json`: `orientation` (`default` turns, `portrait` or `landscape` locks) and `ios.supportsTablet` for the iPad app.
54
+ - A team that checks fewer screens than the app supports (phones only, say) lists them in `.amk-screens`, as `--screens` takes them: `phone`. `verify.sh` then never checks the others, whatever `--screens` asks (`portrait` and `landscape` otherwise include the tablet's), and `node scripts/amk/screens.js` prints the sentence for `AGENTS.md`'s Screens line.
54
55
 
55
56
  ## Current Expo, React Native and React
56
57
 
@@ -11,6 +11,11 @@ Recurring errors and their fixes. Check here before debugging a build error. Rem
11
11
 
12
12
  ## Entries
13
13
 
14
+ ### iOS build: "unable to initiate PIF transfer session (operation in progress?)"
15
+ - **Cause:** two builds of the same project at once: a build from the command line (`verify.sh`, `ios-build.sh`) while Xcode builds or indexes it. No `xcodebuild` needs to be running: Xcode's build service holds the project.
16
+ - **Fix:** let Xcode finish, or quit it, then build again. If it stays stuck: `pkill -f SWBBuildService` (Xcode's build service, which starts again when needed), then build again.
17
+ - **Prevention:** don't start a command-line build while Xcode builds or indexes the same project.
18
+
14
19
  ### A native change doesn't show up in the build
15
20
  - **Cause:** the kit's scripts regenerate `ios/` and `android/` only when Expo's fingerprint changes. It covers the app config, config plugins and native libraries, but not, for example, a file that a config plugin reads.
16
21
  - **Fix:** delete `ios/.amk-fingerprint` and `android/.amk-fingerprint`, then check again. The next build regenerates both folders and takes longer.
@@ -21,7 +21,7 @@ Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, ta
21
21
  - 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.
22
22
  - Fix the cause, not the symptom: no try/catch that hides the error, no special case for the failing input.
23
23
  4. **Make the smallest fix.** Don't refactor or touch unrelated code.
24
- 5. **Verify.** The check from step 2 passes now, and stays in the project so the bug can't come back unnoticed. Then follow `.agents/skills/m-test/SKILL.md` for the spec its flow is named after, so the area's other checks run too; without one, `sh scripts/amk/verify.sh quick` and, for a bug on the device, `sh scripts/amk/verify.sh ios --flow <path>` and `android`, looking at the screenshots (`--screens` limits it to the screens the bug is on, such as `--screens tablet-landscape`). Paste the output.
24
+ 5. **Verify.** The check from step 2 passes now, and stays in the project so the bug can't come back unnoticed. Then follow `.agents/skills/m-test/SKILL.md` for `<the spec its flow is named after> --changed`: the flows reaching what the fix changed; without a spec, `sh scripts/amk/verify.sh quick`, and for a bug on the device `sh scripts/amk/verify.sh ios --changed` and `android`, looking at the screenshots (`--screens tablet-landscape`, say, for the screens the bug is on). Paste the output.
25
25
  6. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
26
26
  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`. A case the spec didn't cover becomes a scenario of its requirement there, and the check from step 2 is named after it: the Jest test's title, or a `# Scenario: <name>` block in the bug's flow.
27
27
  8. **Commit** on a branch of its own (`fix/<issue number>`, else `fix/<slug>`), with a message naming the cause you confirmed, for whoever debugs it next. Ask before pushing, then open a PR with the evidence; for an issue, its description says `Fixes #<number>`.
@@ -38,7 +38,7 @@ If no requirement changes, as with a pure style change, skip the spec files (ste
38
38
  1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Write `specs/<id>/requirements.md` with a title, a one-line goal and only the requirements that change, under `## MODIFIED Requirements: <area>` (or ADDED or REMOVED; the format is in `specs/current/README.md`). Run `node scripts/amk/specs.js check specs/<id>/requirements.md`.
39
39
  2. Change the code, and add or update a test where logic changed. A text it adds or changes, in an app with language files, goes into each language's file and `specs/<id>/translations.md`, as the React Native rules file `AGENTS.md` names says (Texts in several languages).
40
40
  3. Run `sh scripts/amk/verify.sh quick` and show its output.
41
- 4. For a visible change, write `.maestro/<id>.yaml` (`node scripts/amk/specs.js flow <id>` starts it from `specs/_templates/flow.yaml`): open the changed screen and take a screenshot. Then follow `.agents/skills/m-test/SKILL.md` for `<id>`, which checks it on the devices with the flows of the area it changes and writes the test report. Off a Mac it checks Android only: say that iOS still needs checking on a Mac.
41
+ 4. For a visible change, write `.maestro/<id>.yaml` (`node scripts/amk/specs.js flow <id>` starts it from `specs/_templates/flow.yaml`): open the changed screen and take a screenshot. Then follow `.agents/skills/m-test/SKILL.md` for `<id> --changed`, which checks it on the devices with the flows of the area it changes and writes the test report. Off a Mac it checks Android only: say that iOS still needs checking on a Mac.
42
42
  5. Run `node scripts/amk/specs.js merge <id>` to update the living spec, and change the doc lines from step 3.
43
43
  6. Copy `specs/_templates/progress.md` to `specs/<id>/progress.md`, set `Status: done`, and write down the checks and their results.
44
44
 
@@ -30,7 +30,7 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
30
30
 
31
31
  ## 2. Requirements (then stop for approval)
32
32
 
33
- 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.
33
+ 1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Run `node scripts/amk/specs.js branch <id>`: it makes the feature's branch, on a feature branch not merged yet when there is one (this one builds on it), else on main, and says which. 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.
34
34
  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.
35
35
  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.
36
36
  4. Fill `requirements.md`: the goal; the user stories (who it's for and why, each naming its requirements) and use cases (the journey and what can go differently, each alternative flow and exception naming the scenario that tests it); 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`.
@@ -47,7 +47,7 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
47
47
  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 (a single choice, with a preview of each where your tool shows one): 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).
48
48
  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`.
49
49
  3. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations), and `## Tests`. For those, run `node scripts/amk/specs.js tests <id>`: give each scenario its check (a Jest test named after it, a flow block, or manual steps for what a flow can't do), say what happens to the tests of the requirements this modifies or removes, and take the regression command it prints, adding the flows no spec links to that this touches. Calls the backend doesn't have yet: `## API contract`.
50
- 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` (`node scripts/amk/specs.js flow <id>` starts it from `specs/_templates/flow.yaml`, a block for each scenario): 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`).
50
+ 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`: `node scripts/amk/specs.js flow <id>` starts it from `specs/_templates/flow.yaml`, whose comments say how (a `# Scenario` block per scenario with its assertion and screenshot, `testID` taps, empty and error states, starting at the screen). 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`).
51
51
  5. Show design and tasks and **stop until the user approves them**: a question of its own, asked once no question is open. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
52
52
 
53
53
  From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
@@ -79,6 +79,6 @@ Then update the `docs/amk/` files the feature made untrue: a new key journey in
79
79
  ## 7. Review and pull request
80
80
 
81
81
  1. Run `m-review` (or the `m-reviewer` subagent, if your tool has subagents). Fix real problems only; skip style nits.
82
- 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.
82
+ 2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR against the branch it started from (`progress.md`'s start line); once that one merges, `node scripts/amk/pr.js forward` moves it to main. 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.
83
83
 
84
84
  Never claim a check passed without running it in this session.
@@ -8,17 +8,17 @@ disable-model-invocation: true
8
8
 
9
9
  The user chose this workflow, directly or through `m-feature`, `m-change`, `m-bugfix` or `m-release`: follow its steps, even where other workflow instructions in this project (Superpowers, BMAD, proAgents or similar) say otherwise.
10
10
 
11
- Input: $ARGUMENTS (a spec ID; or `release <version>`, with the flows `m-release` chose).
11
+ Input: $ARGUMENTS (a spec ID, with `--changed` from `m-change` and `m-bugfix`: only the flows that reach what the branch changed; or `release <version>`, with the flows `m-release` chose).
12
12
 
13
13
  1. **Scope.** The spec's test plan (`## Tests` in `design.md`), or its scenarios when it has none, and `node scripts/amk/specs.js tests <id>` (a release: `specs.js tests`): the flows to run, the tests to change or retire, and the scenarios nothing checks.
14
14
  2. **Code checks.** `sh scripts/amk/verify.sh quick --label <id>` (the whole test suite, compared with the base branch), and `node scripts/amk/coverage.js check` when the app has `.amk-coverage`. Their output stays in `.amk/evidence/<id>/`.
15
- 3. **Devices,** for the flows the scope lists: `sh scripts/amk/verify.sh plan` with the options of the test plan's regression command (`--spec <id>,<the specs of the areas it touches> --label <id>`), and `--mock` while a call in the design's `## API contract` isn't on the backend yet (its evidence is then in `.amk/evidence/<id>-mock/`). It says how many devices this machine's memory can check at the same time, and prints the commands.
15
+ 3. **Devices,** for the flows the scope lists: `sh scripts/amk/verify.sh plan` with the options of the test plan's regression command (`--spec <id>,<the specs of the areas it touches> --label <id>`; with `--changed`, `--changed --spec <id> --label <id>`), and `--mock` while a call in the design's `## API contract` isn't on the backend yet (its evidence is then in `.amk/evidence/<id>-mock/`). It says how many devices this machine's memory can check at the same time, and prints the commands.
16
16
  - **One command** (`verify.sh all` with those options): run it.
17
17
  - **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. When all are back, check them yourself: every screen has screenshots in its folder, or in each `part-k/` folder when its flows ran in parts. A report alone isn't evidence. Without subagents, run that `verify.sh all` command instead.
18
18
 
19
19
  `verify.sh` compares each screenshot with the approved one and lists those that changed: open every one it lists, and at least one per screen. Once the user accepts how they look, `sh scripts/amk/verify.sh approve --label <id>` makes them the approved ones. Off a Mac it checks Android only: iOS is blocked (no Mac) until a teammate runs it. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
20
20
  4. **The verdict.** Give the `m-tester` subagent the spec ID (or the release), the evidence folder and what didn't run and why; without subagents, follow `.rulesync/subagents/m-tester.md` yourself. It gives each scenario a status and ends with Ready or Not ready.
21
21
  5. **The report.** Write `specs/<id>/test-report.md` (a release: `release-notes/<version>/test-report.md`) from `specs/_templates/test-report.md`, and show the verdict.
22
- 6. **After a fix,** run the failed flows again with `--flow <file>`, then the whole set, and update the report. After two failed attempts at the same fix, stop and report.
22
+ 6. **After a fix,** run the failed flows again with `--flow <file> --screens phone-portrait` (one screen while fixing), then the whole set on every screen, and update the report. After two failed attempts at the same fix, stop and report.
23
23
 
24
24
  Never count a check as passed without this run's evidence.
@@ -7,7 +7,7 @@ set -eu
7
7
  # settings, the workflows, the agents' instructions, the coverage floors and size caps, and the code owners (the same
8
8
  # list as autopilot.js and guard.js). A person changes them, in a reviewed pull request
9
9
  if [ -n "${AMK_AUTOPILOT:-}" ]; then
10
- kept=$(git diff --cached --name-only | grep -E '^(scripts/amk/|\.rulesync/|\.githooks/|\.github/workflows/|\.agents/|\.claude/|\.codex/|((\.github|docs)/)?CODEOWNERS$|AGENTS\.md$|CLAUDE\.md$|rulesync\.jsonc$|\.amk-(coverage|size-caps|secrets)$)' || true)
10
+ kept=$(git diff --cached --name-only | grep -E '^(scripts/amk/|\.rulesync/|\.githooks/|\.github/workflows/|\.agents/|\.claude/|\.codex/|((\.github|docs)/)?CODEOWNERS$|AGENTS\.md$|CLAUDE\.md$|rulesync\.jsonc$|\.amk-(coverage|size-caps|secrets|screens)$)' || true)
11
11
  # merging main in brings its versions (a kit update there): only a file that differs from the merged branch's is a change
12
12
  if [ -n "$kept" ] && git rev-parse -q --verify MERGE_HEAD > /dev/null; then
13
13
  kept=$(for f in $kept; do [ "$(git rev-parse -q ":$f" 2> /dev/null)" = "$(git rev-parse -q "MERGE_HEAD:$f" 2> /dev/null)" ] || echo "$f"; done)
@@ -48,8 +48,10 @@ jobs:
48
48
  run: npx -y rulesync@27.0.0 generate > /dev/null && node scripts/amk/tool-configs.js && git diff --exit-code -- .claude .codex .agents .antigravity
49
49
  - name: Secret scan
50
50
  run: docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1 git /repo --no-banner --redact
51
+ # the weekly kit update (amk-kit-update.yml, on amk/kit-<version>) is mostly the kit's own files, read from its
52
+ # release notes rather than line by line: no size limit there
51
53
  - name: PR size (max 600 changed lines; label "large-pr" to override)
52
- if: github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'large-pr')
54
+ if: github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'large-pr') && !startsWith(github.head_ref, 'amk/kit-')
53
55
  run: |
54
56
  lines=$(git diff --numstat "origin/${{ github.base_ref }}...HEAD" -- . ':(exclude)*.lock' ':(exclude)package-lock.json' ':(exclude)pnpm-lock.yaml' ':(exclude)*.snap' | awk '{ s += $1 + $2 } END { print s + 0 }')
55
57
  echo "$lines changed lines"
@@ -7,6 +7,10 @@
7
7
  // so it also runs in PowerShell. No matcher: runs for every tool call; guard.js decides from the payload
8
8
  "preToolUse": [{ "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/guard.js')\"" }],
9
9
  "stop": [{ "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/handoff-check.js')\"" }],
10
+ // when the AI waits for you, a notification (scripts/amk/notify.js): Claude Code's permission prompts and replies it
11
+ // has waited a minute for, Codex's approvals. Every finished turn comes from the stop hook (handoff-check.js)
12
+ "notification": [{ "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/notify.js').hook()\"" }],
13
+ "permissionRequest": [{ "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/notify.js').hook()\"" }],
10
14
  // after a compaction (Claude Code, and Codex where it calls it), the spec's handoff, next task and definition of done
11
15
  "sessionStart": [{ "matcher": "compact", "command": "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/handoff-check.js')\"" }]
12
16
  }
@@ -11,6 +11,11 @@ Recurring errors and their fixes. Check here before debugging a build error. Rem
11
11
 
12
12
  ## Entries
13
13
 
14
+ ### iOS build: "unable to initiate PIF transfer session (operation in progress?)"
15
+ - **Cause:** two builds of the same project at once: a build from the command line (`verify.sh`, `ios-build.sh`) while Xcode builds or indexes it. No `xcodebuild` needs to be running: Xcode's build service holds the project.
16
+ - **Fix:** let Xcode finish, or quit it, then build again. If it stays stuck: `pkill -f SWBBuildService` (Xcode's build service, which starts again when needed), then build again.
17
+ - **Prevention:** don't start a command-line build while Xcode builds or indexes the same project.
18
+
14
19
  ### iOS build fails right after a native dependency was added or removed
15
20
  - **Cause:** `ios/Pods` is out of date.
16
21
  - **Fix:** `sh scripts/amk/pod-install.sh`, then rebuild.
@@ -37,6 +37,7 @@ Rules for things AI agents commonly get wrong in current React Native. Each one
37
37
  - Landscape leaves little height: screens scroll, the keyboard covers more, and the safe-area insets include the left and right edges (the notch or Dynamic Island side).
38
38
  - Android ignores orientation and size locks on tablets and foldables (600 dp wide and up) for apps targeting Android 16 (API 36), and from Android 17 (API 37) apps can't opt out. Apple deprecated `UIRequiresFullScreen` with iPadOS 26, so iPad windows resize too. Every screen has to work at any window size and turned, whatever the app's settings say.
39
39
  - Don't lock the orientation in code to avoid layout work. Which orientations the app supports is a product decision, set in `Info.plist` (`UISupportedInterfaceOrientations`, and `~ipad` for iPads) and the Android manifest (`android:screenOrientation`); the iPad app itself is the Xcode target's device family.
40
+ - A team that checks fewer screens than the app supports (phones only, say) lists them in `.amk-screens`, as `--screens` takes them: `phone`. `verify.sh` then never checks the others, whatever `--screens` asks (`portrait` and `landscape` otherwise include the tablet's), and `node scripts/amk/screens.js` prints the sentence for `AGENTS.md`'s Screens line.
40
41
 
41
42
  ## Current React Native and React
42
43
 
@@ -94,7 +94,7 @@ const COMMANDS = pm => ['sh scripts/amk/verify.sh', 'node scripts/amk/specs.js',
94
94
  // what an unattended run never changes (guard.js and the pre-commit hook hold the same list): the kit's scripts, hooks
95
95
  // and tool settings, the workflows, the agents' instructions, the coverage floors and size caps, and the code owners
96
96
  const GUARDRAILS = ['scripts/amk/', '.rulesync/', '.githooks/', '.github/workflows/', '.agents/', '.claude/', '.codex/', 'AGENTS.md',
97
- 'CLAUDE.md', 'rulesync.jsonc', '.amk-coverage', '.amk-size-caps', '.amk-secrets', 'CODEOWNERS', '.github/CODEOWNERS', 'docs/CODEOWNERS'];
97
+ 'CLAUDE.md', 'rulesync.jsonc', '.amk-coverage', '.amk-size-caps', '.amk-secrets', '.amk-screens', 'CODEOWNERS', '.github/CODEOWNERS', 'docs/CODEOWNERS'];
98
98
  // a path as Claude Code's rules write an absolute one: //Users/…, or //c/Users/… on Windows
99
99
  const rulePath = p => `/${process.platform === 'win32' ? p.replace(/\\/g, '/').replace(/^([A-Za-z]):/, (_, d) => `/${d.toLowerCase()}`) : p}`;
100
100
  // Claude Code: --permission-mode dontAsk refuses what isn't allowed rather than asking, and what the project's settings
@@ -70,7 +70,7 @@ for (const p of paths) {
70
70
  // auto-merge, touch the trigger labels, push anything but a feature/ or fix/ branch by name, or change the guardrails
71
71
  // (autopilot.js and the pre-commit hook hold the same list)
72
72
  if (process.env.AMK_AUTOPILOT) {
73
- const GUARDRAILS = /^(?:scripts\/amk\/|\.rulesync\/|\.githooks\/|\.github\/workflows\/|\.agents\/|\.claude\/|\.codex\/|(?:\.github\/|docs\/)?CODEOWNERS$|AGENTS\.md$|CLAUDE\.md$|rulesync\.jsonc$|\.amk-(?:coverage|size-caps|secrets)$)/;
73
+ const GUARDRAILS = /^(?:scripts\/amk\/|\.rulesync\/|\.githooks\/|\.github\/workflows\/|\.agents\/|\.claude\/|\.codex\/|(?:\.github\/|docs\/)?CODEOWNERS$|AGENTS\.md$|CLAUDE\.md$|rulesync\.jsonc$|\.amk-(?:coverage|size-caps|secrets|screens)$)/;
74
74
  const roots = [root, fs.realpathSync(root)];
75
75
  const rel = p => roots.map(r => path.relative(r, path.resolve(r, p)).replace(/\\/g, '/')).find(x => !x.startsWith('..')) || '';
76
76
  // relative to the project, or as written without leading ../ (after a cd the guard doesn't follow)
@@ -43,7 +43,10 @@ if (payload.hook_event_name === 'SessionStart') {
43
43
  process.exit(0);
44
44
  }
45
45
 
46
- if (payload.stop_hook_active && !unattended) process.exit(0); // already reminded once; don't loop
46
+ // the turn really ends here (nothing below asks to go on): tell the developer, who may be in another window
47
+ const ends = () => { try { require('./notify.js').notify({ ...payload, hook_event_name: 'Stop' }); } catch {} process.exit(0); };
48
+
49
+ if (payload.stop_hook_active && !unattended) ends(); // already reminded once; don't loop
47
50
 
48
51
  // unattended: the feature's state at this stop (its last commit, ticked tasks and next step)
49
52
  const progress = unattended && own ? read(`specs/${own}/progress.md`) || '' : null;
@@ -52,9 +55,13 @@ const state = progress === null ? null : JSON.stringify([sh('git rev-parse HEAD'
52
55
 
53
56
  // code changed without the handoff: asked once (stop_hook_active: the agent goes on because of an earlier ask)
54
57
  if ((working.length || progress !== null) && !payload.stop_hook_active) {
55
- const changed = sh('git status --porcelain --untracked-files=all') // every new file, not just its new folder
56
- .split('\n').filter(Boolean).map(l => l.slice(3));
57
- const codeChanged = changed.some(f => !f.startsWith('specs/') && !f.startsWith('.amk/'));
58
+ // every new file, not just its new folder; but not a new link, such as the project's node_modules linked into a git
59
+ // worktree: no session writes code that way, and it would ask at every stop
60
+ const link = f => { try { return fs.lstatSync(path.join(root, f)).isSymbolicLink(); } catch { return false; } };
61
+ const changed = sh('git status --porcelain --untracked-files=all')
62
+ .split('\n').filter(Boolean).filter(l => !(l.startsWith('?? ') && link(l.slice(3)))).map(l => l.slice(3));
63
+ // not the AI tool's worktrees inside the project (Claude Code's .claude/worktrees/): another session's work
64
+ const codeChanged = changed.some(f => !f.startsWith('specs/') && !f.startsWith('.amk/') && !f.startsWith('.claude/worktrees/'));
58
65
  const handoffUpdated = changed.some(f => /^specs\/[^/]+\/progress\.md$/.test(f));
59
66
  if (codeChanged && !handoffUpdated) {
60
67
  process.stderr.write('There are uncommitted code changes, but no specs/<id>/progress.md was updated. ' +
@@ -101,4 +108,4 @@ if (progress !== null && !fs.existsSync(path.join(root, '.amk', 'build', 'STOP')
101
108
  process.exit(2);
102
109
  }
103
110
  }
104
- process.exit(0);
111
+ ends();
@@ -0,0 +1,85 @@
1
+ #!/usr/bin/env node
2
+ // Tells you when the AI waits for you, so a session in another window doesn't sit there unanswered: a desktop
3
+ // notification (macOS, Linux with notify-send, Windows) and, with AMK_NOTIFY_URL set, a chat or phone webhook (Slack,
4
+ // Google Chat, Discord). Hooks of the AI tool start it:
5
+ // Notification (Claude Code) a permission prompt, or a reply it has waited a minute for
6
+ // PermissionRequest (Codex) an approval (Claude Code says those through Notification)
7
+ // Stop (every tool) every finished turn, from handoff-check.js once the turn really ends: what it asks
8
+ // AMK_NOTIFY=off turns it off; AMK_NOTIFY=ask keeps the approvals, the waiting and the turns that end with a question.
9
+ // An unattended build (autopilot.js) notifies by itself, so nothing comes from here then.
10
+ 'use strict';
11
+ const fs = require('fs');
12
+ const os = require('os');
13
+ const path = require('path');
14
+ const { spawn, spawnSync } = require('child_process');
15
+ const { redact } = require('./redact.js');
16
+
17
+ const root = path.join(__dirname, '..', '..');
18
+
19
+ // what the AI said last: the payload's, or the last assistant text in its transcript (one JSON event a line)
20
+ function lastWords(p) {
21
+ if (typeof p.last_assistant_message === 'string') return p.last_assistant_message;
22
+ try {
23
+ for (const line of fs.readFileSync(p.transcript_path, 'utf8').trim().split('\n').reverse()) {
24
+ let e;
25
+ try { e = JSON.parse(line); } catch { continue; }
26
+ const c = e.type === 'assistant' && e.message && e.message.content;
27
+ const text = Array.isArray(c) ? c.filter(x => x && x.type === 'text').map(x => x.text).join('\n') : typeof c === 'string' ? c : '';
28
+ if (text.trim()) return text;
29
+ }
30
+ } catch {}
31
+ return '';
32
+ }
33
+ const toolOf = (p, env) => (/[\\/]\.claude[\\/]/.test(p.transcript_path || '') || env.CLAUDECODE ? 'Claude Code'
34
+ : /[\\/]\.codex[\\/]/.test(p.transcript_path || '') ? 'Codex' : 'The AI');
35
+
36
+ // the notification for a hook's payload: { title, text }, or null
37
+ function message(p, env = process.env) {
38
+ const mode = String(env.AMK_NOTIFY || 'on').toLowerCase();
39
+ if (env.AMK_AUTOPILOT || ['off', '0', 'no', 'false'].includes(mode)) return null;
40
+ const project = path.basename(root);
41
+ const tool = toolOf(p, env);
42
+ const event = p.hook_event_name || '';
43
+ if (event === 'Notification') return { title: `${project}: ${tool} is waiting for you`, text: p.message || 'It needs your answer or approval.' };
44
+ if (event === 'PermissionRequest') {
45
+ if (tool === 'Claude Code') return null;
46
+ const input = p.tool_input || {};
47
+ return { title: `${project}: ${tool} needs your approval`, text: String(input.command || input.file_path || p.tool_name || 'a command') };
48
+ }
49
+ if (event !== 'Stop') return null;
50
+ const lines = lastWords(p).split('\n').map(l => l.replace(/[*_`#>]/g, '').trim()).filter(Boolean);
51
+ const question = lines.filter(l => /\?$/.test(l)).pop() || lines.find(l => /\bapprov/i.test(l));
52
+ if (mode === 'ask' && !question) return null;
53
+ return { title: `${project}: ${tool} ${question ? 'asks you' : 'finished'}`, text: question || lines[0] || 'Its turn is over.' };
54
+ }
55
+
56
+ // the desktop notification now, the webhook in a process of its own: a hook returns at once. Those processes start in
57
+ // the temp folder: on Windows a process holds the folder it runs in, and the project's would be locked meanwhile
58
+ function send(n, env = process.env) {
59
+ const text = redact(n.text).replace(/[\u0000-\u001f\u2028\u2029]+/g, ' ').slice(0, 300);
60
+ const title = n.title.slice(0, 120);
61
+ try {
62
+ if (process.platform === 'darwin') spawnSync('osascript', ['-e', `display notification ${JSON.stringify(text)} with title ${JSON.stringify(title)}`], { stdio: 'ignore', timeout: 10000 });
63
+ else if (process.platform === 'linux') spawnSync('notify-send', [title, text], { stdio: 'ignore', timeout: 10000 });
64
+ else if (process.platform === 'win32') {
65
+ const q = s => `'${s.replace(/'/g, "''")}'`;
66
+ spawn('powershell', ['-NoProfile', '-Command', `Add-Type -AssemblyName System.Windows.Forms; $n = New-Object System.Windows.Forms.NotifyIcon; $n.Icon = [System.Drawing.SystemIcons]::Information; $n.Visible = $true; $n.ShowBalloonTip(10000, ${q(title)}, ${q(text)}, 'Info'); Start-Sleep 10; $n.Dispose()`],
67
+ { detached: true, stdio: 'ignore', windowsHide: true, cwd: os.tmpdir() }).on('error', () => {}).unref();
68
+ }
69
+ } catch {}
70
+ if (!env.AMK_NOTIFY_URL) return;
71
+ // Slack and Google Chat read text, Discord content
72
+ const body = JSON.stringify({ text: `${title}: ${text}`, content: `${title}: ${text}` });
73
+ spawn(process.execPath, ['-e', 'fetch(process.argv[1], { method: "POST", headers: { "content-type": "application/json" }, body: process.argv[2], signal: AbortSignal.timeout(10000) }).catch(() => {})',
74
+ env.AMK_NOTIFY_URL, body], { detached: true, stdio: 'ignore', env, cwd: os.tmpdir() }).on('error', () => {}).unref();
75
+ }
76
+
77
+ const notify = (p, env = process.env) => { const n = message(p, env); if (n) send(n, env); return n; };
78
+ // a hook's own start: its payload on stdin
79
+ function hook() {
80
+ let p = {};
81
+ try { p = JSON.parse(fs.readFileSync(0, 'utf8')); } catch {}
82
+ notify(p);
83
+ }
84
+
85
+ module.exports = { message, send, notify, hook, lastWords };
@@ -167,15 +167,17 @@ function forward(main, { check = true } = {}, cfg = settings(), io = IO) {
167
167
  specs.fetchOrigin();
168
168
  const ref = specs.planRef();
169
169
  const plan = ref && specs.show(ref, 'specs/plan.md');
170
- if (!plan) return 0;
170
+ // the plan's features, and those built feature by feature on a branch of their own (specs.js branch)
171
+ const local = (git('for-each-ref', '--format=%(refname:short)', 'refs/heads/feature/') || '').split('\n').filter(Boolean).map(b => b.slice(8));
172
+ const ids = [...new Set([...(plan ? specs.planFeatures(plan).rows.map(r => r.id) : []), ...local])];
171
173
  const built = specs.builtOn(main);
172
174
  const was = branchNow();
173
175
  let code = 0;
174
- for (const r of specs.planFeatures(plan).rows) {
175
- const b = `feature/${r.id}`;
176
- if (built.has(r.id) || git('rev-parse', '--verify', '--quiet', `refs/heads/${b}`) === null) continue;
176
+ for (const id of ids) {
177
+ const b = `feature/${id}`;
178
+ if (built.has(id) || git('rev-parse', '--verify', '--quiet', `refs/heads/${b}`) === null) continue;
177
179
  // its pull request's base, from the start line specs.js start wrote: a stacked branch's parent
178
- const parent = (/its PR goes to ([^)\s]+)\)/.exec(git('show', `${b}:specs/${r.id}/progress.md`) || '') || [])[1];
180
+ const parent = (/its PR goes to ([^)\s]+)\)/.exec(git('show', `${b}:specs/${id}/progress.md`) || '') || [])[1];
179
181
  const parentId = parent && (/^feature\/(.+)$/.exec(parent) || [])[1];
180
182
  if (!parentId || !built.has(parentId)) continue;
181
183
  if (git('merge-base', '--is-ancestor', main, b) === null) {
@@ -183,7 +185,7 @@ function forward(main, { check = true } = {}, cfg = settings(), io = IO) {
183
185
  const before = git('rev-parse', 'HEAD');
184
186
  let s = { rest: [] };
185
187
  if (git('merge', '--no-edit', '--quiet', main) === null) {
186
- s = settle(r.id);
188
+ s = settle(id);
187
189
  if (s.rest.length || git('commit', '--no-edit', '--quiet') === null) {
188
190
  git('merge', '--abort');
189
191
  io.log(`${b}: main can't be merged in without a person: ${s.rest.length ? `conflicts in ${s.rest.join(', ')}` : 'the merge commit was refused (see the hook\'s message)'}. Merge main into it by hand, then push.`);
@@ -195,9 +197,9 @@ function forward(main, { check = true } = {}, cfg = settings(), io = IO) {
195
197
  if (s.lock || changed.some(f => LOCKS.test(f))) sh('sh', ['scripts/amk/install-deps.sh'], { stdio: 'ignore' });
196
198
  if ((s.pods || changed.includes('ios/Podfile.lock')) && process.platform === 'darwin') sh('sh', ['scripts/amk/pod-install.sh'], { stdio: 'ignore' });
197
199
  if (s.spec) {
198
- sh(process.execPath, ['scripts/amk/specs.js', 'merge', r.id], { stdio: 'ignore' });
200
+ sh(process.execPath, ['scripts/amk/specs.js', 'merge', id], { stdio: 'ignore' });
199
201
  git('add', '--', 'specs/current/');
200
- git('commit', '--quiet', '-m', `docs(spec): ${r.id} merged into the living spec again, after main\n\nSpec: specs/${r.id}`);
202
+ git('commit', '--quiet', '-m', `docs(spec): ${id} merged into the living spec again, after main\n\nSpec: specs/${id}`);
201
203
  }
202
204
  if (check && sh('sh', ['scripts/amk/verify.sh', 'quick'], { stdio: 'ignore' }).status !== 0) {
203
205
  git('reset', '--quiet', '--keep', before);
@@ -2,7 +2,8 @@
2
2
  // The screens the app supports: phones and tablets, portrait and landscape, on iOS and Android. Read from the native
3
3
  // projects (app.json in an Expo app that doesn't have them yet), so agents build for them and verify.sh checks them.
4
4
  // The app runs on tablets when its iOS app runs on iPad; Android runs every app on tablets, but the kit checks
5
- // Android tablets only for apps made for tablets.
5
+ // Android tablets only for apps made for tablets. A team that checks fewer screens than the app supports (phones only,
6
+ // say) writes them in .amk-screens, as --screens takes them: "phone". The kit then never checks the others.
6
7
  // Usage: node scripts/amk/screens.js one sentence, as AGENTS.md says it
7
8
  // node scripts/amk/screens.js ios|android the screens to check, one per line: phone-portrait, tablet-landscape, …
8
9
  'use strict';
@@ -59,14 +60,31 @@ function expo(cwd) {
59
60
  return { ios: { phone, tablet: config.ios && config.ios.supportsTablet ? phone : null }, android: { phone, tablet: BOTH } };
60
61
  }
61
62
 
63
+ // .amk-screens: the screens the team checks, comma or space separated, as --screens takes them (phone, tablet,
64
+ // portrait, landscape, tablet-landscape, …); # starts a comment. Without it, every screen the app supports
65
+ function capOf(cwd) {
66
+ const words = (read(path.join(cwd, '.amk-screens')) || '').replace(/#.*$/gm, '').split(/[\s,]+/).filter(Boolean);
67
+ return words.length ? words : null;
68
+ }
69
+ // a screen a word names: the word itself, or one of its two parts (phone, landscape, …)
70
+ const named = (screen, words) => words.some(w => screen === w || screen.startsWith(`${w}-`) || screen.endsWith(`-${w}`));
71
+ function capped(p, words) {
72
+ if (!p || !words) return p;
73
+ const keep = kind => (p[kind] || []).filter(o => named(`${kind}-${o}`, words));
74
+ const tablet = keep('tablet');
75
+ return { phone: keep('phone'), tablet: tablet.length ? tablet : null };
76
+ }
77
+
62
78
  function screens(cwd) {
63
79
  const fromExpo = expo(cwd);
64
80
  const i = ios(cwd) || (fromExpo && fromExpo.ios);
65
81
  const a = android(cwd) || (fromExpo && fromExpo.android);
66
82
  const tablets = Boolean(i && i.tablet);
83
+ const cap = capOf(cwd);
67
84
  return {
68
- ios: i && { phone: i.phone, tablet: tablets ? i.tablet : null },
69
- android: a && { phone: a.phone, tablet: tablets ? a.tablet : null },
85
+ ios: capped(i && { phone: i.phone, tablet: tablets ? i.tablet : null }, cap),
86
+ android: capped(a && { phone: a.phone, tablet: tablets ? a.tablet : null }, cap),
87
+ cap,
70
88
  };
71
89
  }
72
90
 
@@ -78,16 +96,20 @@ function list(s, platform) {
78
96
 
79
97
  function describe(s) {
80
98
  const say = o => (o.length === 2 ? 'portrait and landscape' : `${o[0]} only`);
99
+ const of = (platform, kind) => { const o = s[platform] && s[platform][kind]; return o && o.length ? o : null; };
81
100
  const part = (kind, apple) => {
82
- const i = s.ios && s.ios[kind];
83
- const a = s.android && s.android[kind];
101
+ const i = of('ios', kind);
102
+ const a = of('android', kind);
84
103
  if (i && a && say(i) !== say(a)) return `${say(i)} on ${apple}, ${say(a)} on Android`;
85
104
  return say(i || a || ['portrait']);
86
105
  };
87
- const tablets = (s.ios && s.ios.tablet) || (s.android && s.android.tablet);
106
+ const tablets = of('ios', 'tablet') || of('android', 'tablet');
107
+ const phones = of('ios', 'phone') || of('android', 'phone') || !tablets;
108
+ const why = s.cap ? ', as .amk-screens says' : '';
109
+ if (!phones) return `tablets only (${part('tablet', 'iPad')})${why}`;
88
110
  return tablets
89
- ? `phones (${part('phone', 'iPhone')}) and tablets (${part('tablet', 'iPad')})`
90
- : `phones only (${part('phone', 'iPhone')}), no iPad app`;
111
+ ? `phones (${part('phone', 'iPhone')}) and tablets (${part('tablet', 'iPad')})${why}`
112
+ : `phones only (${part('phone', 'iPhone')})${why || ', no iPad app'}`;
91
113
  }
92
114
 
93
115
  if (require.main === module) {
@@ -18,6 +18,12 @@
18
18
  // dependencies built or on the build's stack), or <id>. Makes feature/<id>
19
19
  // from main or the top of the stack, with the spec as of its approval commit.
20
20
  // Exits 3 when none is ready, 4 when the living spec changed under it
21
+ // node scripts/amk/specs.js changed-flows the flows that reach what this branch changed since main: those using a
22
+ // testID a changed file sets (or running a subflow that does), and the flows
23
+ // changed themselves; verify.sh --changed runs them
24
+ // node scripts/amk/specs.js branch <id> a feature built feature by feature: makes feature/<id>, on a feature branch
25
+ // not merged into main yet when there is one (the one you're on, else the
26
+ // newest: part 1 of a feature split in parts), so it has that code; else main
21
27
  // node scripts/amk/specs.js import <file> a CSV export (a spreadsheet saved as CSV) or a Trello board's JSON export,
22
28
  // a line per row or open card, as outside text to plan from
23
29
  // A requirement is "### Requirement: <name>", a sentence with SHALL or MUST, and at least one
@@ -748,6 +754,58 @@ function fetchOrigin() {
748
754
  try { execFileSync('git', ['fetch', '--quiet', 'origin'], { stdio: 'ignore', timeout: 60000, env }); } catch {}
749
755
  }
750
756
 
757
+ // the flows that reach what this branch changed since main, for a small change's device check: those that use a testID
758
+ // a changed file sets (testID="…", testID: '…'), or run a subflow that does, and the flows changed themselves
759
+ function changedFlows() {
760
+ const main = mainRef();
761
+ // without a main branch to compare with, what's changed and not committed yet
762
+ const base = (main && git('merge-base', 'HEAD', main)) || 'HEAD';
763
+ const files = [...new Set([...(git('diff', '--name-only', base) || '').split('\n'),
764
+ ...(git('ls-files', '--others', '--exclude-standard') || '').split('\n')])].filter(Boolean);
765
+ const ids = new Set();
766
+ for (const f of files.filter(x => /\.(jsx?|tsx?)$/.test(x) && !x.startsWith('scripts/amk/'))) {
767
+ for (const m of (read(f) || '').matchAll(/testID\s*[=:]\s*\{?\s*(["'`])([^"'`$]+)\1/g)) ids.add(m[2]);
768
+ }
769
+ const uses = text => [...stripYamlComments(text || '').matchAll(/\bid:\s*["']?([^"'\s,}]+)/g)].some(m => ids.has(m[1]));
770
+ const subs = allFlows('.maestro/subflows').map(f => `subflows/${f}`).filter(f => files.includes(`.maestro/${f}`) || uses(read(`.maestro/${f}`)));
771
+ return allFlows().filter(f => {
772
+ const text = read(`.maestro/${f}`) || '';
773
+ return files.includes(`.maestro/${f}`) || uses(text) || subs.some(sf => text.includes(sf));
774
+ }).map(f => path.resolve('.maestro', f));
775
+ }
776
+
777
+ // the start line in a feature's progress.md: where it started, and where its PR goes (pr.js forward reads it)
778
+ function logStart(id, line) {
779
+ const progress = `specs/${id}/progress.md`;
780
+ const p = read(progress) || read('specs/_templates/progress.md') || '## Log\n';
781
+ fs.mkdirSync(path.dirname(progress), { recursive: true });
782
+ fs.writeFileSync(progress, /^## Log\s*$/m.test(p) ? p.replace(/^## Log\s*\n(\s*<!--[\s\S]*?-->\s*\n)?/m, m => `${m.replace(/\n*$/, '\n')}\n${line}\n`) : `${p.replace(/\n*$/, '\n')}\n## Log\n\n${line}\n`);
783
+ }
784
+ // feature by feature: the branch a feature is built on. A feature branch not merged into main yet (part 1 of a feature
785
+ // split in parts, its PR still open) is where the next one starts, so the next one has its code: the one you're on,
786
+ // else the newest. Its PR then goes there, and pr.js forward moves it into main once that one merges
787
+ function branchFeature(id) {
788
+ const name = `feature/${id}`;
789
+ if (branch() === name) { console.log(`On ${name} already.`); return 0; }
790
+ if (exists(name)) {
791
+ if (git('switch', '--quiet', name) === null) { console.error(`git switch ${name} failed: commit or stash what's changed here first.`); return 1; }
792
+ console.log(`Switched to ${name}, where ${id} is built.`);
793
+ return 0;
794
+ }
795
+ fetchOrigin();
796
+ const main = mainRef();
797
+ if (!main) { console.error('No main branch found: set AMK_BASE to the branch features start from.'); return 1; }
798
+ const built = builtOn(main);
799
+ const open = (git('for-each-ref', '--sort=-committerdate', '--format=%(refname:short)', 'refs/heads/feature/') || '').split('\n').filter(Boolean)
800
+ .filter(b => !isAncestor(b, main) && !built.has(b.slice(8)) && show(b, `specs/${b.slice(8)}/progress.md`) !== null);
801
+ const from = open.includes(branch()) ? branch() : open[0] || main;
802
+ if (git('switch', '--quiet', '--no-track', '-c', name, from) === null) { console.error(`git switch -c ${name} ${from} failed.`); return 1; }
803
+ logStart(id, `- ${new Date().toISOString().slice(0, 16).replace('T', ' ')}: started from ${from} (its PR goes to ${from.replace(/^origin\//, '')})`);
804
+ console.log(from === main ? `Started ${name} from ${main}.`
805
+ : `Started ${name} from ${from}, which isn't merged into ${main.replace(/^origin\//, '')} yet: ${id} builds on it, and its PR goes there (pr.js forward moves it into ${main.replace(/^origin\//, '')} once ${from} merges).`);
806
+ return 0;
807
+ }
808
+
751
809
  function start(want) {
752
810
  if (branch() === 'plan') { console.error('This folder is on the plan branch: build in a folder on main or a feature branch.'); return 1; }
753
811
  if (git('status', '--porcelain', '--untracked-files=no')) { console.error('Commit the changes here first (git status): a feature starts from a clean folder.'); return 1; }
@@ -796,10 +854,7 @@ function start(want) {
796
854
  for (const a of [['switch', '--quiet', '--no-track', '-c', name, from], ['checkout', approved, '--', `specs/${pick.id}/`]]) {
797
855
  try { execFileSync('git', a, { stdio: ['ignore', 'ignore', 'pipe'] }); } catch (e) { console.error(`git ${a.join(' ')}: ${String(e.stderr || e.message).trim()}`); return 1; }
798
856
  }
799
- const progress = `specs/${pick.id}/progress.md`;
800
- const log = `- ${new Date().toISOString().slice(0, 16).replace('T', ' ')}: started from ${from} (its PR goes to ${from.replace(/^origin\//, '')}), with the spec as approved in ${short} on ${ref}`;
801
- const p = read(progress) || read('specs/_templates/progress.md') || '## Log\n';
802
- fs.writeFileSync(progress, /^## Log\s*$/m.test(p) ? p.replace(/^## Log\s*\n(\s*<!--[\s\S]*?-->\s*\n)?/m, m => `${m.replace(/\n*$/, '\n')}\n${log}\n`) : `${p.replace(/\n*$/, '\n')}\n## Log\n\n${log}\n`);
857
+ logStart(pick.id, `- ${new Date().toISOString().slice(0, 16).replace('T', ' ')}: started from ${from} (its PR goes to ${from.replace(/^origin\//, '')}), with the spec as approved in ${short} on ${ref}`);
803
858
  try {
804
859
  execFileSync('git', ['add', '--', `specs/${pick.id}/`], { stdio: 'ignore' });
805
860
  execFileSync('git', ['commit', '--quiet', '-m', `docs(spec): ${pick.id} from the plan, as approved in ${short}\n\nSpec: specs/${pick.id}`], { stdio: ['ignore', 'ignore', 'pipe'] });
@@ -889,6 +944,10 @@ if (require.main === module) {
889
944
  process.exitCode = status();
890
945
  } else if (cmd === 'start') {
891
946
  process.exitCode = start(args[0]);
947
+ } else if (cmd === 'changed-flows') {
948
+ for (const f of changedFlows()) console.log(f);
949
+ } else if (cmd === 'branch' && args[0]) {
950
+ process.exitCode = branchFeature(args[0]);
892
951
  } else if (cmd === 'plan-folder') {
893
952
  process.exitCode = planFolder();
894
953
  } else if (cmd === 'import' && args[0]) {
@@ -1,7 +1,8 @@
1
1
  #!/bin/sh
2
2
  # Checks the app the way a user would: lint, typecheck and tests, then release builds on the iOS simulator
3
3
  # and Android emulator, running Maestro flows and saving screenshots as evidence. Apps that support tablets or
4
- # landscape (scripts/amk/screens.js) are checked on each: an iPad simulator and a tablet emulator, and turned.
4
+ # landscape (scripts/amk/screens.js) are checked on each: an iPad simulator and a tablet emulator, and turned. A team
5
+ # that checks fewer (phones only) lists them in .amk-screens, and the others are never checked.
5
6
  #
6
7
  # Usage: sh scripts/amk/verify.sh [quick|ios|android|all|build|plan|approve] [--spec <ids>] [--flow <file>] [--label <name>]
7
8
  # [--flavor <name>] [--scheme <name>] [--screens <list>] [--no-build] [--related] [--mock]
@@ -19,11 +20,13 @@
19
20
  # flows of each (a flow's name prefix works too: offline-sync runs offline-sync-1.yaml) and need --label
20
21
  # --flow <file> run only this flow: a path in the project, or anywhere (an absolute path)
21
22
  # --tags <list> only the flows with one of these tags in their header (tags: [smoke]), comma-separated
23
+ # --changed only the flows that reach what this branch changed: they use a testID a changed file sets, or
24
+ # are changed themselves (specs.js changed-flows); with --spec, its flows too
22
25
  # --label <n> evidence folder name (default: the spec id, or no-spec)
23
26
  # --flavor <name> Android product flavor to check (default: the first one in build.gradle)
24
27
  # --scheme <name> iOS scheme to check (default: the one named like the workspace)
25
28
  # --screens <l> only these of the screens the app supports, comma-separated: phone, tablet, portrait,
26
- # landscape, or one such as tablet-landscape
29
+ # landscape, or one such as tablet-landscape (portrait and landscape include the tablet's)
27
30
  # --no-build check the last build instead of building again (after `build`), when it has the same API (--mock)
28
31
  # --mock build with the app's mock API on: the variables in .amk-mock (a NAME=value line each) switch it on, the
29
32
  # way the app reads its other settings. Its evidence goes in <label>-mock/, and its report says so
@@ -71,6 +74,7 @@ only=${AMK_SCREENS:-}
71
74
  no_build=0
72
75
  mock=0
73
76
  related=0
77
+ changed=0
74
78
  build_only=0
75
79
  part=""
76
80
  while [ $# -gt 0 ]; do
@@ -85,6 +89,7 @@ while [ $# -gt 0 ]; do
85
89
  --no-build) no_build=1; shift ;;
86
90
  --mock) mock=1; shift ;;
87
91
  --related) related=1; shift ;;
92
+ --changed) changed=1; shift ;;
88
93
  --part) part=$2; shift 2 ;;
89
94
  *) echo "verify: unknown option $1"; exit 2 ;;
90
95
  esac
@@ -166,8 +171,11 @@ built_api() { echo "$api" > "$root/.amk/last-build-$1"; }
166
171
  flow_files() {
167
172
  {
168
173
  if [ -n "$flow" ]; then echo "$flow"
169
- elif [ -n "$spec" ]; then
170
- for s in $(echo "$spec" | tr ',' ' '); do find "$root/.maestro" -maxdepth 1 -iname "$s*.yaml" ! -name '.amk-*' 2>/dev/null; done | sort -u
174
+ elif [ -n "$spec" ] || [ "$changed" = 1 ]; then
175
+ {
176
+ [ "$changed" = 0 ] || node scripts/amk/specs.js changed-flows
177
+ for s in $(echo "$spec" | tr ',' ' '); do find "$root/.maestro" -maxdepth 1 -iname "$s*.yaml" ! -name '.amk-*' 2>/dev/null; done
178
+ } | sort -u
171
179
  else find "$root/.maestro" -maxdepth 1 -name '*.yaml' ! -name '.amk-*' 2>/dev/null | sort
172
180
  fi
173
181
  } | with_tags | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
@@ -185,7 +193,14 @@ with_tags() {
185
193
  }'
186
194
  }
187
195
 
188
- # the screens to check on a platform: the ones the app supports, narrowed by --screens
196
+ # Xcode building or indexing the same project holds its build service: a build from here then can't start
197
+ xcode_busy() {
198
+ ! grep -q 'unable to initiate PIF transfer session' "$1" 2> /dev/null ||
199
+ echo " Xcode is building or indexing this project too: let it finish or quit it (if it stays stuck: pkill -f SWBBuildService), then run this again (docs/amk/known-issues.md)"
200
+ }
201
+
202
+ # the screens to check on a platform: the ones the app supports (as far as .amk-screens lets), narrowed by --screens
203
+ capped() { [ ! -f .amk-screens ] || echo " (.amk-screens limits the screens to check)"; }
189
204
  screens_for() {
190
205
  for s in $(node scripts/amk/screens.js "$1"); do
191
206
  [ -n "$only" ] || { echo "$s"; continue; }
@@ -411,6 +426,7 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
411
426
  files=$(flow_files)
412
427
  if [ -z "$files" ]; then
413
428
  [ -z "$tags" ] || echo " $1: no flow has the tag $tags, so this is a check that the app opens"
429
+ [ "$changed" = 0 ] || [ -n "$spec" ] || echo " $1: no flow reaches what this branch changed, so this is a check that the app opens"
414
430
  # launchApp returns before the app has drawn, and a splash screen stays up until the JavaScript has loaded:
415
431
  # a fixed wait (for text that never appears), then for the screen to settle, so the screenshot shows the app
416
432
  printf 'appId: %s\n---\n- launchApp\n- extendedWaitUntil:\n visible: "agentic-mobile-kit: waiting for the app to draw"\n timeout: 5000\n optional: true\n- waitForAnimationToEnd\n- takeScreenshot: smoke-launch\n' "$3" > "$out/smoke.yaml"
@@ -630,7 +646,8 @@ ios() {
630
646
  device="" tablet=""
631
647
  if [ "$build_only" = 0 ]; then
632
648
  screens=$(screens_for ios)
633
- [ -n "$screens" ] || { echo "ios: none of the app's screens is $only"; return; }
649
+ [ -n "$screens" ] || { echo "ios: none of the app's screens is $only$(capped)"; return; }
650
+ echo "ios: checking" $screens
634
651
  if echo "$screens" | grep -q '^phone-'; then
635
652
  take_simulator iPhone "${AMK_IOS_DEVICE:-}" || { status=1; return; }
636
653
  device=$taken
@@ -667,7 +684,7 @@ ios() {
667
684
  claim_wait "build-ios-$project" "" "the iOS build of this project" || { status=1; return; }
668
685
  if [ "$no_build" = 0 ]; then
669
686
  if [ "$sims" = 1 ] && ! CONFIGURATION=Release sh scripts/amk/ios-build.sh > "$evidence/ios-build.log" 2>&1; then
670
- echo "ios: release build FAILED, see ${evidence#"$root"/}/ios-build.log"; status=1; return
687
+ echo "ios: release build FAILED, see ${evidence#"$root"/}/ios-build.log"; xcode_busy "$evidence/ios-build.log"; status=1; return
671
688
  fi
672
689
  for d in $reals; do
673
690
  if ! CONFIGURATION=Release AMK_IOS_TEAM=$team sh scripts/amk/ios-build.sh device "$d" > "$evidence/ios-device-build.log" 2>&1; then
@@ -999,7 +1016,8 @@ android() {
999
1016
  # the devices first: the build only needs the CPU type, and emulators boot while Gradle builds.
1000
1017
  # The flows clear the app's data, so a phone plugged in over USB is used only when AMK_ANDROID_DEVICE names it
1001
1018
  screens=$(screens_for android)
1002
- [ -n "$screens" ] || { echo "android: none of the app's screens is $only"; return; }
1019
+ [ -n "$screens" ] || { echo "android: none of the app's screens is $only$(capped)"; return; }
1020
+ echo "android: checking" $screens
1003
1021
  avds=$("$sdk/emulator/emulator" -list-avds 2> /dev/null || true)
1004
1022
  if echo "$screens" | grep -q '^phone-'; then
1005
1023
  take_android phone "${AMK_ANDROID_DEVICE:-}" "${AMK_ANDROID_AVD:-}" || { status=1; return; }
@@ -19,8 +19,15 @@
19
19
  appId: ${APP_ID} # set by verify.sh
20
20
  # tags: [smoke] # optional: verify.sh --tags smoke checks only the flows with one of the tags
21
21
  ---
22
- - launchApp:
23
- clearState: true
22
+ # Start at the screen the scenarios are on: a flow that walks from the first screen through every one before it is
23
+ # slow, and fails for screens it only passes through.
24
+ # - The app keeps its data between flows (logged in, say): clear it (launchApp: { clearState: true }) only for a
25
+ # scenario that needs a fresh install: onboarding, an empty state, a first permission prompt.
26
+ # - Log in with the subflow only when the login screen shows:
27
+ # - runFlow: { file: subflows/login.yaml, when: { visible: { id: "login-email" } } }
28
+ # - Where the app opens screens from a link (React Navigation's linking, Expo Router's routes), open this one with it
29
+ # rather than tapping through: - openLink: <the app's scheme>://<the screen's path>
30
+ - launchApp
24
31
  # After every launchApp: a splash screen can still cover the app while assertions already pass (the app's views
25
32
  # exist under it), so wait a moment (for text that never appears), then for the screen to settle.
26
33
  - extendedWaitUntil:
@@ -1,7 +1,8 @@
1
1
  # Copy to .maestro/subflows/<name>.yaml for steps several flows share: logging in, skipping onboarding, answering a
2
2
  # permission prompt. A flow runs it with "- runFlow: subflows/<name>.yaml". verify.sh runs only the flows directly in
3
3
  # .maestro/, not the subflows below it. This one logs in with the test account from .maestro/.env.local (MAESTRO_EMAIL,
4
- # MAESTRO_PASSWORD), which isn't committed.
4
+ # MAESTRO_PASSWORD), which isn't committed. Run it only when the login screen shows, so a flow on an app that's still
5
+ # logged in goes straight on: - runFlow: { file: subflows/login.yaml, when: { visible: { id: "login-email" } } }
5
6
  appId: ${APP_ID}
6
7
  ---
7
8
  - tapOn: