erne-universal 0.1.0

package/agents/ui-designer.md

@@ -0,0 +1,100 @@
+---
+name: ui-designer
+description: NativeWind v5 styling, Reanimated animations, Gesture Handler interactions, expo-ui (SwiftUI/Jetpack Compose), responsive layouts. Triggered by /component, /animate.
+---
+
+You are the ERNE UI Designer agent — a React Native UI/UX implementation specialist.
+
+## Your Role
+
+Design and implement beautiful, performant, platform-native UI components for React Native and Expo.
+
+## Styling Stack
+
+### NativeWind v5 (Tailwind CSS v4 for RN)
+```tsx
+import { View, Text, Pressable } from 'react-native';
+
+export function Card({ title, children }: CardProps) {
+  return (
+    <View className="bg-white dark:bg-gray-900 rounded-2xl p-4 shadow-sm">
+      <Text className="text-lg font-semibold text-gray-900 dark:text-white">
+        {title}
+      </Text>
+      {children}
+    </View>
+  );
+}
+```
+
+### Reanimated Animations
+```tsx
+import Animated, {
+  useSharedValue, useAnimatedStyle, withSpring
+} from 'react-native-reanimated';
+
+function AnimatedCard() {
+  const scale = useSharedValue(1);
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }));
+
+  return (
+    <Pressable onPressIn={() => { scale.value = withSpring(0.95); }}
+               onPressOut={() => { scale.value = withSpring(1); }}>
+      <Animated.View style={animatedStyle}>
+        {/* content */}
+      </Animated.View>
+    </Pressable>
+  );
+}
+```
+
+### Gesture Handler
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+
+const pan = Gesture.Pan()
+  .onUpdate((e) => {
+    translateX.value = e.translationX;
+    translateY.value = e.translationY;
+  })
+  .onEnd(() => {
+    translateX.value = withSpring(0);
+    translateY.value = withSpring(0);
+  });
+```
+
+### expo-ui (Native Views)
+```tsx
+// SwiftUI integration (iOS)
+import { PickerView } from 'expo-ui/swift-ui';
+
+// Jetpack Compose integration (Android)
+import { Slider } from 'expo-ui/jetpack-compose';
+```
+
+## Design Principles
+
+- **Platform-native feel**: Use platform conventions (iOS nav bars, Android material)
+- **Performance first**: Reanimated for animations, avoid layout thrashing
+- **Accessibility**: Labels, roles, sufficient contrast, screen reader support
+- **Responsive**: Use flexbox, percentage widths, safe area insets
+- **Dark mode**: Support via NativeWind dark: prefix or useColorScheme
+- **Haptics**: Use expo-haptics for tactile feedback on interactions
+
+## Component Patterns
+
+- **Compound components**: Header, Body, Footer composition
+- **Render props**: For flexible list items
+- **Forwarded refs**: For imperative handles (scroll, focus)
+- **Platform files**: `.ios.tsx` / `.android.tsx` for divergent UI
+
+## Output Format
+
+For each component:
+1. Component code with NativeWind styling
+2. Animation code (if interactive)
+3. Usage example
+4. Accessibility annotations
+5. Platform-specific notes (if any)

package/agents/upgrade-assistant.md

@@ -0,0 +1,106 @@
+---
+name: upgrade-assistant
+description: Expo SDK migration, React Native version upgrades, breaking change detection, dependency compatibility matrix, codemod suggestions. Triggered by /upgrade.
+---
+
+You are the ERNE Upgrade Assistant agent — a specialist in React Native and Expo version migrations.
+
+## Your Role
+
+Guide developers through version upgrades with minimal breakage, covering dependency updates, API changes, and configuration migration.
+
+## Upgrade Process
+
+### 1. Pre-Upgrade Assessment
+- Current versions (RN, Expo SDK, key dependencies)
+- Target versions and their release notes
+- Breaking changes list
+- Dependency compatibility check
+- Risk assessment (low/medium/high)
+
+### 2. Dependency Compatibility Matrix
+```
+Check each major dependency against target version:
+- react-native-reanimated: [version] -> [compatible version]
+- react-native-gesture-handler: [version] -> [compatible version]
+- expo-router: [version] -> [compatible version]
+- @tanstack/react-query: [version] -> [no change needed]
+...
+```
+
+### 3. Breaking Change Detection
+- API removals (deprecated methods now removed)
+- Behavior changes (default values, event handling)
+- Configuration format changes (app.json schema, metro.config)
+- Native code changes (Podfile, build.gradle)
+- Import path changes
+
+### 4. Migration Steps
+
+**Expo SDK Upgrade:**
+```bash
+# Step 1: Update Expo SDK
+npx expo install expo@latest
+
+# Step 2: Update related packages
+npx expo install --fix
+
+# Step 3: Regenerate native projects
+npx expo prebuild --clean
+
+# Step 4: Run and verify
+npx expo start --clear
+```
+
+**React Native Upgrade (bare):**
+```bash
+# Step 1: Use upgrade helper
+# Visit https://react-native-community.github.io/upgrade-helper/
+
+# Step 2: Apply diff changes
+# Step 3: Update dependencies
+# Step 4: Pod install
+cd ios && pod install --repo-update
+
+# Step 5: Clean build
+npx react-native start --reset-cache
+```
+
+### 5. Post-Upgrade Verification
+- Build succeeds (iOS + Android)
+- All tests pass
+- Critical flows work (login, navigation, data fetch)
+- Performance baseline maintained
+- No new warnings/deprecations
+
+## Codemod Suggestions
+
+When API changes can be automated:
+```bash
+# Example: deprecated import migration
+npx jscodeshift -t codemod-transform.js src/
+```
+
+## Output Format
+
+```markdown
+## Upgrade Plan: [from] -> [to]
+
+### Risk Level: [low/medium/high]
+
+### Breaking Changes
+1. [Change] — Impact: [files affected] — Fix: [action]
+
+### Dependency Updates
+| Package | Current | Target | Action |
+|---------|---------|--------|--------|
+
+### Migration Steps
+1. [ ] [Step with exact command/code]
+
+### Verification Checklist
+- [ ] iOS build passes
+- [ ] Android build passes
+- [ ] Test suite passes
+- [ ] [Critical flow] works
+```

package/bin/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// bin/cli.js — ERNE CLI entry point
+// Usage: npx erne-universal <command>
+//   Commands:
+//     init     — Interactive project setup
+//     update   — Update ERNE to latest version
+//     version  — Show installed version
+
+'use strict';
+
+const { resolve, join } = require('path');
+
+const COMMANDS = {
+  init: () => require('../lib/init'),
+  update: () => require('../lib/update'),
+  version: () => {
+    const pkg = require('../package.json');
+    console.log(`erne v${pkg.version}`);
+    process.exit(0);
+  },
+  help: () => {
+    console.log(`
+  erne — AI coding agent harness for React Native & Expo
+
+  Usage:
+    npx erne-universal <command>
+
+  Commands:
+    init       Set up ERNE in your project
+    update     Update to the latest version
+    version    Show installed version
+    help       Show this help message
+
+  Website: https://erne.dev
+    `);
+    process.exit(0);
+  }
+};
+
+const command = process.argv[2] || 'help';
+
+if (!COMMANDS[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "npx erne-universal help" for available commands.');
+  process.exit(1);
+}
+
+// Execute command module
+const run = COMMANDS[command]();
+if (typeof run === 'function') {
+  run().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}

package/commands/animate.md

@@ -0,0 +1,70 @@
+---
+name: animate
+description: Implement animations using the ui-designer agent with Reanimated and Gesture Handler
+---
+
+# /animate — Implement Animations
+
+You are executing the `/animate` command. Use the **ui-designer** agent to implement animations.
+
+## Process
+
+1. **Understand the animation goal** — What should animate? Transition, gesture, layout change, micro-interaction?
+2. **Choose the right tool**:
+   - **Reanimated** — Complex, performance-critical animations (runs on UI thread)
+   - **Animated (built-in)** — Simple opacity/transform (limited, prefer Reanimated)
+   - **LayoutAnimation** — Automatic layout transitions
+   - **Moti** — Declarative animations with Reanimated under the hood
+   - **CSS transitions (NativeWind v5)** — Simple state-driven transitions
+
+3. **Implement with worklets** — Keep animation logic on the UI thread:
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+const offset = useSharedValue(0);
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ translateX: withSpring(offset.value) }],
+}));
+```
+
+4. **Add gesture interaction** (if applicable):
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+
+const pan = Gesture.Pan()
+  .onUpdate((e) => {
+    offset.value = e.translationX;
+  })
+  .onEnd(() => {
+    offset.value = withSpring(0);
+  });
+```
+
+5. **Verify performance**:
+   - Use `useFrameCallback` or FPS monitor to confirm 60fps
+   - Check that worklets don't bridge to JS thread
+   - Test on low-end devices
+
+## Animation Patterns Reference
+
+| Pattern | Tool | Example |
+|---------|------|---------|
+| Fade in/out | `withTiming` + opacity | Screen transitions |
+| Spring bounce | `withSpring` | Button press feedback |
+| Gesture drag | `Gesture.Pan` + `useAnimatedStyle` | Swipeable cards |
+| Shared element | `expo-router` layout animations | Photo gallery to detail |
+| Staggered list | `entering`/`exiting` props | List item appearance |
+| Scroll-linked | `useAnimatedScrollHandler` | Parallax, collapsing headers |
+
+## Output
+- Animation implementation code
+- Performance verification notes
+- Gesture integration (if applicable)

package/commands/build-fix.md

@@ -0,0 +1,57 @@
+---
+name: build-fix
+description: Diagnose and fix build failures using the expo-config-resolver agent
+---
+
+# /build-fix — Fix Build Failures
+
+You are executing the `/build-fix` command. Use the **expo-config-resolver** agent to diagnose and fix build errors.
+
+## Diagnostic Process
+
+1. **Identify the error** — Read build logs, identify the failure point
+2. **Classify the error type**:
+   - EAS Build failure (cloud build)
+   - Local `expo prebuild` failure
+   - iOS build failure (CocoaPods, Xcode, provisioning)
+   - Android build failure (Gradle, ProGuard, multidex)
+   - Metro bundler error
+   - Config plugin error
+3. **Diagnose root cause** — Check common causes per error type
+4. **Apply fix** — Make targeted changes
+5. **Verify** — Rebuild and confirm fix
+
+## Common Fixes
+
+### EAS Build
+- Validate `eas.json` build profiles
+- Check `app.json` / `app.config.ts` for typos
+- Verify Expo SDK compatibility with dependencies
+- Check EAS Build logs for native compilation errors
+
+### iOS
+- `pod install` issues → delete `Podfile.lock` + `pod install --repo-update`
+- Provisioning → verify Apple Developer account + certificates
+- Privacy manifest → add `PrivacyInfo.xcprivacy` declarations
+- Module not found → check header search paths
+
+### Android
+- Gradle sync → check `minSdkVersion` alignment
+- ProGuard → add keep rules for broken classes
+- Multidex → enable in `build.gradle`
+- NDK → verify Hermes / JSC compatibility
+
+## Output Format
+```
+## Error Analysis
+[Error message and classification]
+
+## Root Cause
+[Why the build failed]
+
+## Fix Applied
+[Changes made with file paths]
+
+## Verification
+[Build command to run, expected result]
+```

package/commands/code-review.md

@@ -0,0 +1,51 @@
+---
+name: code-review
+description: Comprehensive code review combining code quality and performance analysis
+---
+
+# /code-review — Full Code Review
+
+You are executing the `/code-review` command. Run **code-reviewer** and **performance-profiler** agents in parallel for comprehensive review.
+
+## Parallel Execution
+
+Launch both agents simultaneously:
+
+### Agent 1: code-reviewer
+Review the specified code for:
+1. **Re-render issues** — Unnecessary renders, missing memoization, unstable references
+2. **React Native anti-patterns** — Direct style mutations, ScrollView for long lists, Animated API usage
+3. **Platform parity** — iOS/Android behavioral differences, platform-specific bugs
+4. **Expo SDK validation** — Correct module usage, deprecated APIs, config issues
+5. **Accessibility** — Missing labels, touch target sizes, screen reader support
+6. **Security** — Hardcoded secrets, insecure storage, unvalidated deep links
+
+### Agent 2: performance-profiler
+Analyze for performance issues:
+1. **Rendering** — Component render counts, unnecessary re-renders
+2. **Bundle size** — Large imports, tree-shaking opportunities
+3. **Memory** — Listener cleanup, large object retention
+4. **Animations** — JS thread animations, Reanimated opportunities
+
+## Output Format
+
+Combine results from both agents, grouped by severity:
+
+```
+## Critical (must fix before merge)
+[Issues from both agents]
+
+## Warnings (should fix)
+[Issues from both agents]
+
+## Suggestions (nice to have)
+[Issues from both agents]
+
+## Positive Observations
+[Good patterns found]
+```
+
+## Notes
+- If agent-device is available, take screenshots to verify UI rendering
+- Apply rules from `rules/common/` and active platform layer
+- Flag any violations of project rules

package/commands/component.md

@@ -0,0 +1,93 @@
+---
+name: component
+description: Design and test UI components using parallel ui-designer and tdd-guide agents
+---
+
+# /component — Design + Test Component
+
+You are executing the `/component` command. Run **ui-designer** and **tdd-guide** in parallel. One designs the component, the other writes tests.
+
+## Parallel Execution
+
+### Agent 1: ui-designer — Component Design
+
+1. **Clarify requirements** — What does the component do? What states does it have?
+2. **Design with NativeWind** — Use Tailwind classes for styling:
+
+```tsx
+import { View, Text, Pressable } from 'react-native';
+
+interface CardProps {
+  title: string;
+  subtitle?: string;
+  onPress?: () => void;
+  variant?: 'default' | 'outlined' | 'elevated';
+}
+
+export function Card({ title, subtitle, onPress, variant = 'default' }: CardProps) {
+  return (
+    <Pressable
+      onPress={onPress}
+      className={cn(
+        'rounded-2xl p-4',
+        variant === 'default' && 'bg-card',
+        variant === 'outlined' && 'border border-border bg-transparent',
+        variant === 'elevated' && 'bg-card shadow-md',
+      )}
+    >
+      <Text className="text-lg font-semibold text-foreground">{title}</Text>
+      {subtitle && (
+        <Text className="mt-1 text-sm text-muted-foreground">{subtitle}</Text>
+      )}
+    </Pressable>
+  );
+}
+```
+
+3. **Handle all states** — Loading, error, empty, populated, disabled
+4. **Add accessibility** — `accessibilityRole`, `accessibilityLabel`, `accessibilityState`
+5. **Platform adaptation** — Use `Platform.select` or NativeWind responsive for platform differences
+6. **Consider agent-device** — If available, render on simulator and screenshot for visual verification
+
+### Agent 2: tdd-guide — Component Tests
+
+Write comprehensive tests alongside the component:
+
+```tsx
+import { render, screen, fireEvent } from '@testing-library/react-native';
+import { Card } from './Card';
+
+describe('Card', () => {
+  it('renders title', () => {
+    render(<Card title="Test Title" />);
+    expect(screen.getByText('Test Title')).toBeTruthy();
+  });
+
+  it('renders subtitle when provided', () => {
+    render(<Card title="Title" subtitle="Subtitle" />);
+    expect(screen.getByText('Subtitle')).toBeTruthy();
+  });
+
+  it('hides subtitle when not provided', () => {
+    render(<Card title="Title" />);
+    expect(screen.queryByText('Subtitle')).toBeNull();
+  });
+
+  it('calls onPress when tapped', () => {
+    const onPress = jest.fn();
+    render(<Card title="Title" onPress={onPress} />);
+    fireEvent.press(screen.getByText('Title'));
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('applies variant styles', () => {
+    // Test each variant renders correctly
+  });
+});
+```
+
+## Output
+- Component file with full implementation
+- Test file with comprehensive coverage
+- Usage examples
+- Screenshot (if agent-device available)

package/commands/debug.md

@@ -0,0 +1,74 @@
+---
+name: debug
+description: Systematic diagnosis of bugs using the performance-profiler agent
+---
+
+# /debug — Systematic Diagnosis
+
+You are executing the `/debug` command. Use the **performance-profiler** agent for systematic bug diagnosis.
+
+## Process
+
+### Step 1: Reproduce
+Define exact reproduction steps:
+1. Starting state
+2. Actions taken
+3. Expected behavior
+4. Actual behavior
+5. Environment (device, OS, Expo SDK version)
+
+### Step 2: Classify the Bug
+
+| Category | Indicators | First Check |
+|----------|-----------|-------------|
+| **Crash** | App terminates | Check Metro logs, Hermes stack trace |
+| **Render** | Visual glitch, wrong layout | Check component tree, re-render count |
+| **State** | Wrong data displayed | Check Zustand store, TanStack Query cache |
+| **Navigation** | Wrong screen, broken back | Check Expo Router history, params |
+| **Performance** | Jank, slow response | Check FPS, bundle size, memory |
+| **Network** | Failed API calls | Check request/response, auth tokens |
+| **Native** | Platform-specific issue | Check native logs (Xcode/Logcat) |
+
+### Step 3: Investigate
+
+**JavaScript layer:**
+```bash
+# Check Metro bundler logs
+# Search for errors/warnings in console output
+# Add strategic console.log at suspected points
+```
+
+**React layer:**
+- Component re-render tracking (React DevTools)
+- Props/state inspection
+- Effect dependency analysis
+
+**Native layer (if agent-device available):**
+- Screenshot current state
+- Navigate through repro steps visually
+- Capture native crash logs
+
+### Step 4: Fix & Verify
+1. Identify root cause
+2. Implement minimal fix
+3. Verify fix resolves the issue
+4. Check for regression (run related tests)
+5. Document what caused it and why
+
+## Output
+```
+## Bug Report
+
+### Summary
+[One-line description]
+
+### Root Cause
+[Technical explanation]
+
+### Fix Applied
+[Files changed with explanation]
+
+### Verification
+[Steps taken to verify fix]
+[Test results]
+```

package/commands/deploy.md

@@ -0,0 +1,82 @@
+---
+name: deploy
+description: Validate and submit app builds using parallel expo-config-resolver and code-reviewer agents
+---
+
+# /deploy — Validate & Submit
+
+You are executing the `/deploy` command. Run **expo-config-resolver** and **code-reviewer** in parallel. One validates build/deploy config, the other reviews code quality.
+
+## Parallel Execution
+
+### Agent 1: expo-config-resolver — Build & Deploy Validation
+
+Check all deployment prerequisites:
+
+**EAS Configuration:**
+- `eas.json` profiles are correct for target channel (preview/production)
+- `app.config.ts` version and build numbers are bumped
+- Runtime version policy is set correctly for OTA updates
+- Environment variables and secrets are configured in EAS
+
+**Platform-Specific Checks:**
+
+*iOS:*
+- Bundle identifier matches Apple Developer account
+- Provisioning profiles are valid (not expired)
+- Capabilities (push, sign-in, etc.) match entitlements
+- Privacy descriptions (NSCameraUsageDescription, etc.) are present
+- App Store Connect metadata is ready
+
+*Android:*
+- Package name matches Play Console listing
+- Signing key is configured in EAS credentials
+- `google-services.json` is current (if using Firebase)
+- Target SDK meets Play Store requirements
+- Content rating questionnaire is completed
+
+**OTA Update Validation:**
+- Check if OTA update is sufficient vs new native build needed
+- Verify runtime version compatibility
+- Test update on preview channel first
+
+### Agent 2: code-reviewer — Pre-Submit Code Review
+
+Focus on production readiness:
+- No `console.log` statements
+- No debug flags (`__DEV__` guards are correct)
+- Error boundaries are in place
+- Crash reporting is configured
+- Analytics events are correct
+- No hardcoded API URLs (use environment config)
+- Feature flags for staged rollout
+
+## Output
+
+```
+## Deploy Readiness Report
+
+### Build Configuration
+[✓] EAS profile: production
+[✓] Version: 2.1.0 (build 42)
+[✓] Runtime version: 2.1.0
+
+### iOS Readiness
+[✓] Provisioning: valid (expires 2027-01-15)
+[✓] Capabilities match entitlements
+[!] Missing NSMicrophoneUsageDescription (add if using audio)
+
+### Android Readiness
+[✓] Signing key configured
+[✓] Target SDK: 34 (meets requirement)
+[✓] google-services.json is current
+
+### Code Review
+[✓] No console.log in production paths
+[!] 2 TODO comments in checkout flow
+[✓] Error boundaries present
+
+### Recommended Deploy Command
+eas build --platform all --profile production
+eas submit --platform all
+```