@leejungkiin/awkit 1.2.0 → 1.3.4

package/skills/spec-gate/SKILL.md

@@ -4,11 +4,11 @@ description: >-
   Gate 2 — Architecture & Data Design Gate. Chốt thiết kế kỹ thuật (DB Schema,
   API Contract, State Machine) TRƯỚC KHI cho phép code. Bắt buộc user approve
   thiết kế để tránh "vừa làm vừa sửa database". Auto-triggered bởi orchestrator
-  khi Gate 2 chưa thỏa mãn.
+  khi Gate 2 chưa thỏa mãn. Hỗ trợ auto-detect .kiro/specs/design.md.
 metadata:
   stage: core
-  version: "1.0"
-  tags: [gate, architecture, database, design, spec-first, core]
+  version: "1.1"
+  tags: [gate, architecture, database, design, spec-first, core, kiro]
   requires: orchestrator
 agent: Architect
 trigger: conditional
@@ -58,8 +58,13 @@ Skill này được kích hoạt bởi:
 Trước khi chạy, PHẢI có:
 
 ```
-REQUIRED:
-  → docs/specs/<feature>.md HOẶC BRIEF.md (output từ Gate 1)
+REQUIRED (theo thứ tự ưu tiên):
+  → CHECK 1 (Kiro): .kiro/specs/<module>/design.md
+    → Nếu tồn tại → AUTO-APPROVE: Load làm pre-approved architecture
+    → Skip Phase 2-7, thẳng Phase 8 (Write to NeuralMemory)
+    → Thông báo: "🔍 Phát hiện .kiro/specs design docs.
+       Thiết kế đã được chốt trong Kiro IDE. Auto-approve → Gate 2 PASS."
+  → CHECK 2: docs/specs/<feature>.md HOẶC BRIEF.md (output từ Gate 1)
   → .project-identity (projectId, techStack)
 
 OPTIONAL:
@@ -75,6 +80,17 @@ OPTIONAL:
 ### Phase 1: Context Gathering (Silent)
 
 ```
+0. CHECK KIRO SPECS FIRST (HIGHEST PRIORITY):
+   - Scan .kiro/specs/<module>/design.md
+   - Nếu tồn tại:
+     → Load design.md làm approved architecture
+     → Load .kiro/specs/<project>/design.md cho project-wide schema
+     → Load .kiro/specs/<module>/requirements.md cho acceptance criteria
+     → Lưu vào NeuralMemory: "Kiro architecture loaded: <summary>"
+     → SKIP Phase 2-7, thẳng Phase 8 (write decision to NeuralMemory)
+     → Gate 2 AUTO-PASS
+   - Không tồn tại → tiếp Phase 1 bình thường
+
 1. Đọc BRIEF.md / spec document → Extract:
    - Core entities (Users, Orders, Products...)
    - Relationships (1-N, N-N)
@@ -188,7 +204,21 @@ checklist:
     - [ ] Input validation cho mọi user input?
 ```
 
-### Phase 6: Present & Approval
+### Phase 6: Multi-Role Architecture Review (AI Simulated)
+
+**Trước khi gửi cho user approve, AI TỰ ĐỘNG đóng 5 vai trò chuyên sâu để soát lỗi:**
+
+```
+1. DBA (Database Admin): Đã đánh index các trường queries thường xuyên? Bảng có chuẩn hóa (normalize) chưa? Có issue N+1 query không?
+2. Backend Lead: API có reusable không? Có tính đến rate limit chưa? Transaction boundaries ở đâu?
+3. Security Officer: Có chống SQL Injection không? Data at rest/in transit encrypt thế nào? Cấp quyền Row-level (RBAC)?
+4. QA Automation: Việc setup test data có khó không? Mock API/DB có thuận lợi không?
+5. SRE / DevOps: Nếu data lớn lên, hệ thống có scale nổi? Quá trình migrate db (schema update) có gây downtime không?
+
+*Nếu có P0/P1 issues, AI phải fix bản draft ngay lập tức.*
+```
+
+### Phase 7: Present & Approval
 
 ```
 Present cho user với format:
@@ -206,8 +236,7 @@ Present cho user với format:
 ## State Machine
 [Phase 4 output — nếu có]
 
-## Self-Review ✅
-[Phase 5 checklist results]
+[Phase 7 checklist results]
 
 ## Concerns & Trade-offs
 - [Concern 1]: [Mô tả + recommendation]
@@ -219,7 +248,7 @@ Present cho user với format:
 ───────────────────────────────────
 ```
 
-### Phase 7: Write Design Doc
+### Phase 8: Write Design Doc
 
 Sau khi user approve:
 
@@ -309,4 +338,4 @@ WORKS WITH: nm-memory-sync (store architectural decisions)
 
 ---
 
-*spec-gate v1.0 — Architecture & Data Design Gate for AWKit*
+*spec-gate v1.1 — Architecture & Data Design Gate for AWKit (Kiro Spec Integration)*

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.3: Completion Status Protocol, Search-Before-Building, Boil-the-Lake.
+  v3.4: Kiro Spec Integration, Completion Status Protocol, Search-Before-Building, Boil-the-Lake.
 metadata:
   stage: core
-  version: "3.3"
-  replaces: "v2.0"
+  version: "3.4"
+  replaces: "v3.3"
   requires: symphony-orchestrator
-  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next]
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next, kiro]
 agent: Symphony Enforcer
 allowed-tools:
   - symphony_create_task
@@ -24,10 +24,11 @@ invocation-type: auto
 priority: 1
 ---
 
-# Symphony Enforcer v3.3 — Completion Status Protocol + Gstack Principles
+# Symphony Enforcer v3.4 — Kiro Spec Integration + Completion Status Protocol
 
 > **Purpose:** Đảm bảo AI KHÔNG BAO GIỜ quên cập nhật Symphony.
-> **Key Changes v3.3:**
+> **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
@@ -47,7 +48,7 @@ KHÔNG CÓ NGOẠI LỆ:
 - AI tự detect completion và auto-complete task
 - Task done → PHẢI atomic git commit trước khi suggest next
 - Kết thúc task PHẢI kèm next suggestion
-- BỎ QUA BẤT KỲ STEP NÀO = VI PHẠM
+- BỎ QUA BẤT BẤT KỲ STEP NÀO = VI PHẠM
 ```
 
 ---
@@ -74,30 +75,47 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 → Output: "🧠 Step 2/5: Brain ✅ — switched to {projectId}"
 ```
 
-### Step 3: Spec Alignment — Đọc Project Spec (NEW v3.0)
+### Step 3: Spec Alignment — Đọc Project Spec (v3.4 + Kiro)
 
 ```
-→ Kiểm tra: docs/specs/PROJECT.md tồn tại?
-→ CÓ  → Đọc silent: PROJECT.md + TECH-SPEC.md + REQUIREMENTS.md
-       → Extract constraints liên quan đến task hiện tại
-       → 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?"
-          - Ví dụ: "UI nên dạng list hay cards?"
-       → Output: "📐 Step 3/5: Spec Aligned ✅"
-→ KHÔNG → Skip (project chưa /init) → "📐 Step 3/5: No spec — skipped"
+→ CHECK 1 (Kiro — HIGHEST PRIORITY): .kiro/specs/ tồn tại?
+  → CÓ → Load specs từ .kiro/specs/:
+     - .kiro/specs/<project>/requirements.md → project spec
+     - .kiro/specs/<module>/requirements.md → module specs
+     - .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"
+
+→ CHECK 2 (fallback): docs/specs/PROJECT.md tồn tại?
+  → CÓ  → Đọc silent: PROJECT.md + TECH-SPEC.md + REQUIREMENTS.md
+         → Extract constraints liên quan đến task hiện tại
+         → 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"
 ```
 
-> **Quan trọng:** Nếu TECH-SPEC.md có "Constraints & Non-Negotiables",
+> **Quan trọng:** Nếu .kiro/specs hoặc TECH-SPEC.md có "Constraints & Non-Negotiables",
 > AI PHẢI tuân thủ chúng trong implementation_plan.md.
 
 ### Step 4: Symphony Task — Tạo hoặc nhận task
 
 ```
-→ symphony_available_tasks(filter="my") → check active tasks
-→ CÓ task in_progress phù hợp → dùng tiếp
-→ CÓ task ready phù hợp → symphony_claim_task
-→ KHÔNG CÓ → symphony_create_task(title) → symphony_claim_task(new_id)
+→ CHECK 1 (Kiro tasks): .kiro/specs/<module>/tasks.md tồn tại?
+  → CÓ + chưa import → Parse task items từ tasks.md:
+     - 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"
+     → Claim task phù hợp nhất với user request
+  → CÓ + đã import → symphony_available_tasks → claim task phù hợp
+
+→ CHECK 2 (fallback): symphony_available_tasks(filter="my") → check active tasks
+  → CÓ task in_progress phù hợp → dùng tiếp
+  → 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"
 ```

package/skills/trello-sync/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: trello-sync
+description: |
+  Hệ thống đồng bộ tiến độ dự án lên Trello sử dụng Trello CLI (v1.5+) + REST API.
+  Mỗi dự án = 1 Trello Card. Tiến độ được theo dõi qua Checklists và Comments.
+  AI tự động thêm/đánh dấu checklist items khi hoàn thành task.
+metadata:
+  stage: core
+  version: "3.0"
+  tags: [trello, sync, project-management, tracking, agile]
+agent: Trello Sync Agent
+allowed-tools:
+  - run_command
+trigger: always
+invocation-type: auto
+priority: 2
+---
+
+# Trello Sync v3.0 — Project-Per-Card Protocol
+
+> **Purpose:** Tự động đồng bộ tiến độ dự án lên Trello card tương ứng, giúp team (PM, QC, Dev) theo dõi realtime.
+> **Model:** 1 Card = 1 Dự án. Checklist Items = tasks/features. Comments = milestones.
+> **Tools:** `trello-cli v1.5` (CLI) + Trello REST API (curl) cho checklist items.
+
+---
+
+## ⚠️ Core Rules
+
+```text
+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.
+```
+
+---
+
+## 🔐 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.
+
+### 1. Global Credentials (đặt tại `~/.gemini/antigravity/credentials/trello.json`)
+```json
+{
+  "api_key": "YOUR_TRELLO_API_KEY",
+  "api_token": "YOUR_TRELLO_API_TOKEN"
+}
+```
+
+### 2. Local Project Config (đặt file `.trello-config.json` tại root mỗi dự án)
+```json
+{
+  "board": "Appdexter - Code Magic",
+  "list": "Kiên",
+  "card": "Tên Card Dự Án"
+}
+```
+
+| Field | Mô tả |
+|-------|--------|
+| `board` | Tên board (TÊN, không dùng ID) |
+| `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) |
+
+### 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`.
+---
+
+## 📚 Command Reference
+
+### AWKit Trello CLI (Native, Zero Config Needed in Bash)
+
+Công cụ `awkit` đã cung cấp sẵn các lệnh native quản lý Trello. Phải ƯU TIÊN SỬ DỤNG.
+
+| Action | Command |
+|--------|---------|
+| Cập nhật mô tả (desc) | `awkit trello desc "<text>"` |
+| Comment milestone | `awkit trello comment "<text>"` |
+| Thêm checklist item | `awkit trello item "<name>"` |
+| Check ✅ hoàn thành | `awkit trello complete "<name>"` |
+| 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`.
+
+---
+
+## 🔄 Lifecycle & Trigger Points
+
+### Board Structure (Context)
+
+```
+Board: Appdexter - Code Magic
+├── App cần làm ☘️     ← Backlog (ý tưởng)
+├── Kiên               ← Cards = projects assigned to Kiên
+├── Huy lớn            ← Cards = projects assigned to Huy lớn
+├── Doing              ← Cards actively being worked on
+├── Done               ← Completed cards
+└── ...
+```
+
+Mỗi Card chứa:
+- **Description**: Mô tả dự án, link repo
+- **Checklists**: Các phase (UI, Code Logic, Infrastructure...)
+- **Checklist Items**: Tasks cụ thể trong phase đó
+
+---
+
+### 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).
+
+**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"
+
+# 2. Thêm item mới vào checklist
+awkit trello item "Feature: Login Flow"
+
+# 3. Comment báo bắt đầu
+awkit trello comment "🤖 AI bắt đầu: Login Flow | Symphony: #sym-XXX"
+```
+
+---
+
+### TP2: 📈 Report Progress (Comment Milestone)
+
+**Khi nào:** AI đạt milestone quan trọng (40%, 60%, 80%) hoặc hoàn thành cụm tính năng.
+
+**Action:** Cung cấp thông tin CHUYÊN MÔN nhưng RÕ RÀNG cho PM:
+```bash
+awkit trello comment "⏳ Progress: Login Flow (60%) — UI hoàn thiện. QUYẾT ĐỊNH KỸ THUẬT: Đã chọn SQLite/Room thay vì Firebase để đảm bảo Offline-first theo spec."
+```
+
+---
+
+### TP3: 🛑 Blocked
+
+**Khi nào:** Task bị chặn, cần human input.
+
+```bash
+# Label + Comment
+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.
+
+```bash
+# 1. Đánh dấu checklist item ✅
+awkit trello complete "Feature: Login Flow"
+
+# 2. Comment kết quả
+awkit trello comment "✅ DONE: Login Flow | Commit: #$(git rev-parse --short HEAD)"
+```
+
+---
+
+## 🔗 Symphony Integration
+
+| Symphony Event | Trello Action |
+|----------------|---------------|
+| `symphony_claim_task` | Thêm checklist item (incomplete) + Comment start |
+| `symphony_report_progress` | Comment milestone |
+| Task BLOCKED | Label "Blocked" + Comment |
+| `symphony_complete_task` | Mark item ✅ complete + Comment result |
+
+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`.
+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.
+
+---
+
+## Edge Cases
+
+| 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 |
+| 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` |
+| 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 |
+
+---
+
+## Learnings
+
+- Board "Appdexter - Code Magic": Lists = team members, Cards = projects
+- Tool native CLI `awkit trello` cho phép update thông tin dự án thẳng từ CLI mà không cần inject variables lằng nhằng.
+- KHÔNG sinh script file mồ côi `trello_sync_kiro.py` — phải chạy trực tiếp qua `awkit trello`

package/skills/verification-gate/SKILL.md

@@ -138,6 +138,8 @@ Trước khi claim DONE, kiểm tra **mỗi item** dưới đây:
 ☐ Input validation: User input được validate trước khi process?
 ☐ Concurrency: Thread-safe? Race conditions handled?
 ☐ Backwards compatibility: Breaking changes documented?
+☐ Localization (I18N): Text UI mới đã được thêm vào Localizable.strings (EN & VI) chưa?
+  → Việc bọc `Localized()` trong code là chưa đủ. Phải THỰC SỰ mở file .strings (hoặc chạy update_strings.py) để bổ sung key/value trước khi báo cáo DONE.
 ```
 
 **Nếu thiếu bất kỳ item nào → report DONE_WITH_CONCERNS, không DONE.**

package/skills/visual-design-gate/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: visual-design-gate
+description: >-
+  Gate 2.5 — Visual Design & UI Sync Gate. Thống nhất cách hiểu về UI/UX giữa
+  người dùng và AI thông qua phác thảo bằng Pencil MCP Server, hoặc thông qua 
+  hình ảnh screenshot/design có sẵn. Đảm bảo UI/UX đã được chốt trước khi chia 
+  Symphony tasks và viết code.
+metadata:
+  stage: core
+  version: "1.0"
+  tags: [gate, ui, ux, design, pencil, visual, sync, core]
+  requires: orchestrator
+agent: UI/UX Designer
+trigger: conditional
+invocation-type: auto
+priority: 2.5
+activation_keywords:
+  - "thiết kế giao diện"
+  - "vẽ UI"
+  - "phác thảo màn hình"
+  - "design ui"
+  - "pencil"
+---
+
+# Visual Design Gate v1.0 (Gate 2.5) — UI/UX Sync Gate
+
+> **Purpose:** Giúp AI và người dùng đồng bộ cách hiểu về ý tưởng giao diện (UI/UX)
+> TRƯỚC KHI chia tasks và bắt tay vào code. Sử dụng công cụ Pencil để vẽ preview, 
+> hoặc sử dụng mockups/screenshots do người dùng cung cấp sẵn để làm căn cứ.
+>
+> **Problem it solves:** "Code xong giao diện không ra gì, hoặc chệch hướng so với ý tưởng UI của user"
+
+---
+
+## ⚠️ SCOPE CLARITY
+
+| Skill này LÀM | Skill này KHÔNG làm |
+|---------------|---------------------|
+| Dùng `pencil` MCP server để phác thảo file `.pen` | Viết code React/Swift/Compose UI |
+| Đọc hiểu ảnh đính kèm từ `docs/design` hoặc `docs/screenshot` | Nhận diện DB Schema (việc của spec-gate) |
+| Tương tác với user để chốt màu sắc, bố cục, fonts | Quản lý logic back-end |
+| Giới thiệu user về Pencil tool nếu project cần thiết kế mới | Phân chia task Symphony |
+
+---
+
+## 🚀 ACTIVATION
+
+Skill này được kích hoạt bởi:
+1. **Orchestrator auto-trigger:** Khi Gate 2.5 check FAIL (feature có giao diện nhưng thiếu preview chốt UI, hoặc chưa có design image).
+2. **Explicit command:** `/design-ui` hoặc `/visual-sync`
+3. **Keyword trigger:** "thiết kế giao diện", "design ui bằng pencil", "phác thảo ui"
+
+---
+
+## 📋 INPUT REQUIREMENTS
+
+Trước khi chạy, PHẢI có:
+
+```
+REQUIRED:
+  → docs/specs/<feature>.md (output Gate 1) HOẶC thiết kế DB đã chốt tại Gate 2
+
+OPTIONAL BUT HIGHLY RECOMMENDED:
+  → docs/design/ hoặc docs/screenshot/ chứa ảnh tham khảo đã có.
+```
+
+---
+
+## 🔄 PROCESS
+
+### Phase 1: Context Gathering (Silent)
+
+```
+1. Đọc spec document của feature để xác định các elements UI cần thiết
+   (Danh sách nút, forms, data grids, navigations).
+2. Quyét thư mục `docs/design/` và `docs/screenshot/` xem đã có ảnh tham khảo chưa.
+3. Nếu CÓ ẢNH: Đọc và report phân tích UI của ảnh, và chuyển luôn sang Phase 3 (Approval).
+4. Nếu KHÔNG CÓ ẢNH: Chuyển sang Phase 2 (Pencil Draft).
+```
+
+### Phase 2: Pencil Blueprint Drafting
+
+```
+Khi dự án được chốt là CHƯA có giao diện mẫu, AI phải:
+1. Thông báo cho User: "Để chúng ta hiểu đúng ý nhau về giao diện, tôi sẽ phác thảo một bản vẽ UI bằng công cụ Pencil. Quá trình này sẽ mất một chút thời gian xử lý."
+2. Chạy tool `open_document` để tạo file `docs/design/<feature>.pen` (nếu chưa có).
+3. Sử dụng tool `batch_design`:
+   - Dựng Layout theo chuẩn component (Container, Navbar, Sidebar, Content).
+   - Thêm Text, Buttons, Forms theo dữ liệu đã chốt từ spec-gate (ví dụ: spec ghi có login form email/pass, thì màn hình phải có 2 input + submit button).
+   - Áp color/theme phù hợp với identity của project.
+4. Render screenshot của Pencil (sử dụng `get_screenshot` node id của screen).
+```
+
+### Phase 3: Present & Approval
+
+```
+Present cho user với format sau:
+
+───────────────────────────────────
+🎨 UI/UX DESIGN PREVIEW: <Feature Name>
+───────────────────────────────────
+
+## Design Source
+[Trạng thái: Đã đọc từ ảnh `docs/design/mockup.png` HOẶC Bản nháp Pencil `docs/design/<feature>.pen`]
+
+## Core UI Components
+- [Component 1]: [Mô tả vai trò, ví dụ: Authentication Form chứa inputs login]
+- [Component 2]: [Mô tả trạng thái state...]
+- [Component 3]: ...
+
+## Hình ảnh Preview
+[Đính kèm Screenshot preview nếu dùng Pencil]
+
+───────────────────────────────────
+⏳ Anh xem giao diện tổ chức thế này đã đúng ý đồ anh muốn chưa?
+   - Nếu cần tôi tinh chỉnh bố cục, màu sắc bằng Pencil thì anh cứ báo.
+   - Nếu anh đã chốt, phản hồi "OK" để tôi chia task code nhé!
+───────────────────────────────────
+```
+
+### Phase 4: Write UI Decision Doc
+
+Sau khi user approve:
+
+```
+1. (Nếu xài thư mục chung) Ghi vào file README của thư mục `docs/design/` các quyết định chính về giao diện.
+2. Lưu vào NeuralMemory:
+   nmem_remember(
+     content="Visual Design for <feature> approved. Focus points: <summary_ui_points>",
+     type="decision",
+     tags=["ui", "design", "<projectId>", "<feature>"]
+   )
+3. Proceed → Orchestrator re-checks Gate 2.5 → PASS → Gate 3 (Symphony tasks).
+```
+
+---
+
+## 🔙 DESIGN REVISION PROTOCOL
+
+Khi User yêu cầu sửa bản Pencil phác thảo:
+
+```
+1. Xác định chính xác node cần sửa.
+2. Dùng batch_get từ Pencil MCP để lấy IDs các khung components liên quan.
+3. Chạy Update (U) hoặc Replace (R) logic trên Pencil batch_design tool.
+4. Cập nhật screenshot UI mới gửi lại User.
+5. Tiếp tục vòng lặp cho đến khi "Approved".
+```
+
+---
+
+## 🗣️ Communication Style
+
+```
+❌ "Please provide design mockups or approve the design generation process."
+✅ "Để mình đồng điệu cách triển khai, tôi nghĩ nên phác thảo qua cái giao diện một chút. 
+    Anh có ảnh màn hình / mockup (Figma/PNG) sẵn trong thư mục nào không, hay để tôi dùng công cụ Pencil vẽ nhanh 1 bản phác thảo anh xem qua?"
+```
+
+---
+
+## 🚫 Anti-Patterns
+
+```yaml
+never_do:
+  - Ép user xài Pencil nếu user đã copy đầy đủ file design (ảnh, video) vào /docs/.
+  - Code Front-end UI (HTML/CSS/Swift) khi người dùng chưa đồng ý phương án bố cục.
+  - Vẽ chi tiết quá mất thời gian cho những task internal/CLI thuần túy (Orchestrator phải skip Gate này cho Backend).
+  
+always_do:
+  - Báo hiệu quá trình thao tác với Pencil vì nó sẽ mất thời gian load server, render node, chụp screenshot.
+  - Tái sử dụng các rules về spacing/màu sắc nếu trong file .pen đã có sẵn Design System Variables.
+```
+
+---
+
+*visual-design-gate v1.0 — Visual Design & UI Sync Gate for AWKit*

package/templates/configs/trello-config.json

@@ -0,0 +1,5 @@
+{
+  "BOARD_NAME": "Appdexter - Code Magic",
+  "LIST_NAME": "Your Backlog List",
+  "CARD_NAME": "Project Card Name or ID"
+}

package/VERSION

@@ -1 +0,0 @@
-1.1.6