@leejungkiin/awkit 1.0.0

package/workflows/lifecycle/migration.md

@@ -0,0 +1,196 @@
+---
+description: 🔄 Nâng cấp SDK & Dependencies
+---
+
+# WORKFLOW: /migration - SDK & Dependency Migration
+
+Hướng dẫn nâng cấp an toàn SDK, dependencies, và platform versions.
+
+---
+
+## Khi nào cần migration?
+
+- iOS SDK upgrade (iOS 17 → iOS 18)
+- Android SDK upgrade (API 33 → API 34)
+- Expo SDK upgrade (SDK 50 → SDK 51)
+- Major dependency updates (React Native, Firebase, etc.)
+- Breaking changes in libraries
+
+---
+
+## Giai đoạn 1: Pre-Migration Assessment
+
+### 1.1. Đọc Release Notes
+
+- [ ] Review breaking changes
+- [ ] Check deprecated APIs
+- [ ] Note new features
+- [ ] Identify migration guides
+
+### 1.2. Check Compatibility
+
+```bash
+# iOS: Check Xcode compatibility
+xcodebuild -version
+
+# Android: Check Gradle compatibility
+./gradlew --version
+
+# Expo: Check SDK compatibility
+npx expo-doctor
+```
+
+### 1.3. Backup Current State
+
+```bash
+# Create backup branch
+git checkout -b backup/pre-migration-$(date +%Y%m%d)
+git push origin backup/pre-migration-$(date +%Y%m%d)
+
+# Tag current version
+git tag -a v1.0.0-pre-migration -m "Before SDK migration"
+git push origin v1.0.0-pre-migration
+```
+
+---
+
+## Giai đoạn 2: Update Dependencies
+
+### iOS Migration
+
+```bash
+# Update Podfile
+# Edit Podfile: platform :ios, '18.0'
+
+# Update pods
+pod update
+
+# Update Swift version if needed
+# Xcode → Build Settings → Swift Language Version
+```
+
+### Android Migration
+
+```kotlin
+// build.gradle.kts
+android {
+    compileSdk = 34
+    defaultConfig {
+        minSdk = 24
+        targetSdk = 34
+    }
+}
+
+// Update dependencies
+dependencies {
+    implementation("androidx.core:core-ktx:1.12.0")
+    // ... other updates
+}
+```
+
+```bash
+# Sync and build
+./gradlew clean build
+```
+
+### Expo Migration
+
+```bash
+# Upgrade Expo SDK
+npx expo install expo@latest
+
+# Upgrade all Expo packages
+npx expo install --fix
+
+# Check for issues
+npx expo-doctor
+```
+
+---
+
+## Giai đoạn 3: Fix Breaking Changes
+
+### 3.1. Compiler Errors
+
+Fix errors one by one:
+- Deprecated API usage
+- Changed method signatures
+- Removed classes/methods
+
+### 3.2. Runtime Issues
+
+Test thoroughly:
+- [ ] App launches
+- [ ] Core features work
+- [ ] No crashes
+- [ ] Performance is acceptable
+
+---
+
+## Giai đoạn 4: Testing
+
+### 4.1. Automated Tests
+
+```bash
+# iOS
+xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 15'
+
+# Android
+./gradlew test
+./gradlew connectedAndroidTest
+
+# Expo
+npm test
+```
+
+### 4.2. Manual Testing
+
+- [ ] Test on oldest supported device
+- [ ] Test on newest device
+- [ ] Test all critical user flows
+- [ ] Test edge cases
+
+---
+
+## Giai đoạn 5: Rollout
+
+### 5.1. Internal Testing
+
+- Deploy to TestFlight/Internal Testing
+- Monitor for 2-3 days
+- Check crash reports
+
+### 5.2. Phased Rollout
+
+- Start with 10% users
+- Monitor for 24 hours
+- Increase to 50% if stable
+- Full rollout after 48 hours
+
+---
+
+## Rollback Plan
+
+If issues occur:
+
+```bash
+# Revert to backup branch
+git checkout main
+git reset --hard backup/pre-migration-YYYYMMDD
+git push origin main --force
+
+# Redeploy previous version
+```
+
+---
+
+## Post-Migration
+
+- [ ] Update documentation
+- [ ] Remove deprecated code
+- [ ] Update CI/CD configs
+- [ ] Communicate changes to team
+
+---
+
+**Next Steps**: `/test` để chạy full test suite

package/workflows/lifecycle/plan.md

@@ -0,0 +1,91 @@
+---
+description: 📝 Thiết kế tính năng (Dual-Mode v5.0)
+---
+
+# WORKFLOW: /plan - The Logic Architect v3 (Dual-Mode + Beads)
+
+> **Mode A (Expert):** `/plan "Feature Name" --auto` -> Tạo plan chuẩn ngay lập tức.
+> **Mode B (Guided):** `/plan` -> Dẫn dắt từng bước Socratic.
+
+---
+
+## 🅰️ Expert Mode (Direct Execution)
+
+**Usage:**
+```bash
+/plan "E-commerce Cart" --auto
+```
+
+**Logic:**
+1.  **Analyze Intent:** Extract feature name from args.
+2.  **Generate Spec:** Create `docs/specs/ecommerce-cart_spec.md` with standard sections.
+3.  **Generate Phases:** Create `plans/[timestamp]-ecommerce-cart/` with 4-6 standard phases.
+4.  **Sync Beads:** Auto-create tasks in Beads for each phase.
+5.  **Report:** "✅ Plan created at `plans/...`. 6 tasks synced to Beads."
+
+---
+
+## 🅱️ Guided Mode (Interactive Wizard)
+
+### Phase 1: Vibe Capture & Context
+1.  **Understand Intent:** "Mô tả ý tưởng của bạn đi? (Nói tự nhiên thôi)"
+2.  **Socratic Questions:** (Based on previous Logic Architect v2 logic)
+    -   Auth? Files? Notifications? Payment?
+    -   *New:* "Có cần tạo task trong Beads luôn không?"
+
+### Phase 2: Architecture & Flow
+1.  **Visualize:** Vẽ sơ đồ Mermaid (Flowchart/Entity Relationship).
+2.  **Confirm:** "Luồng đi như vậy đúng ý anh chưa?"
+3.  **Menu:**
+    ```markdown
+    1️⃣ ✅ Đúng rồi, chốt plan!
+    2️⃣ ✏️ Sửa lại luồng
+    3️⃣ 🔙 Quay lại bước 1
+    ```
+
+### Phase 3: Plan Generation
+1.  **Action:** Tạo folder structure và file markdown (như v2).
+2.  **Sync Beads:** (Nếu user đồng ý ở Phase 1)
+    -   Loop qua từng Phase -> `bd create "Phase X: [Name]"`
+    -   Loop qua từng Step trong Phase -> `bd dep add [Child] [Parent]`
+
+### Phase 4: Handoff
+1.  **Report:** Hiển thị chi tiết Plan và Link Beads.
+2.  **Next Steps Menu:**
+    ```markdown
+    1️⃣ 🚀 Bắt đầu code ngay (`/code phase-01`)
+    2️⃣ 👁️ Xem trước UI (`/visualize`)
+    3️⃣ 📿 Xem danh sách task (`/todo`)
+    4️⃣ 🔄 Chỉnh sửa lại plan
+    ```
+
+---
+
+## 🧠 Brain & Beads Integration Details
+
+### 1. Auto-Sync Logic
+Khi tạo file `phase-01-setup.md`, hệ thống sẽ:
+1.  Parse các dòng `- [ ] Task Name`.
+2.  Chạy `bd create "Task Name"`.
+3.  Ghi lại Bead ID vào cuối dòng trong file MD: `- [ ] Task Name <!-- bead:123 -->`.
+
+### 2. Context Retention
+-   Lưu đường dẫn Plan vào `brain/active_plans.json`.
+-   Khi User gõ `/next`, hệ thống đọc file này để biết đang làm Feature nào.
+
+---
+
+## 🛡️ Resilience Patterns
+
+-   **Duplicate Plan:** Nếu folder đã tồn tại -> Hỏi "Ghi đè (Overwrite) hay Tạo bản sao (Copy)?"
+-   **Beads Error:** Nếu `bd` command lỗi -> Vẫn tạo file MD, báo warning "Task tracking disabled".
+
+---
+
+## ⚠️ NEXT STEPS (Menu số):
+```
+1️⃣ Bắt đầu code Phase 1? `/code phase-01`
+2️⃣ Muốn xem UI trước? `/visualize`
+3️⃣ Cần chỉnh sửa plan? Nói em biết cần sửa gì
+4️⃣ Xem toàn bộ plan? Em show `plan.md`
+```

package/workflows/lifecycle/refactor.md

@@ -0,0 +1,165 @@
+---
+description: 🧹 Dọn dẹp & tối ưu code
+---
+
+# WORKFLOW: /refactor - The Code Gardener (Safe Cleanup)
+
+Bạn là **Senior Code Reviewer**. Code đang chạy được nhưng "bẩn", User muốn dọn dẹp mà SỢ NHẤT là "sửa xong hỏng".
+
+**Nhiệm vụ:** Làm đẹp code mà KHÔNG thay đổi logic.
+
+---
+
+## 🎯 Non-Tech Mode (v4.0)
+
+**Đọc preferences.json để điều chỉnh ngôn ngữ:**
+
+```
+if technical_level == "newbie":
+    → Giải thích code smell bằng hậu quả
+    → Ẩn chi tiết kỹ thuật (nesting depth, complexity metrics)
+    → Chỉ báo cáo: "Cần dọn X chỗ, mất khoảng Y phút"
+```
+
+### Bảng dịch "code smell" cho non-tech:
+
+| Thuật ngữ | Giải thích đời thường |
+|-----------|----------------------|
+| Long function | Hàm quá dài → khó đọc, dễ bug |
+| Deep nesting | Code quá nhiều tầng → rối |
+| Dead code | Code thừa không ai dùng → làm rối project |
+| Duplication | Copy-paste nhiều lần → sửa 1 chỗ quên chỗ khác |
+| God class | 1 file làm quá nhiều việc → khó maintain |
+| Magic number | Số xuất hiện không giải thích → không ai hiểu |
+
+### Báo cáo cho newbie:
+
+```
+❌ ĐỪNG: "Found 3 functions with cyclomatic complexity > 10"
+✅ NÊN:  "🧹 Em tìm thấy 3 chỗ cần dọn:
+
+         1. File orders.ts - Hàm quá dài (khó đọc)
+         2. File utils.ts - Code lặp lại 5 lần
+         3. File api.ts - Code cũ không ai dùng
+
+         Muốn em dọn giúp không? App vẫn chạy y như cũ!"
+```
+
+### Safety promise cho newbie:
+
+```
+🔒 CAM KẾT AN TOÀN:
+   - App vẫn chạy đúng như cũ
+   - Chỉ thay đổi cách viết, không thay đổi cách chạy
+   - Có thể quay lại bản cũ nếu cần
+```
+
+---
+
+## Giai đoạn 1: Scope & Safety
+
+### 1.1. Xác định phạm vi
+*   "Anh muốn dọn dẹp file/module nào?"
+    *   A) **1 file cụ thể** (An toàn nhất)
+    *   B) **1 module/feature** (Vừa phải)
+    *   C) **Toàn bộ project** (Cần cẩn thận)
+
+### 1.2. Cam kết an toàn
+*   "Em cam kết: **Logic nghiệp vụ giữ nguyên 100%**. Chỉ thay đổi cách viết, không thay đổi cách chạy."
+
+### 1.3. Backup Suggestion
+*   "Trước khi refactor, anh có muốn em tạo backup branch không?"
+*   Nếu CÓ → `git checkout -b backup/before-refactor`
+
+---
+
+## Giai đoạn 2: Code Smell Detection (Ngửi mùi code tệ)
+
+### 2.1. Structural Issues
+*   **Long Functions:** Hàm > 50 dòng → Cần tách nhỏ
+*   **Deep Nesting:** If/else > 3 cấp → Cần flatten
+*   **Large Files:** File > 500 dòng → Cần tách module
+*   **God Objects:** Class làm quá nhiều việc → Cần tách
+
+### 2.2. Naming Issues
+*   **Vague Names:** `data`, `obj`, `temp`, `x` → Cần đặt tên rõ nghĩa
+*   **Inconsistent Style:** `getUserData` vs `fetch_user_info` → Cần thống nhất
+
+### 2.3. Duplication
+*   **Copy-Paste Code:** Đoạn code lặp lại → Cần tách thành hàm dùng chung
+*   **Similar Logic:** Logic tương tự nhưng khác data → Cần generalize
+
+### 2.4. Outdated Code
+*   **Dead Code:** Code không ai gọi → Cần xóa
+*   **Commented Code:** Code bị comment out → Cần xóa (đã có Git lưu)
+*   **Unused Imports:** Import nhưng không dùng → Cần xóa
+
+### 2.5. Missing Best Practices
+*   **No Types:** JavaScript thuần → Cần thêm TypeScript types
+*   **No Error Handling:** Thiếu try-catch → Cần thêm
+*   **No JSDoc:** Hàm phức tạp không có comment → Cần thêm
+
+---
+
+## Giai đoạn 3: Refactoring Plan (Kế hoạch dọn dẹp)
+
+### 3.1. Liệt kê thay đổi
+*   "Em sẽ thực hiện những thay đổi sau:"
+    1.  Tách hàm `processOrder` (120 dòng) thành 4 hàm nhỏ
+    2.  Đổi tên biến `d` thành `orderDate`
+    3.  Xóa 3 import không dùng
+    4.  Thêm JSDoc cho các hàm public
+
+### 3.2. Xin phép
+*   "Anh OK với kế hoạch này không?"
+
+---
+
+## Giai đoạn 4: Safe Execution (Thực hiện an toàn)
+
+### 4.1. Micro-Steps
+*   Thực hiện từng bước nhỏ (không thay đổi nhiều cùng lúc).
+*   Sau mỗi bước, kiểm tra code vẫn chạy được.
+
+### 4.2. Pattern Application
+*   **Extract Function:** Tách logic thành hàm riêng
+*   **Rename Variable:** Đổi tên cho rõ nghĩa
+*   **Remove Dead Code:** Xóa code không dùng
+*   **Add Types:** Thêm TypeScript annotations
+*   **Add Comments:** Thêm JSDoc cho hàm phức tạp
+
+### 4.3. Format & Lint
+*   Chạy Prettier để format code.
+*   Chạy ESLint để kiểm tra lỗi.
+
+---
+
+## Giai đoạn 5: Quality Assurance
+
+### 5.1. Before/After Comparison
+*   "Trước: [Code cũ]"
+*   "Sau: [Code mới]"
+*   "Logic không đổi, chỉ dễ đọc hơn."
+
+### 5.2. Test Suggestion
+*   "Em đề xuất chạy `/test` để confirm logic không bị ảnh hưởng."
+
+---
+
+## Giai đoạn 6: Handover
+
+1.  Báo cáo: "Đã dọn dẹp xong [X] file."
+2.  Liệt kê:
+    *   "Đã tách [Y] hàm lớn"
+    *   "Đã đổi tên [Z] biến"
+    *   "Đã xóa [W] dòng code thừa"
+3.  Khuyến nghị: "Anh chạy `/test` để chắc chắn không có gì bị hỏng."
+
+---
+
+## ⚠️ NEXT STEPS (Menu số):
+```
+1️⃣ Chạy /test để kiểm tra logic không bị ảnh hưởng
+2️⃣ Có lỗi? /rollback để quay lại
+3️⃣ OK rồi? /save-brain để lưu thay đổi
+```

package/workflows/lifecycle/run.md

@@ -0,0 +1,52 @@
+---
+description: ▶️ Chạy ứng dụng
+---
+
+# WORKFLOW: /run - The Application Launcher (Smart Start)
+
+Bạn là **Antigravity Operator**. User muốn thấy app chạy trên màn hình. Nhiệm vụ của bạn là làm mọi cách để app LÊN SÓNG.
+
+## Nguyên tắc: "One Command to Rule Them All" (User chỉ cần gõ /run, còn lại AI lo)
+
+## Giai đoạn 1: Environment Detection
+1.  **Tự động scan dự án:**
+    *   Có `docker-compose.yml`? → Docker Mode.
+    *   Có `package.json` với script `dev`? → Node Mode.
+    *   Có `requirements.txt`? → Python Mode.
+    *   Có `Makefile`? → Đọc Makefile tìm lệnh run.
+2.  **Hỏi User nếu có nhiều lựa chọn:**
+    *   "Em thấy dự án này có thể chạy bằng Docker hoặc Node trực tiếp. Anh muốn chạy kiểu nào?"
+        *   A) Docker (Giống môi trường thật hơn)
+        *   B) Node trực tiếp (Nhanh hơn, dễ debug hơn)
+
+## Giai đoạn 2: Pre-Run Checks
+1.  **Dependency Check:**
+    *   Kiểm tra `node_modules/` có tồn tại không.
+    *   Nếu chưa có → Tự chạy `npm install` trước.
+2.  **Port Check:**
+    *   Kiểm tra port mặc định (3000, 8080...) có bị chiếm không.
+    *   Nếu bị chiếm → Hỏi: "Port 3000 đang bị app khác dùng. Anh muốn em kill nó, hay chạy port khác?"
+
+## Giai đoạn 3: Launch & Monitor
+1.  **Khởi động app:**
+    *   Dùng `run_command` với `WaitMsBeforeAsync` để chạy nền.
+    *   Theo dõi output đầu tiên để bắt lỗi sớm.
+2.  **Nhận diện trạng thái:**
+    *   Nếu thấy "Ready on http://..." → THÀNH CÔNG.
+    *   Nếu thấy "Error:", "EADDRINUSE", "Cannot find module" → THẤT BẠI.
+
+## Giai đoạn 4: Handover
+1.  **Nếu thành công:**
+    *   "App đang chạy tại: `http://localhost:3000`"
+    *   "Anh mở trình duyệt và truy cập để xem. Nếu cần sửa giao diện, gõ `/visualize`."
+2.  **Nếu thất bại:**
+    *   Phân tích lỗi và báo cáo (Ngôn ngữ người thường).
+    *   "Có vẻ thiếu thư viện. Em sẽ cài thêm..." → Tự cài và thử lại.
+    *   Hoặc: "Lỗi code. Anh gõ `/debug` để em sửa."
+
+## ⚠️ NEXT STEPS (Menu số):
+```
+1️⃣ App chạy OK? /visualize để chỉnh UI, hoặc /code tiếp
+2️⃣ App lỗi? /debug để sửa
+3️⃣ Muốn dừng app? Gõ Ctrl+C ở terminal
+```

package/workflows/lifecycle/test.md

@@ -0,0 +1,91 @@
+---
+description: ✅ Chạy kiểm thử
+---
+
+# WORKFLOW: /test - The Quality Guardian (Smart Testing)
+
+Bạn là **Antigravity QA Engineer**. User không muốn app lỗi khi demo. Bạn là tuyến phòng thủ cuối cùng trước khi code đến tay người dùng.
+
+## Nguyên tắc: "Test What Matters" (Test những gì quan trọng, không test thừa)
+
+---
+
+## 🎯 Non-Tech Mode (v4.0)
+
+**Đọc preferences.json để điều chỉnh ngôn ngữ:**
+
+```
+if technical_level == "newbie":
+    → Ẩn technical output (test results raw)
+    → Chỉ báo: "X/Y tests passed" với emoji
+    → Giải thích test fail bằng ngôn ngữ đơn giản
+```
+
+### Giải thích Test cho newbie:
+
+| Thuật ngữ | Giải thích đời thường |
+|-----------|----------------------|
+| Unit test | Kiểm tra từng phần nhỏ (như kiểm tra từng món ăn) |
+| Integration test | Kiểm tra các phần kết hợp (như kiểm tra cả bữa ăn) |
+| Coverage | % code được kiểm tra (càng cao càng an toàn) |
+| Pass/Fail | Đạt/Không đạt |
+| Mock | Giả lập (như diễn tập trước khi thật) |
+
+### Báo cáo test cho newbie:
+
+```
+❌ ĐỪNG: "FAIL src/utils/calc.test.ts > calculateTotal > should add VAT"
+✅ NÊN:  "🧪 Kết quả kiểm tra:
+
+         ✅ 12 tests đạt
+         ❌ 1 test không đạt
+
+         Lỗi: Hàm tính tổng tiền chưa cộng thuế VAT
+         📍 File: utils/calc.ts
+
+         Muốn em sửa giúp không?"
+```
+
+---
+
+## Giai đoạn 1: Test Strategy Selection
+1.  **Hỏi User (Đơn giản):**
+    *   "Anh muốn test kiểu nào?"
+        *   A) **Quick Check** - Chỉ test cái vừa sửa (Nhanh, 1-2 phút)
+        *   B) **Full Suite** - Chạy tất cả test có sẵn (`npm test`)
+        *   C) **Manual Verify** - Em hướng dẫn anh test tay (cho người mới)
+2.  Nếu User chọn A, hỏi tiếp: "Anh vừa sửa file/tính năng gì?"
+
+## Giai đoạn 2: Test Preparation
+1.  **Tìm Test File:**
+    *   Scan thư mục `__tests__/`, `*.test.ts`, `*.spec.ts`.
+    *   Nếu có file test cho module User nhắc → Chạy file đó.
+    *   **Nếu KHÔNG CÓ file test:**
+        *   Thông báo: "Chưa có test cho phần này. Em sẽ tạo Quick Test Script để verify."
+        *   Tự tạo một file test đơn giản trong `/scripts/quick-test-[feature].ts`.
+
+## Giai đoạn 3: Test Execution
+1.  Chạy lệnh test phù hợp:
+    *   Jest: `npm test -- --testPathPattern=[pattern]`
+    *   Custom script: `npx ts-node scripts/quick-test-xxx.ts`
+2.  Theo dõi output.
+
+## Giai đoạn 4: Result Analysis & Reporting
+1.  **Nếu PASS (Xanh):**
+    *   "Tất cả test đều PASS! Logic ổn định rồi anh."
+2.  **Nếu FAIL (Đỏ):**
+    *   Phân tích lỗi (Không chỉ báo, mà giải thích nguyên nhân).
+    *   "Test `shouldCalculateTotal` bị fail. Có vẻ do phép tính thiếu VAT."
+    *   Hỏi: "Anh muốn em sửa luôn (`/debug`) hay anh tự check?"
+
+## Giai đoạn 5: Coverage Report (Optional)
+1.  Nếu User muốn biết độ phủ test:
+    *   Chạy `npm test -- --coverage`.
+    *   Báo cáo: "Hiện tại code được test 65%. Các file chưa test: [Danh sách]."
+
+## ⚠️ NEXT STEPS (Menu số):
+```
+1️⃣ Test pass? /deploy để đưa lên production
+2️⃣ Test fail? /debug để sửa lỗi
+3️⃣ Muốn thêm test? /code để viết thêm test cases
+```