@leejungkiin/awkit 1.7.7 → 1.7.8

package/skills/code-review/SKILL.md

@@ -1,87 +1,59 @@
 ---
 name: code-review
-description: Use when completing tasks, implementing features, or before merging. Dispatch structured code review with severity classification via Codex CLI.
+description: Use when completing tasks, implementing features, or before merging. Dispatch structured code review with severity classification.
 ---
 
-<!-- ⚠️ SMART REVIEW AGENT — Intelligent routing for Security, Localization, Compliance, and Quality -->
-
-# Smart Code Review
+# Smart Code Review v2.0 (GStack-Powered)
 
 ## Overview
+Perform structured code reviews on modified files (using git diff against origin/main or staged changes) to catch issues before they are committed or merged.
+Antigravity uses the `codex` CLI (or active LLM runner) to perform deep, multi-file code reviews across specific safety and quality domains.
 
-Review early, review often. Catch issues before they cascade.
-Antigravity uses `codex` CLI to perform deep, multi-file code reviews across specific domains (Security, Localization, Compliance, Quality). 
-
-**Core principle:** Actionable, domain-specific feedback via Multi-Agent Flow.
-
-## The Review Modules (Execution via Codex CLI)
+## 📋 The Two-Pass Review Rubric
 
-Thay vì tự đọc diff và đánh giá, Antigravity **BẮT BUỘC** gọi `codex` CLI để thực hiện Code Review nhằm mở rộng Context Window và sử dụng subagent chuyên dụng.
-Dưới đây là 5 Module Review Tự Động. Antigravity tự động map intent của User để chọn Module phù hợp:
+Reviews are divided into two distinct passes depending on severity:
 
-### 1. 🛡️ Security & Privacy Review (Thay thế `/audit`)
-**Dùng khi User yêu cầu:** *"review bảo mật", "check security", "kiểm tra an toàn"*
+### Pass 1 — CRITICAL (Highest Severity)
+*   **SQL & Data Safety:** String interpolation in SQL (require parameterized queries/prepared statements), TOCTOU race conditions (require atomic `WHERE` checks), and bypassing model validations for direct DB writes.
+*   **Race Conditions & Concurrency:** Read-check-write patterns without uniqueness constraints, find-or-create without unique DB indices, and status transitions that are not atomic.
+*   **LLM Output Trust Boundaries:** Ensure LLM-generated values are type/shape/format checked before saving to database, and external URLs generated by LLM are allowlisted.
+*   **Shell Injection:** Variable interpolation in shell execution commands (e.g. `subprocess` with `shell=True` or `exec`/`eval` without sandboxing). Use argument arrays instead.
+*   **Enum & Value Completeness:** When a new enum, status string, tier, or type constant is added, trace it through every switch, filter, or conditional block across the entire project. Ensure all consumers handle the new value.
 
-```bash
-codex -p "Thực hiện Security & Privacy Review. Hãy quét khắt khe các điểm sau:
-1. Hardcoded API Keys/Secrets trong code hoặc file config.
-2. Dữ liệu PII (Personal Identifiable Information) có bị log ra console không (print, console.log).
-3. Lỗ hổng OWASP (SQL Injection, XSS, thiếu Rate Limiting, CORS/Headers lỏng lẻo).
-4. Kiểm tra việc sử dụng Secure Storage (Keychain/EncryptedSharedPreferences).
-5. Phân tích file Privacy Policy có khớp với dữ liệu thực tế thu thập không.
-Trả về báo cáo phân loại Critical/High/Low." --approval-mode auto
-```
+### Pass 2 — INFORMATIONAL (Lower Severity)
+*   **Async/Sync Mixing:** Running synchronous calls (blocking calls, file I/O, sync requests) inside async event loops.
+*   **Column/Field Name Safety:** Verify ORM query columns match actual database schemas.
+*   **LLM Prompt Issues:** 0-indexed lists in prompts (LLMs expect 1-indexed) or listing tools/capabilities that don't match the wired array.
+*   **Completeness Gaps:** Shortcut implementations where complete versions are achievable within 30 minutes, or missing test paths (negative paths, edge cases).
+*   **Time Window Safety:** Date-key lookups assuming 24h coverage without timezone normalization.
+*   **Type Coercion:** Values crossing language/JSON boundaries where types change (e.g. numeric vs string).
 
-### 2. 🌐 Localization & UI Review
-**Dùng khi User yêu cầu:** *"review đa ngôn ngữ", "check hardcode string", "kiểm tra UI"*
+---
 
-```bash
-codex -p "Thực hiện Localization Review. Quét các file UI (Views, Components):
-1. Tìm tất cả các string hiển thị cho người dùng bị hardcode mà chưa bọc qua hàm dịch (i18n, LocalizedStringKey, R.string).
-2. Đối chiếu xem các key được gọi trong UI đã tồn tại trong file từ điển (en/vi) chưa.
-Liệt kê chi tiết tên file và số dòng vi phạm." --approval-mode auto
-```
+## ⚡ The Fix-First Heuristic
 
-### 3. 🍏 Store Compliance Review
-**Dùng khi User yêu cầu:** *"review appstore", "check compliance", "chuẩn bị submit"*
+When reviewing, classify findings into AUTO-FIX (applied automatically without prompting) or ASK (require user confirmation):
 
-```bash
-codex -p "Thực hiện App Store / Play Store Compliance Review. Đánh giá:
-1. Info.plist / AndroidManifest: Các chuỗi giải thích quyền (NSCameraUsageDescription...) có đầy đủ ý nghĩa không.
-2. App Tracking Transparency (ATT): Đã cấu hình và gọi khi cần chưa.
-3. Background Modes: Có khai báo thừa thãi không.
-4. Kiểm tra mã nguồn có API riêng tư (Private APIs) hoặc code tải logic động trái phép không." --approval-mode auto
-```
+| AUTO-FIX (Apply without asking) | ASK (Needs user confirmation) |
+| :--- | :--- |
+| Dead code & unused variables | Security issues (auth, XSS, injection) |
+| Missing eager loading (N+1 queries) | Race conditions & concurrency |
+| Stale comments contradicting code | Design decisions |
+| Magic numbers → named constants | Large fixes (>20 lines of code) |
+| Missing basic input/regex validation | Enum & value completeness changes |
+| Version/dependency mismatches | Anything changing user-visible behavior |
 
-### 4. 🧠 Architecture & Logic Review
-**Dùng khi User yêu cầu:** *"review kiến trúc", "review logic", "code smell"*
-
-```bash
-codex -p "Thực hiện Architecture & Logic Review. Đánh giá:
-1. Vi phạm nguyên tắc SOLID và Clean Architecture (VD: View xử lý Business Logic).
-2. Code duplication (Lặp code) hoặc Hàm quá dài (>50 lines).
-3. Thiếu Error Handling trong các async function / API calls.
-4. Memory Leaks (Retain cycles, forgot to unsubscribe)." --approval-mode auto
-```
+---
 
-### 5. ⚡ Auto Diff Review (Mặc định)
-**Dùng khi User yêu cầu:** *"review", "review diff", "check code vừa viết"* hoặc khi hoàn thành Task.
+## 🚫 Harmless Noise Suppressions (DO NOT flag)
+*   Harmless redundancies that aid readability (e.g., `present?` vs `length > 0`).
+*   Harmless no-ops (e.g., `.reject` on an element never present in the array).
+*   Requests to add comments explaining "why" a threshold was chosen.
+*   Suggestions to write tighter assertions in test cases that are already covering the behavior.
+*   Anything already addressed in the diff.
 
+## 🛠️ Execution via Codex CLI
+Invoke the review module using the non-interactive Codex CLI or active model runner:
 ```bash
-codex -p "Review các thay đổi hiện tại (git diff/staged). Đảm bảo code mới viết đáp ứng Spec, không phá vỡ logic cũ và tuân thủ Coding Convention của dự án. Nếu an toàn, hãy trả về LGTM (Looks Good To Me)." --approval-mode auto
+codex -p "Perform a GStack-style pre-landing review. Highlight Pass 1 (Critical) and Pass 2 (Informational) issues, then apply the Fix-First heuristic." --approval-mode auto
 ```
-
----
-
-## Cách Xử Lý Output Từ Codex
-1. Fix 🔴 **Critical** issues NGAY LẬP TỨC. (VD: Lộ Key, API chưa chặn rate limit).
-2. Fix 🟡 **Important** issues trước khi kết thúc task hoặc chuyển sang Phase mới. (VD: Quên localize string).
-3. Log 🟢 **Minor** issues để cấu trúc lại sau.
-4. Proceed nếu Subagent Codex báo "LGTM" hoặc không có issue nào nghiêm trọng.
-
-## Integration
-
-**Used by:**
-- `single-flow-task-execution` — Review sau mỗi task
-- `symphony-enforcer` — Review trước khi `symphony_complete_task`
-- Thay thế hoàn toàn quy trình thủ công của `/audit` workflow.

package/skills/review/SKILL.md

@@ -1,87 +1,59 @@
 ---
 name: review
-description: Use when completing tasks, implementing features, or before merging. Dispatch structured code review with severity classification via Codex CLI.
+description: Use when completing tasks, implementing features, or before merging. Dispatch structured code review with severity classification.
 ---
 
-<!-- ⚠️ SMART REVIEW AGENT — Intelligent routing for Security, Localization, Compliance, and Quality -->
-
-# Smart Code Review
+# Smart Code Review v2.0 (GStack-Powered)
 
 ## Overview
+Perform structured code reviews on modified files (using git diff against origin/main or staged changes) to catch issues before they are committed or merged.
+Antigravity uses the `codex` CLI (or active LLM runner) to perform deep, multi-file code reviews across specific safety and quality domains.
 
-Review early, review often. Catch issues before they cascade.
-Antigravity uses `codex` CLI to perform deep, multi-file code reviews across specific domains (Security, Localization, Compliance, Quality). 
-
-**Core principle:** Actionable, domain-specific feedback via Multi-Agent Flow.
-
-## The Review Modules (Execution via Codex CLI)
+## 📋 The Two-Pass Review Rubric
 
-Thay vì tự đọc diff và đánh giá, Antigravity **BẮT BUỘC** gọi `codex` CLI để thực hiện Code Review nhằm mở rộng Context Window và sử dụng subagent chuyên dụng.
-Dưới đây là 5 Module Review Tự Động. Antigravity tự động map intent của User để chọn Module phù hợp:
+Reviews are divided into two distinct passes depending on severity:
 
-### 1. 🛡️ Security & Privacy Review (Thay thế `/audit`)
-**Dùng khi User yêu cầu:** *"review bảo mật", "check security", "kiểm tra an toàn"*
+### Pass 1 — CRITICAL (Highest Severity)
+*   **SQL & Data Safety:** String interpolation in SQL (require parameterized queries/prepared statements), TOCTOU race conditions (require atomic `WHERE` checks), and bypassing model validations for direct DB writes.
+*   **Race Conditions & Concurrency:** Read-check-write patterns without uniqueness constraints, find-or-create without unique DB indices, and status transitions that are not atomic.
+*   **LLM Output Trust Boundaries:** Ensure LLM-generated values are type/shape/format checked before saving to database, and external URLs generated by LLM are allowlisted.
+*   **Shell Injection:** Variable interpolation in shell execution commands (e.g. `subprocess` with `shell=True` or `exec`/`eval` without sandboxing). Use argument arrays instead.
+*   **Enum & Value Completeness:** When a new enum, status string, tier, or type constant is added, trace it through every switch, filter, or conditional block across the entire project. Ensure all consumers handle the new value.
 
-```bash
-codex -p "Thực hiện Security & Privacy Review. Hãy quét khắt khe các điểm sau:
-1. Hardcoded API Keys/Secrets trong code hoặc file config.
-2. Dữ liệu PII (Personal Identifiable Information) có bị log ra console không (print, console.log).
-3. Lỗ hổng OWASP (SQL Injection, XSS, thiếu Rate Limiting, CORS/Headers lỏng lẻo).
-4. Kiểm tra việc sử dụng Secure Storage (Keychain/EncryptedSharedPreferences).
-5. Phân tích file Privacy Policy có khớp với dữ liệu thực tế thu thập không.
-Trả về báo cáo phân loại Critical/High/Low." --approval-mode auto
-```
+### Pass 2 — INFORMATIONAL (Lower Severity)
+*   **Async/Sync Mixing:** Running synchronous calls (blocking calls, file I/O, sync requests) inside async event loops.
+*   **Column/Field Name Safety:** Verify ORM query columns match actual database schemas.
+*   **LLM Prompt Issues:** 0-indexed lists in prompts (LLMs expect 1-indexed) or listing tools/capabilities that don't match the wired array.
+*   **Completeness Gaps:** Shortcut implementations where complete versions are achievable within 30 minutes, or missing test paths (negative paths, edge cases).
+*   **Time Window Safety:** Date-key lookups assuming 24h coverage without timezone normalization.
+*   **Type Coercion:** Values crossing language/JSON boundaries where types change (e.g. numeric vs string).
 
-### 2. 🌐 Localization & UI Review
-**Dùng khi User yêu cầu:** *"review đa ngôn ngữ", "check hardcode string", "kiểm tra UI"*
+---
 
-```bash
-codex -p "Thực hiện Localization Review. Quét các file UI (Views, Components):
-1. Tìm tất cả các string hiển thị cho người dùng bị hardcode mà chưa bọc qua hàm dịch (i18n, LocalizedStringKey, R.string).
-2. Đối chiếu xem các key được gọi trong UI đã tồn tại trong file từ điển (en/vi) chưa.
-Liệt kê chi tiết tên file và số dòng vi phạm." --approval-mode auto
-```
+## ⚡ The Fix-First Heuristic
 
-### 3. 🍏 Store Compliance Review
-**Dùng khi User yêu cầu:** *"review appstore", "check compliance", "chuẩn bị submit"*
+When reviewing, classify findings into AUTO-FIX (applied automatically without prompting) or ASK (require user confirmation):
 
-```bash
-codex -p "Thực hiện App Store / Play Store Compliance Review. Đánh giá:
-1. Info.plist / AndroidManifest: Các chuỗi giải thích quyền (NSCameraUsageDescription...) có đầy đủ ý nghĩa không.
-2. App Tracking Transparency (ATT): Đã cấu hình và gọi khi cần chưa.
-3. Background Modes: Có khai báo thừa thãi không.
-4. Kiểm tra mã nguồn có API riêng tư (Private APIs) hoặc code tải logic động trái phép không." --approval-mode auto
-```
+| AUTO-FIX (Apply without asking) | ASK (Needs user confirmation) |
+| :--- | :--- |
+| Dead code & unused variables | Security issues (auth, XSS, injection) |
+| Missing eager loading (N+1 queries) | Race conditions & concurrency |
+| Stale comments contradicting code | Design decisions |
+| Magic numbers → named constants | Large fixes (>20 lines of code) |
+| Missing basic input/regex validation | Enum & value completeness changes |
+| Version/dependency mismatches | Anything changing user-visible behavior |
 
-### 4. 🧠 Architecture & Logic Review
-**Dùng khi User yêu cầu:** *"review kiến trúc", "review logic", "code smell"*
-
-```bash
-codex -p "Thực hiện Architecture & Logic Review. Đánh giá:
-1. Vi phạm nguyên tắc SOLID và Clean Architecture (VD: View xử lý Business Logic).
-2. Code duplication (Lặp code) hoặc Hàm quá dài (>50 lines).
-3. Thiếu Error Handling trong các async function / API calls.
-4. Memory Leaks (Retain cycles, forgot to unsubscribe)." --approval-mode auto
-```
+---
 
-### 5. ⚡ Auto Diff Review (Mặc định)
-**Dùng khi User yêu cầu:** *"review", "review diff", "check code vừa viết"* hoặc khi hoàn thành Task.
+## 🚫 Harmless Noise Suppressions (DO NOT flag)
+*   Harmless redundancies that aid readability (e.g., `present?` vs `length > 0`).
+*   Harmless no-ops (e.g., `.reject` on an element never present in the array).
+*   Requests to add comments explaining "why" a threshold was chosen.
+*   Suggestions to write tighter assertions in test cases that are already covering the behavior.
+*   Anything already addressed in the active diff.
 
+## 🛠️ Execution via Codex CLI
+Invoke the review module using the non-interactive Codex CLI or active model runner:
 ```bash
-codex -p "Review các thay đổi hiện tại (git diff/staged). Đảm bảo code mới viết đáp ứng Spec, không phá vỡ logic cũ và tuân thủ Coding Convention của dự án. Nếu an toàn, hãy trả về LGTM (Looks Good To Me)." --approval-mode auto
+codex -p "Perform a GStack-style pre-landing review. Highlight Pass 1 (Critical) and Pass 2 (Informational) issues, then apply the Fix-First heuristic." --approval-mode auto
 ```
-
----
-
-## Cách Xử Lý Output Từ Codex
-1. Fix 🔴 **Critical** issues NGAY LẬP TỨC. (VD: Lộ Key, API chưa chặn rate limit).
-2. Fix 🟡 **Important** issues trước khi kết thúc task hoặc chuyển sang Phase mới. (VD: Quên localize string).
-3. Log 🟢 **Minor** issues để cấu trúc lại sau.
-4. Proceed nếu Subagent Codex báo "LGTM" hoặc không có issue nào nghiêm trọng.
-
-## Integration
-
-**Used by:**
-- `single-flow-task-execution` — Review sau mỗi task
-- `symphony-enforcer` — Review trước khi `symphony_complete_task`
-- Thay thế hoàn toàn quy trình thủ công của `/audit` workflow.

package/workflows/_uncategorized/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/_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).