agentic-mobile-kit 0.0.2 → 0.2.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 (99) hide show
  1. package/README.md +20 -8
  2. package/bin/cli.js +31 -5
  3. package/lib/init.js +199 -0
  4. package/package.json +9 -3
  5. package/stacks/react-native/template/.agents/skills/LICENSE-callstack +21 -0
  6. package/stacks/react-native/template/.agents/skills/THIRD_PARTY.md +9 -0
  7. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +23 -0
  8. package/stacks/react-native/template/.agents/skills/m-bugfix/agents/openai.yaml +3 -0
  9. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +22 -0
  10. package/stacks/react-native/template/.agents/skills/m-continue/agents/openai.yaml +3 -0
  11. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +50 -0
  12. package/stacks/react-native/template/.agents/skills/m-feature/agents/openai.yaml +3 -0
  13. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +14 -0
  14. package/stacks/react-native/template/.agents/skills/m-pause/agents/openai.yaml +3 -0
  15. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +29 -0
  16. package/stacks/react-native/template/.agents/skills/m-review/agents/openai.yaml +3 -0
  17. package/stacks/react-native/template/.agents/skills/react-native-best-practices/POWER.md +172 -0
  18. package/stacks/react-native/template/.agents/skills/react-native-best-practices/SKILL.md +238 -0
  19. package/stacks/react-native/template/.agents/skills/react-native-best-practices/agents/openai.yaml +4 -0
  20. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-analyze-app.md +208 -0
  21. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-analyze-js.md +264 -0
  22. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-barrel-exports.md +250 -0
  23. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-code-splitting.md +255 -0
  24. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-hermes-mmap.md +167 -0
  25. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-library-size.md +164 -0
  26. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-native-assets.md +208 -0
  27. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-r8-android.md +231 -0
  28. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-tree-shaking.md +215 -0
  29. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-animations-reanimated.md +273 -0
  30. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-atomic-state.md +190 -0
  31. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-bottomsheet.md +339 -0
  32. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-concurrent-react.md +238 -0
  33. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-lists-flatlist-flashlist.md +223 -0
  34. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-measure-fps.md +178 -0
  35. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-memory-leaks.md +168 -0
  36. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-profile-react.md +138 -0
  37. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-react-compiler.md +261 -0
  38. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-uncontrolled-components.md +219 -0
  39. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-android-16kb-alignment.md +114 -0
  40. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-measure-tti.md +221 -0
  41. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-memory-leaks.md +206 -0
  42. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-memory-patterns.md +240 -0
  43. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-platform-setup.md +112 -0
  44. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-profiling.md +140 -0
  45. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-sdks-over-polyfills.md +192 -0
  46. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-threading-model.md +230 -0
  47. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-turbo-modules.md +210 -0
  48. package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-view-flattening.md +180 -0
  49. package/stacks/react-native/template/.agents/skills/react-navigation/SKILL.md +63 -0
  50. package/stacks/react-native/template/.agents/skills/react-navigation/agents/openai.yaml +4 -0
  51. package/stacks/react-native/template/.agents/skills/react-navigation/references/bottom-tabs.md +496 -0
  52. package/stacks/react-native/template/.agents/skills/react-navigation/references/drawers.md +474 -0
  53. package/stacks/react-native/template/.agents/skills/react-navigation/references/form-sheet.md +305 -0
  54. package/stacks/react-native/template/.agents/skills/react-navigation/references/header.md +270 -0
  55. package/stacks/react-native/template/.agents/skills/react-navigation/references/material-top-tabs.md +453 -0
  56. package/stacks/react-native/template/.agents/skills/react-navigation/references/native-bottom-tabs.md +365 -0
  57. package/stacks/react-native/template/.agents/skills/react-navigation/references/safe-areas.md +95 -0
  58. package/stacks/react-native/template/.agents/skills/react-navigation/references/stacks.md +392 -0
  59. package/stacks/react-native/template/.agents/skills/upgrading-react-native/SKILL.md +79 -0
  60. package/stacks/react-native/template/.agents/skills/upgrading-react-native/agents/openai.yaml +4 -0
  61. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/expo-sdk-upgrade.md +65 -0
  62. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/monorepo-singlerepo-targeting.md +34 -0
  63. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/react.md +42 -0
  64. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrade-helper-core.md +122 -0
  65. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrade-verification.md +53 -0
  66. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrading-dependencies.md +41 -0
  67. package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrading-react-native.md +52 -0
  68. package/stacks/react-native/template/.githooks/pre-commit +49 -0
  69. package/stacks/react-native/template/.githooks/pre-push +5 -0
  70. package/stacks/react-native/template/.github/pull_request_template.md +19 -0
  71. package/stacks/react-native/template/.github/workflows/ci.yml +61 -0
  72. package/stacks/react-native/template/.github/workflows/e2e.yml +72 -0
  73. package/stacks/react-native/template/.github/workflows/ios.yml +43 -0
  74. package/stacks/react-native/template/.gitleaks.toml +12 -0
  75. package/stacks/react-native/template/.rulesync/hooks.jsonc +8 -0
  76. package/stacks/react-native/template/.rulesync/permissions.jsonc +36 -0
  77. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +15 -0
  78. package/stacks/react-native/template/AGENTS.md +46 -0
  79. package/stacks/react-native/template/CLAUDE.md +1 -0
  80. package/stacks/react-native/template/docs/ai/conventions.md +8 -0
  81. package/stacks/react-native/template/docs/ai/decisions.md +6 -0
  82. package/stacks/react-native/template/docs/ai/known-issues.md +17 -0
  83. package/stacks/react-native/template/docs/ai/product.md +7 -0
  84. package/stacks/react-native/template/docs/ai/react-native.md +27 -0
  85. package/stacks/react-native/template/docs/ai/structure.md +7 -0
  86. package/stacks/react-native/template/docs/ai/team-process.md +9 -0
  87. package/stacks/react-native/template/docs/ai/tech.md +7 -0
  88. package/stacks/react-native/template/rulesync.jsonc +9 -0
  89. package/stacks/react-native/template/scripts/ai/guard.js +35 -0
  90. package/stacks/react-native/template/scripts/ai/handoff-check.js +28 -0
  91. package/stacks/react-native/template/scripts/ai/install-deps.sh +14 -0
  92. package/stacks/react-native/template/scripts/ai/ios-build.sh +14 -0
  93. package/stacks/react-native/template/scripts/ai/pm-run.sh +16 -0
  94. package/stacks/react-native/template/scripts/ai/verify.sh +139 -0
  95. package/stacks/react-native/template/specs/_templates/design.md +15 -0
  96. package/stacks/react-native/template/specs/_templates/flow.yaml +14 -0
  97. package/stacks/react-native/template/specs/_templates/progress.md +14 -0
  98. package/stacks/react-native/template/specs/_templates/requirements.md +30 -0
  99. package/stacks/react-native/template/specs/_templates/tasks.md +6 -0
@@ -0,0 +1,8 @@
1
+ # Conventions
2
+
3
+ <!-- Fill in with the rules this project already follows.
4
+ - Naming (files, components, hooks, tests).
5
+ - Component structure and styling approach.
6
+ - Error handling and loading/empty states.
7
+ - Testing: what gets unit tests, where tests live, how to mock the API.
8
+ - Commit messages and branch names. -->
@@ -0,0 +1,6 @@
1
+ # Decisions
2
+
3
+ Short log of decisions that affect the whole project. Newest first. Agents add a line when a decision is made in chat.
4
+
5
+ | Date | Decision | Why |
6
+ |---|---|---|
@@ -0,0 +1,17 @@
1
+ # Known issues
2
+
3
+ Recurring errors and their fixes. Check here before debugging a build error. Remove entries that no longer apply.
4
+
5
+ ## Format
6
+
7
+ ### <short error text>
8
+ - **Cause:**
9
+ - **Fix:**
10
+ - **Prevention:**
11
+
12
+ ## Entries
13
+
14
+ ### iOS build fails right after a native dependency was added or removed
15
+ - **Cause:** `ios/Pods` is out of date.
16
+ - **Fix:** `cd ios && pod install`, then rebuild.
17
+ - **Prevention:** run `pod install` in the same change that edits `package.json`.
@@ -0,0 +1,7 @@
1
+ # Product
2
+
3
+ <!-- Fill in, then keep it short (under 40 lines). Agents read this to understand what they're building.
4
+ - What the app does, in two sentences.
5
+ - Who uses it.
6
+ - The 3 to 5 key user journeys (sign-up, checkout, …).
7
+ - Anything that must never break (payments, data sync, …). -->
@@ -0,0 +1,27 @@
1
+ # React Native rules (bare, New Architecture)
2
+
3
+ Rules for things AI agents commonly get wrong in current React Native. Each one comes from a documented platform change.
4
+
5
+ ## Architecture
6
+
7
+ - The New Architecture is the only architecture since React Native 0.82. Never set `newArchEnabled=false`; it's ignored.
8
+ - Write native modules as Turbo Modules and native views as Fabric components, with TypeScript codegen specs. Don't use the old bridge APIs (`NativeModules`, `requireNativeComponent`) in new code.
9
+
10
+ ## Screens and layout
11
+
12
+ - Use `react-native-safe-area-context` for safe areas. React Native's built-in `SafeAreaView` is deprecated and iOS-only.
13
+ - Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
14
+ - For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS, or `OnBackPressedDispatcher` in native code.
15
+ - Check every UI change on both iOS and Android; behavior differs (keyboard, insets, fonts, permissions).
16
+ - Give every interactive element a `testID` (kebab-case, for example `dark-mode-switch`). End-to-end tools tap by `testID`. On iOS, React Native exposes a label and its control as duplicate accessibility elements, so tapping by text can hit the label: nothing happens, yet the tool reports success.
17
+
18
+ ## Native changes
19
+
20
+ - After adding or removing a native dependency: `cd ios && pod install`, then rebuild both apps. Restart Metro with `--reset-cache` if the bundle looks stale.
21
+ - Don't hand-edit `project.pbxproj`. Let CocoaPods or Xcode change it.
22
+ - Don't bump the Android Gradle Plugin, Gradle, Kotlin or the iOS deployment target one by one. Upgrade React Native as a whole with the `upgrading-react-native` skill and the React Native Upgrade Helper.
23
+
24
+ ## Performance and libraries
25
+
26
+ - Follow the `react-native-best-practices` skill for lists, re-renders, startup time and bundle size.
27
+ - Follow the `react-navigation` skill for navigation.
@@ -0,0 +1,7 @@
1
+ # Structure
2
+
3
+ <!-- Fill in. Agents use this to put new code in the right place and to reuse what exists.
4
+ - Folder map (src/screens, src/components, src/api, …) with one line per folder.
5
+ - Where shared UI components and the theme/design tokens live.
6
+ - Where helpers live (dates, formatting, validation), so agents reuse them instead of writing new ones.
7
+ - Native code: anything custom under ios/ and android/. -->
@@ -0,0 +1,9 @@
1
+ # Team process for AI-assisted work
2
+
3
+ - The person who opens a PR owns it and must be able to explain every change without AI.
4
+ - Commits made by an agent end with `Assisted-by: <tool>/<model>` and, when there's a spec, `Spec: specs/<id>`.
5
+ - Keep PRs under 600 changed lines (CI enforces it; the `large-pr` label overrides).
6
+ - Run at most 2 or 3 agents in parallel per person.
7
+ - Don't use "skip permissions", "YOLO" or auto-run modes in any tool.
8
+ - Keep secrets out of the repo folder; inject them at run time.
9
+ - Review the metrics and the `learn` changes once a month. Re-check `AGENTS.md` and `docs/ai/` after every React Native, Xcode or Android Gradle Plugin upgrade, and after switching AI models.
@@ -0,0 +1,7 @@
1
+ # Tech
2
+
3
+ <!-- Fill in. Describe what the project already uses; don't prescribe new tools here.
4
+ - State management, navigation, networking/API client, storage, forms, i18n, analytics.
5
+ - Backend APIs and where their contracts live (OpenAPI file, Postman collection, …).
6
+ - Environments (dev, staging, production) and how the app switches between them.
7
+ - Third-party services (push, crash reporting, payments, maps). -->
@@ -0,0 +1,9 @@
1
+ // Generates per-tool permissions, hooks and subagents from .rulesync/. Run: npx -y rulesync@27.0.0 generate
2
+ // Commit the generated files. Rules and skills don't go through rulesync (AGENTS.md and .agents/skills are shared).
3
+ {
4
+ "targets": ["claudecode", "codexcli", "antigravity-ide", "antigravity-cli"],
5
+ "features": ["permissions", "hooks", "subagents"],
6
+ "outputRoots": ["."],
7
+ "delete": false,
8
+ "preserveUnownedHooks": true
9
+ }
@@ -0,0 +1,35 @@
1
+ #!/usr/bin/env node
2
+ // Agent guard hook (preToolUse). Blocks destructive shell commands and access to secret files.
3
+ // Each AI tool sends a differently shaped JSON payload, so look for command and path fields anywhere in it.
4
+ const fs = require('fs');
5
+
6
+ let payload;
7
+ const raw = fs.readFileSync(0, 'utf8');
8
+ try { payload = JSON.parse(raw); } catch { payload = { command: raw }; }
9
+
10
+ const commands = [];
11
+ const paths = [];
12
+ (function walk(v, key) {
13
+ if (Array.isArray(v)) {
14
+ if (/^(command|cmd|CommandLine)$/i.test(key) && v.every(x => typeof x === 'string')) commands.push(v.join(' '));
15
+ else v.forEach(x => walk(x, key));
16
+ } else if (v && typeof v === 'object') {
17
+ for (const [k, x] of Object.entries(v)) walk(x, k);
18
+ } else if (typeof v === 'string') {
19
+ if (/^(command|cmd|CommandLine)$/i.test(key)) commands.push(v);
20
+ if (/^(file_path|path|AbsolutePath|TargetFile|filePath)$/.test(key)) paths.push(v);
21
+ }
22
+ })(payload, '');
23
+
24
+ const destructive = /\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r|-r\s+-f|-f\s+-r)\b|git\s+reset\s+--hard|git\s+push\s+(.*\s)?(--force|-f)\b|git\s+clean\s+-[a-z]*f|--no-verify|xcrun\s+simctl\s+erase/;
25
+ const secretFile = /(^|[\s/'"=])\.env(\.(?!example\b)[\w.-]+)?(?=$|[\s'";|&)])|\.(keystore|jks|p8|p12|mobileprovision)\b/;
26
+
27
+ const block = reason => { process.stderr.write(`Blocked by scripts/ai/guard.js: ${reason}\n`); process.exit(2); };
28
+ for (const c of commands) {
29
+ if (destructive.test(c)) block(`destructive command: ${c}`);
30
+ if (secretFile.test(c)) block(`shell access to a secret file: ${c}`);
31
+ }
32
+ for (const p of paths) {
33
+ if (secretFile.test(p)) block(`access to a secret file: ${p}`);
34
+ }
35
+ process.exit(0);
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/env node
2
+ // Agent stop hook. If code changed but the active spec's handoff block wasn't updated, ask the agent to update it.
3
+ const fs = require('fs');
4
+ const { execSync } = require('child_process');
5
+
6
+ let payload = {};
7
+ try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch {}
8
+ if (payload.stop_hook_active) process.exit(0); // already reminded once; don't loop
9
+
10
+ // a spec counts only when its handoff says "Status: in progress" (not done, not an untouched template copy)
11
+ const inProgress = d => {
12
+ const f = `specs/${d}/progress.md`;
13
+ return d !== '_templates' && fs.existsSync(f) && /^Status:\s*in progress/im.test(fs.readFileSync(f, 'utf8'));
14
+ };
15
+ const specs = fs.existsSync('specs') ? fs.readdirSync('specs').filter(inProgress) : [];
16
+ if (specs.length === 0) process.exit(0); // no spec in progress (quick change, bug fix, or finished work)
17
+
18
+ const changed = execSync('git status --porcelain', { encoding: 'utf8' })
19
+ .split('\n').filter(Boolean).map(l => l.slice(3));
20
+ const codeChanged = changed.some(f => !f.startsWith('specs/') && !f.startsWith('.ai/'));
21
+ const handoffUpdated = changed.some(f => /^specs\/[^/]+\/progress\.md$/.test(f));
22
+
23
+ if (codeChanged && !handoffUpdated) {
24
+ process.stderr.write('There are uncommitted code changes, but no specs/<id>/progress.md was updated. ' +
25
+ 'Update its handoff block (status, next step, decisions, last checks) before stopping.\n');
26
+ process.exit(2);
27
+ }
28
+ process.exit(0);
@@ -0,0 +1,14 @@
1
+ #!/bin/sh
2
+ # Installs JS dependencies exactly as locked, with the project's package manager.
3
+ set -eu
4
+ if [ -f yarn.lock ]; then
5
+ corepack enable
6
+ if [ -f .yarnrc.yml ]; then yarn install --immutable; else yarn install --frozen-lockfile; fi
7
+ elif [ -f pnpm-lock.yaml ]; then
8
+ corepack enable
9
+ pnpm install --frozen-lockfile
10
+ elif [ -f bun.lock ] || [ -f bun.lockb ]; then
11
+ bun install --frozen-lockfile # ponytail: CI needs a setup-bun step for this branch
12
+ else
13
+ npm ci
14
+ fi
@@ -0,0 +1,14 @@
1
+ #!/bin/sh
2
+ # Builds the iOS app for the simulator without code signing (CI and local checks).
3
+ # CONFIGURATION=Release builds a self-contained app (JS bundled; no Metro needed).
4
+ # Output goes to ios/DerivedData: ios/build holds React Native codegen files from pod install.
5
+ set -eu
6
+ config=${CONFIGURATION:-Debug}
7
+ workspace=$(ls -d ios/*.xcworkspace 2>/dev/null | head -n 1)
8
+ [ -n "$workspace" ] || { echo "No ios/*.xcworkspace found. Run pod install in ios/ first."; exit 1; }
9
+ scheme=$(basename "$workspace" .xcworkspace)
10
+
11
+ xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration "$config" \
12
+ -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
13
+ -derivedDataPath ios/DerivedData CODE_SIGNING_ALLOWED=NO -quiet build
14
+ echo "iOS simulator build OK ($scheme, $config)"
@@ -0,0 +1,16 @@
1
+ #!/bin/sh
2
+ # Runs a package.json script with the project's package manager; skips quietly if the script doesn't exist.
3
+ # Usage: sh scripts/ai/pm-run.sh <script> [args…]
4
+ set -eu
5
+ script=$1; shift
6
+
7
+ if ! node -e "process.exit(require('./package.json').scripts?.[process.argv[1]] ? 0 : 1)" "$script"; then
8
+ echo "skip: no \"$script\" script in package.json"
9
+ exit 0
10
+ fi
11
+
12
+ if [ -f yarn.lock ]; then yarn run "$script" "$@" # works on Yarn 1 and Yarn Berry
13
+ elif [ -f pnpm-lock.yaml ]; then pnpm -s "$script" "$@"
14
+ elif [ -f bun.lock ] || [ -f bun.lockb ]; then bun run "$script" "$@"
15
+ else npm run -s "$script" -- "$@"
16
+ fi
@@ -0,0 +1,139 @@
1
+ #!/bin/sh
2
+ # Checks the app the way a user would: lint, typecheck and tests, then release builds on the iOS simulator
3
+ # and Android emulator, running Maestro flows and saving screenshots as evidence.
4
+ #
5
+ # Usage: sh scripts/ai/verify.sh [quick|ios|android|all] [--spec <id>] [--flow <file>] [--label <name>]
6
+ # quick lint, typecheck, tests
7
+ # ios|android release build, install, run flows, screenshots
8
+ # all everything (default)
9
+ # --spec <id> run .maestro/<id>*.yaml and save evidence in .ai/evidence/<id>/
10
+ # --label <n> evidence folder name (default: the spec id, or a timestamp)
11
+ # (no flows found: a smoke check that launches the app and takes a screenshot)
12
+ # Env: AMK_IOS_DEVICE (simulator name or UDID), AMK_ANDROID_AVD (emulator name)
13
+ set -eu
14
+
15
+ mode=${1:-all}
16
+ [ $# -gt 0 ] && shift
17
+ spec=""
18
+ flow=""
19
+ label=""
20
+ while [ $# -gt 0 ]; do
21
+ case $1 in
22
+ --spec) spec=$2; shift 2 ;;
23
+ --flow) flow=$2; shift 2 ;;
24
+ --label) label=$2; shift 2 ;;
25
+ *) echo "verify: unknown option $1"; exit 2 ;;
26
+ esac
27
+ done
28
+
29
+ root=$(pwd)
30
+ evidence="$root/.ai/evidence/${label:-${spec:-$(date +%Y%m%d-%H%M%S)}}"
31
+ mkdir -p "$evidence"
32
+ status=0
33
+
34
+ flow_files() {
35
+ if [ -n "$flow" ]; then echo "$root/$flow"
36
+ elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" 2>/dev/null | sort
37
+ else find "$root/.maestro" -maxdepth 1 -name '*.yaml' 2>/dev/null | sort
38
+ fi
39
+ }
40
+
41
+ run_flows() { # platform device app_id
42
+ out="$evidence/$1"
43
+ mkdir -p "$out"
44
+ files=$(flow_files)
45
+ if [ -z "$files" ]; then
46
+ printf 'appId: %s\n---\n- launchApp\n- takeScreenshot: smoke-launch\n' "$3" > "$out/smoke.yaml"
47
+ files="$out/smoke.yaml"
48
+ fi
49
+ passed=0
50
+ total=0
51
+ for f in $files; do
52
+ total=$((total + 1))
53
+ name=$(basename "$f" .yaml)
54
+ # screenshots use relative names: older Maestro saves them in the current folder, newer in --test-output-dir
55
+ if (cd "$out" && maestro --device "$2" test --test-output-dir "$out" -e APP_ID="$3" "$f" > "$out/$name.log" 2>&1); then
56
+ passed=$((passed + 1))
57
+ else
58
+ echo " $1: flow $name failed, see ${out#"$root"/}/$name.log"
59
+ status=1
60
+ fi
61
+ done
62
+ shots=$(find "$out" -name '*.png' | wc -l | tr -d ' ')
63
+ echo "$1: flows $passed/$total passed, $shots screenshots in ${out#"$root"/}"
64
+ if [ "$shots" = 0 ]; then
65
+ echo " $1: no screenshots were saved, so there's no evidence; treating this as a failure"
66
+ status=1
67
+ fi
68
+ }
69
+
70
+ quick() {
71
+ if sh scripts/ai/pm-run.sh lint > "$evidence/lint.log" 2>&1 &&
72
+ sh scripts/ai/pm-run.sh typecheck > "$evidence/typecheck.log" 2>&1 &&
73
+ CI=true sh scripts/ai/pm-run.sh test > "$evidence/test.log" 2>&1; then
74
+ echo "quick: lint, typecheck and tests passed"
75
+ else
76
+ echo "quick: FAILED, see the logs in ${evidence#"$root"/}"
77
+ status=1
78
+ fi
79
+ }
80
+
81
+ ios() {
82
+ command -v maestro > /dev/null || { echo "ios: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
83
+ # pod install also generates React Native codegen files into ios/build/generated
84
+ if [ ! -d ios/Pods ] || [ ! -d ios/build/generated ]; then (cd ios && pod install > "$evidence/pod-install.log" 2>&1); fi
85
+ if ! CONFIGURATION=Release sh scripts/ai/ios-build.sh > "$evidence/ios-build.log" 2>&1; then
86
+ echo "ios: release build FAILED, see ${evidence#"$root"/}/ios-build.log"; status=1; return
87
+ fi
88
+ app=$(ls -d ios/DerivedData/Build/Products/Release-iphonesimulator/*.app | head -n 1)
89
+ app_id=$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$app/Info.plist")
90
+ device=$(xcrun simctl list devices available -j | node -e '
91
+ const all = Object.entries(JSON.parse(require("fs").readFileSync(0, "utf8")).devices)
92
+ .flatMap(([rt, ds]) => ds.map(d => ({ ...d, v: (rt.match(/iOS-(\d+)-(\d+)/) || []).slice(1).map(Number) })))
93
+ .filter(d => d.v.length && /iPhone/.test(d.name));
94
+ const want = process.env.AMK_IOS_DEVICE;
95
+ const pick = want ? all.find(d => d.udid === want || d.name === want)
96
+ : all.find(d => d.state === "Booted") || all.sort((a, b) => b.v[0] - a.v[0] || b.v[1] - a.v[1])[0];
97
+ console.log(pick ? pick.udid : "");')
98
+ [ -n "$device" ] || { echo "ios: no iPhone simulator found (set AMK_IOS_DEVICE)"; status=1; return; }
99
+ xcrun simctl boot "$device" 2> /dev/null || true
100
+ xcrun simctl bootstatus "$device" -b > /dev/null
101
+ xcrun simctl install "$device" "$app"
102
+ run_flows ios "$device" "$app_id"
103
+ }
104
+
105
+ android() {
106
+ command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
107
+ sdk=${ANDROID_HOME:-$HOME/Library/Android/sdk}
108
+ adb="$sdk/platform-tools/adb"
109
+ if ! (cd android && ./gradlew assembleRelease --no-daemon -q) > "$evidence/android-build.log" 2>&1; then
110
+ echo "android: release build FAILED, see ${evidence#"$root"/}/android-build.log"; status=1; return
111
+ fi
112
+ apk=$(ls android/app/build/outputs/apk/release/*.apk | head -n 1)
113
+ app_id=$(sed -n 's/.*applicationId *=\{0,1\} *"\([^"]*\)".*/\1/p' android/app/build.gradle* | head -n 1)
114
+ device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
115
+ if [ -z "$device" ]; then
116
+ avd=${AMK_ANDROID_AVD:-$("$sdk/emulator/emulator" -list-avds | head -n 1)}
117
+ [ -n "$avd" ] || { echo "android: no emulator found (create one in Android Studio)"; status=1; return; }
118
+ nohup "$sdk/emulator/emulator" -avd "$avd" -no-snapshot-save -no-boot-anim > /dev/null 2>&1 &
119
+ "$adb" wait-for-device
120
+ until [ "$("$adb" shell getprop sys.boot_completed 2> /dev/null | tr -d '\r')" = 1 ]; do sleep 3; done
121
+ device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
122
+ fi
123
+ "$adb" -s "$device" install -r "$apk" > /dev/null
124
+ # system "isn't responding" pop-ups (common on busy emulators) cover the app and fail flows; app crashes still fail them
125
+ "$adb" -s "$device" shell settings put global hide_error_dialogs 1
126
+ "$adb" -s "$device" shell am broadcast -a android.intent.action.CLOSE_SYSTEM_DIALOGS > /dev/null 2>&1 || true
127
+ run_flows android "$device" "$app_id"
128
+ }
129
+
130
+ case $mode in
131
+ quick) quick ;;
132
+ ios) ios ;;
133
+ android) android ;;
134
+ all) quick; ios; android ;;
135
+ *) echo "verify: unknown mode $mode (quick, ios, android or all)"; exit 2 ;;
136
+ esac
137
+
138
+ echo "Evidence: ${evidence#"$root"/}/ (open the screenshots: a tool saying 'passed' isn't proof)"
139
+ exit $status
@@ -0,0 +1,15 @@
1
+ # <ID>: design
2
+
3
+ ## Existing code to reuse
4
+
5
+ <!-- Search first: components, hooks, API clients and helpers this change will use instead of writing new ones. -->
6
+
7
+ ## Approach
8
+
9
+ <!-- Screens, components, state, API calls, native changes (if any). Keep it to what the task needs. -->
10
+
11
+ ## Files to change
12
+
13
+ ## Risks
14
+
15
+ <!-- What could break; anything that needs a native rebuild or pod install. -->
@@ -0,0 +1,14 @@
1
+ # Copy to .maestro/<id>.yaml. verify.sh runs it on iOS and Android and keeps the screenshots as evidence.
2
+ # Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
3
+ appId: ${APP_ID} # set by verify.sh
4
+ ---
5
+ - launchApp:
6
+ clearState: true
7
+ # Criterion 1: <WHEN … THE APP SHALL …>
8
+ - assertVisible:
9
+ id: "<testID of the element>"
10
+ - takeScreenshot: <id>-1-<short-name>
11
+ # Criterion 2: …
12
+ - tapOn:
13
+ id: "<testID>"
14
+ - takeScreenshot: <id>-2-<short-name>
@@ -0,0 +1,14 @@
1
+ ## Handoff (updated <date time> · <tool> / <model> · branch <branch>)
2
+ Status: <exactly one of: not started | in progress — task N of M | done> (keep these words; the stop hook reads them)
3
+ Done: <tasks finished, with their check results>
4
+ In progress: <current task, what's half-done, file paths>
5
+ Next step: <the very next action>
6
+ Decisions: <decisions made in chat, and where they were written down>
7
+ Open question: <anything waiting for an answer>
8
+ Last verify: <lint / typecheck / test / iOS / Android results>
9
+ Blocked: <none, or what's blocking>
10
+ Notes: <anything the next session must know>
11
+
12
+ ## Log
13
+
14
+ <!-- Newest first: date, task, what was done, evidence (command output, screenshot file names). -->
@@ -0,0 +1,30 @@
1
+ # <ID>: <title>
2
+
3
+ Source: <link to the task in Excel, Trello or the task platform>
4
+
5
+ ## Goal
6
+
7
+ <!-- One or two sentences: what the user can do after this change, and why. -->
8
+
9
+ ## Acceptance criteria
10
+
11
+ <!-- One line each, testable: "WHEN <trigger> THE APP SHALL <response>". -->
12
+ 1. WHEN … THE APP SHALL …
13
+
14
+ ## Edge cases (answer each, or write "n/a")
15
+
16
+ - Offline or slow network:
17
+ - Server error, timeout:
18
+ - Empty, loading and long-content states:
19
+ - Permission denied (camera, location, notifications…):
20
+ - App backgrounded and resumed mid-flow:
21
+ - Small phones, large phones, tablets; dark mode:
22
+ - Accessibility (screen reader labels, font scaling):
23
+ - iOS vs Android differences:
24
+ - Analytics events:
25
+
26
+ ## Out of scope
27
+
28
+ ## Open questions
29
+
30
+ <!-- The agent stops for answers before design starts. -->
@@ -0,0 +1,6 @@
1
+ # <ID>: tasks
2
+
3
+ Each task: about an hour of work, under ~300 changed lines, with its own check. One commit per task.
4
+
5
+ - [ ] 1. <task> — files: <paths> — check: <command or manual step>
6
+ - [ ] 2.