@leejungkiin/awkit 1.3.4 → 1.3.8

package/skills/symphony-enforcer/SKILL.md

@@ -4,13 +4,13 @@ description: |
   Mandatory Symphony checkpoint system. Ensures AI never forgets to create,
   update, or complete tasks in Symphony. Enforces progress reporting at every
   milestone and auto-detects task completion without waiting for user confirmation.
-  v3.4: Kiro Spec Integration, Completion Status Protocol, Search-Before-Building, Boil-the-Lake.
+  v3.5: UI-First Three-Phase Execution with User Test Checkpoints.
 metadata:
   stage: core
-  version: "3.4"
-  replaces: "v3.3"
+  version: "3.5"
+  replaces: "v3.4"
   requires: symphony-orchestrator
-  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next, kiro]
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next, kiro, ui-first, user-test]
 agent: Symphony Enforcer
 allowed-tools:
   - symphony_create_task
@@ -24,17 +24,14 @@ invocation-type: auto
 priority: 1
 ---
 
-# Symphony Enforcer v3.4 — Kiro Spec Integration + Completion Status Protocol
+# Symphony Enforcer v3.5 — UI-First Three-Phase Execution + User Test Checkpoints
 
 > **Purpose:** Đảm bảo AI KHÔNG BAO GIỜ quên cập nhật Symphony.
-> **Key Changes v3.4:**
-> - **Kiro Spec Integration**: Auto-detect `.kiro/specs/` → load specs + import tasks
-> - **Completion Status Protocol**: 4-status (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT)
-> - **Design Compliance (TP1.5)**: Đối chiếu schema changes vs approved design doc
-> - **Pre-Plan Gate**: Đọc spec trước khi plan, hỏi user về constraints
-> - **Auto-Lifecycle**: Liên kết task_boundary ↔ Symphony tự động
-> - **Auto-Next**: BẮT BUỘC gợi ý next steps sau mỗi task done
-> - **Atomic Git Commits**: Tự động commit sau mỗi task done
+> **Key Changes v3.5:**
+> - **Gate 4 Three-Phase Execution**: Phase A (Infra) → Phase B (UI Shell + User Test) → Phase C (Logic + User Test)
+> - **TP1.7: User Test Checkpoint**: Trigger dừng lại cho user test trên device thật
+> - **UI-First Task Ordering**: UI tasks PHẢI đi trước logic tasks trong Symphony
+> - Kế thừa tất cả features v3.4 (Kiro, Completion Status, Design Compliance).
 > **Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
 
 ---
@@ -137,7 +134,7 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 
 ---
 
-## Auto-Lifecycle: task_boundary ↔ Symphony (NEW v3.0)
+## Auto-Lifecycle: task_boundary ↔ Symphony (v3.5)
 
 ```
 LIÊN KẾT TỰ ĐỘNG:
@@ -145,6 +142,12 @@ LIÊN KẾT TỰ ĐỘNG:
 - task_boundary(EXECUTION) → symphony_report_progress(40%)
 - task_boundary(VERIFICATION) → symphony_report_progress(80%)
 - notify_user(BlockedOnUser=false) → TRIGGER TP2 (completion check)
+
+THREE-PHASE MAPPING (Gate 4 — COMPLEX tasks với UI):
+- Phase A done (build OK)     → report_progress(25%) + checkpoint build
+- Phase B done (UI mock)      → report_progress(45%) + TRIGGER TP1.7 (User Test)
+- Phase C per-feature done    → report_progress(50-85%) + TRIGGER TP1.7 (User Test)
+- Phase C all features done   → report_progress(90%) → Gate 5
 ```
 
 AI PHẢI giữ `current_task_id` xuyên suốt session.
@@ -152,6 +155,113 @@ Mỗi lần gọi `task_boundary` với mode mới → đồng thời report pro
 
 ---
 
+## 🚨 Three-Phase Auto-Enforcement Protocol (BẮT BUỘC — v3.5)
+
+> **Vấn đề:** AI không tự chủ động dùng Three-Phase nếu không bị ép.
+> **Giải pháp:** Auto-detect + auto-announce + auto-enforce.
+
+### Phase State Tracking
+
+AI PHẢI duy trì trạng thái phase hiện tại xuyên suốt Gate 4:
+
+```
+current_phase = "A" | "B" | "C" | "none"
+phase_b_confirmed = false | true
+checkpoint_count = 0
+```
+
+### Auto-Detection: Khi nào kích hoạt Three-Phase?
+
+Tại đầu Gate 4 (EXECUTION bắt đầu), AI PHẢI tự kiểm tra:
+
+```
+1. Task được triage là COMPLEX?
+2. Task có UI component? (detect qua):
+   → Symphony task title chứa: screen, view, UI, layout, dashboard, form
+   → Implementation plan mentions: Composable, Fragment, Activity, Screen, View
+   → Design doc tồn tại (docs/design/ hoặc docs/architecture/ có UI sections)
+   → Spec references: wireframe, mockup, screenshot
+   → Platform: Android/iOS/React Native/Flutter (hầu hết có UI)
+
+Nếu CẢ HAI điều kiện thỏa:
+   → BẮT BUỘC kích hoạt Three-Phase
+   → Hiển thị Phase Announcement Block
+```
+
+### Phase Announcement Block (BẮT BUỘC)
+
+Khi kích hoạt Three-Phase, AI PHẢI hiển thị:
+
+```
+🎯 THREE-PHASE EXECUTION ACTIVATED
+══════════════════════════════════════
+🏗️ Phase A: Infrastructure Setup
+   → {list tasks for Phase A}
+🎨 Phase B: UI Shell (Mock Data)
+   → {list tasks for Phase B}
+   → 🧪 USER TEST sau phase này
+⚡ Phase C: Logic Integration
+   → {list tasks for Phase C}
+   → 🧪 USER TEST mỗi feature
+══════════════════════════════════════
+Bắt đầu Phase A...
+```
+
+### Phase Transition Triggers (TỰ ĐỘNG)
+
+AI PHẢI tự động phát hiện khi chuyển phase:
+
+```yaml
+auto_triggers:
+  phase_a_to_b:
+    signal: Tất cả [INFRA] tasks đã done + build OK
+    action: |
+      - Announce: "🏗️ Phase A ✅ — Build thành công. Chuyển sang Phase B (UI Shell)."
+      - Set current_phase = "B"
+      - Bắt đầu code UI tasks
+
+  phase_b_to_checkpoint:
+    signal: Tất cả [UI] tasks đã done
+    action: |
+      - ⛔ DẪNG CODE NGAY LẬP TỨC
+      - TRIGGER TP1.7 (User Test Checkpoint)
+      - CHỊ user confirm "✅ OK" trước khi làm bất cứ gì khác
+      - KHÔNG được tự ý skip bước này
+
+  checkpoint_to_phase_c:
+    signal: User confirmed "✅" hoặc "OK"
+    action: |
+      - Set phase_b_confirmed = true
+      - Set current_phase = "C"
+      - Announce: "🎨 Phase B ✅ — UI đã được duyệt. Chuyển sang Phase C (Logic)."
+      - Bắt đầu code [LOGIC] tasks
+
+  phase_c_per_feature:
+    signal: 1 feature [LOGIC] đã done + có UI impact
+    action: |
+      - TRIGGER TP1.7 (mini checkpoint)
+      - Batch các features nhỏ lại nếu có thể
+```
+
+### Enforcement Rules
+
+```
+❌ VI PHạM NẶNG:
+  - Code logic (Phase C) khi phase_b_confirmed = false
+  - Skip Phase Announcement Block
+  - Code UI và Logic lẫn lộn trong cùng 1 lượt (phải tách rõ phase)
+  - Tự giả vờ user confirm để skip checkpoint
+  - Không hiển thị Phase Announcement khi Three-Phase activated
+
+✅ BẮT BUỘC:
+  - Luôn announce phase transition rõ ràng
+  - Luôn tạo hướng dẫn test CỤ THỂ (không chung chung)
+  - Luôn dùng notify_user(BlockedOnUser=true) cho checkpoints
+  - Ghi lại phase state vào NeuralMemory khi chuyển phase
+```
+
+---
+
 ## Trigger Points
 
 ### TP1: Progress Milestone
@@ -171,13 +281,16 @@ symphony_report_progress(
 )
 ```
 
-**Progress Guide:**
+**Progress Guide (Three-Phase Model):**
 ```
   10% — Task created, đang research/đọc code
-  25% — Implementation plan approved
-  40% — Bắt đầu code changes
-  60% — Code changes xong, đang test
-  80% — Tests pass, đang verification
+  20% — Implementation plan approved
+  25% — Phase A done (build OK, dependencies ready)
+  30% — Phase B bắt đầu (UI shell coding)
+  45% — Phase B done → USER TEST CHECKPOINT #1 (UI review)
+  50% — Phase C bắt đầu (logic integration)
+  50-85% — Phase C per-feature (each feature = +5-10%)
+  85% — Phase C done, đang final verification
   90% — Walkthrough/docs tạo xong
  100% — Hoàn thành (auto-trigger TP2)
 ```
@@ -229,6 +342,80 @@ File patterns:
 
 ---
 
+### TP1.7: User Test Checkpoint (NEW v3.5 — Gate 4 Three-Phase)
+
+**Khi nào:** Trigger ở 2 thời điểm chính trong Gate 4:
+
+1. **Phase B → C Transition (BẮT BUỘC cho COMPLEX):**
+   - ALL UI screens đã code xong với mock data
+   - Navigation hoạt động full flow
+   - App build và chạy OK trên emulator/device
+
+2. **Sau mỗi feature trong Phase C (COMPLEX tasks):**
+   - Feature X đã thay mock bằng real data
+   - Feature works end-to-end trên device
+
+**Điều kiện kích hoạt:**
+```
+COMPLEX + có UI component → BẮT BUỘC TP1.7
+MODERATE + có UI component → OPTIONAL (recommend cho hardware features: camera, GPS, sensors)
+TRIVIAL → SKIP
+Backend-only tasks → SKIP
+```
+
+**Action:**
+```
+1. Report progress trước: symphony_report_progress(current_task, progress)
+
+2. Present User Test Checkpoint:
+
+   🧪 USER TEST CHECKPOINT #{N}
+   ══════════════════════════════════════
+   📱 Phase: {B|C} — {phase_name}
+   📋 Đã code xong: {summary of completed work}
+   📁 Files changed: {N} files
+   
+   🔍 Hướng dẫn test:
+     1. {step 1 — cụ thể, actionable}
+     2. {step 2 — expected behavior}
+     3. {step 3 — edge case to check}
+   
+   ⏳ Anh test xong reply:
+     ✅ OK — tiếp tục
+     ⚠️ Issue: {mô tả} — tôi sẽ fix trước khi đi tiếp
+   ══════════════════════════════════════
+
+3. Gọi notify_user(BlockedOnUser=true) — DỪNG và CHỜ user response
+
+4. User response handling:
+   → "OK" / "✅" → Tiếp tục phase tiếp / feature tiếp
+   → "Issue: ..." → Fix issue → re-run checkpoint
+   → "Skip" → Ghi note concern, tiếp tục (DONE_WITH_CONCERNS later)
+```
+
+**Test Guidance Generation:**
+```
+AI PHẢI tạo hướng dẫn test CỤ THỂ cho từng checkpoint:
+
+Phase B Examples (UI):
+  - "Mở app → bấm tab Health → xem Dashboard có hiển thị 4 cards không?"
+  - "Quay ngang màn hình → layout có bể không?"
+  - "Bấm nút Camera → xem preview có xuất hiện không?"
+
+Phase C Examples (Logic):
+  - "Mở Health Dashboard → data thật có load lên không? (nếu có wifi)"
+  - "Chụp ảnh thức ăn → kết quả AI có trả về trong 5s không?"
+  - "Bấm Save → quay lại list → record mới có xuất hiện không?"
+```
+
+**Enforcement:**
+- ❌ KHÔNG được chuyển từ Phase B → Phase C mà chưa có user confirm (COMPLEX)
+- ❌ KHÔNG được skip checkpoint cho hardware-related features (Camera, GPS, Sensors)
+- ✅ NÊN batch các features nhỏ lại thành 1 checkpoint (tránh quá nhiều interrupt)
+- ✅ Checkpoint cho logic KHÔNG cần nếu feature là pure-backend/invisible
+
+---
+
 ### TP2: Task Complete — Completion Status Protocol
 
 **Khi nào:** AI detect ≥2/4 completion signals:
@@ -470,3 +657,5 @@ Nếu completed:
 - Spec alignment tránh plan bị lệch khỏi project constraints
 - Atomic commits giúp rollback chính xác — 1 task = 1 commit (learned from GSD)
 - KHÔNG auto-push — chỉ commit local, push cần user confirm
+- Three-Phase WORKS vì AI CHỦ ĐỘNG announce — không chờ user gọi (learned from FitWitness v12.3)
+- User test sớm bắt lỗi sớm — code logic trên UI sai = double wasted (learned from FitWitness v12.3)

package/skills/trello-sync/SKILL.md

@@ -30,29 +30,29 @@ priority: 2
 KHÔNG CÓ NGOẠI LỆ:
 - 1 Dự án = 1 Trello Card (KHÔNG tạo card mới cho mỗi task).
 - **Mô tả Card (Description)** BẮT BUỘC phải được update chứa cái nhìn tổng thể về dự án (Mục tiêu, Tech Stack, Tình trạng chung) để Quản lý dễ nắm bắt.
-- Tiến độ = Checklist Items trên card dự án. CHỈ ghi lại các task ở mức High-level / Module / Tính năng lớn.
-- ⛔ KHÔNG BAO GIỜ đồng bộ từng sub-task chi tiết (từ file `.kiro/specs/tasks.md` hay Symphony) thành checklist item trên Trello, làm vậy sẽ gây rác board (spam).
+- **Trello (PM View) vs Kiro (Dev View):** Trello là màn hình dành cho Quản lý (PM, QC), còn `.kiro/specs/tasks.md` là nơi để AI/Dev làm việc. Hai khái niệm này hoàn toàn khác nhau.
+- [QUAN TRỌNG] Checklist Items trên Trello = ĐẦU VIỆC NGHIỆP VỤ (Business Features). VD: "Màn hình Đăng Nhập", "Chức năng AI Chat", "Tích hợp Thanh Toán".
+- ⛔ TUYỆT ĐỐI CẤM đưa các GIAI ĐOẠN QUY TRÌNH (Process Gates) vào Checklist Items. KHÔNG CÓ CÁC MỤC NHƯ: "Tài liệu", "Thiết kế Giao diện", "Gate 1", "Phase 2", "App Scaffolding".
+- PM KHÔNG QUAN TÂM ĐẾN QUY TRÌNH GATE CỦA AI. Progress qua các Gate (Gate 1, Gate 2...) CHỈ ĐƯỢC BÁO CÁO qua Comment.
+- KHÔNG BAO GIỜ bứng nguyên các task kỹ thuật chi tiết (VD: "Tạo file `BloodPressureViewModel.kt`") lên Trello. CẤM ĐỒNG BỘ (bulk-sync) raw `tasks.md` sang Trello.
+- BẮT BUỘC ĐỒNG BỘ TOÀN BỘ DANH SÁCH NGHIỆP VỤ TỔNG HỢP (Features): Chờ đến khi Đặc tả kỹ thuật (Specs) đã có rõ các tính năng, AI mới parse ra các Features thành các Checklist Items để Quản lý (PM) có thể thấy trọn vẹn scope.
 - Card KHÔNG di chuyển giữa lists (list = team member, cố định).
-- Comment ở milestone quan trọng PHẢI bao gồm các quyết định kỹ thuật cốt lõi hoặc nguyên nhân gốc rễ, không chỉ ghi "Done" chung chung.
-- Comment chỉ ở milestone quan trọng, KHÔNG spam.
-- KHÔNG ĐƯỢC sinh script file python/bash (VD: `trello_sync_kiro.py`) để đồng bộ hàng loạt (bulk sync) từ file markdown lên Trello.
+- Comment ở milestone quan trọng PHẢI bao gồm các quyết định cốt lõi hoặc sự thay đổi phase (VD: "Đã hoàn thành Gate 2 Design", "Bắt đầu code Logic").
 ```
 
 ---
 
 ## 🔐 Auth & Config
 
-Bảo mật: API Key và Token được lưu tại Global, cấu hình dự án (Board/List/Card) lưu tại Local.
+Credentials được lưu dưới dạng **environment variables** (`TRELLO_KEY`, `TRELLO_TOKEN`) trong shell profile (`~/.zshrc` hoặc `~/.bashrc`). Cấu hình dự án (Board/List/Card) lưu tại `.trello-config.json` ở root mỗi dự án.
 
-### 1. Global Credentials (đặt tại `~/.gemini/antigravity/credentials/trello.json`)
-```json
-{
-  "api_key": "YOUR_TRELLO_API_KEY",
-  "api_token": "YOUR_TRELLO_API_TOKEN"
-}
-```
+### 1. Global Credentials (Environment Variables)
 
-### 2. Local Project Config (đặt file `.trello-config.json` tại root mỗi dự án)
+User setup lần đầu qua **interactive wizard** khi chạy `awkit init`:
+- CLI tự hỏi API Key → tạo link authorize token → hỏi Token → lưu vào `~/.zshrc`.
+- Nếu user đã setup rồi, CLI tự skip bước này.
+
+### 2. Local Project Config (`.trello-config.json` tại root dự án)
 ```json
 {
   "board": "Appdexter - Code Magic",
@@ -67,9 +67,21 @@ Bảo mật: API Key và Token được lưu tại Global, cấu hình dự án
 | `list` | Tên list chứa card (= team member đang phụ trách) |
 | `card` | Tên card dự án (phải khớp chính xác trên Trello) |
 
+### 🔄 Credential Auto-Recovery (BẮT BUỘC cho AI)
+
+Khi `awkit trello` báo **"Trello credentials not found"**, AI PHẢI thực hiện:
+
+```text
+Lần 1: chạy `source ~/.zshrc` → retry lệnh awkit trello
+Lần 2: chạy `source ~/.zshrc` → retry lệnh awkit trello
+Lần 3 (vẫn lỗi): báo user "Trello chưa được cấu hình. Vui lòng chạy awkit init để setup lại."
+```
+
+> ⚠️ KHÔNG được tự tạo script, tự inject biến, hay tự sửa file `.zshrc`. CHỈ dùng `source` và `awkit init`.
+
 ### Tự Động Hóa Qua `awkit trello` (BẮT BUỘC)
 
-AI không cần tự inject ENV hay tìm kiếm cấu hình. Công cụ lệnh `awkit trello` v1.3.0+ sẽ TỰ ĐỘNG đọc từ Global Config và Local Config để thực thi nhanh chóng. MỌI thao tác Trello phải đi qua `awkit trello`.
+AI không cần tự inject ENV hay tìm kiếm cấu hình. Công cụ lệnh `awkit trello` v1.3.0+ sẽ TỰ ĐỘNG đọc từ env vars và `.trello-config.json`. MỌI thao tác Trello phải đi qua `awkit trello`.
 ---
 
 ## 📚 Command Reference
@@ -114,21 +126,23 @@ Mỗi Card chứa:
 
 ### TP1: 🚀 Start Task / Start Project (Description + Checklist)
 
-**Khi nào:** AI bắt đầu project mới hoặc làm task lớn mới (claim Symphony task).
+**Khi nào:** AI bắt đầu project mới, hoặc chuẩn bị triển khai Specs đã chốt (Gate 3/Gate 4). 
+*(Lưu ý: Không tạo Checklist Items các phase "Gate 1", "Gate 2" - lúc này chỉ dùng Comment hoặc Update Description thôi).*
 
 **Action:**
 ```bash
 # Update Card Description với thông tin cực kỳ rõ ràng cho Quản lý (PM) dự án
 awkit trello desc "**Trạng thái:** Đang phát triển. **Công nghệ:** Kotlin, Jetpack Compose, Room. **Tiến độ hiện tại:** ... (Tóm tắt sơ lược)"
 
-# 1. Tạo checklist (nếu cần, ví dụ Sprint)
-awkit trello checklist "Sprint 2026-03"
+# 1. Tạo checklist dựa trên Module/Epic Nghiệp vụ thực tế
+awkit trello checklist "Module: Xác thực Người Dùng"
 
-# 2. Thêm item mới vào checklist
-awkit trello item "Feature: Login Flow"
+# 2. Thêm item mới vào checklist (Tuyệt đối KHÔNG ĐẶT TÊN theo Gate/Phase/Scaffolding)
+awkit trello item "Đăng nhập bằng Google"
+awkit trello item "Hồ sơ Người Dùng"
 
-# 3. Comment báo bắt đầu
-awkit trello comment "🤖 AI bắt đầu: Login Flow | Symphony: #sym-XXX"
+# 3. Comment thông báo cập nhật tiến trình hoặc trạng thái Agent
+awkit trello comment "🤖 AI bắt đầu: Xây dựng giao diện Đăng Nhập | Symphony: #sym-XXX"
 ```
 
 ---
@@ -157,26 +171,35 @@ awkit trello block "API 500 on /auth/login. Cần Backend check."
 
 ### TP4: ✅ Task Done (Đánh dấu Item Complete)
 
-**Khi nào:** Task hoàn thành, verification pass.
+**Khi nào:** Toàn bộ cụm Tính năng Nghiệp vụ (Epic/Feature bao gồm nhiều sub-tasks) đã hoàn thành và sẵn sàng test.
+*(Lưu ý: Không check item nếu chỉ mới xong 1 task code con lập trình)*
 
 ```bash
-# 1. Đánh dấu checklist item ✅
-awkit trello complete "Feature: Login Flow"
+# 1. Đánh dấu checklist item đại diện cho tính năng ✅
+awkit trello complete "Đăng nhập bằng Google"
 
 # 2. Comment kết quả
-awkit trello comment "✅ DONE: Login Flow | Commit: #$(git rev-parse --short HEAD)"
+awkit trello comment "✅ DONE Feature: Đăng nhập bằng Google | Commit: #$(git rev-parse --short HEAD)"
 ```
 
 ---
 
-## 🔗 Symphony Integration
+## 🔗 Symphony Integration (NGUYÊN TẮC: Nhiều Task Code -> 1 Trello Feature)
+
+⚠️ **CHÚ Ý CỰC KỲ QUAN TRỌNG:** KHÔNG MAP 1:1 TỪ SYMPHONY SANG TRELLO CHECKLIST!
+Trong Symphony có thể có 50 task nhỏ (VD: Tạo View, Viết API, Sửa CSS). Trello chỉ có 5 Checklist Items lớn (VD: Chức năng Đăng nhập, Profile, Thanh toán). 
+Do đó: **CẤM** gọi `awkit trello item` mỗi khi claim 1 task con từ Symphony. Nếu làm vậy Trello sẽ biến thành bãi rác toàn các task code lặt vặt.
+
+**Cách Sync Đúng:**
+- Thiết lập Checklist Items ngay từ đầu dựa trên Spec tổng.
+- Khi code từng phân hệ con, ĐỪNG sinh ra checklist mới.
 
 | Symphony Event | Trello Action |
 |----------------|---------------|
-| `symphony_claim_task` | Thêm checklist item (incomplete) + Comment start |
+| `symphony_claim_task` | **CHỈ** Comment báo tiến độ: "Đang xử lý code: [Task]..." |
 | `symphony_report_progress` | Comment milestone |
 | Task BLOCKED | Label "Blocked" + Comment |
-| `symphony_complete_task` | Mark item ✅ complete + Comment result |
+| `symphony_complete_task` | **CHỈ** Comment: "Xong code task [Task]." *(Tùy chọn: nếu feature lớn xong 100%, mới call `complete` cho item chính)* |
 
 Trong comment, **PHẢI** ghi Symphony Task ID: `Symphony: #sym-XXX`
 
@@ -184,9 +207,11 @@ Trong comment, **PHẢI** ghi Symphony Task ID: `Symphony: #sym-XXX`
 
 ## 🎯 Best Practices
 
-1. **Checklist naming**: Theo phase/module lớn (VD: "Module: fw-01-foundation", "Sprint 2026-03").
-2. **Item naming**: Mô tả tính năng lớn (VD: "Login Flow", "Firebase Integration"). KHÔNG ĐƯA CÁC ĐẦU MỤC CODE LEVEL VÀO ĐÂY (VD: "Thêm nút bấm", "Sửa CSS", v.v.).
-3. **Minimizing noise**: Comment chỉ ở milestones, KHÔNG spam mỗi dòng code. Cấm bulk-sync checklist item từ `tasks.md`.
+1. **Checklist naming (Module/Epic)**: Tên checklist thể hiện mảng Tính năng/Module lớn (VD: "Module: Authentication", "Sprint: Workout Tính năng cốt lõi").
+   ⛔ KHÔNG ĐẶT theo quy trình AI như "Gate 1", "Phase: Setup", "Giai đoạn Design".
+2. **Item naming (Product Features)**: Tên item là tính năng/màn hình cụ thể (VD: "Google Sign-In", "Màn hình Thông kê Calorie", "Chức năng AI tư vấn thực đơn"). 
+   ⛔ KHÔNG ĐẶT kiểu "Tài liệu Specs", "Code Scaffolding", "Sửa CSS" hay "Tạo file ABC".
+3. **Minimizing noise**: Cập nhật milestone (chuyển gate, chuyển phase) qua **Comment** trên Card, KHÔNG GHI THÀNH **Checklist item** (vốn dĩ checklist item là thứ bàn giao được cho user). Cấm bulk-sync từ `tasks.md`.
 4. **Graceful degradation**: CLI/API lỗi → log warning, KHÔNG block code flow.
 5. **Dùng lệnh Native**: Luôn luôn gọi `awkit trello <lệnh>` thay vì `trello-cli` thủ công.
 6. **Card KHÔNG di chuyển**: Card nằm cố định trong list team member. KHÔNG move card.
@@ -198,12 +223,13 @@ Trong comment, **PHẢI** ghi Symphony Task ID: `Symphony: #sym-XXX`
 | Tình huống | Xử lý |
 |-----------|--------|
 | `.trello-config.json` không tồn tại | ⛔ Bỏ qua Trello sync, log cảnh báo, tiếp tục code |
+| **Credentials not found** | `source ~/.zshrc` → retry (max 2 lần). Vẫn lỗi → báo user chạy `awkit init` |
 | Card not found | Chạy `sync`, retry. Nếu vẫn lỗi → báo user |
-| Checklist chưa có | Tạo checklist mới bằng `card:checklist` |
+| Checklist chưa có | Tạo checklist mới bằng `awkit trello checklist` |
 | Item trùng tên | Dùng `card:checklists` kiểm tra trước khi thêm |
-| Rate limit / API error | Log warning, tiếp tục code, KHÔNG block flow |
-| Token hết hạn | Báo user refresh trong `.trello-config.json` |
-| Dự án chưa có card trên Trello | Báo user tạo card trên board, cập nhật config |
+| Rate limit / API error | Log warning, tiếp tục code, KHÔNG block flow. CLI tự retry 429. |
+| Token hết hạn | Báo user chạy `awkit init` để setup lại credential mới |
+| Dự án chưa có card trên Trello | Báo user tạo card trên board, cập nhật `.trello-config.json` |
 
 ---