@leejungkiin/awkit 1.7.6 → 1.7.8

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/skills/threejs-animation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: threejs-animation
+description: "three.js keyframe animation system: AnimationMixer, AnimationClip, AnimationAction, KeyframeTrack variants, PropertyBinding, PropertyMixer, AnimationObjectGroup, AnimationUtils; mixing and crossfading clips, loop modes, timeScale, weight; addon AnimationClipCreator and CCDIKSolver for procedural rigs. Use when playing glTF clips, blending actions, or authoring procedural tracks; for skin deformation rigging on meshes see threejs-objects; for math interpolants without clips see threejs-math only when not tied to AnimationMixer."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `AnimationMixer.update`, `AnimationAction` play/pause/stop, crossfade, synchronized clips
+- `AnimationClip` from glTF or `AnimationClipCreator`, retargeting caveats at API level
+- Keyframe tracks: position/rotation/scale/color tracks, boolean/string tracks where applicable
+- IK: `CCDIKSolver` / `CCDIKHelper` from addons
+
+**IMPORTANT: animation vs objects**
+
+- **threejs-animation** = time evaluation and tracks.
+- **threejs-objects** = `SkinnedMesh`/`Skeleton` attachment, bind pose—mesh side.
+
+**Trigger phrases include:**
+
+- "AnimationMixer", "AnimationAction", "AnimationClip", "crossFade", "KeyframeTrack"
+- "动画混合", "骨骼动画", "剪辑", "淡入淡出"
+
+## How to use this skill
+
+1. **Collect clips** from `gltf.animations` or create with utilities / `AnimationClipCreator`.
+2. **Create mixer** bound to root object (often `scene` or rig root).
+3. **Create actions** per clip via `mixer.clipAction(clip)`; configure loop mode (`LoopOnce`, `LoopRepeat`, `LoopPingPong`).
+4. **Per frame**: compute delta seconds (use `Clock` from core—documented under Core in docs index), call `mixer.update(delta)`.
+5. **Blending**: adjust `weight`, `crossFadeTo`, `enabled` flags; watch for additive vs full replacement semantics per docs.
+6. **PropertyBinding**: understand path strings targeting bones/morphs—errors often from wrong object names.
+7. **IK addon**: attach solver after base animation if using CCD IK from examples.
+
+See [examples/workflow-mixer-action.md](examples/workflow-mixer-action.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Animation (index) | https://threejs.org/docs/#Animation |
+| Action | https://threejs.org/docs/AnimationAction.html |
+| Mixer | https://threejs.org/docs/AnimationMixer.html |
+| Clip | https://threejs.org/docs/AnimationClip.html |
+| Tracks | https://threejs.org/docs/KeyframeTrack.html |
+
+More: [references/official-sections.md](references/official-sections.md).
+
+## Scope
+
+- **In scope:** Core Animation module, keyframe pipeline, listed addons for clip creation and IK.
+- **Out of scope:** DCC export best practices; physics ragdoll; audio sync (link conceptually only).
+
+## Common pitfalls and best practices
+
+- Forgetting `mixer.update` freezes animation; double `update` per frame speeds up.
+- Mixing clips with incompatible hierarchies causes violent pops—validate bind pose.
+- Root motion must be handled in game logic if not baked—document explicitly.
+- Large track counts cost CPU—strip unused tracks in preprocessing when possible.
+
+## Documentation and version
+
+Behavior of `AnimationMixer`, tracks, and glTF animation import can change between three.js majors. Treat the [Animation](https://threejs.org/docs/#Animation) section of the [docs index](https://threejs.org/docs/) as authoritative for the user’s installed version; when upgrading, check the three.js repository release notes and migration notes for renamed properties or loader output.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Cite the exact class (`AnimationMixer`, `AnimationAction`, etc.) or addon (`CCDIKSolver`) from the official docs.
+2. Include at least one `https://threejs.org/docs/...` link (e.g. [AnimationAction](https://threejs.org/docs/AnimationAction.html)).
+3. Relate clips to `SkinnedMesh` / skeleton via **threejs-objects** when deformation is involved.
+4. Mention `mixer.update(delta)` and a stable time source (`Clock`) explicitly.
+5. Reference official **examples** by name only (no full file paste).
+
+## References
+
+- https://threejs.org/docs/#Animation
+- https://threejs.org/docs/AnimationMixer.html
+- https://threejs.org/docs/AnimationAction.html
+- https://threejs.org/docs/PropertyBinding.html
+
+## Keywords
+
+**English:** animationmixer, animationaction, animationclip, keyframetrack, crossfade, skinning, propertybinding, three.js
+
+**中文：** 动画混合、AnimationMixer、AnimationAction、关键帧、骨骼动画、剪辑、淡入淡出、three.js

package/skills/threejs-animation/examples/workflow-mixer-action.md

@@ -0,0 +1,20 @@
+# Workflow: play one glTF clip
+
+## Steps
+
+1. After **threejs-loaders** provides `gltf` with `animations` array non-empty.
+
+2. `const mixer = new THREE.AnimationMixer(gltf.scene);`
+
+3. `const clip = gltf.animations[0]; const action = mixer.clipAction(clip); action.play();`
+
+4. In the render loop: `const delta = clock.getDelta(); mixer.update(delta);` then render (**threejs-renderers**).
+
+5. To switch clips, prepare second `clipAction`, then `action.crossFadeTo(nextAction, duration, false)` per docs.
+
+6. Dispose mixer when discarding the rig if your app hot-swaps characters.
+
+## Anchor
+
+- https://threejs.org/docs/AnimationMixer.html
+- https://threejs.org/docs/AnimationAction.html

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

@@ -0,0 +1,19 @@
+# Animation module (core)
+
+- https://threejs.org/docs/AnimationAction.html
+- https://threejs.org/docs/AnimationClip.html
+- https://threejs.org/docs/AnimationMixer.html
+- https://threejs.org/docs/AnimationObjectGroup.html
+- https://threejs.org/docs/AnimationUtils.html
+- https://threejs.org/docs/KeyframeTrack.html
+- https://threejs.org/docs/VectorKeyframeTrack.html
+- https://threejs.org/docs/QuaternionKeyframeTrack.html
+- https://threejs.org/docs/PropertyBinding.html
+- https://threejs.org/docs/PropertyMixer.html
+
+**Addons**
+
+- https://threejs.org/docs/AnimationClipCreator.html
+- https://threejs.org/docs/CCDIKSolver.html
+
+See https://threejs.org/docs/#Animation

package/skills/threejs-audio/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: threejs-audio
+description: "three.js audio spatialization: AudioListener attached to camera rig, Audio and PositionalAudio sources, AudioAnalyser for FFT/time-domain data, and integration with Web Audio API contexts; AudioLoader is referenced from threejs-loaders for file decoding. Use when placing 3D sound, configuring panner parameters, or building audio visualization; not a replacement for full game audio middleware."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `AudioListener` on `Camera`, `Audio` vs `PositionalAudio`, distance models, refDistance/maxDistance/rolloff
+- `AudioAnalyser` for visualization bars/spectrum
+- Browser autoplay policies blocking audio start
+
+**IMPORTANT: audio vs loaders**
+
+| Step | Skill |
+|------|--------|
+| Decode mp3/ogg buffer | **threejs-loaders** (`AudioLoader`) |
+| Spatial playback API | **threejs-audio** |
+
+**Trigger phrases include:**
+
+- "PositionalAudio", "AudioListener", "AudioAnalyser", "panner"
+- "空间音频", "音量衰减", "频谱"
+
+## How to use this skill
+
+1. **Attach listener** to camera object so head-related audio follows view.
+2. **Validate AudioContext state** — check `listener.context.state` before playback; resume if suspended.
+3. **Create context** compatible with user gesture unlock patterns in browsers.
+4. **PositionalAudio** — set `refDistance`, `maxDistance`, `rolloffFactor`, `distanceModel` per docs.
+5. **Load buffer** via `AudioLoader` (**threejs-loaders**), then `positionalAudio.setBuffer`.
+6. **Analyser** — connect graph `listener.context.createAnalyser()` pathways per examples; watch performance.
+7. **Update** — audio nodes usually need no per-frame update unless following moving sources manually.
+
+### Example: PositionalAudio with context validation
+
+```javascript
+import * as THREE from 'three';
+
+const listener = new THREE.AudioListener();
+camera.add(listener);
+
+// Validate AudioContext state before attempting playback
+function ensureAudioContext() {
+  if (listener.context.state === 'suspended') {
+    listener.context.resume();
+  }
+}
+
+// Resume on user gesture (required by browser autoplay policy)
+document.addEventListener('click', ensureAudioContext, { once: true });
+
+const sound = new THREE.PositionalAudio(listener);
+const loader = new THREE.AudioLoader();
+loader.load('sound.mp3', (buffer) => {
+  sound.setBuffer(buffer);
+  sound.setRefDistance(20);
+  sound.setRolloffFactor(1);
+});
+mesh.add(sound); // Attach to a scene object for spatial positioning
+```
+
+See [examples/workflow-positional-audio.md](examples/workflow-positional-audio.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Audio | https://threejs.org/docs/AudioListener.html |
+| Audio | https://threejs.org/docs/Audio.html |
+| Audio | https://threejs.org/docs/PositionalAudio.html |
+| Audio | https://threejs.org/docs/AudioAnalyser.html |
+
+Extended list: [references/official-sections.md](references/official-sections.md).
+
+## Scope
+
+- **In scope:** Core Audio classes, spatialization parameters, analyser usage overview.
+- **Out of scope:** FMOD/Wwise-style authoring tools.
+
+## Common pitfalls and best practices
+
+- Autoplay restrictions require user interaction to resume AudioContext.
+- Too many positional sources hurt CPU—pool or LOD audio.
+- Ensure world units match distance model expectations.
+
+## Documentation and version
+
+Audio classes are under [Audio](https://threejs.org/docs/#Audio) in [three.js docs](https://threejs.org/docs/). Decoding buffers uses `AudioLoader`—see **threejs-loaders**. Browser Web Audio policies are external but must be mentioned when `AudioContext` is suspended.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `AudioListener`, `PositionalAudio`, or `AudioAnalyser` as relevant.
+2. Delegate file loading of sound buffers to **threejs-loaders** (`AudioLoader`).
+3. Note autoplay / user-gesture requirements for resuming context.
+4. Relate distance attenuation to world units and **threejs-objects** placement.
+5. Avoid promising DAW-level mixing—stay within three.js audio scope.
+
+## References
+
+- https://threejs.org/docs/#Audio
+- https://threejs.org/docs/AudioListener.html
+- https://threejs.org/docs/PositionalAudio.html
+
+## Keywords
+
+**English:** audio, positional audio, listener, analyser, spatial sound, web audio, three.js
+
+**中文：** 音频、空间音频、AudioListener、PositionalAudio、Web Audio、three.js

package/skills/threejs-audio/examples/workflow-positional-audio.md

@@ -0,0 +1,15 @@
+# Workflow: positional loop with loader
+
+## Steps
+
+1. Create `AudioListener`, `camera.add(listener)`.
+
+2. `const sound = new THREE.PositionalAudio(listener);`
+
+3. `const loader = new THREE.AudioLoader();` (**threejs-loaders**) `loader.load('file.ogg', buffer => { sound.setBuffer(buffer); sound.setRefDistance(1); sound.play(); });`
+
+4. Add `sound` as child of moving mesh or update position each frame.
+
+5. Connect `AudioAnalyser` only if visualization required—extra CPU.
+
+Browser autoplay: resume context on first click if needed.

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

@@ -0,0 +1,16 @@
+# Audio module (core)
+
+Index: https://threejs.org/docs/#Audio
+
+- https://threejs.org/docs/AudioListener.html
+- https://threejs.org/docs/Audio.html
+- https://threejs.org/docs/PositionalAudio.html
+- https://threejs.org/docs/AudioAnalyser.html
+
+**Loaders (decode buffers — see skill `threejs-loaders`)**
+
+- https://threejs.org/docs/AudioLoader.html
+
+**Addons (positional helper)**
+
+- https://threejs.org/docs/PositionalAudioHelper.html

package/skills/threejs-camera/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: threejs-camera
+description: "three.js cameras: Camera base, PerspectiveCamera, OrthographicCamera, CubeCamera, ArrayCamera, StereoCamera; projection matrices, aspect, FOV, orthographic frustum sizes, near/far planes, and dynamic environment maps with CubeCamera. Use when placing views, rendering reflections, or multi-view splits; for XR projections and eye matrices use threejs-webxr; for post pass camera tricks use threejs-postprocessing alongside threejs-renderers."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Switching perspective vs orthographic, `fov`, `aspect`, `zoom`, `near`, `far`
+- `CubeCamera` for real-time environment maps or reflections (update rate caveats)
+- `ArrayCamera`/`StereoCamera` for multi-view or stereo off-axis projection (non-XR)
+
+**IMPORTANT: camera vs webxr vs post**
+
+| Topic | Skill |
+|-------|--------|
+| Standard desktop projection | **threejs-camera** |
+| XR reference spaces, IPD | **threejs-webxr** |
+| Offscreen pass cameras inside composer | **threejs-postprocessing** |
+
+**Trigger phrases include:**
+
+- "PerspectiveCamera", "OrthographicCamera", "CubeCamera", "aspect", "near", "far"
+- "透视相机", "正交", "立方体相机"
+
+## How to use this skill
+
+1. **Perspective**: set `aspect` = width/height; update on resize (**threejs-renderers** example workflow).
+2. **Orthographic**: define `left/right/top/bottom` in world units for CAD/2.5D views.
+3. **Near/far**: balance depth precision vs containing scene bounds; relate to fog (**threejs-scenes**).
+4. **CubeCamera**: position at reflection probe; call `update` when scene static enough; use render target outputs per docs.
+5. **Stereo/Array**: advanced; cite docs for eye parameters; defer XR to **threejs-webxr**.
+6. **Projection matrix**: call `updateProjectionMatrix()` after parameter edits.
+7. **Helpers**: `CameraHelper` lives in **threejs-helpers**.
+
+### Example: Resize handler with updateProjectionMatrix
+
+```javascript
+window.addEventListener('resize', () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+See [examples/workflow-perspective-resize.md](examples/workflow-perspective-resize.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Cameras (index) | https://threejs.org/docs/#Cameras |
+| Cameras | https://threejs.org/docs/Camera.html |
+| Perspective | https://threejs.org/docs/PerspectiveCamera.html |
+| Orthographic | https://threejs.org/docs/OrthographicCamera.html |
+| Cube | https://threejs.org/docs/CubeCamera.html |
+| Multi-view | https://threejs.org/docs/ArrayCamera.html |
+| Stereo (non-XR) | https://threejs.org/docs/StereoCamera.html |
+
+## Scope
+
+- **In scope:** Core camera classes and parameters; cube/array/stereo overview.
+- **Out of scope:** WebXR reference spaces, eye matrices, session lifecycle (**threejs-webxr**); shadow map camera tuning (**threejs-lights**); pass-internal cameras in composer (**threejs-postprocessing**).
+
+## Common pitfalls and best practices
+
+- Wrong `aspect` after resize stretches image—always sync with canvas.
+- Too small `near` hurts depth precision in large worlds.
+- `CubeCamera` every frame is expensive—throttle for performance.
+
+## Documentation and version
+
+Camera parameters and `CubeCamera` update behavior follow the [Cameras](https://threejs.org/docs/#Cameras) section of [three.js docs](https://threejs.org/docs/). WebXR uses different projection paths—hand off to **threejs-webxr** when the user mentions headsets or reference spaces.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `PerspectiveCamera`, `OrthographicCamera`, or `CubeCamera` as relevant.
+2. Pair resize with **threejs-renderers** `setSize` / DPR patterns when relevant.
+3. Route `XR`/`WebXRManager` questions to **threejs-webxr** after one-line renderer mention.
+4. Mention `updateProjectionMatrix()` after intrinsic changes.
+5. Use **threejs-helpers** `CameraHelper` for shadow frustum debug when discussing lights.
+
+## References
+
+- https://threejs.org/docs/#Cameras
+- https://threejs.org/docs/PerspectiveCamera.html
+- https://threejs.org/docs/CubeCamera.html
+
+## Keywords
+
+**English:** perspectivecamera, orthographiccamera, cubecamera, projection, aspect, near, far, three.js
+
+**中文：** 相机、透视、正交、投影、近裁剪、远裁剪、CubeCamera、three.js

package/skills/threejs-camera/examples/workflow-perspective-resize.md

@@ -0,0 +1,13 @@
+# Workflow: perspective camera on window resize
+
+## Steps
+
+1. Store `PerspectiveCamera` reference.
+
+2. On resize: `camera.aspect = width / height; camera.updateProjectionMatrix();`
+
+3. Pair with renderer `setSize` from **threejs-renderers** examples.
+
+4. For orthographic cameras, recompute `left/right/top/bottom` if using fit-to-view logic.
+
+This is the standard pattern used across three.js examples.

package/skills/threejs-controls/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: threejs-controls
+description: "Addon camera and object manipulation controls: OrbitControls, MapControls, FlyControls, FirstPersonControls, TrackballControls, ArcballControls, DragControls, PointerLockControls, TransformControls; damping, target focal point, and integration with the animation loop. Use for editor-style navigation and gizmos—not a full game character controller stack; pair with Raycaster selection patterns in threejs-objects when transforming selections."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Orbiting/panning/dolly around a target, inertia/damping, min/max distance/polar angles
+- Map-like pan (MapControls) or flying (FlyControls)
+- Transform gizmo translate/rotate/scale with `TransformControls`
+- Dragging objects in plane (DragControls), pointer lock FPS (PointerLockControls)
+
+**IMPORTANT: controls vs webxr**
+
+| Context | Skill |
+|---------|--------|
+| Desktop/browser camera nav | **threejs-controls** |
+| XR controller poses | **threejs-webxr** |
+
+**Trigger phrases include:**
+
+- "OrbitControls", "TransformControls", "MapControls", "PointerLockControls"
+- "轨道", "变换控制器", "漫游"
+
+## How to use this skill
+
+1. **Import** from addons path (**threejs-dev-setup**).
+2. **Construct** with `(camera, domElement)`; for `TransformControls` also attach to renderer events.
+3. **Animation loop**: when `enableDamping`, call `controls.update()` each frame.
+4. **TransformControls**: wire `dragging-changed` to disable Orbit temporarily; sync with selection from **threejs-objects**.
+5. **Constraints**: set min/max distance/angles to avoid flipping or underground views.
+6. **Dispose**: `controls.dispose()` when tearing down.
+
+### Example: OrbitControls with damping
+
+```javascript
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.enableDamping = true;
+controls.dampingFactor = 0.05;
+controls.minDistance = 2;
+controls.maxDistance = 50;
+
+// Must call update() each frame when damping is enabled
+function animate() {
+  controls.update();
+  renderer.render(scene, camera);
+}
+renderer.setAnimationLoop(animate);
+```
+
+See [examples/workflow-orbit-damping.md](examples/workflow-orbit-damping.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Controls | https://threejs.org/docs/OrbitControls.html |
+| Controls | https://threejs.org/docs/TransformControls.html |
+| Controls | https://threejs.org/docs/MapControls.html |
+| Controls (index) | https://threejs.org/docs/#Controls |
+
+## Scope
+
+- **In scope:** Official addons controls usage patterns.
+- **Out of scope:** Full physics character motor; mobile gesture frameworks.
+
+## Common pitfalls and best practices
+
+- Forgetting `update()` with damping enabled causes drift never settling.
+- TransformControls fighting with Orbit—pause one while using the other.
+- Pointer lock requires user gesture and exit handling.
+
+## Documentation and version
+
+Controls are under [Controls](https://threejs.org/docs/#Controls) (Addons) in [three.js docs](https://threejs.org/docs/). API details (`enableDamping`, events) evolve—link `OrbitControls` / `TransformControls` pages for the user’s three.js version.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link the specific controls class from the docs.
+2. State `controls.update()` when damping is on, every frame.
+3. Coordinate `TransformControls` with selection / **threejs-objects** raycasting.
+4. Separate desktop navigation from **threejs-webxr** locomotion.
+5. Call `dispose()` on controls when unmounting canvas.
+
+## References
+
+- https://threejs.org/docs/#Controls
+- https://threejs.org/docs/OrbitControls.html
+- https://threejs.org/docs/TransformControls.html
+
+## Keywords
+
+**English:** orbitcontrols, transformcontrols, mapcontrols, damping, camera controls, three.js
+
+**中文：** OrbitControls、轨道、TransformControls、变换控制器、阻尼、three.js

package/skills/threejs-controls/examples/workflow-orbit-damping.md

@@ -0,0 +1,15 @@
+# Workflow: OrbitControls with damping
+
+## Steps
+
+1. `const controls = new OrbitControls(camera, renderer.domElement);`
+
+2. `controls.enableDamping = true; controls.dampingFactor = 0.05;`
+
+3. Each frame before render: `controls.update();`
+
+4. Listen to `controls.addEventListener('change', render)` only if using lazy rendering; continuous apps already render in rAF.
+
+5. On destroy: `controls.dispose()`.
+
+API: https://threejs.org/docs/OrbitControls.html