@leejungkiin/awkit 1.7.6 → 1.7.8

package/skills/threejs-renderers/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: threejs-renderers
+description: "Core rendering pipeline for three.js using WebGLRenderer and WebGPURenderer, canvas sizing, device pixel ratio, color space and tone mapping, output encoding, WebGL/WebGPU render targets, Info statistics, and addon overlay renderers (CSS2D/CSS3D/SVG). Use when tuning the draw loop, performance, or switching WebGPU vs WebGL; for EffectComposer passes use threejs-postprocessing; for XR session lifecycle use threejs-webxr; for shader graphs use threejs-node-tsl."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `WebGLRenderer` or `WebGPURenderer` creation, `setSize`, `setPixelRatio`, `setAnimationLoop`
+- Color management: `outputColorSpace`, `toneMapping`, exposure-like behavior via renderer properties
+- `WebGLRenderTarget`, `WebGLCubeRenderTarget`, MRT, readback, or render-to-texture setup at renderer level
+- `Info` (`render`, `triangles`, `calls`) for profiling; `CanvasTarget` / storage textures when working from docs index
+
+**IMPORTANT: this skill vs neighbors**
+
+| Topic | Use skill |
+|-------|-----------|
+| Fullscreen passes, bloom, SSAO, composer chain | **threejs-postprocessing** |
+| VR/AR session, `XRButton`, hand models | **threejs-webxr** |
+| Node-based frame graph / TSL post stack | **threejs-node-tsl** + renderer enablement |
+| Loading assets | **threejs-loaders** |
+
+**Trigger phrases include:**
+
+- "WebGLRenderer", "WebGPURenderer", "setPixelRatio", "toneMapping", "WebGLRenderTarget"
+- "渲染器", "像素比", "色调映射", "离屏渲染"
+
+## How to use this skill
+
+1. **Choose API**: `WebGLRenderer` for widest compatibility; `WebGPURenderer` when targeting WebGPU and node/TSL stack per project rules.
+2. **Size**: match drawing buffer to canvas CSS size × `devicePixelRatio` with a sane cap (performance).
+3. **Color**: set `outputColorSpace` / `toneMapping` consistently with textures and materials (cross-link threejs-textures, threejs-materials).
+4. **Loop**: prefer `setAnimationLoop` for WebXR-friendly loops; otherwise `requestAnimationFrame`.
+5. **Render targets**: pick `WebGLRenderTarget` vs cube/3D/array variants per environment/reflection needs; document dispose when recreating.
+6. **Overlay UI**: import `CSS2DRenderer` / `CSS3DRenderer` from addons; sync size with main renderer.
+7. **Profiling**: read `renderer.info` in dev builds only; explain cost of high pixel ratio and overdraw.
+8. **WebXR hook**: enable XR on renderer but delegate session to **threejs-webxr**.
+
+See [examples/workflow-renderer-resize.md](examples/workflow-renderer-resize.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Core Renderers | https://threejs.org/docs/WebGLRenderer.html |
+| WebGPU | https://threejs.org/docs/WebGPURenderer.html |
+| Render targets | https://threejs.org/docs/WebGLRenderTarget.html |
+| Core PostProcessing (class) | https://threejs.org/docs/PostProcessing.html |
+| Addons renderers | https://threejs.org/docs/CSS2DRenderer.html |
+
+More class links: [references/official-sections.md](references/official-sections.md).
+
+## Scope
+
+- **In scope:** Renderer construction, sizing, color/tone, targets, Info, addon CSS/SVG renderers, high-level XR enable only.
+- **Out of scope:** Individual composer passes (threejs-postprocessing); XR input (threejs-webxr); file IO (threejs-loaders).
+
+## Common pitfalls and best practices
+
+- Uncapped DPR burns fill rate; cap `setPixelRatio(Math.min(devicePixelRatio, 2))` on dense scenes.
+- Mixing sRGB textures with wrong `outputColorSpace` causes washed or crushed blacks.
+- Forgetting `dispose()` on render targets and full-screen quads leaks GPU memory on hot reload.
+- `WebGPURenderer` feature set moves quickly—always cite current docs version note in answers.
+
+## Documentation and version
+
+`WebGLRenderer`, `WebGPURenderer`, and color-management defaults evolve across releases. Use the [Renderers](https://threejs.org/docs/#Renderers) section of [three.js docs](https://threejs.org/docs/) for the user’s three.js line; WebGPU and node stacks may require newer minors—link class pages rather than memorizing constructor defaults.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link official renderer or render-target pages (`WebGLRenderer`, `WebGLRenderTarget`, etc.).
+2. Relate `outputColorSpace` / `toneMapping` to **threejs-textures** and **threejs-materials** when color looks wrong.
+3. Point XR session details to **threejs-webxr** after `renderer.xr.enabled` is mentioned.
+4. Mention `dispose()` for render targets and render lists on teardown or hot reload.
+5. Cite **Addons → Renderers** (`CSS2DRenderer`, …) when overlays are in scope.
+
+## References
+
+- https://threejs.org/docs/WebGLRenderer.html
+- https://threejs.org/docs/WebGPURenderer.html
+- https://threejs.org/docs/#Renderers
+- https://threejs.org/docs/Info.html
+
+## Keywords
+
+**English:** webglrenderer, webgpurenderer, rendertarget, pixelratio, tonemapping, outputcolorspace, css2d, css3d, three.js
+
+**中文：** WebGLRenderer、WebGPU、渲染目标、像素比、色调映射、输出色彩空间、渲染器、three.js

package/skills/threejs-renderers/examples/workflow-renderer-resize.md

@@ -0,0 +1,21 @@
+# Workflow: responsive renderer and DPR cap
+
+## Goal
+
+Keep drawing buffer size in sync with the canvas element and limit device pixel ratio on high-DPI displays.
+
+## Steps
+
+1. Listen to `window` `resize` (or ResizeObserver on the canvas parent).
+
+2. Read `clientWidth` / `clientHeight` of the element hosting the canvas.
+
+3. Call `renderer.setSize(width, height, false)` when the third argument should match CSS pixels (typical for full-window).
+
+4. Set `renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))` (adjust cap per project).
+
+5. If using composer or effects that depend on resolution, update passes after resize—see **threejs-postprocessing**.
+
+6. Update projection `camera.aspect` for perspective cameras and `camera.updateProjectionMatrix()`.
+
+This complements **threejs-camera**; do not duplicate XR projection here.

package/skills/threejs-renderers/references/official-sections.md

@@ -0,0 +1,14 @@
+# Renderer-related docs (non-exhaustive)
+
+- https://threejs.org/docs/WebGLRenderer.html
+- https://threejs.org/docs/WebGPURenderer.html
+- https://threejs.org/docs/WebGLCubeRenderTarget.html
+- https://threejs.org/docs/WebGL3DRenderTarget.html
+- https://threejs.org/docs/Renderer.html
+- https://threejs.org/docs/PostProcessing.html
+- https://threejs.org/docs/CSS2DRenderer.html
+- https://threejs.org/docs/CSS3DRenderer.html
+- https://threejs.org/docs/SVGRenderer.html
+- https://threejs.org/docs/WebXRManager.html
+
+Use the live [docs index](https://threejs.org/docs/#Renderers) for additions in new three.js releases.

package/skills/threejs-scenes/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: threejs-scenes
+description: "three.js Scene graph root object, linear Fog and exponential FogExp2, Scene.background for solid colors or textures, and high-level environment background concepts that tie to PMREM and loaders in other skills. Use when configuring world container, atmospheric fog, or background; for HDR env map file loading use threejs-loaders; for GPU texture settings after load use threejs-textures; for tone mapping use threejs-renderers."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `Scene` as root, `scene.background`, environment or skyball setup at scene level
+- `Fog` or `FogExp2` parameters (`near`, `far`, `color`, density) and interaction with camera far plane
+- Organizing render lists conceptually (children of scene)
+
+**IMPORTANT: scenes vs textures vs loaders**
+
+| Concern | Skill |
+|---------|--------|
+| Scene + fog API | **threejs-scenes** |
+| Texture sampling, PMREM generator usage | **threejs-textures** |
+| Fetching HDR/glTF | **threejs-loaders** |
+
+**Trigger phrases include:**
+
+- "Scene", "Fog", "FogExp2", "background", "雾"
+- "场景根节点", "线性雾", "指数雾"
+
+## How to use this skill
+
+1. Instantiate `Scene` and add lights/meshes/cameras as children per graph rules (**threejs-objects**).
+2. Choose fog: linear `Fog` vs exponential `FogExp2` for outdoor/horizon feel.
+3. Tune fog `near`/`far` alongside camera `far` to avoid clipping artifacts.
+4. Set `scene.background` to `Color`, `Texture`, or cube map per docs; env lighting still needs matching renderer/material settings.
+5. When user wants IBL from HDR file, point to loaders → textures → materials pipeline explicitly.
+6. Document that fog does not replace frustum culling for performance.
+
+### Example: Scene with fog and background
+
+```javascript
+import * as THREE from 'three';
+
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(0xa0a0a0);
+
+// Linear fog — match color with background to hide horizon seam
+scene.fog = new THREE.Fog(0xa0a0a0, 10, 50);
+
+// Ensure camera far plane covers fog range
+camera.far = 60; // slightly beyond fog far
+camera.updateProjectionMatrix();
+```
+
+See [examples/workflow-fog-background.md](examples/workflow-fog-background.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Scenes | https://threejs.org/docs/Scene.html |
+| Fog | https://threejs.org/docs/Fog.html |
+| FogExp2 | https://threejs.org/docs/FogExp2.html |
+
+## Scope
+
+- **In scope:** `Scene`, fog types, background field semantics at API level.
+- **Out of scope:** HDR / glTF file fetch (**threejs-loaders**); PMREM and texture sampling (**threejs-textures**); tone mapping / output color space defaults (**threejs-renderers**); full-screen fog-only post stack (**threejs-postprocessing**) unless tying to scene `Fog`; custom atmospheric scattering shaders beyond core fog API.
+
+## Common pitfalls and best practices
+
+- Fog color should harmonize with background to hide the horizon seam.
+- Very large `far` on camera with fog still needs scene scale consistency.
+- `background` rotation/intensity features depend on renderer version—cite current docs.
+
+## Documentation and version
+
+`Scene`, `Fog`, and background fields are documented under [Scenes](https://threejs.org/docs/#Scenes) in [three.js docs](https://threejs.org/docs/). Environment-related visuals often combine this skill with **threejs-textures** (PMREM) and **threejs-loaders** (HDR files) — link those pages when the user moves from “fog color” to “HDR sky”.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `Scene`, `Fog`, or `FogExp2` official pages.
+2. Relate fog distances to **threejs-camera** `far` plane and world scale.
+3. Defer PMREM/HDR file steps to **threejs-textures** / **threejs-loaders** with one sentence each.
+4. Avoid duplicating full color-management tutorials — point to renderer + textures skills.
+
+## Keywords
+
+**English:** scene, fog, fogexp2, background, environment, three.js
+
+**中文：** 场景、雾、Fog、背景、环境、three.js

package/skills/threejs-scenes/examples/workflow-fog-background.md

@@ -0,0 +1,13 @@
+# Workflow: fog plus solid background
+
+## Steps
+
+1. `scene.background = new THREE.Color(0x87ceeb);`
+
+2. `scene.fog = new THREE.Fog(0x87ceeb, near, far);` — adjust `near`/`far` relative to world units.
+
+3. Keep `PerspectiveCamera.far` larger than fog `far` or tune both together.
+
+4. Remove fog by setting `scene.fog = null`.
+
+For textured HDR backgrounds, load env via **threejs-loaders** then assign textures per **threejs-textures** / PMREM flow.

package/skills/threejs-textures/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: threejs-textures
+description: "three.js textures: Texture, DataTexture, CubeTexture, CompressedTexture variants, DepthTexture, VideoTexture, CanvasTexture, 3D/array textures, Source; sampling parameters, mipmaps, anisotropy, wrap/mag/min filters; PMREMGenerator in Extras for environment map prefiltering. Use when configuring GPU texture objects and PMREM; for Draco/KTX2 transcoder file paths use threejs-loaders; for material map slots use threejs-materials; for output color pipeline use threejs-renderers."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `texture.wrapS` / `wrapT`, `minFilter`, `magFilter`, `generateMipmaps`, `anisotropy`
+- `colorSpace` / correct handling of sRGB vs linear data maps
+- Creating `DataTexture`, `CubeTexture`, compressed GPU formats, video/canvas driven textures
+- `PMREMGenerator` from environment maps for IBL
+
+**IMPORTANT: textures vs loaders**
+
+| Step | Skill |
+|------|--------|
+| Decode file / HTTP | **threejs-loaders** |
+| Configure GPU `Texture` | **threejs-textures** |
+
+**Trigger phrases include:**
+
+- "Texture", "CubeTexture", "PMREM", "colorSpace", "mipmap", "各向异性"
+- "环境贴图", "数据纹理", "压缩纹理"
+
+## How to use this skill
+
+1. **Classify** texture dimensionality and format (2D, cube, depth, compressed, data).
+2. **Color pipeline**: set `colorSpace` appropriately; normal/roughness maps are non-color data.
+3. **Sampling**: choose filters; enable mipmaps when minification occurs; consider max anisotropy.
+4. **PMREM**: feed env map through `PMREMGenerator` per docs; assign result to scene/env/intensity paths as required.
+5. **Video/canvas**: understand update needs each frame for `VideoTexture` / `CanvasTexture`.
+6. **Disposal**: `dispose()` textures when replacing to free GPU memory.
+7. **KTX2/Basis**: transcoder wiring belongs in **threejs-loaders** before this step.
+
+See [examples/workflow-pmrem-env.md](examples/workflow-pmrem-env.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Textures | https://threejs.org/docs/Texture.html |
+| Cube | https://threejs.org/docs/CubeTexture.html |
+| Data | https://threejs.org/docs/DataTexture.html |
+| PMREM | https://threejs.org/docs/PMREMGenerator.html |
+
+## Scope
+
+- **In scope:** Core Textures + PMREMGenerator; sampling and color pipeline at texture level.
+- **Out of scope:** Loader configuration; post-processing passes that sample buffers (threejs-postprocessing).
+
+## Common pitfalls and best practices
+
+- sRGB albedo in linear workflow without proper colorSpace looks wrong next to renderer output.
+- Non-power-of-two textures have mip/wrap limitations unless padded.
+- Forgetting texture disposal on hot reload leaks VRAM.
+
+## Documentation and version
+
+Texture classes and `PMREMGenerator` are documented under [Textures](https://threejs.org/docs/#Textures) and [PMREMGenerator](https://threejs.org/docs/PMREMGenerator.html) in [three.js docs](https://threejs.org/docs/). Compressed and KTX2 paths often depend on **threejs-loaders** for transcoder setup before this skill applies.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `Texture`, `DataTexture`, `CubeTexture`, or `PMREMGenerator` as appropriate.
+2. Tie `colorSpace` / filtering to **threejs-renderers** output and **threejs-materials** maps.
+3. Send Draco/KTX2 **decoder wiring** questions to **threejs-loaders** first.
+4. Emphasize `dispose()` when replacing env maps or large atlases.
+5. Mention [Global](https://threejs.org/docs/#Global) constants only when wrapping/filter enums matter.
+
+## References
+
+- https://threejs.org/docs/#Textures
+- https://threejs.org/docs/Texture.html
+- https://threejs.org/docs/PMREMGenerator.html
+
+## Keywords
+
+**English:** texture, cubemap, pmrem, mipmap, colorspace, compressed texture, data texture, three.js
+
+**中文：** 纹理、立方体贴图、PMREM、mipmap、色彩空间、压缩纹理、three.js

package/skills/threejs-textures/examples/workflow-pmrem-env.md

@@ -0,0 +1,19 @@
+# Workflow: PMREM from an equirectangular texture
+
+## Preconditions
+
+- An equirectangular HDR or suitable env image is already a `Texture` (often via **threejs-loaders**).
+
+## Steps
+
+1. Create `PMREMGenerator(renderer)`.
+
+2. `const envMap = pmremGenerator.fromEquirectangular(equirectTexture).texture;`
+
+3. Assign to scene or materials per your lighting model; intensity via renderer or material properties (**threejs-materials**).
+
+4. `pmremGenerator.dispose()` when done generating; dispose intermediate textures per docs.
+
+5. Dispose `equirectTexture` if no longer needed.
+
+Cross-check current [PMREMGenerator](https://threejs.org/docs/PMREMGenerator.html) for API variants (`fromScene`, etc.).

package/skills/threejs-webxr/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: threejs-webxr
+description: "WebXR integration for three.js: WebXRManager and XRManager on the renderer, session initialization patterns, VRButton and ARButton helpers, XRControllerModelFactory and hand model families, XREstimatedLight, XRPlanes, and related addon Webxr utilities. Use for immersive sessions and controller/hand tracking—not for standard desktop camera projection (threejs-camera) or composer post effects (threejs-postprocessing)."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Entering VR/AR, `navigator.xr`, reference spaces, session `requestAnimationFrame` loop via renderer
+- `VRButton`, `ARButton`, `XRButton` creation patterns from examples
+- Controller models, hand tracking meshes, estimated real-world lighting probes
+
+**IMPORTANT: webxr vs renderers vs camera**
+
+| Topic | Skill |
+|-------|--------|
+| Enable XR on renderer, sizing | **threejs-renderers** (basics) + **threejs-webxr** (session) |
+| Desktop projection | **threejs-camera** |
+
+**Trigger phrases include:**
+
+- "WebXR", "VRButton", "ARButton", "XRControllerModelFactory", "hand tracking"
+- "虚拟现实", "增强现实", "沉浸式"
+
+## How to use this skill
+
+1. **HTTPS** requirement and feature detection for XR availability.
+2. **Buttons**: use official button factories to create DOM entry points; handle session end.
+3. **Renderer**: call `renderer.xr.enabled = true` patterns per docs; prefer `setAnimationLoop` for XR loops.
+4. **Controllers**: attach models via factories; read gamepad axes/buttons carefully with fallbacks.
+5. **Hands**: opt-in hand models when runtime supports; performance implications.
+6. **Lighting**: `XREstimatedLight` for AR realism—combine with **threejs-lights** cautiously.
+7. **Exit**: restore non-XR render loop and resize handling on session end.
+
+### Example: VR session with error handling
+
+```javascript
+import { VRButton } from 'three/addons/webxr/VRButton.js';
+
+// Feature detection and session start
+if ('xr' in navigator) {
+  renderer.xr.enabled = true;
+  document.body.appendChild(VRButton.createButton(renderer));
+
+  renderer.xr.addEventListener('sessionstart', () => {
+    console.log('XR session started');
+  });
+  renderer.xr.addEventListener('sessionend', () => {
+    console.log('XR session ended — restoring desktop view');
+  });
+} else {
+  console.warn('WebXR not supported in this browser');
+}
+```
+
+See [examples/workflow-xr-button.md](examples/workflow-xr-button.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Renderer XR | https://threejs.org/docs/WebXRManager.html |
+| Webxr addons | https://threejs.org/docs/VRButton.html |
+| Webxr addons | https://threejs.org/docs/ARButton.html |
+| Webxr addons | https://threejs.org/docs/XRControllerModelFactory.html |
+
+## Scope
+
+- **In scope:** Documented WebXR manager + listed addons for buttons/controllers/hands/planes.
+- **Out of scope:** Store submission, OpenXR runtime specifics, custom native layers.
+
+## Common pitfalls and best practices
+
+- Desktop testing requires XR emulation or hardware; fail gracefully.
+- Mismatched reference space causes floor offset—validate stage vs local-floor.
+- Heavy post chains may not meet VR frame time—profile aggressively.
+
+## Documentation and version
+
+WebXR entry points span **Addons → Webxr** and renderer [`WebXRManager`](https://threejs.org/docs/WebXRManager.html) in [three.js docs](https://threejs.org/docs/). Browser and device capabilities vary—answers should cite the official example name and three.js version when possible.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `WebXRManager`, `VRButton`, `ARButton`, or controller factories as relevant.
+2. Use `setAnimationLoop` patterns with **threejs-renderers** for XR render loops.
+3. Avoid duplicating desktop **threejs-camera** projection advice for XR eyes.
+4. Mention reference space choice (local-floor, etc.) at a high level with docs link.
+5. Flag performance interaction with **threejs-postprocessing** in VR.
+
+## References
+
+- https://threejs.org/docs/WebXRManager.html
+- https://threejs.org/docs/VRButton.html
+- https://threejs.org/docs/ARButton.html
+- https://threejs.org/docs/XRControllerModelFactory.html
+
+## Keywords
+
+**English:** webxr, vr, ar, xr session, controller, hand tracking, three.js
+
+**中文：** WebXR、VR、AR、VRButton、手柄、手部追踪、沉浸式、three.js

package/skills/threejs-webxr/examples/workflow-xr-button.md

@@ -0,0 +1,15 @@
+# Workflow: VR entry button
+
+## Steps
+
+1. Ensure site served over HTTPS and `navigator.xr` checked.
+
+2. `document.body.appendChild(VRButton.createButton(renderer));` per [VRButton](https://threejs.org/docs/VRButton.html) for your three version.
+
+3. `renderer.xr.enabled = true;` Use `renderer.setAnimationLoop` callback for render + updates.
+
+4. Handle session end to restore window `resize` behavior if needed.
+
+5. For AR passthrough use `ARButton` instead—see **threejs-webxr** doc map.
+
+Always verify against the official example that matches your three.js revision.

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/goal.md

@@ -0,0 +1,86 @@
+---
+description: 🎯 Codex Goal Conductor — Pursue high-level goals autonomously using Codex coordination
+---
+
+# /goal — Codex Goal Mode Workflow
+
+> Launch Codex in Goal Mode to orchestrate multi-agent task execution and pursue complex goals.
+
+---
+
+## 🛠️ Step-by-Step Execution
+
+### 1. Prerequisites Check
+Ensure Codex CLI is installed on the system:
+```bash
+which codex || echo "NOT_INSTALLED"
+```
+If missing, suggest the user install it:
+```bash
+npm i -g @openai/codex
+```
+
+### 2. Launching the Goal
+Initiate the goal execution loop:
+```bash
+awkit goal "Build a simple greeting command line tool"
+```
+Or execute through a specific pipeline command:
+```bash
+awkit pipeline goal "FeatureName"
+```
+
+### 3. Loop Execution Flow
+1. **Initialize State:** Create directory `codex-reports/goals/<goal_id>/` and output the planned task list.
+2. **Set Goal Mode:** Set `goal_mode = true` globally so that checkpoints automatically verify and bypass user blocks.
+3. **Task Orchestration:** The loop script (`scripts/codex-goal.js`) executes tasks sequentially:
+   - Partition goal → Delegate plan/design to Claude.
+   - Implement code → Delegate implementation to Qwen.
+   - Verification → Run Codex sub-agents (`critic` or `tester`).
+4. **State Persistence:** Save logs and state changes at the end of each step.
+
+---
+
+## 🔔 Sub-commands
+
+### `/goal:status`
+Check the status of the currently active goal and print active task reports:
+```bash
+node scripts/codex-goal.js --status
+```
+
+### `/goal:pause`
+Pause the active goal execution loop and save the current state:
+```bash
+node scripts/codex-goal.js --pause
+```
+
+### `/goal:resume`
+Resume the most recently paused or saved goal session:
+```bash
+node scripts/codex-goal.js --resume
+```
+
+### `/goal:cancel`
+Cancel the active goal session, clean up temporary resources, and reset `goal_mode = false`:
+```bash
+node scripts/codex-goal.js --cancel
+```
+
+---
+
+## 🔔 Sound Notifications
+
+Upon task completion or session completion, trigger sound alerts:
+- Success: `afplay /System/Library/Sounds/Glass.aiff && say "Goal phase completed successfully"`
+- Paused/Blocker: `afplay /System/Library/Sounds/Basso.aiff && say "Goal execution paused. User attention required."`
+
+---
+
+## 🚫 Fallback Policy
+
+- If Codex CLI fails to launch or encounters critical issues:
+  - Fall back to standard **Gemini Conductor** or **Claude Planner** workflows (`scripts/claude-plan.js` or `agy`).
+- If Qwen CLI is not available during execution:
+  - Fall back to `agy --model gemini-3.5-flash` for code generation.
+- Ensure the orchestration script does not crash and logs error outputs gracefully to `codex-reports/goals/error.log`.