@leejungkiin/awkit 1.3.7 → 1.4.0

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.6"
+  replaces: "v3.5"
   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,15 @@ invocation-type: auto
 priority: 1
 ---
 
-# Symphony Enforcer v3.4 — Kiro Spec Integration + Completion Status Protocol
+# Symphony Enforcer v3.6 — UI-First Three-Phase Execution + Legacy Cleanup
 
 > **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.6:**
+> - **Step 0.5: Legacy Artifact Cleanup**: Auto-detect stale `.symphony/tasks.json` and warn user
+> - **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.5 (Kiro, Completion Status, Design Compliance).
 > **Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
 
 ---
@@ -55,16 +53,32 @@ KHÔNG CÓ NGOẠI LỆ:
 
 ## 🔒 STRICT STARTUP PROTOCOL (BẮT BUỘC)
 
-Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **5 steps tuần tự**.
+Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **6 steps tuần tự**.
 KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 
+### Step 0.5: Legacy Artifact Cleanup (AUTO — v3.6)
+
+```
+→ Kiểm tra: .symphony/tasks.json tồn tại?
+→ CÓ  → ⚠️ CẢNH BÁO: "Legacy tasks.json detected. Symphony uses SQLite DB — this file is stale."
+       → Khuyên user xoá: "rm .symphony/tasks.json"
+       → KHÔNG tự xoá (safety guardrail) — chỉ cảnh báo.
+       → Ghi log vào NeuralMemory: "Legacy tasks.json found at {project}, warned user."
+→ KHÔNG → ✅ Clean (no legacy artifacts)
+→ Output: "🧹 Step 0.5: Legacy Check ✅ — No stale artifacts"
+```
+
+> **Lý do:** Symphony v2+ sử dụng SQLite DB (`symphony.db`) làm single source of truth.
+> File `tasks.json` là di sản từ phiên bản cũ (pre-SQLite). Nếu tồn tại song song sẽ gây
+> "split-brain" — một nửa tool đọc JSON, một nửa đọc DB → dữ liệu lệch pha.
+
 ### Step 1: Project Identity — `.project-identity`
 
 ```
 → Kiểm tra: file .project-identity có tồn tại?
 → CÓ  → Đọc projectId, projectName
 → KHÔNG → ⛔ DỪNG. Hỏi user hoặc tạo .project-identity.
-→ Output: "📋 Step 1/5: Project Identity ✅ — {projectId}"
+→ Output: "📋 Step 1/6: Project Identity ✅ — {projectId}"
 ```
 
 ### Step 2: NeuralMemory Brain — Switch brain
@@ -72,7 +86,7 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 ```
 → nmem brain use <projectId>
 → nmem_recap(level=1) — load context
-→ Output: "🧠 Step 2/5: Brain ✅ — switched to {projectId}"
+→ Output: "🧠 Step 2/6: Brain ✅ — switched to {projectId}"
 ```
 
 ### Step 3: Spec Alignment — Đọc Project Spec (v3.4 + Kiro)
@@ -85,7 +99,7 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
      - .kiro/specs/<module>/design.md → architecture
      - .kiro/specs/<module>/tasks.md → task breakdown (cho Step 4)
      → Extract constraints liên quan đến task hiện tại
-     → Output: "📐 Step 3/5: Kiro Specs Loaded ✅ — {N} modules, {M} design docs"
+     → Output: "📐 Step 3/6: Kiro Specs Loaded ✅ — {N} modules, {M} design docs"
 
 → CHECK 2 (fallback): docs/specs/PROJECT.md tồn tại?
   → CÓ  → Đọc silent: PROJECT.md + TECH-SPEC.md + REQUIREMENTS.md
@@ -93,8 +107,8 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
          → NẾU PLANNING mode:
             - Hỏi user 1-3 câu về constraints/UX cụ thể của feature
             - Ví dụ: "Feature này cần offline support không?"
-         → Output: "📐 Step 3/5: Spec Aligned ✅"
-  → KHÔNG → Skip (project chưa /init) → "📐 Step 3/5: No spec — skipped"
+         → Output: "📐 Step 3/6: Spec Aligned ✅"
+  → KHÔNG → Skip (project chưa /init) → "📐 Step 3/6: No spec — skipped"
 ```
 
 > **Quan trọng:** Nếu .kiro/specs hoặc TECH-SPEC.md có "Constraints & Non-Negotiables",
@@ -108,7 +122,7 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
      - Group theo module name
      - Đánh tag kèm module name
      → ⛔ CẢNH BÁO: KHÔNG đồng bộ hàng loạt các item nhỏ này lên Trello (để tránh rác board). Chỉ đồng bộ lên cấp module hoặc feature lớn.
-     → Output: "🎯 Step 4/5: Kiro Tasks Imported ✅ — {N} tasks created"
+     → Output: "🎯 Step 4/6: Kiro Tasks Imported ✅ — {N} tasks created"
      → Claim task phù hợp nhất với user request
   → CÓ + đã import → symphony_available_tasks → claim task phù hợp
 
@@ -117,7 +131,7 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
   → CÓ task ready phù hợp → symphony_claim_task
   → KHÔNG CÓ → symphony_create_task(title) → symphony_claim_task(new_id)
 → Lưu task_id cho TP1-TP4
-→ Output: "🎯 Step 4/5: Task ✅ — #sym-XYZ claimed"
+→ Output: "🎯 Step 4/6: Task ✅ — #sym-XYZ claimed"
 ```
 
 ### Step 5: Confirmation Block
@@ -125,11 +139,12 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 ```
 🚦 STARTUP PROTOCOL COMPLETE
 ══════════════════════════════════════
-  Step 1: 📋 Project Identity  ✅  {projectId}
-  Step 2: 🧠 NeuralMemory      ✅  brain: {projectId}
-  Step 3: 📐 Spec Alignment     ✅  {constraints_count} constraints loaded
-  Step 4: 🎯 Task              ✅  #sym-XYZ — "{title}"
-  Step 5: ✅ READY TO WORK
+  Step 0.5: 🧹 Legacy Check     ✅  No stale artifacts
+  Step 1:   📋 Project Identity  ✅  {projectId}
+  Step 2:   🧠 NeuralMemory      ✅  brain: {projectId}
+  Step 3:   📐 Spec Alignment     ✅  {constraints_count} constraints loaded
+  Step 4:   🎯 Task              ✅  #sym-XYZ — "{title}"
+  Step 5:   ✅ READY TO WORK
 ══════════════════════════════════════
 ```
 
@@ -137,7 +152,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 +160,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 +173,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 +299,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 +360,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 +675,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,19 +30,23 @@ 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).
-- 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.
+- **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` hay `task.md` là nơi để AI/Dev làm việc.
+- [QUAN TRỌNG NHẤT VỀ ĐỘ CHI TIẾT (GRANULARITY)]: Khi được yêu cầu chia task để sync lên Trello, AI PHẢI CHIA NHỎ các phase/tính năng lớn ra thành các Sub-features / Điểm chạm nghiệp vụ (Medium-detail). CẤM làm task quá chung chung.
+  - BAD (Quá chung chung): "Hoàn thiện Launch", "Setup Thanh Toán", "Xử lý Logic".
+  - BAD (Quá chi tiết / Dev task): "Tạo file BillingManager.kt", "Sửa padding cho nút Share".
+  - GOOD (Chuẩn PM View): "Tích hợp Google Play Billing v7", "Xử lý AlarmManager nhắc nhở đo huyết áp", "Cài đặt Crashlytics", "Thiết kế Store Assets (Icon, Screenshots)".
+- AI NÊN gom nhóm các Items vào thành nhiều Checklist rõ ràng theo từng phân khu lớn (VD: `Checklist: 1. Hoàn Thiện Logic`, `Checklist: 2. Monetization`, `Checklist: 3. Analytics & QA`).
+- ⛔ 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".
+- Progress qua các Gate (Gate 1, Gate 2...) CHỈ ĐƯỢC BÁO CÁO qua Comment. Quản lý không quan tâm AI đang ở Gate nào trên Checklists.
+- BẮT BUỘC ĐỒNG BỘ TOÀN BỘ DANH SÁCH NGHIỆP VỤ TỔNG HỢP: Khi Spec/dự án đã hòm hòm, AI phân mảnh các scope thành các Checklist Items (như quy tắc Granularity ở trên).
+- 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: "Đã thiết kế xong màn hình Home", "Bắt đầu code Logic tracking").
 ```
 
 ---
 
 ## 🔐 Auth & Config
 
-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.
+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 trong `"trello"` key của `.project-identity` ở root mỗi dự án (fallback: `.trello-config.json`).
 
 ### 1. Global Credentials (Environment Variables)
 
@@ -50,15 +54,21 @@ 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)
+### 2. Local Project Config (`"trello"` key trong `.project-identity`)
 ```json
 {
-  "board": "Appdexter - Code Magic",
-  "list": "Kiên",
-  "card": "Tên Card Dự Án"
+  "projectName": "MyApp",
+  "projectId": "myapp",
+  "trello": {
+    "board": "Appdexter - Code Magic",
+    "list": "Kiên",
+    "card": "Tên Card Dự Án"
+  }
 }
 ```
 
+> **Fallback:** Nếu `.project-identity` không có key `trello`, CLI sẽ thử đọc `.trello-config.json` (backward compat).
+
 | Field | Mô tả |
 |-------|--------|
 | `board` | Tên board (TÊN, không dùng ID) |
@@ -79,7 +89,7 @@ Lần 3 (vẫn lỗi): báo user "Trello chưa được cấu hình. Vui lòng c
 
 ### 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ừ env vars và `.trello-config.json`. 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à `.project-identity`. MỌI thao tác Trello phải đi qua `awkit trello`.
 ---
 
 ## 📚 Command Reference
@@ -97,7 +107,7 @@ Công cụ `awkit` đã cung cấp sẵn các lệnh native quản lý Trello. P
 | Báo Blocked / Lỗi | `awkit trello block "<reason>"` |
 | Tạo checklist mới | `awkit trello checklist "<name>"` |
 
-> 💡 Nếu gặp board/list/card "not found", cấu hình có thể sai, báo user kiểm tra lại `.trello-config.json`.
+> 💡 Nếu gặp board/list/card "not found", cấu hình có thể sai, báo user kiểm tra lại `trello` key trong `.project-identity`.
 
 ---
 
@@ -124,21 +134,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"
 ```
 
 ---
@@ -167,26 +179,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`
 
@@ -194,9 +215,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.
@@ -207,14 +230,14 @@ 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 |
+| Trello config not found | ⛔ 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 `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. 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` |
+| Dự án chưa có card trên Trello | Báo user tạo card trên board, cập nhật `trello` trong `.project-identity` |
 
 ---