@leejungkiin/awkit 1.6.5 → 1.6.8

package/workflows/ui/create-spec-architect.md

@@ -49,80 +49,110 @@ Hỏi người dùng các câu hỏi:
 mkdir -p docs/specs/[feature-name]
 ```
 
-### 3.2. Requirements Template
+### 3.2. Detailed Concept/Requirements Template (Theo chuẩn Đẹp Tướng)
 
 **File:** `docs/specs/[feature]/requirements.md`
 
 ```markdown
-# [Feature] Requirements
+# Concept Document — [Tính Năng/Giao Diện]
+> "[Slogan hoặc câu định vị ngắn gọn]"
+
+[⚠️ AI INSTRUCTION: BẮT BUỘC sử dụng cấu trúc cực kỳ chi tiết, dùng ASCII Diagram (Plain text) cho các kiến trúc/luồng xử lý và bảng biểu như template chuẩn.]
+
+## 1. Tầm nhìn & Lý do tồn tại
+* **Tóm tắt dự án:** ...
+* **Vấn đề được giải quyết:** ...
+* **Đối tượng người dùng cốt lõi:** ...
+
+## 2. Triết lý cốt lõi
+### 2.1 Các lớp phân tích / Nền tảng (Bắt buộc vẽ ASCII logic block)
+```text
+┌─────────────────────────────────────────────────┐
+│                   [LỚP 1]                       │
+├─────────────────────────────────────────────────┤
+│                   [LỚP 2]                       │
+└─────────────────────────────────────────────────┘
+                        ↓
+              [ĐỘNG CƠ XỬ LÝ CHÍNH]
+```
+### 2.2 Nguyên tắc thiết kế tính năng (Tối thiểu 5 nguyên tắc)
 
-## Introduction
-[1-2 sentences: What & Why]
+## 3. Kiến trúc ứng dụng
+### 3.1 Stack kỹ thuật (Bảng ánh xạ UI, AI, DB, BaaS)
+### 3.2 Cấu trúc màn hình (Vẽ sơ đồ Folder Tree routing)
 
-## Glossary
-- **Term**: Definition
+## 4. Luồng xử lý cốt lõi (Vẽ ASCII Flowchain logic)
 
-## Requirements
+## 5. Onboarding — Mindset & Thiết kế
+* Triết lý: Value trước, đăng ký sau
+* Cấu trúc Slides (Slide 0 -> 3): Chi tiết animation, thông điệp.
+* Design Patterns: Count-up, Stagger, v.v.
 
-### RQ-01: [Requirement Name]
-**Story:** As a [user], I want [action], so that [benefit].
+## 6. Gợi ý tính năng — Mindset (Logic mapping, Không Generic)
+* Đưa ví dụ ❌ Text chung chung vs ✅ Text phân tích chiều sâu.
 
-**Criteria:**
-1. WHEN [trigger], THEN [behavior]
-2. WHEN [error], THEN [handling]
-3. WHILE [state], THEN [constraint]
+## 7. Design System
+* Palette màu (Bảng Hex + Tên)
+* Animation & Icon conventions
 
-### RQ-02: [Requirement Name]
-**Story:** As a [user], I want [action], so that [benefit].
+## 8. Vòng lặp tăng trưởng & Engagement
+* Vẽ ASCII Loop tuần hoàn giữ chân user
+* Bảng Trigger Notifications
 
-**Criteria:**
-1. WHEN [trigger], THEN [behavior]
+## 9. Mô hình kinh doanh (Cây tính năng Free vs Premium)
+## 10. Nguyên tắc kỹ thuật (Performance, Data flow, Error handling)
+## 11. Roadmap (Phase MVP -> Depth -> Growth)
+## 12. Điều Không Được Làm (Anti-patterns - 7 quy tắc cấm kỵ)
 ```
 
-### 3.3. Design Template
+### 3.3. Design Template (Theo chuẩn Đồ Họa & UI)
 
 **File:** `docs/specs/[feature]/design.md`
 
 ```markdown
-# [Feature] Design
-
-## Overview
-[Architecture approach in 2-3 sentences]
-
-## Component Hierarchy
-```
-FeatureView
+# UI/Visual Design Document — [Tính Năng/Giao Diện]
+> "[Slogan hoặc Nguyên tắc chủ đạo của giao diện: "Ví dụ: Mỗi tab một sứ mệnh – không overlap"]"
+
+## 1. Tổng Quan & Metadata
+* **Phiên bản & Thời gian:** ...
+* **Mục tiêu:** [Lý do thay đổi/Kết quả đồ họa mong muốn]
+
+## 2. Nguyên Tắc Thiết Kế (Design Principles)
+1. [Tình trạng hiển thị / Phân cấp Animation theo tier]
+2. [Sử dụng hệ thống thông báo/Badge thông minh]
+
+## 3. Đặc Tả Hình Ảnh (Component Specs)
+### 3.1 Thông số kỹ thuật (Thẩm mỹ)
+* **Kích thước:** [Ví dụ: Height: 60px + SafeArea]
+* **Màu sắc & Shadow:** [Mã màu Hex, Elevation, Border]
+* **Trạng thái:** [Màu Active/Inactive, Font Weight]
+
+### 3.2 Danh sách Element
+* Mô tả chi tiết Icon, Label, Mức hiển thị.
+
+## 4. Chi Tiết Các Màn Hình (Screen Breakdown)
+### 4.1 Layout: [Tên Màn Hình]
+* Theo chiều dọc:
+  - Header / Hero Section
+  - Grid / Danh sách
+  - Action Buttons (Bottom)
+### 4.2 Component Hierarchy (Cấu trúc giao diện)
+```text
+FeatureView (Root)
 ├── HeaderComponent
 ├── ContentSection
-│   ├── ItemList
-│   └── ItemDetail
 └── ActionButtons
 ```
 
-## Data Models
-```swift
-struct Model: Codable, Identifiable {
-    let id: UUID
-    let property: String
-}
+## 5. Đặc Tả Chuyển Động (Animation & Graphic Logic)
+* **Animation Spec:** [Kiểu: Spring, Ease. Damping/Duration cụ thể]
+* **Haptic:** [Rung khi chạm/thành công]
+* **Badge Graphic Logic:** [Vị trí chấm đỏ, điều kiện nhấp nháy/biến mất]
 
-enum ViewState {
-    case idle, loading, loaded([Model]), error(Error)
-}
+## 6. Sơ Đồ Routing (Màn Hình)
+* **Cấu trúc Thư mục UI:** [Sơ đồ App Router, ví dụ: app/(tabs)/explore]
+* Không đi sâu vào Database. Chỉ liệt kê File UI mới.
 ```
-
-## Key Interfaces
-| Component | Purpose | Dependencies |
-|-----------|---------|--------------|
-| ViewModel | State management | Repository |
-| Repository | Data access | API, Cache |
-
-## UI Specs
-- **Colors:** [Primary, Secondary, Accent]
-- **Typography:** [Title, Body, Caption sizes]
-- **Animations:** [Duration, Easing]
-```
-
 ### 3.4. Task Generation (Symphony)
  
 **Script:** `docs/specs/[feature]/init_tasks.sh`

package/workflows/ui/image-gen.md

@@ -0,0 +1,118 @@
+---
+description: 🎨 Image Generator — Tạo App Icons, Mascots và Pets (Hatch-style) với chất lượng Studio (Soft-Edge & Hole-Aware)
+---
+
+# /image-gen — High-Quality Asset Production Workflow
+
+> Quy trình tạo Asset chuyên nghiệp, tự động tách nền và xử lý cạnh mượt mà (PicWish Style).
+> Hỗ trợ tạo Pet Bundle (Trứng + Thú cưng) tương tự Codex nhưng chất lượng cao hơn.
+
+// turbo-all
+
+---
+
+## Sub-commands
+
+### `/image-gen:icon` — Tạo bộ App Icon
+
+1. Hỏi user về chủ đề (Theme), phong cách (Style - mặc định: `vector`), và **Kích thước lưới** (Grid - mặc định: `3x3`).
+2. Tự động tính toán số lượng `{count}` dựa trên lưới (vd: 3x3 -> 9 icons).
+3. Thông báo user: "🎨 Đang phác thảo bộ Icon Set {grid} cho chủ đề: {theme}..."
+4. Thực thi lệnh tạo:
+```bash
+create-icon {theme} {grid} {style}
+```
+5. Sau khi ảnh được tạo, thông báo: "✅ Đã tạo xong và xử lý Soft-Edge. File lưu tại: `assets/generated/`."
+
+### `/image-gen:mascot` — Tạo bộ Linh vật / Mascot
+
+1. Hỏi user về nhân vật (Character), phong cách (Style - mặc định: `chibi`), và **Kích thước lưới** (Grid - mặc định: `3x3`).
+2. Tự động tính toán số lượng `{count}` dựa trên lưới.
+3. Thông báo user: "🧸 Đang thiết kế bộ Mascot {grid} cho: {character}..."
+4. Thực thi lệnh tạo:
+```bash
+create-mascot {character} {grid} {style}
+```
+5. Sau khi ảnh được tạo, thông báo: "✅ Mascot đã sẵn sàng với nền trong suốt hoàn hảo!"
+
+### `/image-gen:pet` — Tạo Pet Bundle (Ấp trứng)
+
+1. Hỏi user về loại Pet (ví dụ: `fire dragon`, `ice phoenix`) và **Kích thước lưới** (Grid - mặc định: `4x4` cho đầy đủ trạng thái).
+2. Thông báo user: "🐣 Đang tạo Pet Bundle ({grid}) cho: {pet_type}..."
+3. Thực thi lệnh tạo:
+```bash
+create-pet {pet_type} {grid}
+```
+4. Tạo thư mục cấu hình: `mkdir -p assets/pets/{pet_id}`
+5. Ghi file `pet.json` mẫu tương thích hệ thống Hatch Pet.
+6. Thông báo: "✨ Pet Bundle đã được đóng gói tại `assets/pets/{pet_id}/`."
+
+### `/image-gen:process` — Xử lý ảnh có sẵn (Hole-Aware)
+
+1. User cung cấp đường dẫn ảnh nguồn (`input_path`).
+2. Xác định tên file đầu ra (`output_name.webp`).
+3. Thực thi lệnh xử lý với thuật toán v3.1:
+```bash
+process-image {input_path} assets/generated/{output_name}.webp 15
+```
+
+### `/image-gen:openrouter` — Tạo ảnh qua OpenRouter (GPT-5.4-Image)
+
+Quy trình sử dụng script `openrouter_image_gen.py` (Codex-grade) hỗ trợ 3 chế độ:
+
+#### 1. Chế độ `generate` (Text-to-Image)
+Dùng để tạo mới asset từ mô tả văn bản, hỗ trợ các tham số Art Direction cực mạnh:
+```bash
+python3 ~/.gemini/antigravity/scripts/openrouter_image_gen.py generate \
+  --prompt "{chủ_thể}" \
+  --style "{phong_cách}" \
+  --lighting "{ánh_sáng}" \
+  --palette "{tông_màu}" \
+  --out "assets/generated/{filename}.webp"
+```
+
+#### 2. Chế độ `edit` (Image-to-Image / Style Transfer)
+Dùng để biến đổi ảnh có sẵn (Local path hoặc URL) sang phong cách khác hoặc chỉnh sửa chi tiết:
+```bash
+python3 ~/.gemini/antigravity/scripts/openrouter_image_gen.py edit \
+  --image "{đường_dẫn_ảnh_gốc}" \
+  --prompt "{mô_tả_chỉnh_sửa}" \
+  --style "{phong_cách_mới}" \
+  --out "assets/generated/{filename}.webp"
+```
+
+#### 3. Chế độ `generate-batch` (Chạy hàng loạt)
+Dùng để sinh hàng loạt asset từ file `.jsonl` (tối đa 100 jobs) với cơ chế Retry tự động:
+```bash
+python3 ~/.gemini/antigravity/scripts/openrouter_image_gen.py generate-batch \
+  --input "jobs.jsonl" \
+  --out-dir "assets/generated/batch/" \
+  --concurrency 3
+```
+
+> **Note**: Script tự động xử lý Upload ảnh local lên `tmpfiles.org` và có cơ chế Exponential Backoff để chống lỗi nghẽn (429).
+
+---
+
+## 🛠 Quality Standards (Codex Hatch Pet Technique)
+
+- **🚫 CẤM DÙNG "Nền trong suốt / Transparent Background"**: TUYỆT ĐỐI KHÔNG thêm các từ khóa "transparent background", "nền trong suốt", "alpha channel" vào prompt sinh ảnh. Việc này sẽ khiến AI (như DALL-E, Midjourney, OpenRouter) sinh ra **nền caro giả (fake checkerboard)** bám dính vào nhân vật, cực kỳ khó xoá.
+- **✅ Background**: LUÔN ưu tiên sử dụng `solid bright green background #00FF00` hoặc `solid white background #FFFFFF` (nếu nhân vật có màu xanh) để AI render chi tiết tốt nhất, không bị đổ bóng (no shadows cast on the background).
+- **🛠 Hậu kỳ (Post-Processing)**: Sau khi sinh ảnh thô có nền Solid, BẮT BUỘC sử dụng công cụ Python Chroma-key cục bộ (process-image hoặc process_sprites.py) để gỡ nền.
+- **Edges & Holes**: Script Python sẽ tự động áp dụng Alpha Feathering (Blur 0x3) để triệt tiêu răng cưa, và xóa các vùng kẹt trong cánh/tay nhưng bảo vệ đôi mắt (Morphology Close).
+
+---
+
+## Communication
+
+Mỗi khi bắt đầu một lượt generate:
+```
+🎨 [Antigravity Artist] Đang khởi tạo xưởng vẽ cho {asset_type}...
+🚀 Chiến lược: Neutral White + Soft-Edge Alpha.
+```
+
+Sau khi hoàn tất:
+```
+✅ Hoàn tất! Asset của bạn đã được tối ưu hóa WebP và tách nền sạch sẽ.
+📍 Vị trí: [đường dẫn]
+```