@buivietphi/skill-mobile-mt 2.0.0

package/shared/agent-rules-template.md

@@ -0,0 +1,343 @@
+# Agent Rules Template — All Agents
+
+> Each AI agent reads a specific project-level file automatically every session.
+> Copy the relevant section below to your project root.
+
+---
+
+## Quick Reference
+
+| Agent | File to create | Location |
+|-------|---------------|----------|
+| **Claude Code** | `CLAUDE.md` | Project root |
+| **Cursor** | `.cursorrules` | Project root |
+| **Windsurf** | `.windsurfrules` | Project root |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/` folder |
+| **Codex (OpenAI)** | `AGENTS.md` | Project root |
+| **Gemini CLI** | `GEMINI.md` | Project root |
+| **Kimi** | No auto-load file — paste rules as context | — |
+| **Antigravity** | Configured in Antigravity YAML `context.rules` | Agent config |
+
+---
+
+## Claude Code → `CLAUDE.md`
+
+```markdown
+# Project: [Your App Name]
+
+## Stack
+- Framework: [React Native CLI / Expo SDK XX / Flutter X.X / iOS / Android]
+- Language: [TypeScript / JavaScript / Dart / Swift / Kotlin]
+- State: [Redux Toolkit / Zustand / Riverpod / BLoC / StateFlow]
+- Navigation: [React Navigation v6 / Expo Router / GoRouter / UIKit / Jetpack]
+- API: [axios / fetch / Dio / Firebase / GraphQL]
+- Package Manager: [yarn / npm / pnpm / bun / flutter pub]
+
+## Auto-Check Rules (apply after EVERY code change)
+
+Before saying "done", verify:
+- No console.log / print / NSLog in production code
+- No hardcoded secrets or API keys
+- All async operations wrapped in try/catch
+- All 4 states handled: loading / error / empty / success
+- useEffect / dispose / viewModelScope has cleanup
+- FlatList (not ScrollView) for lists > 20 items
+- No force unwrap (! / !! / as!) without null check
+- TypeScript: no implicit 'any'
+- New screens registered in navigator
+
+If ANY check fails → fix it before marking done.
+
+## What NOT to do
+- NEVER suggest migrating to a different framework
+- NEVER change state management library
+- NEVER add packages without checking SDK compatibility
+- NEVER mix package managers (yarn + npm)
+```
+
+---
+
+## Cursor → `.cursorrules`
+
+```
+# [Your App Name] — Cursor Rules
+
+## Project
+- Framework: [React Native CLI / Expo SDK XX / Flutter X.X / iOS / Android]
+- Language: [TypeScript / Dart / Swift / Kotlin]
+- State: [Redux Toolkit / Zustand / Riverpod / BLoC]
+- Package Manager: [yarn / npm / bun / flutter pub]
+
+## Code Style
+- PascalCase for screens and components
+- camelCase for hooks, services, utils
+- Absolute imports with @/ alias (if configured)
+
+## Auto-Check (before every completion)
+- No console.log in production code
+- No hardcoded secrets or API keys
+- All async wrapped in try/catch
+- All 4 states: loading / error / empty / success
+- useEffect has cleanup (return () => ...)
+- FlatList (not ScrollView) for dynamic lists
+- No implicit 'any' in TypeScript
+
+## Never
+- Change framework or architecture
+- Change state management library
+- Add packages without checking SDK compatibility
+- Mix package managers
+```
+
+---
+
+## Windsurf → `.windsurfrules`
+
+```
+# [Your App Name] — Windsurf Rules
+
+Project: [Your App Name]
+Framework: [React Native CLI / Expo / Flutter / iOS / Android]
+Language: [TypeScript / Dart / Swift / Kotlin]
+State management: [Redux Toolkit / Zustand / Riverpod / BLoC]
+Package manager: [yarn / npm / bun / flutter pub]
+
+## Coding Rules
+
+Always:
+- Wrap all async operations in try/catch
+- Handle all 4 states: loading, error, empty, success
+- Add cleanup to useEffect (return () => ...)
+- Use FlatList for dynamic lists (not ScrollView)
+- Use PascalCase for components and screens
+- Use camelCase for hooks, services, and utilities
+- No implicit 'any' in TypeScript
+
+Never:
+- Leave console.log in production code
+- Hardcode secrets, tokens, or API keys
+- Store tokens in AsyncStorage / SharedPreferences / UserDefaults
+- Change the framework or architecture
+- Add packages without verifying SDK compatibility
+- Mix yarn and npm
+
+## Security (non-negotiable)
+- Tokens → SecureStore / Keychain / EncryptedSharedPreferences
+- API calls → HTTPS only
+- Sensitive data → never in logs
+- User input → sanitize before display
+```
+
+---
+
+## GitHub Copilot → `.github/copilot-instructions.md`
+
+```markdown
+# Copilot Instructions — [Your App Name]
+
+## Project Context
+- **Framework:** [React Native CLI / Expo SDK XX / Flutter X.X / iOS / Android]
+- **Language:** [TypeScript / JavaScript / Dart / Swift / Kotlin]
+- **State Management:** [Redux Toolkit / Zustand / Riverpod / BLoC]
+- **Package Manager:** [yarn / npm / bun / flutter pub]
+
+## Conventions
+- PascalCase: components, screens, classes
+- camelCase: hooks, services, utilities, variables
+- Files named same as their default export
+
+## Required Patterns
+
+### Every async function
+```typescript
+try {
+  setLoading(true);
+  const result = await apiCall();
+  setData(result);
+} catch (error) {
+  setError(error.message);
+} finally {
+  setLoading(false);
+}
+```
+
+### Every screen must handle 4 states
+```typescript
+if (loading) return <LoadingScreen />;
+if (error) return <ErrorScreen error={error} />;
+if (!data?.length) return <EmptyScreen />;
+return <DataScreen data={data} />;
+```
+
+### Every useEffect with subscriptions
+```typescript
+useEffect(() => {
+  const sub = subscribe();
+  return () => sub.unsubscribe(); // REQUIRED
+}, []);
+```
+
+## Rules
+- No console.log in production
+- No hardcoded secrets or API keys
+- FlatList (not ScrollView) for dynamic lists
+- Tokens in SecureStore / Keychain only
+- No force unwrap without null check
+- No implicit 'any' in TypeScript
+```
+
+---
+
+## Codex (OpenAI) → `AGENTS.md` (project root)
+
+```markdown
+# [Your App Name] — Agent Rules
+
+## Project
+- Framework: [React Native / Expo / Flutter / iOS / Android]
+- Language: [TypeScript / Dart / Swift / Kotlin]
+- State: [Redux Toolkit / Zustand / Riverpod / BLoC]
+- Package Manager: [yarn / npm / bun / flutter pub]
+
+## Rules for All Tasks
+
+### Always
+- Wrap async in try/catch
+- Handle: loading / error / empty / success states
+- Cleanup useEffect (return unsubscribe/cancel)
+- Use FlatList for dynamic lists
+- PascalCase components, camelCase hooks/services
+
+### Never
+- console.log in production
+- Hardcode secrets or API keys
+- Store tokens in AsyncStorage (use SecureStore/Keychain)
+- Suggest changing framework or state management
+- Add packages without verifying SDK compatibility
+- Mix yarn and npm
+
+### Security
+- Tokens → SecureStore (RN) / Keychain (iOS) / EncryptedSharedPreferences (Android)
+- API → HTTPS only
+- Logs → never include sensitive data
+- Input → sanitize before display
+
+## Architecture
+[FILL IN: describe your feature structure]
+Example: feature-based (src/features/auth/, src/features/home/)
+
+## Preferred Commands
+- Install: [yarn install / npm install / flutter pub get]
+- Run: [yarn ios / yarn android / flutter run]
+- Test: [yarn test / flutter test]
+```
+
+---
+
+## Gemini CLI → `GEMINI.md`
+
+```markdown
+# [Your App Name] — Gemini Rules
+
+## Project Stack
+- Framework: [React Native / Expo / Flutter / iOS / Android]
+- Language: [TypeScript / Dart / Swift / Kotlin]
+- State: [Redux Toolkit / Zustand / Riverpod / BLoC]
+- Package Manager: [yarn / npm / bun / flutter pub]
+
+## Code Quality Rules
+
+Apply before every completion:
+
+1. No console.log / print / NSLog in production
+2. No hardcoded API keys, tokens, or secrets
+3. All async wrapped in try/catch with proper error handling
+4. All 4 states implemented: loading / error / empty / success
+5. useEffect cleanup present when using subscriptions or timers
+6. FlatList used for lists (not ScrollView with map)
+7. TypeScript: no implicit 'any'
+8. New screens registered in the navigator
+
+## Security Rules
+- Token storage: SecureStore / Keychain / EncryptedSharedPreferences ONLY
+- API calls: HTTPS only
+- Logs: no sensitive data
+- User input: sanitize before rendering
+
+## Constraints
+- Do not change framework or architecture
+- Do not change state management library
+- Do not add packages without checking SDK compatibility
+- Do not mix package managers
+```
+
+---
+
+## Kimi — No Auto-Load
+
+Kimi does not read a project file automatically. Options:
+
+**Option 1 — Paste at start of conversation:**
+```
+Project rules:
+- Framework: [React Native / Flutter / iOS / Android]
+- No console.log in production
+- All async in try/catch
+- All 4 states: loading/error/empty/success
+- Tokens in SecureStore/Keychain only
+- No implicit 'any' in TypeScript
+- Do not change framework or state management
+```
+
+**Option 2 — Use skill-mobile-mt:**
+Load SKILL.md as context at the start of the Kimi conversation.
+
+---
+
+## Antigravity — YAML Config
+
+Add to your Antigravity configuration:
+
+```yaml
+skill:
+  name: skill-mobile-mt
+  version: "1.0.0"
+
+context:
+  rules:
+    - No console.log / print / NSLog in production code
+    - No hardcoded secrets or API keys
+    - Tokens in SecureStore / Keychain / EncryptedSharedPreferences ONLY
+    - All async wrapped in try/catch
+    - All 4 states handled: loading / error / empty / success
+    - useEffect / dispose / viewModelScope has cleanup
+    - FlatList (not ScrollView) for dynamic lists
+    - No implicit 'any' in TypeScript
+
+  project:
+    framework: "[react-native / flutter / ios / android]"
+    language: "[typescript / dart / swift / kotlin]"
+    state_management: "[redux / zustand / riverpod / bloc]"
+    package_manager: "[yarn / npm / bun / flutter-pub]"
+
+  constraints:
+    - NEVER suggest migrating to a different framework
+    - NEVER change state management library
+    - NEVER add packages without checking SDK compatibility
+    - NEVER mix package managers
+```
+
+---
+
+## Summary
+
+| Agent | Auto-loaded? | File |
+|-------|-------------|------|
+| Claude Code | YES — every session | `CLAUDE.md` |
+| Cursor | YES — every chat | `.cursorrules` |
+| Windsurf | YES — every session | `.windsurfrules` |
+| GitHub Copilot | YES — workspace context | `.github/copilot-instructions.md` |
+| Codex | YES — when AGENTS.md exists | `AGENTS.md` |
+| Gemini CLI | YES — when GEMINI.md exists | `GEMINI.md` |
+| Kimi | NO — paste manually | (none) |
+| Antigravity | YES — via YAML config | Antigravity config |

package/shared/ai-dlc-workflow.md

@@ -0,0 +1,237 @@
+# AI-DLC Workflow — Mobile Development
+
+> AI-Driven Development Lifecycle adapted for mobile projects.
+> Based on AWS AI-DLC methodology. Use for complex features (3+ screens/units).
+
+---
+
+## When to Activate
+
+| Task | AI-DLC? |
+|------|---------|
+| Bug fix, single-file change | No — direct fix |
+| Add 1 screen, minor feature | No — Feature Scaffold in SKILL.md |
+| Multi-screen feature (auth, checkout, onboarding) | **Yes** |
+| New project setup / architecture decision | **Yes** |
+| Major refactor across multiple files | **Yes** |
+| Performance optimization (app-wide) | **Yes** |
+
+**Rule:** If task requires 3+ units of work → use AI-DLC. Otherwise → use normal flow.
+
+---
+
+## Phase 1: Elaboration
+
+**Goal:** Decompose task before writing any code.
+
+### Step 1 — Define Intent
+
+```
+Intent: [One sentence describing the goal]
+Example: "Auth feature — login, register, forgot password with biometric"
+```
+
+### Step 2 — Decompose into Units
+
+Each Unit = 1 deliverable piece (screen, service, config).
+
+```
+Units:
+  1. [Screen/Component/Service name] — [what it does]
+  2. [Screen/Component/Service name] — [what it does]
+  ...
+
+Example:
+  1. Login screen — email/password form + validation + API call
+  2. Register screen — form + password rules + terms checkbox
+  3. Forgot password flow — email input → OTP verify → new password
+  4. Token storage — SecureStore (RN) / Keychain (iOS) / EncryptedSharedPrefs (Android)
+  5. Auth state manager — global auth state + auto-refresh
+  6. Navigation guard — redirect unauthenticated users to login
+```
+
+### Step 3 — Select Operating Mode
+
+| Mode | When | Human role |
+|------|------|-----------|
+| **HITL** | New team, unfamiliar codebase, critical feature | Approve each Unit before next |
+| **OHOTL** | Familiar codebase, trusted patterns | Monitor, intervene if needed |
+| **AHOTL** | Well-defined scope, strong test coverage | Review at end |
+
+**Default for mobile:** HITL (present each Unit for approval).
+
+### Step 4 — Present Plan to User
+
+Before coding, show:
+```
+Intent: Auth feature
+Units: 6 (listed above)
+Mode: HITL
+Estimated: [X files new, Y files modified]
+Platform: [detected framework]
+
+Proceed? (yes / adjust units / change mode)
+```
+
+---
+
+## Phase 2: Construction Loop
+
+For each Unit, cycle through 4 Hats:
+
+### Hat 1: Architecture
+
+**Read:** `shared/architecture-intelligence.md` + platform file
+
+- Choose pattern (MVVM, Clean Arch, feature-based)
+- Define file structure for this Unit
+- Check: does this match existing project patterns?
+
+```
+Architecture decision:
+  Pattern: [chosen pattern]
+  Files to create: [list]
+  Files to modify: [list]
+  Dependencies: [new packages if any]
+```
+
+### Hat 2: Builder
+
+**Read:** Platform file (`react-native/react-native.md`, `flutter/flutter.md`, etc.)
+
+- Write code following platform patterns
+- Apply Feature Scaffold Protocol from SKILL.md
+- Use existing project conventions (naming, imports, structure)
+
+**Builder rules:**
+- One Unit at a time — finish before starting next
+- Match existing code style exactly
+- No premature abstraction
+- Handle all 4 states: loading / error / empty / success
+
+### Hat 3: Security
+
+**Read:** Security rules in SKILL.md + `shared/anti-patterns.md`
+
+Run 7-category scan on the Unit's code:
+
+| Category | Check |
+|----------|-------|
+| Secrets | No hardcoded keys, tokens, URLs |
+| Storage | Tokens in SecureStore/Keychain only |
+| Input | User input sanitized before display |
+| Network | HTTPS only, no cleartext |
+| Data | No PII in logs, no sensitive data exposed |
+| Auth | Token refresh, session expiry handled |
+| Platform | iOS ATS, Android ProGuard, exported components |
+
+**If any violation found → BLOCK Unit. Fix before proceeding.**
+
+### Hat 4: Reviewer
+
+**Read:** `shared/code-review.md` + `shared/common-pitfalls.md`
+
+Self-review checklist:
+- [ ] Clean Architecture respected (UI → Domain → Data)
+- [ ] Single responsibility (max 300 lines per file)
+- [ ] No console.log / print in production
+- [ ] Error handling complete (try/catch, error states)
+- [ ] Navigation registered
+- [ ] Types complete (no implicit any)
+- [ ] Platform-specific edge cases handled
+- [ ] Accessibility basics (labels, contrast)
+
+**If review fails → return to Builder Hat. Fix, then re-review.**
+
+### Unit Complete
+
+```
+Unit [N]: [name]
+  Status: ✅ complete
+  Files created: [list]
+  Files modified: [list]
+  Security: passed
+  Review: passed
+  → Proceed to Unit [N+1]
+```
+
+---
+
+## Phase 3: Backpressure Gates
+
+Quality gates that **block** progress automatically:
+
+```
+Gate 1: TypeScript / Dart / Kotlin compiler  → must pass
+Gate 2: Lint (ESLint / flutter analyze)       → must pass
+Gate 3: Security scan (Hat 3)                 → must pass
+Gate 4: Self-review (Hat 4)                   → must pass
+Gate 5: Unit test (if test file exists)       → must pass
+```
+
+**Backpressure rule:** If any gate fails, the Builder Hat fixes the issue before moving to the next Unit. Max 3 fix attempts per gate — if still failing, ask user.
+
+---
+
+## Phase 4: Completion
+
+When all Units are done:
+
+```
+Intent: [name]
+  Units: [N] completed
+  Files created: [list all]
+  Files modified: [list all]
+  Security: all Units passed
+  Review: all Units passed
+
+  Remaining:
+  - [ ] Run full test suite
+  - [ ] Test on both platforms (if cross-platform)
+  - [ ] Verify navigation flow end-to-end
+```
+
+---
+
+## Mobile-Specific Adaptations
+
+### Cross-Platform Units
+
+For React Native / Flutter projects, each screen Unit should verify:
+- iOS rendering (safe area, notch, Dynamic Island)
+- Android rendering (back button, status bar, edge-to-edge)
+- Both platform navigation behaviors
+
+### Native Module Units
+
+When Unit involves native code (camera, biometric, push):
+1. Builder Hat writes JS/Dart bridge first
+2. Builder Hat writes iOS native (Swift/ObjC)
+3. Builder Hat writes Android native (Kotlin/Java)
+4. Security Hat checks permissions on both platforms
+
+### State Management Units
+
+Architecture Hat decides ONCE, applies to all Units:
+- RN: Redux Toolkit / Zustand / Jotai / TanStack Query
+- Flutter: Riverpod / BLoC / Provider
+- iOS: TCA / Observable / Combine
+- Android: StateFlow / LiveData
+
+Never mix state management within one Intent.
+
+---
+
+## Hat ↔ Skill File Mapping
+
+| Hat | Primary file | Secondary file |
+|-----|-------------|---------------|
+| Architecture | `shared/architecture-intelligence.md` | Platform file |
+| Builder | Platform file (RN/Flutter/iOS/Android) | `shared/offline-first.md` (if offline) |
+| Security | SKILL.md § Security | `shared/anti-patterns.md` |
+| Reviewer | `shared/code-review.md` | `shared/common-pitfalls.md` |
+
+---
+
+> AI-DLC for mobile: Elaborate → Construct (4 Hats per Unit) → Backpressure gates → Complete.
+> Default mode: HITL. Activate when task ≥ 3 units. Skip for bug fixes and small changes.