@leejungkiin/awkit 1.4.0 → 1.4.3

package/bin/claude-generators.js

@@ -0,0 +1,122 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generates Claude Code CLAUDE.md from core/GEMINI.md template.
+ * Replaces Antigravity-specific paths and references with Claude Code equivalents.
+ * @param {string} sourcePath Path to core/CLAUDE.md (pre-adapted template)
+ * @param {string} destPath Destination path (e.g. <project>/CLAUDE.md)
+ */
+function generateClaudeRules(sourcePath, destPath) {
+    if (!fs.existsSync(sourcePath)) {
+        console.log(`⚠️  Template not found: ${sourcePath}`);
+        return;
+    }
+
+    const content = fs.readFileSync(sourcePath, 'utf8');
+
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, content.trim() + '\n');
+    console.log(`✅ Claude Code CLAUDE.md generated at: ${destPath}`);
+}
+
+/**
+ * Copies skill directories to Claude Code .claude/skills/ structure.
+ * Preserves full directory structure: <skill-name>/SKILL.md + scripts/ + templates/
+ * Injects YAML frontmatter if missing.
+ */
+function generateClaudeSkills(srcDir, destDir) {
+    if (!fs.existsSync(srcDir)) return;
+
+    fs.mkdirSync(destDir, { recursive: true });
+    const skills = fs.readdirSync(srcDir);
+
+    let count = 0;
+    for (const skill of skills) {
+        const skillSrcDir = path.join(srcDir, skill);
+        if (!fs.statSync(skillSrcDir).isDirectory()) continue;
+        if (skill === '.DS_Store') continue;
+
+        // Skip non-skill directories (schemas, skills, workflows nested dirs)
+        const skillFile = path.join(skillSrcDir, 'SKILL.md');
+        if (!fs.existsSync(skillFile)) continue;
+
+        const skillDestDir = path.join(destDir, skill);
+        const fileCount = copySkillDir(skillSrcDir, skillDestDir);
+
+        // Ensure SKILL.md has YAML frontmatter
+        ensureFrontmatter(path.join(skillDestDir, 'SKILL.md'), skill);
+
+        count++;
+    }
+    console.log(`✅ Generated ${count} Claude Code skills in ${destDir}`);
+}
+
+/**
+ * Recursively copies a skill directory preserving structure.
+ */
+function copySkillDir(src, dest) {
+    if (!fs.existsSync(src)) return 0;
+    fs.mkdirSync(dest, { recursive: true });
+
+    let count = 0;
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+        if (entry.name === '.DS_Store') continue;
+        if (entry.name === '__pycache__') continue;
+
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            count += copySkillDir(srcPath, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+            count++;
+        }
+    }
+    return count;
+}
+
+/**
+ * Ensures a SKILL.md file has proper YAML frontmatter.
+ * If missing, injects name and description extracted from content.
+ */
+function ensureFrontmatter(filePath, skillName) {
+    if (!fs.existsSync(filePath)) return;
+
+    let content = fs.readFileSync(filePath, 'utf8');
+
+    // Already has frontmatter
+    if (content.startsWith('---\n')) {
+        // Ensure 'name' field exists
+        if (!content.match(/^name:/m)) {
+            content = content.replace('---\n', `---\nname: ${skillName}\n`);
+            fs.writeFileSync(filePath, content);
+        }
+        return;
+    }
+
+    // Extract description from first line or heading
+    let description = `Antigravity skill: ${skillName}`;
+    const descMatch = content.match(/^#\s+(.+)/m);
+    if (descMatch) {
+        description = descMatch[1].replace(/[`*_]/g, '').trim();
+    }
+
+    // Also try to extract from YAML-like description in body
+    const bodyDescMatch = content.match(/^description:\s*(.+)/m);
+    if (bodyDescMatch) {
+        description = bodyDescMatch[1].trim();
+    }
+
+    const frontmatter = `---\nname: ${skillName}\ndescription: "${description}"\n---\n`;
+    content = frontmatter + content;
+    fs.writeFileSync(filePath, content);
+}
+
+module.exports = {
+    generateClaudeRules,
+    generateClaudeSkills,
+};

package/core/AGENTS.md

@@ -36,3 +36,19 @@ symphony_status                   # Check system status
 - NEVER stop before pushing — that leaves work stranded locally
 - NEVER say "ready to push when you are" — YOU must push
 - If push fails, resolve and retry until it succeeds
+
+## AUTO-COMMIT RULE
+
+**After a successful build (0 errors)**, commit immediately — do NOT wait for session end.
+
+```bash
+git add -A
+git commit -m "fix: <concise description>"   # conventional commit format
+git push                                       # non-force push, safe to auto-run
+```
+
+**Rules:**
+- Commit NGAY sau build 0 errors — không gom lại cuối session.
+- `git push` (non-force) được phép chạy tự động.
+- Push fail → `git pull --rebase && git push` (retry 1 lần).
+- Vẫn fail → báo user, KHÔNG force push.

package/core/CLAUDE.md

@@ -0,0 +1,155 @@
+# CLAUDE.md — Antigravity Orchestrator
+
+> Rules + routing only. Gate details → skills. Auto-generated by AWKit.
+
+---
+
+## Identity
+
+- Bạn là **Antigravity Orchestrator**.
+- Pragmatic. Regression-averse. Symphony-first. Multi-project.
+
+---
+
+## Session Protocol
+
+> [!CAUTION]
+> MỌI session có task code/debug/plan PHẢI chạy init chain TRƯỚC bất kỳ action nào.
+> Bỏ qua = vi phạm. KHÔNG CÓ NGOẠI LỆ.
+
+### Init Chain (BẮT BUỘC)
+
+```
+symphony-orchestrator → awf-session-restore → nm-memory-sync → orchestrator → action
+```
+
+Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
+
+### Ngoại lệ
+
+- Câu hỏi đơn giản (hỏi-đáp, giải thích) → không cần init chain.
+- User nói rõ bỏ qua → được phép.
+
+### Exit Protocol
+
+- Task done → auto-complete Symphony → **BẮT BUỘC** `symphony next` + present gợi ý.
+- Kết thúc message → **LUÔN** kèm "Next steps" section.
+- `nm-memory-sync` auto-save (W1–W4 triggers).
+- Deploy/push → kiểm tra in-progress tasks trước, confirm với user.
+
+---
+
+## Rules
+
+### Code
+- Production quality. File < 500 lines.
+- Không sửa code ngoài scope.
+- Không deploy/push không hỏi.
+- Không hardcode secrets → `.env`.
+- Không `git reset --hard`.
+- AI models: Gemini 2.5+ only.
+- Firebase: Firebase AI Logic SDK.
+
+### Auto-Commit After Build (BẮT BUỘC)
+- Build thành công (0 errors) → **TỰ ĐỘNG** `git add` → `git commit` → `git push`.
+- KHÔNG hỏi user, KHÔNG chờ approval cho commit thường.
+- Commit message: conventional format (`fix:`, `feat:`, `refactor:`, `chore:`).
+- `git push` (non-force) được phép auto-run.
+- Nếu push fail → retry 1 lần với `git pull --rebase && git push`.
+- Nếu vẫn fail → báo user, KHÔNG force push.
+
+### 7-Gate Autonomous System
+- orchestrator PHẢI triage complexity (TRIVIAL/MODERATE/COMPLEX) trước mọi task.
+- COMPLEX tasks PHẢI qua 7 Gates tuần tự:
+  - Gate 1 (Spec): `brainstorm-agent` → BRIEF.md / spec document
+  - Gate 1.5 (Module Spec): `module-spec-writer` → per-module product specs (screens, flows, rules)
+  - Gate 2 (Architecture): `spec-gate` → design doc + user approve
+  - Gate 2.5 (Visual Design): `visual-design-gate` → Thống nhất UI
+  - Gate 3 (Tasks): `symphony-enforcer` → tạo Symphony tickets
+  - Gate 4 (Execution): code theo ticket, đối chiếu design doc
+  - Gate 5 (Verification): `verification-gate` + `code-review`
+- Gate 1.5 MANDATORY khi: COMPLEX + >3 modules hoặc port/migration projects.
+- Gate 1.5 SKIP khi: TRIVIAL/MODERATE hoặc single-module projects.
+- TRIVIAL tasks bypass → thẳng Gate 4.
+- MODERATE tasks → Gate 3 + 4 + 5.
+- AI tự detect gate state — user KHÔNG CẦN gọi workflow bằng tay.
+- Trong lúc code, nếu cần sửa schema khác approved design → ⛔ DỪNG, quay Gate 2.
+
+### NeuralMemory
+- Brain = projectId. Switch trước mọi nmem call.
+- Mọi `nmem_remember()` PHẢI tag projectId.
+- Cross-brain: `nmem_recall(query, brains=["default", projectId])`.
+- KHÔNG gọi nmem tool TRƯỚC khi brain switch xong.
+
+### Communication
+- Chat: Tiếng Việt.
+- Code/Docs/Comments: Tiếng Anh.
+- Kết thúc task: Tóm tắt + Test + Next steps.
+- Không rõ: Hỏi lại, tối đa 2 lần.
+
+### Anti-sycophancy (Trung thực)
+- PHẢI push back khi approach của user có vấn đề — giải thích rõ trade-offs.
+- KHÔNG nói "Great idea!" nếu idea có red flags → nêu rủi ro trước.
+- Nêu cả ưu VÀ nhược điểm của mọi approach, không chỉ list ưu điểm.
+- Nếu request vi phạm best practices → cảnh báo TRƯỚC khi implement.
+- Khi phát hiện pattern sai → đề xuất alternative, không im lặng đồng ý.
+- Acknowledge limitations: nói "Tôi không chắc" khi không chắc.
+
+### Safety Guardrails (Destructive Commands)
+- KHÔNG BAO GIỜ chạy destructive commands tự động:
+  - `rm -rf`, `rm -r`, `rmdir` (recursive delete)
+  - `git push --force`, `git reset --hard`, `git clean -fd`
+  - `DROP TABLE`, `DROP DATABASE`, `DELETE FROM` (without WHERE)
+  - `docker system prune`, `docker volume rm`
+  - `npm publish`, `pod trunk push`
+  - Bất kỳ command nào deploy lên production
+- Double-confirm với user trước khi chạy destructive command.
+- Nếu không chắc command có destructive hay không → hỏi trước.
+
+### 6 Decision Principles (Auto-decide)
+Khi AI cần tự quyết định mà không hỏi user:
+1. **Complete > Shortcuts** — Implement đủ, không bỏ edge cases.
+2. **Evidence > Assumptions** — Dựa trên data, không đoán.
+3. **Standard > Custom** — Ưu tiên solution có sẵn, chuẩn ngành.
+4. **Explicit > Implicit** — Code rõ ràng, không "clever" tricks.
+5. **Test > Trust** — Viết test, không "chắc chắn đúng".
+6. **Small > Big** — Incremental changes, không big-bang refactor.
+
+### Project Context
+- CODEBASE.md tồn tại → KHÔNG scan raw directory.
+- KHÔNG hỏi user về project structure.
+- CODEBASE.md outdated → ghi chú "⚠️ dùng /codebase-sync".
+
+### GitNexus (Code Intelligence)
+- Project đã index (`.gitnexus/` tồn tại) → PHẢI dùng GitNexus tools.
+- Trước khi edit symbol → `gitnexus_impact` check blast radius.
+- Trước khi commit → `gitnexus_detect_changes()` verify scope.
+- Risk HIGH/CRITICAL → PHẢI cảnh báo user trước khi sửa.
+- Explore code lạ → ưu tiên `gitnexus_query` thay vì grep thủ công.
+- Rename symbol → PHẢI dùng `gitnexus_rename` (dry_run trước).
+- Index stale → cảnh báo "⚠️ chạy `npx gitnexus analyze`".
+
+---
+
+## Routing
+
+- **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` (triage + gate-check) → action
+- **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `module-spec-writer` (G1.5) → `spec-gate` (G2) → `visual-design-gate` (G2.5) → `symphony-enforcer` (G3) → `verification-gate` (G5)
+- **Code intelligence:** `gitnexus-intelligence` (impact analysis, blast radius, safe refactoring)
+- **Skill catalog:** xem `orchestrator/SKILL.md`
+
+---
+
+## Paths
+
+```
+<project>/
+├── CLAUDE.md              # Rules (file này)
+└── .claude/
+    └── skills/            # Skills (auto-activate)
+        ├── orchestrator/
+        │   └── SKILL.md
+        ├── brainstorm-agent/
+        │   └── SKILL.md
+        └── ...
+```

package/core/GEMINI.md

@@ -1,6 +1,6 @@
-# GEMINI.md — Antigravity v12.1
+# GEMINI.md — Antigravity v12.3
 
-> Rules + routing only. Gate details → skills. Updated: 2026-03-23
+> Rules + routing only. Gate details → skills. Updated: 2026-03-25
 
 ---
 
@@ -44,28 +44,52 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 ### Code
 - Production quality. File < 500 lines.
 - Không sửa code ngoài scope.
-- Không deploy/push không hỏi.
 - Không hardcode secrets → `.env`.
 - Không `git reset --hard`.
 - AI models: Gemini 2.5+ only.
 - Firebase: Firebase AI Logic SDK.
 
-### 6-Gate Autonomous System (v12.1)
+### Auto-Commit After Build (BẮT BUỘC)
+- Build thành công (0 errors) → **TỰ ĐỘNG** `git add` → `git commit` → `git push`.
+- KHÔNG hỏi user, KHÔNG chờ approval cho commit thường.
+- Commit message: conventional format (`fix:`, `feat:`, `refactor:`, `chore:`).
+- `git push` (non-force) được phép `SafeToAutoRun=true`.
+- Nếu push fail → retry 1 lần với `git pull --rebase && git push`.
+- Nếu vẫn fail → báo user, KHÔNG force push.
+
+### 7-Gate Autonomous System (v12.3)
 - orchestrator PHẢI triage complexity (TRIVIAL/MODERATE/COMPLEX) trước mọi task.
-- COMPLEX tasks PHẢI qua 6 Gates tuần tự:
+- COMPLEX tasks PHẢI qua 7 Gates tuần tự:
   - Gate 1 (Spec): `brainstorm-agent` → BRIEF.md / spec document
   - Gate 1.5 (Module Spec): `module-spec-writer` → per-module product specs (screens, flows, rules)
   - Gate 2 (Architecture): `spec-gate` → design doc + user approve
+  - Gate 2.5 (Visual Design): `visual-design-gate` → Thống nhất UI qua Pencil hoặc ảnh đính kèm
   - Gate 3 (Tasks): `symphony-enforcer` → tạo Symphony tickets
-  - Gate 4 (Execution): code theo ticket, đối chiếu design doc
+  - Gate 4 (Execution — **3-Phase**): code theo ticket với **User Test Checkpoints**
+    - **Phase A** 🏗️ Infrastructure: dependencies, DI, navigation skeleton → build check
+    - **Phase B** 🎨 UI Shell: tất cả screens với mock data → **🧪 USER TEST CHECKPOINT** (user test UI trên device)
+    - **Phase C** ⚡ Logic: thay mock bằng real data, per-feature → **🧪 USER TEST CHECKPOINT** mỗi feature
   - Gate 5 (Verification): `verification-gate` + `code-review`
+- **Gate 4 Three-Phase Rules (AUTO-ENFORCE):**
+  - AI PHẢI **CHỦ ĐỘNG** kích hoạt Three-Phase — KHÔNG chờ user yêu cầu.
+  - AI PHẢI hiển thị **Phase Announcement Block** khi bắt đầu Gate 4.
+  - AI PHẢI **TỰ ĐỘNG dừng** và trigger User Test Checkpoint (TP1.7) khi Phase B xong.
+  - COMPLEX + có UI → BẮT BUỘC 3 phases + tất cả checkpoints.
+  - MODERATE + có UI → Phase A+C gộp, Phase B optional.
+  - TRIVIAL → bypass hoàn toàn (code thẳng).
+  - Phase B → C transition: PHẢI có user confirm UI OK trước khi code logic.
+  - Mỗi feature trong Phase C xong → checkpoint nhỏ cho user test.
+  - ⛔ Code logic khi chưa confirm UI = VI PHẠM NẶNG.
+  - Chi tiết: xem `symphony-enforcer/SKILL.md` (Three-Phase Auto-Enforcement Protocol).
+- **Kiro Spec Integration:** Khi `.kiro/specs/` tồn tại → auto-accelerate Gates 1, 1.5, 2, 3.
 - Gate 1.5 MANDATORY khi: COMPLEX + >3 modules hoặc port/migration projects.
 - Gate 1.5 SKIP khi: TRIVIAL/MODERATE hoặc single-module projects.
+- Gate 2.5 SKIP khi: Backend/logic-only tasks.
 - TRIVIAL tasks bypass → thẳng Gate 4.
 - MODERATE tasks → Gate 3 + 4 + 5.
 - AI tự detect gate state — user KHÔNG CẦN gọi workflow bằng tay.
-- Trong lúc code, nếu cần sửa schema khác approved design → ⛔ DỪNG, quay Gate 2.
-- Chi tiết: xem `orchestrator/SKILL.md` (triage) + `module-spec-writer/SKILL.md` (Gate 1.5) + `spec-gate/SKILL.md` (Gate 2).
+- Trong lúc code, nếu cần sửa schema/UI khác approved design → ⛔ DỪNG, quay Gate 2/2.5 tương ứng.
+- Chi tiết: xem `orchestrator/SKILL.md` (triage) + `symphony-enforcer/SKILL.md` (TP1.7 checkpoints).
 
 ### NeuralMemory
 - Brain = projectId. Switch trước mọi nmem call.
@@ -95,6 +119,7 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
   - `docker system prune`, `docker volume rm`
   - `npm publish`, `pod trunk push`
   - Bất kỳ command nào deploy lên production
+- **Ngoại lệ:** `git add`, `git commit`, `git push` (non-force) được auto-run sau build thành công.
 - Double-confirm với user trước khi chạy destructive command.
 - Nếu không chắc command có destructive hay không → hỏi trước.
 
@@ -122,6 +147,16 @@ Khi AI cần tự quyết định mà không hỏi user:
 - Index stale → cảnh báo "⚠️ chạy `npx gitnexus analyze`".
 - Chi tiết: xem `gitnexus-intelligence/SKILL.md`.
 
+### Kiro Specs (IDE Integration)
+- `.kiro/specs/` tồn tại → PHẢI dùng làm source of truth cho Gates 1, 1.5, 2, 3.
+- `requirements.md` → Gate 1 (Spec) + Gate 1.5 (Module Spec) AUTO-PASS.
+- `design.md` → Gate 2 (Architecture) AUTO-APPROVE (pre-approved by IDE).
+- `tasks.md` → Gate 3 (Tasks) AUTO-IMPORT vào Symphony.
+- `.kiro/specs` ưu tiên hơn `docs/specs` khi cả hai tồn tại.
+- Gate 2.5 (Visual) và Gate 5 (Verification) KHÔNG bị ảnh hưởng.
+- Khi code (Gate 4), PHẢI đối chiếu với `.kiro/specs/<module>/` tương ứng.
+- Chi tiết: xem `orchestrator/SKILL.md` (Kiro Spec Detection section).
+
 ### Two-Agent Flow (Conductor)
 - Antigravity CHỦ ĐỘNG gọi `gemini -p "..." --approval-mode plan` khi cần tầm nhìn rộng.
 - CLI dùng **quota pool riêng** → không ảnh hưởng Antigravity quota.
@@ -136,7 +171,7 @@ Khi AI cần tự quyết định mà không hỏi user:
 ## Routing
 
 - **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` (triage + gate-check) → action
-- **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `module-spec-writer` (G1.5) → `spec-gate` (G2) → `symphony-enforcer` (G3) → `verification-gate` (G5)
+- **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `module-spec-writer` (G1.5) → `spec-gate` (G2) → `visual-design-gate` (G2.5) → `symphony-enforcer` (G3) → `verification-gate` (G5)
 - **Code intelligence:** `gitnexus-intelligence` (impact analysis, blast radius, safe refactoring)
 - **Skill catalog:** xem `orchestrator/SKILL.md`
 - **Workflows:** 75+ (`/xxx`). Core: `/init` `/code` `/debug` `/recap` `/next` `/todo` `/gitnexus`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejungkiin/awkit",
-  "version": "1.4.0",
+  "version": "1.4.3",
   "description": "Antigravity Workflow Kit. Unified AI agent orchestration system.",
   "main": "bin/awk.js",
   "bin": {

package/skills/ai-sprite-maker/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ai-sprite-maker
+description: "Interactive AI Sprite Generator. Kích hoạt khi user muốn tạo game sprites, character sheets, hoặc assets 2D. Tích hợp generate_image nội bộ theo kèm kịch bản xoá phông tự động Python (Chroma-key)."
+version: 1.0.0
+trigger: conditional
+activation_keywords:
+  - "tạo sprite"
+  - "làm sprite"
+  - "game asset"
+  - "cắt nền sprite"
+---
+
+# 🎨 AI Sprite Maker Skill
+
+> **Purpose:** Tự động hoá quy trình tạo Game Sprites (nhân vật, vật phẩm) qua AI, từ khâu lên ý tưởng đến lúc xuất file `.png` nền trong suốt hoàn chỉnh.
+> **Scope:** Kết hợp `generate_image`, và xử lý hậu kỳ cắt/nền xuyên thấu qua script Python cục bộ.
+
+## 🚀 Luồng tương tác (Interactive Flow)
+
+### Bước 1: Khảo sát cấu hình (The Interview)
+Trước khi vẽ, hãy hỏi người dùng các thông tin cơ bản, GỢI MỞ KÈM VÍ DỤ để user dễ hình dung:
+- **Chủ thể:** (e.g., Hiệp sĩ, quái vật, rương báu, hoặc "một chú mèo dễ thương").
+- **Góc nhìn (Perspective):** Vẫn giữ các thuật ngữ chuyên ngành nhưng kèm giải thích ngắn. (e.g. *Top-down* nhìn từ trên xuống như game nông trại, *Side-scroller* nhìn ngang để đi ải như Mario, *Isometric 8 hướng* cho game chiến thuật).
+- **Trạng thái & Hoạt ảnh (Animation/Frames):** Giải thích cho user hiểu rằng sprite dùng trong game thường bao gồm nhiều khung hình (frames). Ví dụ: *"Để làm một chú mèo đang đi bộ (walk cycle), bạn sẽ cần một dải Sprite Sheet gồm khoảng 4 đến 6 frames liên tiếp."* Hỏi xem họ muốn làm tĩnh 1 dáng (Idle pose / Concept) hay muốn tạo một dải hoạt ảnh (Sprite Sheet).
+- **Phong cách (Art Style):** (e.g. Pixel art 16-bit cổ điển, Vector cel-shaded, 3D Render).
+
+### Bước 1.5: Áp dụng Tiêu chuẩn Lưới (Grid Protocol)
+Để đảm bảo ảnh AI sinh ra khớp 100% với tham số cắt ảnh của Python, hệ thống QUI ĐỊNH CÁC CHUẨN GRID SAU:
+1. **Chuẩn Action Đơn (Đi/Chạy/Idle ngang):** Lưới `4x1` hoặc `6x1` (1 hàng ngang).
+   - *Ép vào Prompt:* `ensure exactly 4 frames arranged in a perfectly straight 4x1 horizontal grid layout, 1 row only`.
+   - *Tham số Python chạy ngầm:* `--align 4x1`
+2. **Chuẩn RPG 4 Hướng (Top-down đa hướng Lên/Xuống/Trái/Phải):** Lưới `4x4` (4 hàng, mỗi hàng 4 frames).
+   - *Ép vào Prompt:* `ensure exactly a 4x4 grid layout, 4 equal rows and 4 equal columns, precise character sheet formatting, aligned grid`.
+   - *Tham số Python chạy ngầm:* `--align 4x4`
+3. **Chuẩn Ảnh Tĩnh (Concept/Avatar):** Dùng cắt nền bình thường. KHÔNG ép keyword grid, KHÔNG gọi kèm hàm `--align`.
+
+### Bước 2: Sinh ảnh (Generation)
+Sau khi chốt ý tưởng, AI đối chiếu với Grid Protocol bên trên để hoàn thiện prompt. Dùng tool `generate_image` với tuỳ biến sau:
+- LUÔN kết hợp chặt chẽ các keyword về chuẩn Grid Layout (nếu là ảnh động) như đã định nghĩa ở Bước 1.5.
+- **ĐỂ TRÁNH BỊ CHÈN CHỮ VÀO FRAME:** LUÔN thêm keyword: `no text, no wording, no watermark, no labels, no frame numbers, clean blank spacing`.
+- BẮT BUỘC chèn đoạn hậu tố nền xanh sau đây để Python nhận toạ độ cắt: 
+  `solid bright green background #00FF00, high contrast, clean distinct edges, isolated subject, no shadows cast on the background.`
+- Đặt ImageName mô tả đúng chủ thể, kết thúc bằng `_raw` (vd: `cat_walk_4x1_raw`).
+
+### Bước 3: Hậu kỳ (Post-Processing)
+Ngay khi ảnh thô sinh ra thành công, AI tự động gọi script Python `process_sprites.py` để xử lý ảnh final.
+
+- **Đối với ảnh tĩnh (Concept/Avatar):** Chỉ gỡ nền xanh an toàn.
+```bash
+python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/process_sprites.py <đường_dẫn_ảnh_raw> <đường_dẫn_lưu_ảnh_final>
+```
+
+- **Đối với Dải hoạt ảnh (Sprite Sheet):** KIÊN QUYẾT TỰ ĐỘNG bổ sung tham số `--align SốCộtxSốHàng` để tự động căn lề thẳng tắp mặt đất cho mọi frame hình. AI sẽ tự đếm xem ảnh vừa sinh ra có bao nhiêu cột và hàng để truyền tham số tương ứng (VD: 3 cột 2 hàng thì biên dịch thành `--align 3x2`).
+Nhờ vậy nhân vật sẽ chạy mượt mà ngay trên Canvas JS/Unity mà người dùng KHÔNG CẦN chỉnh tay (zero manual intervention).
+```bash
+python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/process_sprites.py <đường_raw> <đường_final> --align 3x2
+```
+
+### Bước 4: Nghiệm thu & Preview Animation (Review & Test)
+Sau khi xử lý thành công, hãy thực hiện các việc sau:
+1. Nhúng (embed) cả ảnh thô lẫn ảnh thành phẩm vào Chat cho user kiểm tra thành quả trong suốt.
+2. **NẾU LÀ SPRITE SHEET (Ảnh động):** BẮT BUỘC tạo nhanh một file `preview.html` lưu cùng thư mục với ảnh final. File HTML này dùng CSS/JS đơn giản (ví dụ: `animation-timing-function: steps(N)` hoặc HTML5 Canvas) để animate dải sprite. Tính toán đúng kích thước dựa trên số cột/hàng (như 4x1, 4x4) và chỉ định khung ảnh (frame kích thước) chính xác.
+3. Chạy lệnh mở file trên trình duyệt cho user (VD: dùng công cụ Terminal chạy `open <đường_dẫn_tuyệt_đối_của_html>` đối với môi trường Mac).
+4. Khuyến khích user test hoạt ảnh trực tiếp. Hỏi user tốc độ (speed) và độ mượt (smoothness) có ổn không.
+5. **Tùy chọn: Gói thành Video/GIF Animation (Mới):** Nếu user muốn tạo hẳn file ảnh động (GIF) hoặc Video (MP4) để chia sẻ:
+   - Sử dụng script `animate_sprite.py` được cung cấp trong skill.
+   - Ví dụ lệnh cắt sprite 4x1 thành GIF (tốc độ 100ms, phóng to 2x):
+     ```bash
+     python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/animate_sprite.py <đường_final.png> <đường_ra.gif> --grid 4x1 --duration 100 --scale 2.0
+     ```
+   - Xuất ra MP4 (Yêu cầu hệ thống cài sẵn `ffmpeg`, đổi đuôi thành `.mp4`):
+     ```bash
+     python ~/.gemini/antigravity/skills/ai-sprite-maker/scripts/animate_sprite.py <đường_final.png> <đường_ra.mp4> --grid 4x1
+     ```
+6. Cuối cùng, brainstorm với user bước tiếp theo (Làm thêm sprite khác, chia sẻ Telegram, hoặc viết code logic tích hợp sprite này vào game).---
+
+## 🛠 Script Python Xoá Nền (Chroma-key)
+Skill đính kèm một script Python không phụ thuộc AI nặng tại:
+`~/.gemini/antigravity/skills/ai-sprite-maker/scripts/process_sprites.py`
+
+*(Yêu cầu thiết bị có cài đặt module `Pillow` trong môi trường Python: `pip install Pillow`).*

package/skills/ai-sprite-maker/scripts/animate_sprite.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+import sys
+import os
+import argparse
+import subprocess
+from PIL import Image
+
+def create_animation(input_path, output_path, cols, rows, duration=100, scale=1.0):
+    try:
+        img = Image.open(input_path)
+        img = img.convert("RGBA")
+    except Exception as e:
+        print(f"Error opening {input_path}: {e}")
+        sys.exit(1)
+
+    width, height = img.size
+    frame_width = width // cols
+    frame_height = height // rows
+
+    frames = []
+    for r in range(rows):
+        for c in range(cols):
+            # Crop the frame
+            box = (c * frame_width, r * frame_height, (c + 1) * frame_width, (r + 1) * frame_height)
+            frame = img.crop(box)
+            
+            # Scale if necessary
+            if scale != 1.0:
+                new_size = (int(frame_width * scale), int(frame_height * scale))
+                frame = frame.resize(new_size, Image.Resampling.NEAREST)
+                
+            frames.append(frame)
+
+    if not frames:
+        print("Error: No frames could be extracted.")
+        sys.exit(1)
+
+    # If output is mp4, generate a temporary gif first
+    is_mp4 = output_path.lower().endswith('.mp4')
+    gif_path = output_path.replace('.mp4', '.gif') if is_mp4 else output_path
+
+    try:
+        # Save as GIF
+        frames[0].save(
+            gif_path,
+            save_all=True,
+            append_images=frames[1:],
+            duration=duration,
+            loop=0,
+            disposal=2  # Restore to background color
+        )
+        print(f"Successfully generated GIF: {gif_path}")
+
+        # Convert to MP4 if requested
+        if is_mp4:
+            print(f"Converting GIF to MP4 using ffmpeg...")
+            # Requires ffmpeg installed
+            cmd = [
+                'ffmpeg', '-y', '-i', gif_path,
+                '-movflags', 'faststart', '-pix_fmt', 'yuv420p',
+                '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2',
+                output_path
+            ]
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            print(f"Successfully generated MP4: {output_path}")
+            
+            # Keep or remove the temp gif? We'll keep it as a bonus, or remove it.
+            # os.remove(gif_path) # uncomment to remove
+            
+    except Exception as e:
+        print(f"Error saving animation: {e}")
+        sys.exit(1)
+
+def main():
+    parser = argparse.ArgumentParser(description="Convert a Sprite Sheet to an animated GIF or MP4.")
+    parser.add_argument("input", help="Path to the input sprite sheet image.")
+    parser.add_argument("output", help="Path to the output file (.gif or .mp4).")
+    parser.add_argument("--grid", required=True, help="Grid format (cols x rows), e.g., 4x1 or 3x2.")
+    parser.add_argument("--duration", type=int, default=100, help="Duration of each frame in milliseconds (default: 100).")
+    parser.add_argument("--scale", type=float, default=1.0, help="Scale factor for the output frames (default: 1.0).")
+    
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.input):
+        print(f"Error: Output file not found '{args.input}'")
+        sys.exit(1)
+
+    try:
+        dims = args.grid.lower().split('x')
+        if len(dims) != 2:
+            raise ValueError()
+        cols, rows = int(dims[0]), int(dims[1])
+        if cols <= 0 or rows <= 0:
+            raise ValueError()
+    except ValueError:
+        print(f"Error: Invalid grid format '{args.grid}'. Use <cols>x<rows>, e.g., 4x1.")
+        sys.exit(1)
+
+    create_animation(args.input, args.output, cols, rows, args.duration, args.scale)
+
+if __name__ == "__main__":
+    main()