mobile-ai-agents 1.0.23

package/skills/cross-platform/crash-triage.md

@@ -0,0 +1,53 @@
+# Skill — /crash-triage
+
+**Platform:** Cross-Platform
+**Slash Command:** `/crash-triage`
+**Composable With:** agents/cross-platform/crasher/agent.md
+
+---
+
+## Purpose
+
+Rapid crash triage for any mobile platform. Paste a stacktrace, get a root cause and fix. The first thing to run when a crash alert fires.
+
+---
+
+## Skill Prompt
+
+```
+Triage the provided mobile crash stacktrace:
+
+STEP 1 — CLASSIFY
+Identify the crash type:
+- NullPointerException / nil dereference
+- IndexOutOfBoundsException / array out of bounds
+- ClassCastException / invalid cast
+- ANR (Application Not Responding) — main thread blocked
+- OOM (OutOfMemoryError) — memory exhaustion
+- EXC_BAD_ACCESS — iOS memory corruption / dangling pointer
+- Unhandled exception / promise rejection (RN)
+- Assertion failure / fatalError (Swift)
+- Stack overflow (infinite recursion)
+
+STEP 2 — FIND THE ORIGIN
+Read the stacktrace top to bottom:
+- The top frame is usually the symptom, not the cause.
+- Find the first frame in YOUR code (not framework code).
+- The origin is usually 3–8 frames below the top.
+
+STEP 3 — STATE THE ROOT CAUSE
+One sentence: "The crash occurs because X happens when Y condition is true."
+
+STEP 4 — THE FIX
+Concrete code change. Not "add a null check" — the actual check, in the actual function.
+
+STEP 5 — REGRESSION TEST
+One sentence: "Write a test that calls [function] with [condition] and asserts [expected behavior]."
+
+Output format:
+CRASH TYPE: <type>
+ORIGIN: <file:function:line>
+ROOT CAUSE: <one sentence>
+FIX: <code snippet>
+REGRESSION TEST: <description>
+```

package/skills/cross-platform/deeplink-debug.md

@@ -0,0 +1,57 @@
+# Skill — /deeplink-debug
+
+**Platform:** Cross-Platform
+**Slash Command:** `/deeplink-debug`
+
+---
+
+## Purpose
+
+Diagnoses broken deep links across Android and iOS. Notoriously painful — this skill walks through every failure mode systematically.
+
+---
+
+## Skill Prompt
+
+```
+Debug the described deep link issue step by step:
+
+PROVIDE THIS INFORMATION:
+1. Deep link URL or app link (e.g. https://app.example.com/product/123 or myapp://product/123)
+2. Platform: Android, iOS, or both
+3. Symptom: doesn't open app / opens wrong screen / opens app but crashes / works on dev not prod
+4. Link type: App Link (Android) / Universal Link (iOS) / Custom URL scheme / Branch.io / Firebase Dynamic Link
+
+ANDROID APP LINKS CHECKLIST:
+[ ] android:autoVerify="true" in the intent-filter (without this, App Links don't work)
+[ ] Intent filter scheme is "https" (not "http") for App Links
+[ ] /.well-known/assetlinks.json served at the exact domain, over HTTPS, with correct JSON
+[ ] assetlinks.json contains the correct SHA-256 certificate fingerprint
+    (Get fingerprint: keytool -list -v -keystore debug.keystore — debug != production!)
+[ ] assetlinks.json is accessible without redirect (redirects break App Link verification)
+[ ] App is installed and App Link verification has been triggered (reboot or reinstall)
+[ ] Test: adb shell am start -a android.intent.action.VIEW -d "https://yourdomain.com/path"
+
+iOS UNIVERSAL LINKS CHECKLIST:
+[ ] apple-app-site-association (AASA) file served at /.well-known/apple-app-site-association
+[ ] AASA is served with Content-Type: application/json (not .well-known/apple-app-site-association.json)
+[ ] AASA contains the correct appID (TeamID.BundleID) in the "applinks" section
+[ ] AASA path patterns match the URLs being tested (wildcards: * matches one path component, ** matches any)
+[ ] Associated Domains entitlement includes applinks:yourdomain.com
+[ ] Test on real device (simulator doesn't support Universal Links)
+[ ] Test: Settings → Developer → Universal Links → Diagnostics tool (iOS 16+)
+
+CUSTOM URL SCHEMES (fallback):
+[ ] Scheme registered in AndroidManifest.xml / Info.plist
+[ ] Scheme not conflicting with another installed app (no guarantee of uniqueness)
+[ ] Test: adb shell am start -a android.intent.action.VIEW -d "myapp://path"
+         xcrun simctl openurl booted "myapp://path"
+
+COMMON FAILURES AND FIXES:
+- "Works in dev, not prod": different signing certificate → different SHA-256 fingerprint in assetlinks.json
+- "Opens browser instead of app": assetlinks.json or AASA not found / served with wrong Content-Type
+- "App opens but wrong screen": intent/URL handler not matching the path pattern
+- "Crashes on open": deep link handler accessing null navigation state before initialization
+
+Output a step-by-step diagnosis with the most likely cause first.
+```

package/skills/cross-platform/feature-slice.md

@@ -0,0 +1,48 @@
+# Skill — /feature-slice
+
+**Platform:** Cross-Platform
+**Slash Command:** `/feature-slice`
+
+---
+
+## Purpose
+
+Breaks a mobile feature epic into independently shippable, correctly-sized tickets. Works with Jira, Linear, and GitHub Issues. Prevents the "one giant PR" anti-pattern.
+
+---
+
+## Skill Prompt
+
+```
+Slice the described mobile feature into independently shippable tickets:
+
+SLICING RULES:
+1. Each ticket should be shippable behind a feature flag without breaking existing behavior.
+2. Each ticket should be completable by one engineer in 1–3 days.
+3. Tickets are ordered: data layer first, then domain, then UI.
+4. "Independently shippable" means the app still works if only this ticket is merged.
+
+LAYER ORDER (mobile Clean Architecture):
+1. Data models / API contract (can be merged immediately, no visible change)
+2. Repository / data source implementation
+3. Domain use case
+4. ViewModel / state management
+5. UI scaffold (empty screen, no data)
+6. UI with real data
+7. Error states and edge cases
+8. Analytics / logging
+9. Tests (can be bundled with each layer or as a final ticket)
+
+OUTPUT PER TICKET:
+Title: [PLATFORM] Layer — What it does
+Acceptance Criteria:
+- [ ] Criterion 1
+- [ ] Criterion 2
+Dependencies: <ticket numbers this depends on>
+Estimated effort: <S | M | L> (S=4h, M=1d, L=2-3d)
+
+Also flag:
+- Any tickets that can be done in parallel (no dependency between them)
+- Any ticket that is a blocker for everything else (do it first)
+- Any ticket that touches existing code and needs a regression test
+```

package/skills/cross-platform/grill-mobile.md

@@ -0,0 +1,64 @@
+# Skill — /grill-mobile
+
+**Platform:** Cross-Platform
+**Slash Command:** `/grill-mobile`
+**Viral Potential:** HIGHEST — 20 questions before any mobile code is written
+
+---
+
+## Purpose
+
+Asks 20 mobile-specific alignment questions before writing a single line of code. Prevents the most common mobile AI mistakes: wrong API level, reinventing native components, ignoring platform constraints.
+
+Inspired by mattpocock's `/grill-me` — the mobile-specific version.
+
+---
+
+## Skill Prompt
+
+```
+Before writing any code for this mobile feature, ask the following 20 questions.
+Wait for answers before proceeding. Group them into 5 rounds of 4 questions each
+so the conversation feels natural rather than overwhelming.
+
+ROUND 1 — Platform Basics
+1. What platform(s) are we targeting? (Android, iOS, Flutter, React Native, Unity/Unreal?)
+2. What is the minimum OS version / SDK level we support?
+3. Is this a new feature in a greenfield project or modifying an existing codebase?
+4. Which design system or component library is in use? (Material3, Cupertino, custom?)
+
+ROUND 2 — Technical Context
+5. What state management solution is in use? (ViewModel/StateFlow, Bloc, Riverpod, Redux, Zustand, none?)
+6. What dependency injection framework, if any? (Hilt, Koin, Provider, none?)
+7. Are there existing components in the codebase that already solve part of this?
+8. What is the target frame rate? (30fps for low-end, 60fps, 120fps for premium?)
+
+ROUND 3 — User & Device Reality
+9. What type of device is the primary target? (High-end flagship, mid-range, low-RAM budget?)
+10. Will this feature work offline? What is the offline behavior?
+11. Are there users with accessibility needs we should design for? (Screen reader, large text, motor?)
+12. What is the expected data size? (A handful of items, hundreds, thousands?)
+
+ROUND 4 — Integration & Constraints
+13. What API or backend does this feature connect to? Any rate limits or auth requirements?
+14. Are there any app store policies affecting this feature? (Location, permissions, content?)
+15. What is the target app size budget? Any constraints on adding dependencies?
+16. Is this screen deep-linkable? What parameters does the deep link carry?
+
+ROUND 5 — Quality & Delivery
+17. What is the test strategy? (Unit only, integration, UI test, manual only?)
+18. Has this feature been designed in Figma or another tool? Can you share the spec?
+19. What does "done" look like? What are the acceptance criteria?
+20. What are the top 3 edge cases we must handle before this ships?
+
+After receiving answers, summarize your understanding of the feature in 3 bullet points
+and confirm with the developer before writing any code.
+```
+
+---
+
+## Notes
+
+- Use this at the start of every non-trivial feature implementation.
+- Answers to questions 1, 2, 8, 9 directly prevent the most common AI mobile coding mistakes.
+- The summary-and-confirm step catches misunderstandings before they become wrong code.

package/skills/cross-platform/mobile-mcp-qa.md

@@ -0,0 +1,193 @@
+# Skill — /mobile-mcp-qa
+
+**Platform:** Android / iOS / Flutter / React Native  
+**Slash Command:** `/mobile-mcp-qa`  
+**Composable With:** APPFORGE, AXIOM, SWIFT, DART, BRIDGE, CRASHER, PERF, Mobile Memory
+
+---
+
+## Purpose
+
+Use Mobile MCP to run AI-assisted QA on a real device, emulator, or simulator. This skill turns a feature flow into a repeatable device test plan using screenshots, accessibility snapshots, element inspection, taps, typing, swipes, app install, app launch, and device orientation checks.
+
+Mobile MCP is best used after implementation, during APPFORGE Stage 7 Full QA, or before store submission.
+
+---
+
+## Prerequisites
+
+Install Mobile MCP in your AI tool:
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
+```
+
+Codex:
+
+```bash
+codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
+```
+
+You also need at least one available Android emulator/device or iOS simulator/device.
+
+---
+
+## Input Format
+
+```text
+COMMAND: /mobile-mcp-qa
+PLATFORM: <Android | iOS | Flutter | React Native>
+APP_ID: <Android package name or iOS bundle id>
+BUILD_PATH: <optional apk/ipa/app path>
+DEVICE: <optional target device name>
+FLOW:
+<numbered user flow to test>
+EXPECTED:
+<expected UI state, navigation, data, and analytics>
+EDGE_CASES:
+<offline, invalid input, rotation, restart, permissions, api errors>
+```
+
+---
+
+## Skill Prompt
+
+```text
+Run a Mobile MCP QA pass for the provided mobile app flow.
+
+STEP 1 — VERIFY SETUP
+- List available devices.
+- Select the requested device, or choose the first available emulator/simulator.
+- If BUILD_PATH is provided, install the app.
+- Launch APP_ID.
+- Capture screen size and orientation.
+
+STEP 2 — BASELINE SCREEN
+- Take a screenshot.
+- List elements on screen.
+- Record the initial screen name and visible primary actions.
+- If accessibility data is incomplete, fall back to screenshot-based coordinate reasoning.
+
+STEP 3 — EXECUTE FLOW
+For each user-flow step:
+- Identify the target element.
+- Prefer accessibility element interaction when available.
+- Use coordinate tap only when element metadata is missing.
+- Type text where required.
+- Swipe only when the target is off-screen.
+- Take a screenshot after every major state transition.
+
+STEP 4 — VERIFY EXPECTED RESULT
+Check:
+- Correct screen reached
+- Correct labels and values rendered
+- Loading, empty, and error states behave as expected
+- Navigation stack and back behavior work
+- Keyboard behavior is sane
+- Orientation does not break layout
+- App restart preserves required state
+- Offline/API error behavior is user-safe
+
+STEP 5 — REPORT
+Return:
+MOBILE MCP QA REPORT
+====================
+Platform:
+Device:
+App:
+Flow:
+Result: PASS | FAIL | BLOCKED
+
+Steps Executed:
+| Step | Action | Evidence | Result |
+|---|---|---|---|
+
+Issues:
+| Severity | Screen | Issue | Repro Step | Fix |
+|---|---|---|---|---|
+
+Screenshots Captured:
+- <screenshot name or description>
+
+Accessibility Findings:
+- <missing labels, small targets, focus issues>
+
+Recommended Next Action:
+<single concrete fix or next test>
+```
+
+---
+
+## Example
+
+### Input
+
+```text
+COMMAND: /mobile-mcp-qa
+PLATFORM: Android
+APP_ID: com.example.invoice
+FLOW:
+1. Launch app.
+2. Tap Add Invoice.
+3. Enter client "Acme Studio".
+4. Enter amount "450".
+5. Set due date tomorrow.
+6. Save invoice.
+7. Confirm invoice appears on dashboard.
+EXPECTED:
+Dashboard shows Acme Studio, $450, due tomorrow, status Unpaid.
+EDGE_CASES:
+Rotate on dashboard, restart app, verify invoice persists.
+```
+
+### Output
+
+```text
+MOBILE MCP QA REPORT
+====================
+Platform: Android
+Device: Pixel_7_API_35
+App: com.example.invoice
+Flow: Create invoice and verify dashboard persistence
+Result: FAIL
+
+Steps Executed:
+| Step | Action | Evidence | Result |
+|---|---|---|---|
+| 1 | Launched app | Home screenshot shows empty dashboard | PASS |
+| 2 | Tapped Add Invoice | Add Invoice screen visible | PASS |
+| 3 | Entered client and amount | Form fields populated | PASS |
+| 4 | Saved invoice | Returned to dashboard | PASS |
+| 5 | Restarted app | Dashboard empty after relaunch | FAIL |
+
+Issues:
+| Severity | Screen | Issue | Repro Step | Fix |
+|---|---|---|---|---|
+| CRITICAL | Dashboard | Invoice is not persisted after app restart | Save invoice, terminate app, relaunch | Verify Room insert is awaited before navigation |
+
+Screenshots Captured:
+- home-empty-initial
+- add-invoice-filled
+- dashboard-after-save
+- dashboard-after-restart
+
+Accessibility Findings:
+- Add Invoice button has label.
+- Amount field missing content description for currency expectation.
+
+Recommended Next Action:
+Fix invoice persistence by awaiting InvoiceDao.insert() before navigating back to Dashboard, then rerun the restart persistence flow.
+```

package/skills/cross-platform/mobile-memory-graph.md

@@ -0,0 +1,179 @@
+# Skill — /mobile-memory-graph
+
+**Platform:** Cross-Platform  
+**Slash Command:** `/mobile-memory-graph`  
+**Composable With:** Mobile Memory, AXIOM, SWIFT, DART, BRIDGE, FORGE, UNREAL
+
+---
+
+## Purpose
+
+Build the Knowledge Graph section of `MOBILE_MEMORY.md` from pasted mobile code files. Use it when the user wants architecture context, dependency flow, god node detection, or a token-reduced map of a codebase.
+
+---
+
+## Input Format
+
+````text
+COMMAND: /mobile-memory-graph
+FILES:
+FILE: <relative/path/File.kt>
+```kotlin
+<code>
+```
+FILE: <relative/path/File.swift>
+```swift
+<code>
+```
+````
+
+Accept Kotlin, Java, Swift, Dart, TypeScript, TSX, JavaScript, JSX, C#, and Blueprint/C++ snippets.
+
+---
+
+## Platform Detection
+
+| Signal | Platform |
+|---|---|
+| `.kt`, `androidx`, `ViewModel`, `StateFlow`, `HiltViewModel` | Android |
+| `.swift`, `SwiftUI`, `ObservableObject`, `@Published`, `MainActor` | iOS |
+| `.dart`, `Widget`, `StateNotifier`, `Bloc`, `Riverpod` | Flutter |
+| `.tsx`, `.jsx`, `React Native`, `NativeModules`, `FlatList` | React Native |
+| `.cs`, `MonoBehaviour`, `Update()`, `Rigidbody` | Unity |
+
+---
+
+## Skill Prompt
+
+```text
+Build the Knowledge Graph section of MOBILE_MEMORY.md from the provided code files.
+
+Output only:
+## 🗺️ Knowledge Graph
+
+Required subsections:
+1. Nodes table
+2. Key Edges table
+3. God Nodes table
+4. Architecture Violations list
+5. Token Reduction Summary
+
+Node types:
+[UI] [VM] [UC] [REPO] [NET] [DB] [DI] [NAV] [TEST]
+
+Health values:
+OK, CRITICAL, WARNING, DEBT
+
+Edge types:
+OBSERVES, CALLS, INJECTS, NAVIGATES_TO, EMITS, VIOLATES
+
+Every edge note must start with a confidence tag:
+- EXTRACTED: direct code evidence exists
+- INFERRED: strongly implied by naming/imports/framework convention
+- AMBIGUOUS: possible relationship but insufficient code shown
+
+Platform checks:
+- Android: flag GlobalScope, repository construction in ViewModel, exposed MutableStateFlow, UI navigation from ViewModel, repository called by 2+ ViewModels.
+- iOS: flag retain cycles, force unwraps, MainActor misuse, ObservableObject with 6+ @Published, class with 4+ protocol conformances.
+- Flutter: flag expensive build() work, missing const constructors, unawaited futures, StateNotifier with 3+ consumers, build() over 200 lines.
+- React Native: flag bridge calls in hot paths, missing keys on lists, Context with 5+ consumers, component over 150 lines.
+- Unity: flag Update() abuse, GC allocations in hot paths, physics calls in Update(), class with 5+ responsibilities.
+
+Token reduction estimate:
+Estimate raw file tokens from code volume and compare to graph token count. Use conservative math and state assumptions.
+```
+
+---
+
+## Output Format
+
+```markdown
+## 🗺️ Knowledge Graph
+
+### Nodes
+| Node | Type | Layer | Health |
+|---|---|---|---|
+| [ClassName] | [VM/REPO/UI/etc] | [UI/Domain/Data] | [OK/CRITICAL/WARNING/DEBT] |
+
+### Key Edges
+| From | Edge | To | Note |
+|---|---|---|---|
+| [Node] | OBSERVES | [Node] | EXTRACTED: [why this matters] |
+
+### God Nodes
+| Node | Connections | Platform Risk | Recommendation |
+|---|---|---|---|
+
+### Architecture Violations
+- [Class] VIOLATES [rule] — [explanation] → [fix]
+
+### Token Reduction Summary
+- Raw files estimated: [N] tokens
+- Graph summary: [N] tokens
+- Reduction: [X×]
+- Assumption: [how estimate was calculated]
+```
+
+---
+
+## Example
+
+### Input
+
+````text
+COMMAND: /mobile-memory-graph
+FILE: app/cart/CartViewModel.kt
+```kotlin
+@HiltViewModel
+class CartViewModel @Inject constructor() : ViewModel() {
+    val uiState = MutableStateFlow(CartState())
+    private val repo = CartRepository(RetrofitCartApi())
+
+    fun checkout(activity: Activity) {
+        GlobalScope.launch {
+            repo.checkout()
+            activity.startActivity(Intent(activity, PaymentActivity::class.java))
+        }
+    }
+}
+```
+````
+
+### Output
+
+```markdown
+## 🗺️ Knowledge Graph
+
+### Nodes
+| Node | Type | Layer | Health |
+|---|---|---|---|
+| CartViewModel | VM | UI | CRITICAL |
+| CartRepository | REPO | Data | WARNING |
+| RetrofitCartApi | NET | Data | OK |
+| PaymentActivity | NAV | UI | WARNING |
+
+### Key Edges
+| From | Edge | To | Note |
+|---|---|---|---|
+| CartViewModel | CALLS | CartRepository | EXTRACTED: ViewModel constructs and calls repository directly |
+| CartRepository | CALLS | RetrofitCartApi | INFERRED: repository receives RetrofitCartApi constructor dependency |
+| CartViewModel | NAVIGATES_TO | PaymentActivity | EXTRACTED: ViewModel starts Activity through Activity reference |
+| CartViewModel | VIOLATES | Coroutine ownership | EXTRACTED: uses GlobalScope inside ViewModel |
+
+### God Nodes
+| Node | Connections | Platform Risk | Recommendation |
+|---|---|---|---|
+| CartViewModel | 4 | High: mixes state, DI, coroutine ownership, and navigation | Inject repository, use viewModelScope, emit navigation event |
+
+### Architecture Violations
+- CartViewModel VIOLATES Clean Architecture — constructs CartRepository and RetrofitCartApi directly → inject dependencies with Hilt.
+- CartViewModel VIOLATES state encapsulation — exposes MutableStateFlow publicly → expose StateFlow via asStateFlow().
+- CartViewModel VIOLATES lifecycle ownership — uses GlobalScope → use viewModelScope.
+- CartViewModel VIOLATES navigation ownership — starts Activity directly → emit navigation event and let UI navigate.
+
+### Token Reduction Summary
+- Raw files estimated: 180 tokens
+- Graph summary: 125 tokens
+- Reduction: 1.4×
+- Assumption: Small snippet; larger projects improve because repeated code bodies collapse into nodes and edges.
+```