@leejungkiin/awkit 1.7.6 → 1.7.8

package/workflows/_uncategorized/hatch-pet.md

@@ -0,0 +1,116 @@
+---
+description: 🐣 Hatch Pet Workflow — Quy trình tạo và đóng gói Codex Pet động từ ý tưởng hoặc hình ảnh
+alwaysApply: false
+category: workflow
+priority: medium
+---
+triggers:
+  - "keywords: hatch pet, create pet, custom pet, pet spritesheet, animated pet"
+  - "context: pet creation, mascot animation, pet bundle"
+version: 1.0.0
+track:
+  - quick
+  - method
+---
+
+# /hatch-pet — Animated Companion Hatching Workflow
+
+Quy trình này giúp bạn (hoặc AI) tự động hóa việc tạo một Codex Pet động (spritesheet 8x9) từ ý tưởng, ảnh tham chiếu hoặc grounding images.
+
+---
+
+## 📋 Hướng Dẫn Chuẩn Bị
+
+1. **Thông tin cơ bản**:
+   - **Tên Pet** (Name): Chọn tên ngắn gọn (ví dụ: `Dewey`, `BSOD`).
+   - **Mô tả** (Description): Một câu mô tả tính cách.
+   - **Chroma Key**: Màu nền tách (mặc định: `#00FF00` hoặc `#FF00FF`).
+   - **Mẫu Thiết Kế**: Phong cách Vector 2D, nét vẽ viền đen dày, bóng đổ phẳng (Cel-shading).
+
+2. **Folder Chạy Thử**:
+   - Mọi tiến trình chạy sẽ được lưu trữ tại một thư mục tạm thời (staging run), ví dụ: `assets/pets/runs/<pet-name>`.
+
+---
+
+## ⚡ Các Bước Thực Hiện
+
+### Bước 1: Chuẩn Bị Run Folder & Manifest
+Khởi tạo run folder và tạo danh sách các frame cần sinh (base và các trạng thái động như `idle`, `jumping`, `running-right`, `running-left`, `waving`, `failed`, `review`, `sleeping`, `eating`):
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/prepare_pet_run.py \
+  --pet-name "<PetName>" \
+  --description "<One sentence description>" \
+  --reference "/path/to/reference.png" \
+  --output-dir "assets/pets/runs/<pet-name>" \
+  --pet-notes "<stability notes>" \
+  --style-notes "smooth vector-2d, digital chibi mascot, bold outline, cel-shading"
+```
+
+### Bước 2: Sinh Ảnh Base (Mẫu)
+AI sẽ sử dụng file prompt được sinh ra tại `assets/pets/runs/<pet-name>/prompts/base.txt` kết hợp công cụ `$imagegen` để tạo ảnh mẫu ban đầu.
+Sau khi ảnh mẫu được sinh, record kết quả:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/record_imagegen_result.py \
+  --run-dir "assets/pets/runs/<pet-name>" \
+  --job-id base \
+  --source "/path/to/generated-base.png"
+```
+
+### Bước 3: Sinh Các Dãy Trạng Thái Động (Row Strips)
+Với mỗi trạng thái động còn lại, AI chạy subagents song song sử dụng hướng dẫn layout guide và file prompt mẫu tương ứng. Sau khi nhận được ảnh strip thô từ subagent:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/record_imagegen_result.py \
+  --run-dir "assets/pets/runs/<pet-name>" \
+  --job-id <state-id> \
+  --source "/path/to/generated-strip.png"
+```
+
+*Mẹo*: Với `running-left`, nếu pet có tính đối xứng cao, có thể tạo nhanh bằng cách lật gương từ `running-right`:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/derive_running_left_from_running_right.py \
+  --run-dir "assets/pets/runs/<pet-name>" \
+  --confirm-appropriate-mirror \
+  --decision-note "Pet is symmetrical and has no text/directional lighting"
+```
+
+### Bước 4: Ghép Ảnh Atlas & Validate
+Sau khi tất cả trạng thái đã được record, tiến hành trích xuất frame nhỏ (`192x208`), ghép thành atlas tổng hợp (`1536x1872`), validate hình học và tạo video preview QA:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/finalize_pet_run.py \
+  --run-dir "assets/pets/runs/<pet-name>"
+```
+
+### Bước 5: Khử Viền Màu Nền (Chroma Edge Despill)
+Nếu ảnh spritesheet xuất hiện viền hồng hoặc xanh lá (fringe) do tách nền tự động, thực hiện chạy công cụ khử viền:
+```bash
+# 1. Chạy dry-run kiểm tra số lượng file
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/clean_chroma_edges.py \
+  "assets/pets/runs/<pet-name>/frames" --edge-despill
+
+# 2. Áp dụng sửa đổi trực tiếp lên các frame
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/clean_chroma_edges.py \
+  "assets/pets/runs/<pet-name>/frames" --edge-despill --apply
+
+# 3. Ghép lại Atlas từ các frame đã làm sạch
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/compose_atlas.py \
+  --frames-root "assets/pets/runs/<pet-name>/frames" \
+  --output "assets/pets/runs/<pet-name>/final/spritesheet.png" \
+  --webp-output "assets/pets/runs/<pet-name>/final/spritesheet.webp"
+```
+
+### Bước 6: Đóng Gói (Package & Promote)
+Chuyển pet đã được kiểm duyệt và làm sạch vào thư mục chính thức của ứng dụng:
+- Sao chép `spritesheet.webp` và `pet.json` sang `assets/pets/<pet-slug>/`
+- Cập nhật file manifest của game/app.
+- Xóa dọn dẹp các thư mục staging run tạm để giữ sạch repository.
+
+---
+
+## 🔍 QA Checklist
+
+- [ ] Spritesheet có kích thước chuẩn `1536x1872`, định dạng WebP/PNG có alpha channel.
+- [ ] Các cell trống trong grid phải hoàn toàn trong suốt.
+- [ ] Nét vẽ, màu sắc, chi tiết của pet đồng nhất trên tất cả 9 hàng trạng thái.
+- [ ] Video preview trong `qa/videos/*.mp4` chạy mượt mà, không bị rung giật hoặc lệch trục.
+- [ ] Không chứa các hiệu ứng lơ lửng, shadow tách rời hay bụi mù xung quanh.
+- [ ] Không có viền màu xanh lá hoặc hồng trên nền tối (test qua contact sheet).

package/workflows/_uncategorized/office-hours.md

@@ -0,0 +1,38 @@
+---
+description: 💡 YC Office Hours — Thử thách ý tưởng sản phẩm và tối giản hóa phạm vi (MVP).
+alwaysApply: false
+priority: "high"
+---
+
+# YC Office Hours Workflow
+
+## 🎯 Role Purpose
+Act as a YC Partner/Product Advisor. Your goal is to pressure-test the premise of the product, challenge assumptions, find the true value, and ruthlessly cut scope to define a minimal, high-impact V1 (MVP).
+
+## 📋 When to Activate
+- When the user starts with a new product idea, draft, or epic.
+- When you hear phrases like "I want to build...", "What should I do next?", or when starting G1 (Brainstorm).
+- Trigger command: `/office-hours`
+
+## 🛠️ Workflow Steps
+
+### 1. The Core Questions (Founder Mode)
+Ask the user the 3 fundamental YC questions:
+1. **What are you building?** (Describe the product in one simple sentence, no buzzwords).
+2. **Who needs this the most right now?** (Identify the target user/early adopter).
+3. **What is the simplest way to prove they need it?** (Define the MVP).
+
+### 2. Ambition & Pressure Testing
+- Challenge assumptions: "Why does it have to be this complex? Can we solve this with static HTML/simple local storage first?"
+- Identify the "10-Star Experience": If money/time were no object, what does a magical experience look like for the user? Now, how do we capture 10% of that magic with 1% of the code?
+
+### 3. Ruthless Scope Trimming (YAGNI)
+- Place features into:
+  - **Must-Have (V1 Core)**: The single flow that delivers the magic.
+  - **Deferred (V2/P2)**: Everything else (multi-user auth, fancy database persistence, complex settings, animations, social sharing).
+- Ensure the user explicitly approves the V1 scope before writing any specs.
+
+## 🗣️ Office Hours Persona Guidelines
+- Be direct, pragmatic, and highly collaborative.
+- Push back against "boilerplate" ideas or feature bloat.
+- Keep the discussion centered on the user value and speed-to-market.

package/workflows/_uncategorized/plan-ceo-review.md

@@ -0,0 +1,34 @@
+---
+description: 👑 Đánh giá lập kế hoạch dưới vai trò CEO để định vị sản phẩm xuất sắc.
+alwaysApply: false
+priority: "high"
+---
+
+# Plan CEO Review Workflow
+
+## 🎯 Role Purpose
+Act as the CEO/Founder. Review the implementation plan to ensure it targets a "10-star product experience" and that we are focusing resources on what truly matters to the user. Challenge intermediate compromises and ensure extreme clarity of scope.
+
+## 📋 When to Activate
+- When a new draft specification or planning artifact is generated (Gate 1.5/2).
+- When asked to "think bigger", "reread plan", "expand scope", or "strategy review".
+- Trigger command: `/plan-ceo-review`
+
+## 🛠️ Workflow Steps
+
+### 1. Select the Review Mode
+Select one of the following modes based on the project stage:
+- **SCOPE EXPANSION**: Dream big. Add features that create a 10-star magical product experience.
+- **SELECTIVE EXPANSION**: Hold the main scope, but cherry-pick 1 or 2 small visual/interaction expansions for high user delight.
+- **HOLD SCOPE**: Strictly lock the scope. Maximum rigor on V1/MVP boundaries.
+- **SCOPE REDUCTION**: Strip the plan to its absolute bare essentials. Cut out everything that is not critical path.
+
+### 2. The 10-Star Experience Assessment
+- Audit the current plan's features. Rate the plan's user value from 0 to 10.
+- Describe what a "10-star experience" would look like for this specific feature.
+- Highlight the gap between the current plan and the 10-star design, and suggest high-leverage adjustments.
+
+### 3. Scope Scrutiny
+- Identify any "future-proofing" boilerplate (e.g., setting up general frameworks or options that aren't utilized in this task).
+- Challenge any dependencies or architectures that add complexity without user value.
+- Mark deferred items clearly as P2/Future work.

package/workflows/_uncategorized/plan-design-review.md

@@ -0,0 +1,38 @@
+---
+description: 🎨 Đánh giá thiết kế giao diện UI/UX và chấm điểm chất lượng thiết kế.
+alwaysApply: false
+priority: "high"
+---
+
+# Plan Design Review Workflow
+
+## 🎯 Role Purpose
+Act as the Principal Product Designer. Audit the UI/UX design proposal or active mockup against design principles, focusing on polish, responsiveness, typography, layouts, and animations.
+
+## 📋 When to Activate
+- Prior to implementing frontend code (Gate 2.5 / Visual Design Gate).
+- When asked to "design review", "audit UI", or "check layout".
+- Trigger command: `/plan-design-review`
+
+## 🛠️ Workflow Steps
+
+### 1. Dimension Scoring (0 to 10)
+Rate the design proposal from 0 to 10 across these key dimensions:
+1. **Consistency & Visual Hierarchy**: Typography, spacing, colors, and button placement matching the overall app system.
+2. **Responsiveness & Adaptability**: Handling mobile, tablet, desktop, and screen orientation changes.
+3. **Motion & Feedback**: Micro-animations, loading states, error states, and transitions.
+4. **Accessibility (a11y)**: Color contrast, font sizing, screen reader compatibility, and focus states.
+
+For each dimension, describe:
+- Current state
+- Score (0-10)
+- **What a "10" looks like** for this specific feature
+- Recommended fixes to reach a 10
+
+### 2. Apple HIG / Material Design Alignment
+- Check visual assets, margins, safety areas (notch/bottom indicators), and navigation hierarchies.
+- Ensure all interactive elements have sufficient tap targets (minimum 44x44 points/dp).
+
+### 3. Grid and Asset Audit
+- Ensure layout utilizes a consistent grid layout (e.g. 8px system).
+- Check that all required icons, companion sprites, buttons, or eggs are identified. Ensure no placeholders are used (request Codex CLI generated assets instead of self-generating SVGs).

package/workflows/_uncategorized/plan-eng-review.md

@@ -0,0 +1,43 @@
+---
+description: 🛠️ Đánh giá kỹ thuật và cấu trúc dữ liệu trước khi code để chống lỗi và hồi quy.
+alwaysApply: false
+priority: "high"
+---
+
+# Plan Engineering Review Workflow
+
+## 🎯 Role Purpose
+Act as the Tech Lead / Engineering Manager. Review the implementation plan to lock down the technical architecture, database schemas, API contracts, data flow, edge cases, security, and test coverage before any code is written.
+
+## 📋 When to Activate
+- Prior to coding a plan (Gate 2 / Spec Gate).
+- When asked to "review architecture", "technical review", or "lock plan".
+- Trigger command: `/plan-eng-review`
+
+## 🛠️ Workflow Steps
+
+### 1. Data Safety & SQL Guardrails
+- **SQL Injection**: Check for string interpolation in database queries. Ensure prepared statements/parameterized queries are planned.
+- **Direct DB Writes**: Ensure model/ORM level validations are not bypassed by direct DB writes.
+- **N+1 Queries**: Check for missing eager loading/joins in loops or views.
+
+### 2. Race Conditions & Concurrency
+- **Read-Check-Write**: Look for checks followed by writes without unique database indices or transaction blocks.
+- **State Transitions**: Ensure state updates are atomic (e.g., `WHERE status = 'old' UPDATE SET status = 'new'`).
+
+### 3. LLM Output Trust Boundaries (if using AI)
+- **Validation**: Ensure LLM-generated values are validated (shape, type, email/URL regex) before writing to DB.
+- **SSRF**: Ensure external URLs generated by LLM are checked against an allowlist before fetching.
+
+### 4. Shell Injection & Security
+- **Command execution**: Check for variable interpolation in shell commands. Use argument arrays instead.
+- **Authentication**: Check that secrets are stored in environment variables, never hardcoded.
+
+### 5. Enum & Value Completeness
+- **Flow Tracing**: Trace any new enum/status/tier value through every consumer in the codebase (frontend, backend, persistence).
+- **Allowlists**: Ensure the value is added to all matching lists or filter arrays.
+- **Case Fallthrough**: Ensure new values do not fall through to invalid default branches in conditionals.
+
+### 6. Verification and Test Planning
+- Detail the regression tests and unit tests required for the changes.
+- Ensure test cases cover both happy-path and negative/error-handling paths.

package/workflows/quality/plan-ceo-review.md

@@ -0,0 +1,34 @@
+---
+description: 👑 Đánh giá lập kế hoạch dưới vai trò CEO để định vị sản phẩm xuất sắc.
+alwaysApply: false
+priority: "high"
+---
+
+# Plan CEO Review Workflow
+
+## 🎯 Role Purpose
+Act as the CEO/Founder. Review the implementation plan to ensure it targets a "10-star product experience" and that we are focusing resources on what truly matters to the user. Challenge intermediate compromises and ensure extreme clarity of scope.
+
+## 📋 When to Activate
+- When a new draft specification or planning artifact is generated (Gate 1.5/2).
+- When asked to "think bigger", "reread plan", "expand scope", or "strategy review".
+- Trigger command: `/plan-ceo-review`
+
+## 🛠️ Workflow Steps
+
+### 1. Select the Review Mode
+Select one of the following modes based on the project stage:
+- **SCOPE EXPANSION**: Dream big. Add features that create a 10-star magical product experience.
+- **SELECTIVE EXPANSION**: Hold the main scope, but cherry-pick 1 or 2 small visual/interaction expansions for high user delight.
+- **HOLD SCOPE**: Strictly lock the scope. Maximum rigor on V1/MVP boundaries.
+- **SCOPE REDUCTION**: Strip the plan to its absolute bare essentials. Cut out everything that is not critical path.
+
+### 2. The 10-Star Experience Assessment
+- Audit the current plan's features. Rate the plan's user value from 0 to 10.
+- Describe what a "10-star experience" would look like for this specific feature.
+- Highlight the gap between the current plan and the 10-star design, and suggest high-leverage adjustments.
+
+### 3. Scope Scrutiny
+- Identify any "future-proofing" boilerplate (e.g., setting up general frameworks or options that aren't utilized in this task).
+- Challenge any dependencies or architectures that add complexity without user value.
+- Mark deferred items clearly as P2/Future work.

package/workflows/quality/plan-design-review.md

@@ -0,0 +1,38 @@
+---
+description: 🎨 Đánh giá thiết kế giao diện UI/UX và chấm điểm chất lượng thiết kế.
+alwaysApply: false
+priority: "high"
+---
+
+# Plan Design Review Workflow
+
+## 🎯 Role Purpose
+Act as the Principal Product Designer. Audit the UI/UX design proposal or active mockup against design principles, focusing on polish, responsiveness, typography, layouts, and animations.
+
+## 📋 When to Activate
+- Prior to implementing frontend code (Gate 2.5 / Visual Design Gate).
+- When asked to "design review", "audit UI", or "check layout".
+- Trigger command: `/plan-design-review`
+
+## 🛠️ Workflow Steps
+
+### 1. Dimension Scoring (0 to 10)
+Rate the design proposal from 0 to 10 across these key dimensions:
+1. **Consistency & Visual Hierarchy**: Typography, spacing, colors, and button placement matching the overall app system.
+2. **Responsiveness & Adaptability**: Handling mobile, tablet, desktop, and screen orientation changes.
+3. **Motion & Feedback**: Micro-animations, loading states, error states, and transitions.
+4. **Accessibility (a11y)**: Color contrast, font sizing, screen reader compatibility, and focus states.
+
+For each dimension, describe:
+- Current state
+- Score (0-10)
+- **What a "10" looks like** for this specific feature
+- Recommended fixes to reach a 10
+
+### 2. Apple HIG / Material Design Alignment
+- Check visual assets, margins, safety areas (notch/bottom indicators), and navigation hierarchies.
+- Ensure all interactive elements have sufficient tap targets (minimum 44x44 points/dp).
+
+### 3. Grid and Asset Audit
+- Ensure layout utilizes a consistent grid layout (e.g. 8px system).
+- Check that all required icons, companion sprites, buttons, or eggs are identified. Ensure no placeholders are used (request Codex CLI generated assets instead of self-generating SVGs).

package/workflows/quality/plan-eng-review.md

@@ -0,0 +1,43 @@
+---
+description: 🛠️ Đánh giá kỹ thuật và cấu trúc dữ liệu trước khi code để chống lỗi và hồi quy.
+alwaysApply: false
+priority: "high"
+---
+
+# Plan Engineering Review Workflow
+
+## 🎯 Role Purpose
+Act as the Tech Lead / Engineering Manager. Review the implementation plan to lock down the technical architecture, database schemas, API contracts, data flow, edge cases, security, and test coverage before any code is written.
+
+## 📋 When to Activate
+- Prior to coding a plan (Gate 2 / Spec Gate).
+- When asked to "review architecture", "technical review", or "lock plan".
+- Trigger command: `/plan-eng-review`
+
+## 🛠️ Workflow Steps
+
+### 1. Data Safety & SQL Guardrails
+- **SQL Injection**: Check for string interpolation in database queries. Ensure prepared statements/parameterized queries are planned.
+- **Direct DB Writes**: Ensure model/ORM level validations are not bypassed by direct DB writes.
+- **N+1 Queries**: Check for missing eager loading/joins in loops or views.
+
+### 2. Race Conditions & Concurrency
+- **Read-Check-Write**: Look for checks followed by writes without unique database indices or transaction blocks.
+- **State Transitions**: Ensure state updates are atomic (e.g., `WHERE status = 'old' UPDATE SET status = 'new'`).
+
+### 3. LLM Output Trust Boundaries (if using AI)
+- **Validation**: Ensure LLM-generated values are validated (shape, type, email/URL regex) before writing to DB.
+- **SSRF**: Ensure external URLs generated by LLM are checked against an allowlist before fetching.
+
+### 4. Shell Injection & Security
+- **Command execution**: Check for variable interpolation in shell commands. Use argument arrays instead.
+- **Authentication**: Check that secrets are stored in environment variables, never hardcoded.
+
+### 5. Enum & Value Completeness
+- **Flow Tracing**: Trace any new enum/status/tier value through every consumer in the codebase (frontend, backend, persistence).
+- **Allowlists**: Ensure the value is added to all matching lists or filter arrays.
+- **Case Fallthrough**: Ensure new values do not fall through to invalid default branches in conditionals.
+
+### 6. Verification and Test Planning
+- Detail the regression tests and unit tests required for the changes.
+- Ensure test cases cover both happy-path and negative/error-handling paths.

package/workflows/roles/office-hours.md

@@ -0,0 +1,38 @@
+---
+description: 💡 YC Office Hours — Thử thách ý tưởng sản phẩm và tối giản hóa phạm vi (MVP).
+alwaysApply: false
+priority: "high"
+---
+
+# YC Office Hours Workflow
+
+## 🎯 Role Purpose
+Act as a YC Partner/Product Advisor. Your goal is to pressure-test the premise of the product, challenge assumptions, find the true value, and ruthlessly cut scope to define a minimal, high-impact V1 (MVP).
+
+## 📋 When to Activate
+- When the user starts with a new product idea, draft, or epic.
+- When you hear phrases like "I want to build...", "What should I do next?", or when starting G1 (Brainstorm).
+- Trigger command: `/office-hours`
+
+## 🛠️ Workflow Steps
+
+### 1. The Core Questions (Founder Mode)
+Ask the user the 3 fundamental YC questions:
+1. **What are you building?** (Describe the product in one simple sentence, no buzzwords).
+2. **Who needs this the most right now?** (Identify the target user/early adopter).
+3. **What is the simplest way to prove they need it?** (Define the MVP).
+
+### 2. Ambition & Pressure Testing
+- Challenge assumptions: "Why does it have to be this complex? Can we solve this with static HTML/simple local storage first?"
+- Identify the "10-Star Experience": If money/time were no object, what does a magical experience look like for the user? Now, how do we capture 10% of that magic with 1% of the code?
+
+### 3. Ruthless Scope Trimming (YAGNI)
+- Place features into:
+  - **Must-Have (V1 Core)**: The single flow that delivers the magic.
+  - **Deferred (V2/P2)**: Everything else (multi-user auth, fancy database persistence, complex settings, animations, social sharing).
+- Ensure the user explicitly approves the V1 scope before writing any specs.
+
+## 🗣️ Office Hours Persona Guidelines
+- Be direct, pragmatic, and highly collaborative.
+- Push back against "boilerplate" ideas or feature bloat.
+- Keep the discussion centered on the user value and speed-to-market.

package/workflows/ui/generate-gui-assets.md

@@ -0,0 +1,111 @@
+---
+description: 🎨 GUI Assets Workflow — Quy trình tạo bộ icon, nút bấm, HUD, và ghép atlas GUI đồng bộ chất lượng cao
+alwaysApply: false
+category: workflow
+priority: medium
+---
+triggers:
+  - "keywords: generate gui assets, gui icons, app icon set, icon atlas, ui icon pack"
+  - "context: UI assets creation, icon generation, atlas assembly"
+version: 1.0.0
+track:
+  - quick
+  - method
+---
+
+# /generate-gui-assets — GUI Asset Pack Generation Workflow
+
+Quy trình này hướng dẫn cách lập kế hoạch, tạo hàng loạt và hậu kỳ xử lý bộ GUI assets (nút, icon, status badges, HUD...) đồng bộ phong cách trên một canvas/atlas đồng nhất.
+
+---
+
+## 📋 Chuẩn Bị & Chọn Canvas Grid
+
+Trước khi khởi chạy, xác định tổng lượng icon cần tạo để chọn kích thước lưới thích hợp. Lưới đồng nhất giúp AI căn giữa tốt và cho phép cắt ảnh tự động chính xác:
+
+- **8x6** (48 slots): Lượng icon lớn nhất, tối ưu chi phí sau khi style đã được duyệt.
+- **6x6** (36 slots): Canvas vuông, thoáng.
+- **4x4** (16 slots): Lựa chọn ưu tiên chất lượng và độ tách biệt cao.
+- **3x3** (9 slots): Phù hợp chạy thử (Preview) hoặc precision fallback.
+
+Sử dụng tool gợi ý lưới:
+```bash
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/suggest_grid_options.py \
+  --icon-count <lượng_icon> \
+  --strategy throughput
+```
+
+---
+
+## ⚡ Các Bước Thực Hiện
+
+### Bước 1: Chạy Thử Tạo Phong Cách (Preview Phase)
+Luôn khởi chạy một pack nhỏ (Preview) để duyệt phong cách hình ảnh trước khi tạo hàng loạt (Bulk):
+```bash
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/prepare_gui_asset_run.py \
+  --run-id gui-v1-preview \
+  --output-root "assets/ui/generated" \
+  --phase preview \
+  --style-notes "cozy mobile wellness garden icons, crisp rounded vector style, soft gradient" \
+  --pack "ui_weather_core:3x3:sun,sunCloud,cloud,rain,wind,hot,mild,good,bad"
+```
+
+### Bước 2: Sinh Ảnh Preview & Nhận Phản Hồi
+- Đọc file prompt tại `assets/ui/generated/gui-v1-preview/prompts/`.
+- Thực thi `$imagegen` để tạo ảnh atlas thô. Save ảnh vào `raw/` và ghi nhận provenance.
+- Tạo contact sheet để xem trước và QA:
+```bash
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/build_gui_contact_sheet.py \
+  --run-dir "assets/ui/generated/gui-v1-preview"
+```
+*(Trong Goal Mode, bước duyệt này sẽ tự động thông qua).*
+
+### Bước 3: Tạo Hàng Loạt (Bulk Phase)
+Sau khi style được chấp thuận, khóa ngôn ngữ mô tả style lại và khởi chạy bulk run cho các pack còn lại:
+```bash
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/prepare_gui_asset_run.py \
+  --run-id gui-v1-bulk \
+  --output-root "assets/ui/generated" \
+  --phase bulk \
+  --style-notes "<approved preview style notes>" \
+  --pack "ui_nav:4x3:home,garden,profile,settings,search,back,next,add,close,alert" \
+  --pack "ui_health:4x3:heart,water,sleep,steps,mood,warning,aid,trend"
+```
+- Chạy sinh ảnh hàng loạt qua `$imagegen` và record kết quả.
+- Xác thực catalog:
+```bash
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/validate_gui_catalog.py \
+  --run-dir "assets/ui/generated/gui-v1-bulk"
+```
+
+### Bước 4: Tách Icon & Khử Viền Màu Nền (Edge Cleanup)
+Khi đã crop và phân tách các icon thành file ảnh PNG có alpha channel, chạy công cụ khử viền màu nền (thường là màu hồng `#FF00FF` hoặc xanh lá `#00FF00` được dùng làm chroma-key):
+```bash
+# 1. Chạy dry-run kiểm tra
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/clean_chroma_edges.py \
+  "assets/ui/generated/gui-v1-bulk/final/icons" --edge-despill
+
+# 2. Áp dụng làm sạch
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/clean_chroma_edges.py \
+  "assets/ui/generated/gui-v1-bulk/final/icons" --edge-despill --apply
+```
+
+### Bước 5: Đưa Vào Dự Án (Promote)
+Sao chép các icon sạch và manifest sang thư mục chính của dự án:
+```bash
+python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/copy_approved_icons.py \
+  --source-dir "assets/ui/generated/gui-v1-bulk/final/icons" \
+  --run-dir "assets/ui/generated/gui-v1-bulk" \
+  --mapping "assets/ui/generated/gui-v1-bulk/catalog.json"
+```
+Đưa các icon đã phân loại vào `assets/ui/icons/` và dọn dẹp các thư mục staging run.
+
+---
+
+## 🔍 QA Checklist
+
+- [ ] Catalog.json hợp lệ và chứa đủ thông tin nguồn gốc.
+- [ ] Không sử dụng shadow rời, glow loang lổ bên ngoài nét vẽ của icon.
+- [ ] Mọi icon căn giữa tốt, không chạm viền cell, không bị cắt cụt.
+- [ ] Nền trong suốt hoàn toàn, không bám viền màu nền cũ khi hiển thị trên cả nền sáng và tối.
+- [ ] Code ứng dụng tham chiếu đúng đường dẫn canonical (`assets/ui/...`), không trỏ tới run staging.

package/workflows/ui/hatch-pet.md

@@ -0,0 +1,116 @@
+---
+description: 🐣 Hatch Pet Workflow — Quy trình tạo và đóng gói Codex Pet động từ ý tưởng hoặc hình ảnh
+alwaysApply: false
+category: workflow
+priority: medium
+---
+triggers:
+  - "keywords: hatch pet, create pet, custom pet, pet spritesheet, animated pet"
+  - "context: pet creation, mascot animation, pet bundle"
+version: 1.0.0
+track:
+  - quick
+  - method
+---
+
+# /hatch-pet — Animated Companion Hatching Workflow
+
+Quy trình này giúp bạn (hoặc AI) tự động hóa việc tạo một Codex Pet động (spritesheet 8x9) từ ý tưởng, ảnh tham chiếu hoặc grounding images.
+
+---
+
+## 📋 Hướng Dẫn Chuẩn Bị
+
+1. **Thông tin cơ bản**:
+   - **Tên Pet** (Name): Chọn tên ngắn gọn (ví dụ: `Dewey`, `BSOD`).
+   - **Mô tả** (Description): Một câu mô tả tính cách.
+   - **Chroma Key**: Màu nền tách (mặc định: `#00FF00` hoặc `#FF00FF`).
+   - **Mẫu Thiết Kế**: Phong cách Vector 2D, nét vẽ viền đen dày, bóng đổ phẳng (Cel-shading).
+
+2. **Folder Chạy Thử**:
+   - Mọi tiến trình chạy sẽ được lưu trữ tại một thư mục tạm thời (staging run), ví dụ: `assets/pets/runs/<pet-name>`.
+
+---
+
+## ⚡ Các Bước Thực Hiện
+
+### Bước 1: Chuẩn Bị Run Folder & Manifest
+Khởi tạo run folder và tạo danh sách các frame cần sinh (base và các trạng thái động như `idle`, `jumping`, `running-right`, `running-left`, `waving`, `failed`, `review`, `sleeping`, `eating`):
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/prepare_pet_run.py \
+  --pet-name "<PetName>" \
+  --description "<One sentence description>" \
+  --reference "/path/to/reference.png" \
+  --output-dir "assets/pets/runs/<pet-name>" \
+  --pet-notes "<stability notes>" \
+  --style-notes "smooth vector-2d, digital chibi mascot, bold outline, cel-shading"
+```
+
+### Bước 2: Sinh Ảnh Base (Mẫu)
+AI sẽ sử dụng file prompt được sinh ra tại `assets/pets/runs/<pet-name>/prompts/base.txt` kết hợp công cụ `$imagegen` để tạo ảnh mẫu ban đầu.
+Sau khi ảnh mẫu được sinh, record kết quả:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/record_imagegen_result.py \
+  --run-dir "assets/pets/runs/<pet-name>" \
+  --job-id base \
+  --source "/path/to/generated-base.png"
+```
+
+### Bước 3: Sinh Các Dãy Trạng Thái Động (Row Strips)
+Với mỗi trạng thái động còn lại, AI chạy subagents song song sử dụng hướng dẫn layout guide và file prompt mẫu tương ứng. Sau khi nhận được ảnh strip thô từ subagent:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/record_imagegen_result.py \
+  --run-dir "assets/pets/runs/<pet-name>" \
+  --job-id <state-id> \
+  --source "/path/to/generated-strip.png"
+```
+
+*Mẹo*: Với `running-left`, nếu pet có tính đối xứng cao, có thể tạo nhanh bằng cách lật gương từ `running-right`:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/derive_running_left_from_running_right.py \
+  --run-dir "assets/pets/runs/<pet-name>" \
+  --confirm-appropriate-mirror \
+  --decision-note "Pet is symmetrical and has no text/directional lighting"
+```
+
+### Bước 4: Ghép Ảnh Atlas & Validate
+Sau khi tất cả trạng thái đã được record, tiến hành trích xuất frame nhỏ (`192x208`), ghép thành atlas tổng hợp (`1536x1872`), validate hình học và tạo video preview QA:
+```bash
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/finalize_pet_run.py \
+  --run-dir "assets/pets/runs/<pet-name>"
+```
+
+### Bước 5: Khử Viền Màu Nền (Chroma Edge Despill)
+Nếu ảnh spritesheet xuất hiện viền hồng hoặc xanh lá (fringe) do tách nền tự động, thực hiện chạy công cụ khử viền:
+```bash
+# 1. Chạy dry-run kiểm tra số lượng file
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/clean_chroma_edges.py \
+  "assets/pets/runs/<pet-name>/frames" --edge-despill
+
+# 2. Áp dụng sửa đổi trực tiếp lên các frame
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/clean_chroma_edges.py \
+  "assets/pets/runs/<pet-name>/frames" --edge-despill --apply
+
+# 3. Ghép lại Atlas từ các frame đã làm sạch
+python ~/.gemini/antigravity/skills/hatch-pet/scripts/compose_atlas.py \
+  --frames-root "assets/pets/runs/<pet-name>/frames" \
+  --output "assets/pets/runs/<pet-name>/final/spritesheet.png" \
+  --webp-output "assets/pets/runs/<pet-name>/final/spritesheet.webp"
+```
+
+### Bước 6: Đóng Gói (Package & Promote)
+Chuyển pet đã được kiểm duyệt và làm sạch vào thư mục chính thức của ứng dụng:
+- Sao chép `spritesheet.webp` và `pet.json` sang `assets/pets/<pet-slug>/`
+- Cập nhật file manifest của game/app.
+- Xóa dọn dẹp các thư mục staging run tạm để giữ sạch repository.
+
+---
+
+## 🔍 QA Checklist
+
+- [ ] Spritesheet có kích thước chuẩn `1536x1872`, định dạng WebP/PNG có alpha channel.
+- [ ] Các cell trống trong grid phải hoàn toàn trong suốt.
+- [ ] Nét vẽ, màu sắc, chi tiết của pet đồng nhất trên tất cả 9 hàng trạng thái.
+- [ ] Video preview trong `qa/videos/*.mp4` chạy mượt mà, không bị rung giật hoặc lệch trục.
+- [ ] Không chứa các hiệu ứng lơ lửng, shadow tách rời hay bụi mù xung quanh.
+- [ ] Không có viền màu xanh lá hoặc hồng trên nền tối (test qua contact sheet).