@buivietphi/skill-mobile-mt 2.0.0

package/AGENTS.md

@@ -0,0 +1,482 @@
+# Skill Mobile MT — Agent Rules
+
+> Multi-agent compatibility layer for Claude Code, Cline, Roo Code, Cursor, Windsurf, Copilot, Codex, Gemini CLI, Kimi, Kilo Code, Kiro, Antigravity, and all Agent Skills-compatible tools.
+
+---
+
+## Agent Compatibility Matrix
+
+| Agent | How it loads rules | Setup | Think Block |
+|-------|-------------------|-------|-------------|
+| Claude Code | `~/.claude/skills/` (auto) | `npx skill-mobile-mt --claude` | `<think>...</think>` |
+| **Cline** | **`.clinerules/` in project root** | **`npx skill-mobile-mt --init cline`** | Inline reasoning |
+| **Roo Code** | **`.roo/rules/` in project root** | **`npx skill-mobile-mt --init roocode`** | Inline reasoning |
+| **Cursor** | **`.cursorrules` in project root** | **`npx skill-mobile-mt --init cursor`** | Inline reasoning |
+| **Windsurf** | **`.windsurfrules` in project root** | **`npx skill-mobile-mt --init windsurf`** | Inline reasoning |
+| **Copilot** | **`.github/copilot-instructions.md`** | **`npx skill-mobile-mt --init copilot`** | `// PLAN:` comments |
+| Codex | `~/.codex/skills/` (auto) | `npx skill-mobile-mt --codex` | `<think>...</think>` |
+| Gemini CLI | `~/.gemini/skills/` (auto) | `npx skill-mobile-mt --gemini` | `## Thinking:` block |
+| Kimi | `~/.kimi/skills/` (manual) | `npx skill-mobile-mt --kimi` | `【思考】` or markdown |
+| **Kilo Code** | **`.kilocode/rules/` in project root** | **`npx skill-mobile-mt --init kilocode`** | Inline reasoning |
+| **Kiro** | **`.kiro/steering/` in project root** | **`npx skill-mobile-mt --init kiro`** | Inline reasoning |
+| Antigravity | `~/.agents/skills/` (auto) | `npx skill-mobile-mt --antigravity` | Agent-native format |
+
+---
+
+## Full File Structure
+
+```
+skill-mobile-mt/
+├── SKILL.md                        ← Entry point. Always load first.
+├── AGENTS.md                       ← This file. Multi-agent config.
+│
+├── react-native/
+│   └── react-native.md             ← RN + Expo patterns (5,108 tokens)
+│
+├── flutter/
+│   └── flutter.md                  ← Flutter + Dart 3.x patterns (2,100 tokens)
+│
+├── ios/
+│   └── ios-native.md               ← Swift + UIKit/SwiftUI patterns (1,452 tokens)
+│
+├── android/
+│   └── android-native.md           ← Kotlin + Compose + Java legacy patterns (4,400 tokens)
+│
+└── shared/
+    │
+    ├── ── CORE (always load) ──────────────────────────────────
+    ├── code-review.md               ← Senior review checklist (865 tokens)
+    ├── bug-detection.md             ← Auto bug scanner (499 tokens)
+    ├── prompt-engineering.md        ← Auto-think + XML templates (3,927 tokens)
+    │
+    ├── ── ON-DEMAND (load by task) ────────────────────────────
+    ├── error-recovery.md            ← 16 build/runtime error fixes (2,435 tokens)
+    ├── document-analysis.md         ← Parse images/PDFs/DOCX → code (1,200 tokens)
+    ├── anti-patterns.md             ← PII, cardinality, payload detection (2,800 tokens)
+    ├── performance-prediction.md    ← Frame budget, FPS prediction (1,500 tokens)
+    ├── platform-excellence.md       ← iOS 18+ vs Android 15+ UX + HIG (2,200 tokens)
+    ├── version-management.md        ← SDK compat matrix + release testing (3,500 tokens)
+    ├── observability.md             ← Sessions as 4th pillar (3,000 tokens)
+    ├── architecture-intelligence.md ← Patterns from 30+ production repos (4,500 tokens)
+    ├── common-pitfalls.md           ← Known issue patterns (1,160 tokens)
+    ├── release-checklist.md         ← App Store/Play Store checklist (587 tokens)
+    │
+    ├── offline-first.md             ← Local-first + sync patterns (2,566 tokens)
+    ├── testing-strategy.md          ← Detox + Maestro + XCUITest + Espresso E2E (2,200 tokens)
+    ├── ci-cd.md                     ← GitHub Actions CI templates (2,500 tokens)
+    ├── ai-dlc-workflow.md           ← AI-DLC structured workflow for complex features (2,500 tokens)
+    ├── ui-ux-mobile.md              ← Design system, screen templates, touch, navigation, a11y (5,500 tokens)
+    │
+    ├── ── TEMPLATES (copy to your project) ────────────────────
+    ├── claude-md-template.md        ← CLAUDE.md for Claude Code (copy to project root)
+    └── agent-rules-template.md      ← Rules for ALL agents: Cursor/.cursorrules, Windsurf/.windsurfrules, Copilot/.github/copilot-instructions.md, Codex/AGENTS.md, Gemini/GEMINI.md, Antigravity YAML
+```
+
+**Token totals:**
+- Smart load (1 platform + core shared): **~40,900 tokens** (31.9% of 128K)
+- Full load (all files): **~77,000 tokens** (60.2% of 128K)
+
+---
+
+## When Smart Load vs Full Load
+
+### Smart Load (default — always used)
+
+**Triggered by:** `@skill-mobile-mt` or `@skill-mobile-mt project`
+
+**Loads automatically:**
+```
+SKILL.md                           (~13,200 tokens)
++ 1 platform file                  (~1,580–5,730 tokens depending on platform)
++ shared/code-review.md            (~1,500 tokens)
++ shared/bug-detection.md          (~800 tokens)
++ shared/prompt-engineering.md     (~5,600 tokens)
+─────────────────────────────────────────────────
+≈ 38,600 tokens total (estimated)
+```
+
+**Use case:** Regular coding, new features, code review. Covers 90% of daily work.
+
+---
+
+### On-Demand Load (triggered automatically by task type)
+
+The agent reads the task, then decides which extra file to load:
+
+| Task the user asks for | File loaded |
+|------------------------|-------------|
+| "Fix this crash / build error" | `shared/error-recovery.md` |
+| "Read this screenshot / PDF / DOCX" | `shared/document-analysis.md` |
+| "Add analytics / logging / crash tracking" | `shared/anti-patterns.md` + `shared/observability.md` |
+| "Build a FlatList / animation" | `shared/performance-prediction.md` |
+| "Make it feel native on iOS/Android" | `shared/platform-excellence.md` |
+| "Install this package / upgrade SDK" | `shared/version-management.md` |
+| "Prepare for App Store / Play Store" | `shared/release-checklist.md` |
+| "Weird issue, not sure why" | `shared/common-pitfalls.md` |
+| "Write / run E2E tests" | `shared/testing-strategy.md` |
+| "Setup CI/CD / GitHub Actions" | `shared/ci-cd.md` |
+| "Big feature / multi-screen" | `shared/ai-dlc-workflow.md` |
+| "Create/design screen / demo UI" | `shared/ui-ux-mobile.md` |
+
+**Load cost:** +500 to +3,500 tokens per on-demand file.
+
+---
+
+### Full Load (never automatic — AI reads all files)
+
+**No automatic trigger.** Full load happens when the AI reads every file without being selective — either because it's over-eager, or because the user explicitly asks for it.
+
+**Total:** ~72,300 tokens (56.5% of 128K, 36% of 200K)
+
+**How it actually works:**
+- `@skill-mobile-mt` only injects SKILL.md into context
+- From there, the AI uses the `Read` tool to open additional files
+- Smart load = AI reads selectively (only what the task needs)
+- Full load = AI reads every file in shared/ + all platform files
+
+**When full load makes sense:**
+- User says "load everything" or "give me a full audit"
+- New project setup where all patterns are relevant simultaneously
+- Cross-platform (iOS + Android + RN) with all shared patterns needed
+- Antigravity agent configured to load all files upfront
+
+**When it's wasteful:**
+- Single focused task ("fix this bug", "add this screen") — loads 3x more tokens than needed
+- Single-platform projects — loading all 4 platform files is waste
+
+---
+
+## Antigravity Configuration
+
+```yaml
+skill:
+  name: skill-mobile-mt
+  version: "1.4.2"
+  author: buivietphi
+  category: engineering
+  tags:
+    - mobile
+    - react-native
+    - flutter
+    - ios
+    - android
+    - clean-architecture
+    - code-review
+    - senior
+
+  modes:
+    default:
+      description: "Use pre-built production patterns from 18 real mobile apps"
+      loads:
+        # Core — always
+        - SKILL.md
+        - "{detected-platform}/{platform}.md"
+        - shared/code-review.md
+        - shared/bug-detection.md
+        - shared/prompt-engineering.md
+        # On-demand — add based on task
+        # - shared/error-recovery.md
+        # - shared/anti-patterns.md
+        # - shared/performance-prediction.md
+        # - shared/platform-excellence.md
+        # - shared/version-management.md
+        # - shared/observability.md
+        # - shared/document-analysis.md
+        # - shared/release-checklist.md
+        # - shared/common-pitfalls.md
+
+    project:
+      description: "Read current project, adapt to its framework and conventions"
+      argument: "project"
+      loads:
+        - SKILL.md (Section: Project Adaptation)
+        - "{detected-platform}/{platform}.md"
+        - shared/code-review.md
+        - shared/bug-detection.md
+        - shared/prompt-engineering.md
+
+  platform_detection:
+    react-native:
+      detect: "package.json contains 'react-native' or 'expo'"
+      load: "react-native/react-native.md"
+    flutter:
+      detect: "pubspec.yaml exists"
+      load: "flutter/flutter.md"
+    ios:
+      detect: "*.xcodeproj or *.xcworkspace exists (without pubspec.yaml)"
+      load: "ios/ios-native.md"
+    android:
+      detect: "build.gradle exists (without package.json or pubspec.yaml)"
+      load: "android/android-native.md"
+
+  language_detection:
+    typescript: ".tsx/.ts files in src/"
+    javascript: ".jsx/.js files in src/"
+    dart: ".dart files in lib/"
+    swift: ".swift files"
+    kotlin: ".kt files"
+    java: ".java files in app/src/"
+
+  context_budget:
+    max_tokens: 77000
+    smart_load_tokens: 40900
+    savings: "~47%"
+```
+
+---
+
+## File Loading Rules for All Agents
+
+### Smart Loading Protocol
+
+Every agent MUST follow this loading sequence:
+
+```
+1. ALWAYS load: SKILL.md (entry point, auto-detect, universal principles)
+
+2. AUTO-DETECT project:
+   - Framework (React Native / Flutter / iOS / Android)
+   - Language (TypeScript / JavaScript / Dart / Swift / Kotlin / Java)
+   - Package manager (yarn / npm / pnpm / bun / flutter pub / pod)
+   - State management
+   - Navigation
+
+3. LOAD the matching platform subfolder:
+   - react-native/react-native.md  (only if RN/Expo)
+   - flutter/flutter.md            (only if Flutter)
+   - ios/ios-native.md             (only if iOS native)
+   - android/android-native.md     (only if Android native)
+
+4. Cross-platform? Load multiple:
+   - Flutter → also load ios/ + android/ (native modules)
+   - React Native → also load ios/ + android/ (native modules)
+
+5. ALWAYS load shared/ (core):
+   - shared/code-review.md
+   - shared/bug-detection.md
+   - shared/prompt-engineering.md
+
+6. LOAD shared/ (on-demand, based on task):
+   - shared/error-recovery.md         (when debugging build/runtime errors)
+   - shared/document-analysis.md      (when reading images, PDFs, DOCX)
+   - shared/anti-patterns.md          (when reviewing or writing observability code)
+   - shared/performance-prediction.md (when building lists, animations, heavy screens)
+   - shared/platform-excellence.md    (when implementing platform-specific UX)
+   - shared/version-management.md     (when installing packages or upgrading SDK)
+   - shared/observability.md          (when adding logging, analytics, crash tracking)
+   - shared/common-pitfalls.md        (when encountering unfamiliar errors)
+   - shared/release-checklist.md      (when preparing for App Store/Play Store submission)
+
+7. SKIP non-matching platform subfolders (saves ~66% context)
+```
+
+### Loading Priority
+
+```
+Priority 1 (CRITICAL):  SKILL.md — Auto-detect, mode selection, principles
+Priority 2 (HIGH):      {platform}/{platform}.md — Framework-specific patterns
+Priority 3 (MEDIUM):    shared/code-review.md — Review checklist
+Priority 4 (MEDIUM):    shared/bug-detection.md — Auto-scanner
+Priority 5 (MEDIUM):    shared/prompt-engineering.md — Auto-think templates
+Priority 6 (ON-DEMAND): shared/error-recovery.md — Build/runtime error fixes
+Priority 6 (ON-DEMAND): shared/anti-patterns.md — PII, cardinality, payload detection
+Priority 6 (ON-DEMAND): shared/performance-prediction.md — Frame budget calculations
+Priority 6 (ON-DEMAND): shared/platform-excellence.md — iOS 18+ vs Android 15+ UX
+Priority 6 (ON-DEMAND): shared/version-management.md — SDK compatibility matrix
+Priority 6 (ON-DEMAND): shared/observability.md — Sessions as 4th pillar
+Priority 6 (ON-DEMAND): shared/document-analysis.md — Parse images/PDFs → code
+Priority 6 (ON-DEMAND): shared/release-checklist.md — Pre-release verification
+Priority 6 (ON-DEMAND): shared/common-pitfalls.md — Known issue patterns
+Priority 6 (ON-DEMAND): shared/testing-strategy.md — Detox + Maestro + XCUITest + Espresso E2E
+Priority 6 (ON-DEMAND): shared/ci-cd.md — GitHub Actions CI/CD templates
+Priority 6 (ON-DEMAND): shared/ai-dlc-workflow.md — AI-DLC structured workflow for complex features
+Priority 6 (ON-DEMAND): shared/ui-ux-mobile.md — Screen templates, design tokens, components, dark mode
+```
+
+---
+
+## Agent-Specific Behavior
+
+### Claude Code
+- Supports `$ARGUMENTS` — use `project` to trigger project mode
+- Can invoke sub-files via Read tool from subfolders
+- Full tool access for project scanning and auto-detect
+
+### Codex
+- Load SKILL.md as system context or prepend to conversation
+- Reference subfolder files with Read tool when needed
+- Use `project` keyword to trigger project adaptation mode
+
+### Gemini CLI
+- Load SKILL.md as system context
+- Parse mode from user prompt ("use project mode" or default)
+- Reference subfolder files as needed
+
+### Kimi
+- Load SKILL.md as knowledge base
+- Supports both Chinese and English prompts
+- Think blocks use `【思考】` format
+
+### Cline
+- Reads `.clinerules/` directory from project root (also supports `.clinerules` single file)
+- Also reads from `~/.cline/skills/` for global skills
+- Run `npx @buivietphi/skill-mobile-mt --init cline` to generate `.clinerules/mobile-rules.md`
+- Supports conditional rules with YAML frontmatter `paths:` field
+
+### Roo Code
+- Reads `.roo/rules/` directory from project root (recursive, multi-file)
+- Also reads from `~/.roo/skills/` for global skills
+- Supports mode-specific rules: `.roo/rules-code/`, `.roo/rules-architect/`
+- Run `npx @buivietphi/skill-mobile-mt --init roocode` to generate `.roo/rules/mobile-rules.md`
+- Auto-loads `AGENTS.md` from workspace root
+
+### Cursor
+- Reads `.cursorrules` from project root
+- Run `npx @buivietphi/skill-mobile-mt --init cursor` to generate `.cursorrules`
+- The generated file includes auto-detected framework, rules, and security patterns
+- Think blocks embedded as inline reasoning in Composer
+
+### GitHub Copilot
+- Reads `.github/copilot-instructions.md` from project
+- Run `npx @buivietphi/skill-mobile-mt --init copilot` to generate the file
+- The generated file includes code patterns, required templates, and rules
+- Think blocks as `// PLAN:` comments before code
+
+### Windsurf
+- Reads `.windsurfrules` from project root
+- Run `npx @buivietphi/skill-mobile-mt --init windsurf` to generate `.windsurfrules`
+- The generated file includes coding rules, security rules, and architecture patterns
+- Think blocks as inline reasoning
+
+### Kilo Code
+- Reads `.kilocode/rules/` directory from project root
+- Also reads from `~/.kilocode/rules/` for global rules
+- Supports mode-specific rules: `.kilocode/rules-code/`, `.kilocode/rules-architect/`
+- Run `npx @buivietphi/skill-mobile-mt --init kilocode` to generate `.kilocode/rules/mobile-rules.md`
+- Auto-loads `AGENTS.md` from workspace root
+
+### Kiro (AWS)
+- Reads `.kiro/steering/` directory from project root
+- Also reads from `~/.kiro/steering/` for global steering
+- Uses YAML frontmatter with `inclusion: always|fileMatch|manual|auto`
+- Run `npx @buivietphi/skill-mobile-mt --init kiro` to generate `.kiro/steering/mobile-rules.md`
+- Separate specs system in `.kiro/specs/` for feature development
+
+### Antigravity
+- Orchestrator loads based on detected project type
+- Follows `platform_detection` rules above
+- Respects `context_budget` limits
+
+---
+
+## Project-Level Rules (Auto-Loaded Per Agent)
+
+Each agent reads a specific file from the **user's project root** every session.
+These are separate from the skill files — they go in the user's project, not in skill-mobile-mt/.
+
+| Agent | File | Location |
+|-------|------|----------|
+| Claude Code | `CLAUDE.md` | Project root |
+| Cline | `.clinerules/` directory | Project root |
+| Roo Code | `.roo/rules/` directory | Project root |
+| Cursor | `.cursorrules` | Project root |
+| Windsurf | `.windsurfrules` | Project root |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.github/` folder |
+| Codex | `AGENTS.md` | Project root |
+| Gemini CLI | `GEMINI.md` | Project root |
+| Kimi | No auto-load — paste as context | — |
+| Kilo Code | `.kilocode/rules/` directory | Project root |
+| Kiro | `.kiro/steering/` directory | Project root |
+| Antigravity | YAML `context.rules` field | Antigravity config |
+
+**Templates for all agents:** `shared/agent-rules-template.md`
+Copy the relevant section to your project to enable auto-check rules in every session.
+
+```bash
+# After installing skill-mobile-mt, find the templates at:
+~/.claude/skills/skill-mobile-mt/shared/agent-rules-template.md
+~/.claude/skills/skill-mobile-mt/shared/claude-md-template.md
+```
+
+---
+
+## Installation Paths
+
+### Skill directory install (agents that read from skills/)
+
+```bash
+# Claude Code
+~/.claude/skills/skill-mobile-mt/
+
+# Cline
+~/.cline/skills/skill-mobile-mt/
+
+# Roo Code
+~/.roo/skills/skill-mobile-mt/
+
+# Codex
+~/.codex/skills/skill-mobile-mt/
+
+# Gemini CLI
+~/.gemini/skills/skill-mobile-mt/
+
+# Kimi
+~/.kimi/skills/skill-mobile-mt/
+
+# Kilo Code
+~/.kilocode/skills/skill-mobile-mt/
+
+# Kiro
+~/.kiro/skills/skill-mobile-mt/
+
+# Antigravity (shared agent directory)
+~/.agents/skills/skill-mobile-mt/
+
+# Custom path
+npx @buivietphi/skill-mobile-mt --path /your/custom/path
+```
+
+### Project-level files (agents that read from project root)
+
+These agents read rules from project-level files. Use `--init` to generate them:
+
+```bash
+# Generate all project-level files (interactive selector)
+npx @buivietphi/skill-mobile-mt --init
+
+# Generate specific agent file
+npx @buivietphi/skill-mobile-mt --init cursor     # → .cursorrules
+npx @buivietphi/skill-mobile-mt --init cline      # → .clinerules/mobile-rules.md
+npx @buivietphi/skill-mobile-mt --init roocode    # → .roo/rules/mobile-rules.md
+npx @buivietphi/skill-mobile-mt --init copilot    # → .github/copilot-instructions.md
+npx @buivietphi/skill-mobile-mt --init windsurf   # → .windsurfrules
+npx @buivietphi/skill-mobile-mt --init kilocode   # → .kilocode/rules/mobile-rules.md
+npx @buivietphi/skill-mobile-mt --init kiro       # → .kiro/steering/mobile-rules.md
+npx @buivietphi/skill-mobile-mt --init all        # → all files
+```
+
+**What `--init` does:**
+1. Auto-detects your project (framework, language, state management, etc.)
+2. Generates rules files pre-filled with your detected stack
+3. Includes all mobile best practices, security rules, and quality gates
+4. Won't overwrite existing files (safe to run multiple times)
+
+---
+
+## Metadata
+
+```json
+{
+  "id": "skill-mobile-mt",
+  "name": "skill-mobile-mt",
+  "version": "2.0.0",
+  "author": "buivietphi",
+  "category": "engineering",
+  "description": "Master Senior Mobile Engineer. Pre-built patterns from 30+ production repos + project adaptation. Auto-detects language and framework. React Native, Flutter, iOS, Android.",
+  "risk": "low",
+  "source": "buivietphi (MIT)",
+  "platforms": ["react-native", "flutter", "ios", "android"],
+  "languages": ["typescript", "javascript", "dart", "swift", "kotlin", "java"],
+  "agents": ["claude-code", "cline", "roo-code", "cursor", "windsurf", "copilot", "codex", "gemini", "kimi", "kilo-code", "kiro", "antigravity"]
+}
+```