@buivietphi/skill-mobile-mt 1.0.1 → 1.2.0

package/AGENTS.md

@@ -6,16 +6,16 @@
 
 ## Agent Compatibility Matrix
 
-| Agent | Skill Path | Invocation | Think Block |
-|-------|-----------|------------|-------------|
-| Claude Code | `~/.claude/skills/skill-mobile-mt/` | `@skill-mobile-mt` or `@skill-mobile-mt project` | `<think>...</think>` |
-| Codex | `~/.codex/skills/skill-mobile-mt/` | `@skill-mobile-mt` or load as context | `<think>...</think>` |
-| Gemini CLI | `~/.gemini/skills/skill-mobile-mt/` | Load as context | `## Thinking:` block |
-| Kimi | `~/.kimi/skills/skill-mobile-mt/` | Load as context | `【思考】` or markdown |
-| Cursor | `~/.cursor/skills/skill-mobile-mt/` | Auto-loaded in Composer | Inline reasoning |
-| Copilot | `~/.copilot/skills/skill-mobile-mt/` | Loaded via workspace | `// PLAN:` comments |
-| Windsurf | `~/.windsurf/skills/skill-mobile-mt/` | Auto-loaded | Inline reasoning |
-| Antigravity | `~/.agents/skills/skill-mobile-mt/` | Loaded by orchestrator | Agent-native format |
+| Agent | How it loads rules | Setup | Think Block |
+|-------|-------------------|-------|-------------|
+| Claude Code | `~/.claude/skills/` (auto) | `npx skill-mobile-mt --claude` | `<think>...</think>` |
+| 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 |
+| **Cursor** | **`.cursorrules` in project root** | **`npx skill-mobile-mt --init cursor`** | Inline reasoning |
+| **Copilot** | **`.github/copilot-instructions.md`** | **`npx skill-mobile-mt --init copilot`** | `// PLAN:` comments |
+| **Windsurf** | **`.windsurfrules` in project root** | **`npx skill-mobile-mt --init windsurf`** | Inline reasoning |
+| Antigravity | `~/.agents/skills/` (auto) | `npx skill-mobile-mt --antigravity` | Agent-native format |
 
 ---
 
@@ -53,6 +53,7 @@ skill-mobile-mt/
     ├── platform-excellence.md       ← iOS 18+ vs Android 15+ UX (1,500 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)
     │
@@ -136,7 +137,7 @@ The agent reads the task, then decides which extra file to load:
 ```yaml
 skill:
   name: skill-mobile-mt
-  version: "1.0.0"
+  version: "1.2.0"
   author: buivietphi
   category: engineering
   tags:
@@ -298,10 +299,23 @@ Priority 6 (ON-DEMAND): shared/common-pitfalls.md — Known issue patterns
 - Supports both Chinese and English prompts
 - Think blocks use `【思考】` format
 
-### Cursor / Copilot / Windsurf
-- Auto-loaded when skill directory detected in workspace
-- Mode determined by presence of project files in workspace
-- Think blocks embedded as comments before code
+### Cursor
+- **Does NOT read from `~/.cursor/skills/`** — reads `.cursorrules` from project root
+- Run `npx @buivietphi/skill-mobile-mt --init cursor` in your project to generate `.cursorrules`
+- The generated file includes auto-detected framework, rules, and security patterns
+- Think blocks embedded as inline reasoning in Composer
+
+### GitHub Copilot
+- **Does NOT read from `~/.copilot/skills/`** — reads `.github/copilot-instructions.md`
+- Run `npx @buivietphi/skill-mobile-mt --init copilot` in your project to generate the file
+- The generated file includes code patterns, required templates, and rules
+- Think blocks as `// PLAN:` comments before code
+
+### Windsurf
+- **Does NOT read from `~/.windsurf/skills/`** — reads `.windsurfrules` from project root
+- Run `npx @buivietphi/skill-mobile-mt --init windsurf` in your project to generate `.windsurfrules`
+- The generated file includes coding rules, security rules, and architecture patterns
+- Think blocks as inline reasoning
 
 ### Antigravity
 - Orchestrator loads based on detected project type
@@ -339,6 +353,8 @@ Copy the relevant section to your project to enable auto-check rules in every se
 
 ## Installation Paths
 
+### Skill directory install (agents that read from skills/)
+
 ```bash
 # Claude Code (global)
 ~/.claude/skills/skill-mobile-mt/
@@ -355,15 +371,6 @@ Copy the relevant section to your project to enable auto-check rules in every se
 # Kimi
 ~/.kimi/skills/skill-mobile-mt/
 
-# Cursor
-~/.cursor/skills/skill-mobile-mt/
-
-# Windsurf
-~/.windsurf/skills/skill-mobile-mt/
-
-# Copilot
-~/.copilot/skills/skill-mobile-mt/
-
 # Antigravity (shared agent directory)
 ~/.agents/skills/skill-mobile-mt/
 
@@ -371,6 +378,28 @@ Copy the relevant section to your project to enable auto-check rules in every se
 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, NOT from a skills directory.
+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 copilot    # → .github/copilot-instructions.md
+npx @buivietphi/skill-mobile-mt --init windsurf   # → .windsurfrules
+npx @buivietphi/skill-mobile-mt --init all        # → all three 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
@@ -379,7 +408,7 @@ npx @buivietphi/skill-mobile-mt --path /your/custom/path
 {
   "id": "skill-mobile-mt",
   "name": "skill-mobile-mt",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "author": "buivietphi",
   "category": "engineering",
   "description": "Master Senior Mobile Engineer. Pre-built patterns from 18 production apps + project adaptation. Auto-detects language and framework. React Native, Flutter, iOS, Android.",

package/README.md

@@ -2,7 +2,7 @@
 
 **Master Senior Mobile Engineer** — AI skill for Claude Code, Codex, Gemini CLI, Kimi, Cursor, Copilot, Windsurf, and Antigravity.
 
-Pre-built architecture patterns from **18 production mobile apps + 4 production open-source skills** + auto-adaptation to your current project.
+Pre-built architecture patterns from **30+ production repos (200k+ GitHub stars)** including Ignite, Expensify, Mattermost, Immich, AppFlowy, Now in Android, TCA + auto-adaptation to your current project.
 
 ## Install
 
@@ -10,20 +10,38 @@ Pre-built architecture patterns from **18 production mobile apps + 4 production
 npx @buivietphi/skill-mobile-mt
 ```
 
-Interactive mode — detects which AI agents are installed and prompts you.
+Interactive checkbox UI — detects which AI agents are installed, lets you select with arrow keys + space.
 
 ### Install to specific agents
 
 ```bash
-npx @buivietphi/skill-mobile-mt --claude       # Claude Code only
-npx @buivietphi/skill-mobile-mt --codex        # Codex only
-npx @buivietphi/skill-mobile-mt --gemini       # Gemini CLI only
-npx @buivietphi/skill-mobile-mt --kimi         # Kimi only
-npx @buivietphi/skill-mobile-mt --antigravity  # Antigravity only
-npx @buivietphi/skill-mobile-mt --all          # All detected agents
+npx @buivietphi/skill-mobile-mt --claude       # Claude Code
+npx @buivietphi/skill-mobile-mt --codex        # Codex
+npx @buivietphi/skill-mobile-mt --gemini       # Gemini CLI
+npx @buivietphi/skill-mobile-mt --kimi         # Kimi
+npx @buivietphi/skill-mobile-mt --antigravity  # Antigravity
+npx @buivietphi/skill-mobile-mt --all          # All agents
 npx @buivietphi/skill-mobile-mt --path ./dir   # Custom directory
 ```
 
+### Generate project-level rules (Cursor, Copilot, Windsurf)
+
+Cursor, Copilot, and Windsurf read rules from **project-level files**, not from a skills directory. Run `--init` inside your project to generate them:
+
+```bash
+npx @buivietphi/skill-mobile-mt --init            # Interactive selector
+npx @buivietphi/skill-mobile-mt --init cursor     # .cursorrules
+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 all        # All three files
+```
+
+**What `--init` does:**
+1. Auto-detects your project (framework, language, state management, navigation, API client, package manager)
+2. Generates rules files pre-filled with your detected stack
+3. Includes mobile best practices, security rules, and quality gates
+4. Won't overwrite existing files (safe to run multiple times)
+
 ## Usage
 
 ### Mode 1: Pre-Built Architecture (default)
@@ -32,11 +50,11 @@ npx @buivietphi/skill-mobile-mt --path ./dir   # Custom directory
 @skill-mobile-mt
 ```
 
-Uses battle-tested patterns extracted from real production apps:
-- **10 React Native apps** — Redux, MobX, Apollo/GraphQL, React Navigation
-- **3 Flutter apps** — Riverpod, Clean Architecture, Dio, GoRouter
-- **4 Android Native apps** — Multi-module Gradle, Hilt, Compose, Room
-- **1 iOS Native app** — Swift, MVVM, CocoaPods, Combine
+Uses battle-tested patterns from 30+ production repos:
+- **React Native** — Ignite (19.7k stars), Obytes Template, Expensify/App, Mattermost Mobile, Artsy Eigen
+- **Flutter** — Immich (93.5k stars), AppFlowy (68.2k), Spotube (44.6k), Hiddify, Ente Photos
+- **iOS** — TCA / Point-Free (14.4k), Clean Arch SwiftUI, Modern Clean Arch
+- **Android** — Now in Android (20.7k), Android Showcase, Mihon (18.8k)
 
 ### Mode 2: Adapt to Your Project (project)
 
@@ -47,8 +65,123 @@ Uses battle-tested patterns extracted from real production apps:
 Reads your current project first, then follows **your** conventions:
 - Detects framework, language, package manager, state management, navigation
 - Matches your naming, imports, file structure, patterns
+- Clones the most similar existing feature when scaffolding new ones
 - Never suggests migrations or imposes different architecture
 
+## Quick Start Examples
+
+### Step 1: Install the skill
+
+```bash
+# Install globally (one-time setup)
+npx @buivietphi/skill-mobile-mt
+```
+
+You'll see an interactive checkbox — use arrow keys to navigate, space to select, Enter to confirm:
+
+```
+  Select agents to install:
+  ↑↓ navigate   Space toggle   A select all   Enter confirm   Q cancel
+
+  › ◉ Claude Code   [detected]
+    ◯ Cursor         [detected]
+    ◯ Windsurf       [not found]
+    ◯ Copilot        [not found]
+    ◯ Codex          [not found]
+    ◉ Gemini CLI     [detected]
+    ◯ Kimi           [not found]
+    ◯ Antigravity    [not found]
+```
+
+### Step 2 (Cursor/Copilot/Windsurf only): Generate project rules
+
+```bash
+# cd into your mobile project first
+cd ~/projects/my-app
+
+# Generate rules for your agents
+npx @buivietphi/skill-mobile-mt --init all
+```
+
+Output:
+
+```
+  📁 Project directory: /Users/you/projects/my-app
+  🔍 Detected: Expo (React Native) (TypeScript)
+
+  ✓ .cursorrules → Cursor (auto-detected: Expo (React Native))
+  ✓ .github/copilot-instructions.md → GitHub Copilot
+  ✓ .windsurfrules → Windsurf
+
+  ✅ Done! → 3 file(s) generated
+```
+
+### Step 3: Use in your AI agent
+
+#### Claude Code
+
+```bash
+# In Claude Code terminal, type:
+@skill-mobile-mt
+
+# Then ask anything:
+> Create auth feature with login and register screens
+
+# Or with project mode (reads YOUR code first):
+@skill-mobile-mt project
+> Add cart feature following the same pattern as ProductList
+```
+
+#### Cursor
+
+After running `--init cursor`, Cursor auto-loads `.cursorrules` every session. Just open your project and code — Cursor follows the rules automatically.
+
+```
+# In Cursor Composer, just ask:
+> Create a login screen with email/password
+> Fix the crash in ProductDetail when images is null
+> Review this PR for mobile best practices
+```
+
+#### GitHub Copilot
+
+After running `--init copilot`, Copilot reads `.github/copilot-instructions.md` as workspace context.
+
+```
+# In VS Code with Copilot Chat:
+> Add pagination to the product list
+> Handle offline mode for the cart feature
+```
+
+#### Windsurf
+
+After running `--init windsurf`, Windsurf auto-loads `.windsurfrules`. Just code normally.
+
+#### Gemini CLI
+
+```bash
+# In Gemini CLI:
+@skill-mobile-mt
+> Setup a new Flutter project with Riverpod + clean architecture
+```
+
+#### Codex / Kimi / Antigravity
+
+Same as Claude Code — the skill is loaded from the skills directory.
+
+### Example Prompts (all agents)
+
+| What you want | What to type |
+|--------------|-------------|
+| New feature | `Create auth feature with login, register, forgot password` |
+| New screen | `Add settings screen with profile, notifications, theme toggle` |
+| Fix bug | `Fix crash when product.images is undefined` |
+| Code review | `Review src/features/cart/ for mobile best practices` |
+| Performance | `Optimize ProductList — it's janky when scrolling 100+ items` |
+| Architecture | `Setup project structure for a new Expo app with Zustand + TanStack Query` |
+| Release | `Prepare the app for App Store submission` |
+| Security | `Audit the auth flow for security vulnerabilities` |
+
 ## Auto-Detect
 
 The skill automatically detects before any action:
@@ -102,6 +235,7 @@ iOS only?
 | `shared/code-review.md` | 865 |
 | `shared/bug-detection.md` | 499 |
 | `shared/prompt-engineering.md` | 3,927 |
+| `shared/architecture-intelligence.md` | 4,500 |
 | `shared/common-pitfalls.md` | 1,160 |
 | `shared/error-recovery.md` | 2,435 |
 | `shared/document-analysis.md` | 1,200 |
@@ -111,36 +245,51 @@ iOS only?
 | `shared/platform-excellence.md` | 1,500 |
 | `shared/version-management.md` | 3,500 |
 | `shared/observability.md` | 3,000 |
-| **Total** | **~41,700** |
+| `shared/claude-md-template.md` | ~500 |
+| `shared/agent-rules-template.md` | ~2,500 |
+| **Total** | **~46,000** |
 
 ## Installed Structure
 
 ```
 ~/.claude/skills/               (or ~/.gemini/skills/, ~/.agents/skills/, etc.)
 └── skill-mobile-mt/
-    ├── SKILL.md                    Entry point + auto-detect
-    ├── AGENTS.md                   Multi-agent compatibility
+    ├── SKILL.md                       Entry point + auto-detect + quality gates
+    ├── AGENTS.md                      Multi-agent compatibility
     ├── react-native/
-    │   └── react-native.md         React Native patterns
+    │   └── react-native.md            React Native + Expo patterns
     ├── flutter/
-    │   └── flutter.md              Flutter patterns
+    │   └── flutter.md                 Flutter + Dart patterns
     ├── ios/
-    │   └── ios-native.md           iOS Swift patterns
+    │   └── ios-native.md              iOS Swift patterns
     ├── android/
-    │   └── android-native.md       Android Kotlin patterns
+    │   └── android-native.md          Android Kotlin patterns
     └── shared/
-        ├── code-review.md          Senior review checklist
-        ├── bug-detection.md        Auto bug scanner
-        ├── prompt-engineering.md   Intelligent prompt generation
-        ├── common-pitfalls.md      Problem → Symptoms → Solution
-        ├── error-recovery.md       Fix build/runtime errors
-        ├── document-analysis.md    Parse docs/images → code
-        ├── anti-patterns.md        PII, cardinality, payload detection
-        ├── performance-prediction.md  Predict FPS/memory BEFORE shipping
-        ├── platform-excellence.md  iOS 18+ vs Android 15+ guidelines
-        ├── version-management.md   SDK compatibility matrix + release testing
-        ├── observability.md        Sessions as 4th pillar, context-rich events
-        └── release-checklist.md    Pre-release verification
+        ├── code-review.md             Senior review checklist
+        ├── bug-detection.md           Auto bug scanner
+        ├── prompt-engineering.md      Auto-think + prompt templates
+        ├── architecture-intelligence.md  Patterns from 30+ production repos
+        ├── common-pitfalls.md         Problem → Symptoms → Solution
+        ├── error-recovery.md          16 build/runtime error fixes
+        ├── document-analysis.md       Parse docs/images → code
+        ├── anti-patterns.md           PII, cardinality, payload detection
+        ├── performance-prediction.md  Frame budget, FPS prediction
+        ├── platform-excellence.md     iOS 18+ vs Android 15+ guidelines
+        ├── version-management.md      SDK compatibility matrix
+        ├── observability.md           Sessions as 4th pillar
+        ├── release-checklist.md       Pre-release verification
+        ├── claude-md-template.md      CLAUDE.md template for projects
+        └── agent-rules-template.md    Rules templates for all agents
+```
+
+### Project-level files (generated by `--init`)
+
+```
+your-project/
+├── .cursorrules                       Cursor rules (auto-detected stack)
+├── .windsurfrules                     Windsurf rules (auto-detected stack)
+└── .github/
+    └── copilot-instructions.md        Copilot rules (auto-detected stack)
 ```
 
 ## What's Included
@@ -183,6 +332,10 @@ iOS only?
 - Requirements Extraction: user stories, screen flows, data models, business rules
 - Document → Code pipeline: read → extract → map features → scaffold
 
+### Architecture Intelligence (from 30+ production repos)
+
+- **Architecture Intelligence** (`architecture-intelligence.md`): Cross-platform patterns from Ignite, Immich, AppFlowy, TCA, Now in Android and more. Includes: dual state management, feature-based modules, bootstrap/startup pattern, functional error handling, architecture validation (Konsist), production folder structure templates, and decision matrices for state/nav/testing.
+
 ### Production Patterns (from Senaiverse, Mhuxain, VoltAgent, Nexus)
 
 - **Anti-Pattern Detection** (`anti-patterns.md`): Detect PII leaks (CRITICAL), high cardinality tags, unbounded payloads, unstructured logs, sync telemetry on main thread — with auto-fix suggestions
@@ -208,16 +361,16 @@ iOS only?
 
 ## Supported Agents
 
-| Agent | Install Path | Status |
-|-------|-------------|--------|
-| Claude Code | `~/.claude/skills/skill-mobile-mt/` | Full support |
-| Codex | `~/.codex/skills/skill-mobile-mt/` | Full support |
-| Gemini CLI | `~/.gemini/skills/skill-mobile-mt/` | Full support |
-| Kimi | `~/.kimi/skills/skill-mobile-mt/` | Full support |
-| Cursor | `~/.cursor/skills/skill-mobile-mt/` | Full support |
-| Copilot | `~/.copilot/skills/skill-mobile-mt/` | Full support |
-| Windsurf | `~/.windsurf/skills/skill-mobile-mt/` | Full support |
-| Antigravity | `~/.agents/skills/skill-mobile-mt/` | Full support |
+| Agent | How it works | Setup command |
+|-------|-------------|---------------|
+| **Claude Code** | Reads from `~/.claude/skills/` | `npx skill-mobile-mt --claude` |
+| **Codex** | Reads from `~/.codex/skills/` | `npx skill-mobile-mt --codex` |
+| **Gemini CLI** | Reads from `~/.gemini/skills/` | `npx skill-mobile-mt --gemini` |
+| **Kimi** | Reads from `~/.kimi/skills/` | `npx skill-mobile-mt --kimi` |
+| **Antigravity** | Reads from `~/.agents/skills/` | `npx skill-mobile-mt --antigravity` |
+| **Cursor** | Reads `.cursorrules` from project root | `npx skill-mobile-mt --init cursor` |
+| **Copilot** | Reads `.github/copilot-instructions.md` | `npx skill-mobile-mt --init copilot` |
+| **Windsurf** | Reads `.windsurfrules` from project root | `npx skill-mobile-mt --init windsurf` |
 
 ## License
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: skill-mobile-mt
-description: "Master Senior Mobile Engineer. Use when: building mobile features, fixing mobile bugs, reviewing mobile code, mobile architecture, React Native, Flutter, iOS Swift, Android Kotlin, mobile performance, mobile security audit, mobile code review, app release. Two modes: (1) default = pre-built production patterns, (2) 'project' = reads current project and adapts."
-version: "1.0.0"
+description: "Master Senior Mobile Engineer. Patterns from 30+ production repos (200k+ GitHub stars: Ignite, Expensify, Mattermost, Immich, AppFlowy, Now in Android, TCA). Use when: building mobile features, fixing mobile bugs, reviewing mobile code, mobile architecture, React Native, Flutter, iOS Swift, Android Kotlin, mobile performance, mobile security audit, mobile code review, app release. Two modes: (1) default = pre-built production patterns, (2) 'project' = reads current project and adapts."
+version: "1.2.0"
 author: buivietphi
 priority: high
 user-invocable: true
@@ -72,7 +72,9 @@ USER REQUEST                    → ACTION (Read tool required)
 
 "Add X to existing Y"           → MODIFY existing files, don't create new structure
 
-"Setup project / architecture"  → Read platform file first (see Smart Loading below)
+"Setup project / architecture"  → Read: shared/architecture-intelligence.md
+                                  then: Read platform file (see Smart Loading below)
+                                  then: suggest structure based on project size + stack
 
 "Fix / debug X"                 → Read: shared/bug-detection.md
                                   then: read code → find root cause → fix → verify