oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-mobile/resources/screen-template.tsx

@@ -0,0 +1,179 @@
+/**
+ * Screen Template for Mobile Agent (React Native)
+ *
+ * Demonstrates best practices for React Native screens:
+ *   - Typed navigation props (React Navigation v7 native-stack)
+ *   - Consumes TanStack Query hooks (useTodosQuery + mutations) — NEVER axios directly
+ *   - Explicit isPending / error-with-retry / empty / data states via the shared
+ *     LoadingView / ErrorView / EmptyStateView components (snippets.md §12)
+ *   - FlatList with a stable keyExtractor and item-level accessibility roles
+ *   - RefreshControl wired to the query's refetch (pull-to-refresh)
+ *   - StyleSheet at the bottom; no inline style objects in render
+ *
+ * Layout: src/features/todos/ui/ExampleScreen.tsx
+ * The hooks (useTodosQuery, useToggleTodo, useDeleteTodo) live in
+ * src/features/todos/{queries.ts,mutations.ts}; the screen only composes them.
+ */
+
+import React, { useCallback } from 'react';
+import {
+  View,
+  Text,
+  FlatList,
+  TouchableOpacity,
+  RefreshControl,
+  StyleSheet,
+  type ListRenderItem,
+} from 'react-native';
+import type { NativeStackScreenProps } from '@react-navigation/native-stack';
+import type { RootStackParamList } from '@navigation/types';
+import { LoadingView } from '@shared/components/LoadingView';
+import { ErrorView } from '@shared/components/ErrorView';
+import { EmptyStateView } from '@shared/components/EmptyStateView';
+import { useTodosQuery } from '../queries';
+import { useToggleTodo, useDeleteTodo } from '../mutations';
+import type { Todo } from '@api/todos';
+
+// Typed screen props: navigation.navigate is compile-time checked against the
+// RootStackParamList, so passing the wrong params to 'TodoDetail' is a type error.
+type Props = NativeStackScreenProps<RootStackParamList, 'TodoList'>;
+
+export function ExampleScreen({ navigation }: Props) {
+  // Read hook — returns cached data instantly and revalidates in the background.
+  const { data: todos, isPending, isError, error, refetch, isRefetching } =
+    useTodosQuery();
+
+  // Write hooks — the screen fires intents; the hooks own optimistic updates,
+  // rollback, and cache invalidation. The screen never touches the query cache.
+  const toggleMutation = useToggleTodo();
+  const deleteMutation = useDeleteTodo();
+
+  // --- Intents -------------------------------------------------------------
+
+  const handleToggle = useCallback(
+    (id: string) => toggleMutation.mutate(id),
+    [toggleMutation],
+  );
+
+  const handleDelete = useCallback(
+    (id: string) => deleteMutation.mutate(id),
+    [deleteMutation],
+  );
+
+  const handleOpenDetail = useCallback(
+    (id: string) => navigation.navigate('TodoDetail', { id }),
+    [navigation],
+  );
+
+  // renderItem is defined once (stable identity) so FlatList rows don't churn.
+  const renderItem: ListRenderItem<Todo> = useCallback(
+    ({ item }) => (
+      <View style={styles.row}>
+        <TouchableOpacity
+          style={styles.checkbox}
+          onPress={() => handleToggle(item.id)}
+          accessibilityRole="checkbox"
+          accessibilityState={{ checked: item.completed }}
+          testID={`todo-checkbox-${item.id}`}
+          accessibilityLabel={`Toggle ${item.title}`}
+        >
+          <Text style={styles.checkboxGlyph}>{item.completed ? '☑' : '☐'}</Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity
+          style={styles.titleContainer}
+          onPress={() => handleOpenDetail(item.id)}
+          accessibilityRole="button"
+        >
+          <Text style={[styles.title, item.completed && styles.completed]}>
+            {item.title}
+          </Text>
+        </TouchableOpacity>
+
+        <TouchableOpacity
+          onPress={() => handleDelete(item.id)}
+          accessibilityRole="button"
+          testID={`todo-delete-${item.id}`}
+          accessibilityLabel={`Delete ${item.title}`}
+        >
+          <Text style={styles.deleteIcon}>✕</Text>
+        </TouchableOpacity>
+      </View>
+    ),
+    [handleToggle, handleDelete, handleOpenDetail],
+  );
+
+  // --- State switch --------------------------------------------------------
+  // Order matters: pending (first load, no cached data) → error → empty → data.
+  // Each non-data state delegates to a shared component so every screen renders
+  // them identically. isPending is the v5 first-load flag; isRefetching drives
+  // the pull-to-refresh spinner without hiding already-cached rows.
+
+  if (isPending) {
+    return <LoadingView label="Loading todos" />;
+  }
+
+  if (isError) {
+    return <ErrorView error={error} onRetry={refetch} />;
+  }
+
+  if (todos.length === 0) {
+    return <EmptyStateView message="No todos yet. Add your first one!" />;
+  }
+
+  // --- Data state ----------------------------------------------------------
+
+  return (
+    <FlatList
+      data={todos}
+      keyExtractor={(item) => item.id}
+      renderItem={renderItem}
+      contentContainerStyle={styles.listContent}
+      refreshControl={
+        <RefreshControl refreshing={isRefetching} onRefresh={refetch} />
+      }
+      // Keep the empty branch above authoritative; this is a defensive fallback.
+      ListEmptyComponent={
+        <EmptyStateView message="No todos yet. Add your first one!" />
+      }
+    />
+  );
+}
+
+// StyleSheet at the bottom — StyleSheet.create freezes the objects and lets RN
+// pass style IDs across the bridge instead of fresh objects on every render.
+const styles = StyleSheet.create({
+  listContent: {
+    flexGrow: 1,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderBottomColor: '#e0e0e0',
+  },
+  checkbox: {
+    marginRight: 12,
+  },
+  checkboxGlyph: {
+    fontSize: 18,
+  },
+  titleContainer: {
+    flex: 1,
+  },
+  title: {
+    fontSize: 16,
+    color: '#212121',
+  },
+  completed: {
+    textDecorationLine: 'line-through',
+    color: '#9e9e9e',
+  },
+  deleteIcon: {
+    color: '#9e9e9e',
+    fontSize: 16,
+    paddingLeft: 12,
+  },
+});

package/skills/oma-mobile/resources/tech-stack.md

@@ -0,0 +1,69 @@
+# Mobile Agent - Tech Stack Index
+
+Per-platform tech stacks live under `variants/{platform}/`, mirroring
+`oma-backend/variants/`. Each variant owns its own `stack.yaml` (SSOT),
+`tech-stack.md`, `snippets.md`, and API template. This file holds only the
+**cross-platform guidance** shared by every variant plus a pointer index.
+
+## Platform Variants
+
+| Platform | Stack manifest | Tech stack | Snippets | API template |
+|----------|----------------|-----------|----------|--------------|
+| Swift (iOS native) | `../variants/swift-ios/stack.yaml` | `../variants/swift-ios/tech-stack.md` | `../variants/swift-ios/snippets.md` | `../variants/swift-ios/api-template.swift` |
+| Kotlin (Android native) | `../variants/kotlin-android/stack.yaml` | `../variants/kotlin-android/tech-stack.md` | `../variants/kotlin-android/snippets.md` | `../variants/kotlin-android/api-template.kt` |
+| Flutter | `../variants/flutter/stack.yaml` | `../variants/flutter/tech-stack.md` | `../variants/flutter/snippets.md` | `../variants/flutter/api-template.dart` |
+| React Native | `../variants/react-native/stack.yaml` | `../variants/react-native/tech-stack.md` | `../variants/react-native/snippets.md` | `../variants/react-native/api-template.ts` |
+
+Stack selection: detect from project files (`Package.swift` / `settings.gradle.kts` +
+`com.android.application` / `pubspec.yaml` / `package.json` + `react-native`), or run `/stack-set` to generate a
+project-specific `stack/` from the matching variant baseline. The variant
+`stack.yaml` is the default; `/stack-set` may override any field per project.
+
+## Stack at a glance
+
+| | Swift iOS | Kotlin Android | Flutter | React Native |
+|---|---|---|---|---|
+| Language | Swift 6+ | Kotlin 2.1+ | Dart 3.10+ | TypeScript (strict) |
+| UI | SwiftUI | Jetpack Compose / Material 3 | Flutter / Material 3 | React Native |
+| State | Observation (`@MainActor @Observable`) | `ViewModel` + `StateFlow` (Hilt) | Riverpod 3 | Zustand 5 (client) + TanStack Query 5 (server) |
+| Navigation | NavigationStack | Navigation Compose (type-safe routes) | GoRouter 17 | React Navigation v7 |
+| HTTP transport | URLSession | Ktor Client (OkHttp engine; MockEngine in tests) | Dio | Axios |
+| API/data layer | swift-openapi-generator | openapi-generator `kotlin`/`jvm-ktor` | Repository (Dio) | TanStack Query + `api/` |
+| Response cache (when required) | hyperoslo/Cache | Room repository | Drift offline-first repo | TanStack Query |
+| Durable storage | SwiftData / Keychain | Room / DataStore / EncryptedSharedPreferences | Drift / flutter_secure_storage | MMKV / secure-store |
+| Unit test | XCTest / Swift Testing | JUnit + coroutines-test + ktor-client-mock | flutter_test + mocktail | jest + RNTL (matchers built in ≥12.4) |
+| E2E | XCUITest | Maestro | Maestro | Maestro |
+
+## Repository-layer response cache when required
+
+When offline behavior, latency, or repeated reads justify caching, use the selected variant's Repository / data-layer cache — the
+same philosophy across platforms, different idiomatic tooling:
+
+- Cache **decoded domain models**, never raw transport bytes / `HTTPBody` /
+  raw HTTP responses.
+- **Stale-while-revalidate** on reads: serve cached immediately, revalidate in
+  the background, update state.
+- **Invalidate on write**: every create/update/delete drops the affected cache
+  keys so the next read repopulates.
+- Cache key = operation + params (never URLs); explicit TTL (never infinite).
+- The cache is for transient, server-owned data only. Durable user-owned data
+  and secrets stay in the platform's durable store / secure store.
+
+See each variant's `tech-stack.md` "Response Cache" section and `snippets.md`
+for the platform-specific implementation.
+
+## Cross-platform guidelines (shared)
+
+- **Clean Architecture**: domain → data → presentation (App/Core/Features/Shared
+  on Swift; `app/{ui,data,di}` + `api-client` on Kotlin). Business logic never
+  lives in UI widgets/views/composables.
+- **Platform design**: Material Design 3 on Android, iOS Human Interface
+  Guidelines on iOS. Use platform checks for platform-specific behavior.
+- **State management**: no raw `setState`/ad-hoc state for complex logic — use
+  the variant's state solution.
+- **Networking**: transport-layer interceptors handle auth/retry/logging only;
+  domain-model caching is a repository concern (see above). Handle offline
+  gracefully.
+- **Lifecycle**: dispose controllers / cancel tasks to prevent leaks.
+- **Performance**: 60fps target; test on both platforms.
+- **E2E**: Maestro for critical user flows.

package/skills/oma-mobile/variants/README.md

@@ -0,0 +1,45 @@
+# variants/ — Mobile Platform Variants
+
+The `variants/` directory is the home for **all** mobile platform stacks,
+mirroring the layout used by `oma-backend/variants/`. Every supported platform
+is represented here, each as a self-contained variant.
+
+| Variant | `stack.yaml` `language` | Files |
+|---------|------------------------|-------|
+| `swift-ios/` | `swift` | `stack.yaml`, `tech-stack.md`, `snippets.md`, `api-template.swift` |
+| `kotlin-android/` | `kotlin` | `stack.yaml`, `tech-stack.md`, `snippets.md`, `api-template.kt` |
+| `flutter/` | `flutter` | `stack.yaml`, `tech-stack.md`, `snippets.md`, `api-template.dart` |
+| `react-native/` | `react-native` | `stack.yaml`, `tech-stack.md`, `snippets.md`, `api-template.ts` |
+
+## Layout contract
+
+Each `variants/{platform}/` directory contains:
+
+- **`stack.yaml`** — the stack SSOT, validated against `stack.schema.json`.
+  Declares `language`, `framework`, `state`, `navigation`, `http_client`,
+  `local_storage`, `response_cache`, `structure`, `source`, and a `verify:`
+  block consumed by `oma verify agent mobile`.
+- **`tech-stack.md`** — human-readable narrative reference (`stack.yaml` wins on
+  conflict).
+- **`snippets.md`** — copy-paste-ready, numbered code patterns.
+- **`api-template.{swift,kt,dart,ts}`** — the canonical data/repository template,
+  including the repository-layer response cache when required.
+
+`stack.schema.json` is the shared schema for all variants.
+
+## resources/ is shared meta only
+
+The sibling `resources/` directory holds **only** cross-platform, protocol, and
+meta documents shared by every variant: `execution-protocol.md`,
+`checklist.md`, `error-playbook.md`, `tech-stack.md` (the variant index +
+cross-platform guidance), and the screen templates. Platform-specific stack
+narrative and snippets belong in the variant, not in `resources/`.
+
+## Stack selection
+
+A project's stack is detected from its manifest (`Package.swift`, `settings.gradle.kts`
++ `com.android.application`, `pubspec.yaml`, `package.json` + `react-native`) or
+chosen via `/stack-set`, which seeds a
+project-specific `stack/` from the matching variant baseline (adapt, never
+blind-copy). The variant `stack.yaml` is the default; any field may be overridden
+per project.