@xonovex/skills 0.1.0

package/skills/terraform-guidelines/reference/module-definition.md

@@ -0,0 +1,81 @@
+# module-definition: Module Definition Pattern
+
+**Guideline:** Define reusable modules with typed variables, validation rules, computed locals, and explicit outputs
+
+**Rationale:** Well-defined interfaces make modules composable and prevent configuration errors
+
+**Example:**
+
+```hcl
+# modules/network/variables.tf
+variable "vpc_cidr" {
+  description = "CIDR block for VPC"
+  type        = string
+  validation {
+    condition     = can(cidrhost(var.vpc_cidr, 0))
+    error_message = "Must be valid IPv4 CIDR"
+  }
+}
+
+variable "environment" {
+  description = "Environment name"
+  type        = string
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Must be dev, staging, or prod"
+  }
+}
+
+variable "availability_zones" {
+  description = "List of availability zones"
+  type        = list(string)
+  default     = []
+}
+
+# modules/network/main.tf
+locals {
+  common_tags = merge(
+    var.tags,
+    {
+      Module      = "network"
+      Environment = var.environment
+      ManagedBy   = "terraform"
+    }
+  )
+
+  subnet_cidrs = [
+    for i, az in var.availability_zones :
+    cidrsubnet(var.vpc_cidr, 8, i)
+  ]
+}
+
+resource "aws_vpc" "this" {
+  cidr_block           = var.vpc_cidr
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = merge(local.common_tags, {
+    Name = "${var.environment}-vpc"
+  })
+}
+
+# modules/network/outputs.tf
+output "vpc_id" {
+  description = "ID of the VPC"
+  value       = aws_vpc.this.id
+}
+
+output "vpc_cidr" {
+  description = "CIDR block of the VPC"
+  value       = aws_vpc.this.cidr_block
+}
+```
+
+**Techniques:**
+- **Type constraints:** Specify all variable types to enable early validation
+- **Validation blocks:** Add business logic constraints like CIDR format checking
+- **Common locals:** Centralize shared tags and computed values for consistency
+- **CIDR transformations:** Use cidrsubnet() in locals for flexible subnet allocation
+- **Descriptive outputs:** Export all useful values with clear descriptions
+- **Environment isolation:** Use tags and naming patterns for multi-environment support
+

package/skills/terraform-guidelines/reference/module-structure.md

@@ -0,0 +1,51 @@
+# module-structure: Module Organization
+
+**Guideline:** Organize modules with separate directories for reusable modules and environment-specific configurations
+
+**Rationale:** Clear separation between modules and environments enables reusability and environment isolation
+
+**Example:**
+
+```
+terraform/
+├── modules/
+│   ├── network/
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── outputs.tf
+│   │   └── README.md
+│   ├── compute/
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── outputs.tf
+│   │   └── README.md
+│   └── database/
+│       ├── main.tf
+│       ├── variables.tf
+│       ├── outputs.tf
+│       └── README.md
+└── environments/
+    ├── dev/
+    │   ├── main.tf
+    │   ├── variables.tf
+    │   ├── terraform.tfvars
+    │   └── backend.tf
+    ├── staging/
+    │   ├── main.tf
+    │   ├── variables.tf
+    │   ├── terraform.tfvars
+    │   └── backend.tf
+    └── prod/
+        ├── main.tf
+        ├── variables.tf
+        ├── terraform.tfvars
+        └── backend.tf
+```
+
+**Techniques:**
+- **Modules directory:** Group reusable infrastructure components by capability
+- **Environments directory:** Create separate root modules for dev, staging, prod
+- **Standard files:** Use main.tf, variables.tf, outputs.tf, backend.tf consistently
+- **Module README:** Document each module's purpose, variables, and outputs
+- **Relative sourcing:** Use relative paths in module sources for portability
+

package/skills/terraform-guidelines/reference/remote-state.md

@@ -0,0 +1,38 @@
+# remote-state: Remote State Configuration
+
+**Guideline:** Store state remotely with encryption and locking, isolate per environment
+
+**Rationale:** Remote state enables team collaboration and prevents concurrent modification conflicts
+
+**Example:**
+
+```hcl
+# environments/prod/backend.tf
+terraform {
+  backend "s3" {
+    bucket         = "myapp-terraform-state-prod"
+    key            = "prod/terraform.tfstate"
+    region         = "us-east-1"
+    encrypt        = true
+    dynamodb_table = "terraform-state-lock-prod"
+
+    # Prevent accidental state deletion
+    lifecycle {
+      prevent_destroy = true
+    }
+  }
+}
+
+# Each environment has isolated state
+# dev: s3://myapp-tf-state-dev/dev/terraform.tfstate
+# staging: s3://myapp-tf-state-staging/staging/terraform.tfstate
+# prod: s3://myapp-tf-state-prod/prod/terraform.tfstate
+```
+
+**Techniques:**
+- **S3 backend:** Store state in versioned, encrypted S3 buckets
+- **DynamoDB locking:** Use DynamoDB tables to prevent concurrent modifications
+- **Encryption:** Enable server-side encryption on S3 backend buckets
+- **Per-environment isolation:** Create separate state buckets for dev, staging, prod
+- **State lifecycle:** Prevent accidental state deletion with versioning and backups
+

package/skills/terraform-guidelines/reference/root-module.md

@@ -0,0 +1,71 @@
+# root-module: Root Module Pattern
+
+**Guideline:** Keep root modules thin by composing child modules with provider config and environment-specific values
+
+**Rationale:** Root modules orchestrate infrastructure without duplicating logic, modules remain reusable
+
+**Example:**
+
+```hcl
+# environments/prod/main.tf
+terraform {
+  required_version = ">= 1.12"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = var.aws_region
+
+  default_tags {
+    tags = {
+      Environment = "prod"
+      Project     = "myapp"
+      ManagedBy   = "terraform"
+    }
+  }
+}
+
+locals {
+  availability_zones = ["${var.aws_region}a", "${var.aws_region}b", "${var.aws_region}c"]
+
+  common_tags = {
+    Project     = "myapp"
+    Environment = "prod"
+  }
+}
+
+module "network" {
+  source = "../../modules/network"
+
+  vpc_cidr           = "10.0.0.0/16"
+  environment        = "prod"
+  availability_zones = local.availability_zones
+  tags               = local.common_tags
+}
+
+module "compute" {
+  source = "../../modules/compute"
+
+  vpc_id            = module.network.vpc_id
+  subnet_ids        = module.network.public_subnet_ids
+  environment       = "prod"
+  instance_type     = "t3.medium"
+  desired_capacity  = 3
+  tags              = local.common_tags
+}
+```
+
+**Techniques:**
+- **Provider blocks:** Configure required providers with version constraints
+- **Default tags:** Use provider default_tags to apply common tags to all resources
+- **Thin root:** Root modules only compose child modules, no resource creation
+- **Module composition:** Wire module outputs as inputs to dependent modules
+- **Environment locals:** Compute availability zones and common tags once
+- **Relative sourcing:** Use ../../modules/ paths for portable module references
+

package/skills/terraform-guidelines/reference/typed-variables.md

@@ -0,0 +1,90 @@
+# typed-variables: Variable Types and Validation
+
+**Guideline:** Use type constraints and validation blocks for all variables to catch configuration errors early
+
+**Rationale:** Typed variables with validation provide immediate feedback and prevent invalid deployments
+
+**Example:**
+
+```hcl
+# String with validation
+variable "environment" {
+  description = "Environment name"
+  type        = string
+
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Environment must be dev, staging, or prod"
+  }
+}
+
+# Number with constraints
+variable "instance_count" {
+  description = "Number of instances"
+  type        = number
+  default     = 2
+
+  validation {
+    condition     = var.instance_count >= 1 && var.instance_count <= 10
+    error_message = "Instance count must be between 1 and 10"
+  }
+}
+
+# Boolean
+variable "enable_monitoring" {
+  description = "Enable detailed monitoring"
+  type        = bool
+  default     = true
+}
+
+# List
+variable "allowed_cidr_blocks" {
+  description = "CIDR blocks allowed to access"
+  type        = list(string)
+  default     = []
+}
+
+# Map
+variable "tags" {
+  description = "Resource tags"
+  type        = map(string)
+  default     = {}
+}
+
+# Object with structure
+variable "database_config" {
+  description = "Database configuration"
+  type = object({
+    instance_class    = string
+    allocated_storage = number
+    engine_version    = string
+    backup_retention  = number
+  })
+  default = {
+    instance_class    = "db.t3.micro"
+    allocated_storage = 20
+    engine_version    = "15.4"
+    backup_retention  = 7
+  }
+}
+
+# Optional values (Terraform 1.3+)
+variable "optional_config" {
+  description = "Optional configuration"
+  type = object({
+    required_field = string
+    optional_field = optional(string, "default")
+    optional_number = optional(number)
+  })
+}
+```
+
+**Techniques:**
+- **Basic types:** Use string, number, bool, list, map for simple variables
+- **Validation blocks:** Add business logic constraints like allowed values
+- **Range validation:** Check numeric ranges with >= and <= operators
+- **Complex types:** Use object() for structured configurations with nested fields
+- **Optional fields:** Use optional(type, default) for flexible object schemas
+- **Sensible defaults:** Provide practical defaults for common configurations
+- **Early feedback:** Type and validation errors appear before plan phase
+

package/skills/threejs-guidelines/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: threejs-guidelines
+description: >-
+  Trigger on `.js/.ts` files with Three.js imports, `three` package usage, or 3D scene code. Use when building vanilla Three.js applications. Apply for scene setup, meshes, materials, lighting, loaders, animation, interaction, shaders, post-processing, performance optimization. Keywords: Three.js, WebGL, WebGPU, Scene, Renderer, Mesh, BufferGeometry, MeshStandardMaterial, GLTFLoader, Raycaster, ShaderMaterial, EffectComposer, InstancedMesh.
+---
+
+# Three.js Coding Guidelines
+
+Vanilla Three.js for scene setup, rendering, meshes, materials, lights, animation, interaction, and effects.
+
+## Essentials
+
+- **Scene structure** - Organize Object3D hierarchy; use Groups for logical organization, see [reference/scene-fundamentals.md](reference/scene-fundamentals.md)
+- **Render loop** - Frame-rate independence with `clock.getDelta()`, see [reference/scene-fundamentals.md](reference/scene-fundamentals.md)
+- **Disposal** - Dispose geometries, materials, textures to prevent memory leaks, see [reference/scene-fundamentals.md](reference/scene-fundamentals.md)
+- **Pixel ratio** - Cap at 2 with `Math.min(devicePixelRatio, 2)`, see [reference/scene-fundamentals.md](reference/scene-fundamentals.md)
+- **Color space** - Use `SRGBColorSpace` for colors, `NoColorSpace` for data, see [reference/textures.md](reference/textures.md)
+- **Shadows** - Enable on renderer, light, mesh; keep frustum tight, see [reference/lighting-shadows.md](reference/lighting-shadows.md)
+
+## Core Topics
+
+- Read [reference/scene-fundamentals.md](reference/scene-fundamentals.md) - Scene, Renderer, Object3D, cleanup, render loop
+- Read [reference/geometry.md](reference/geometry.md) - Shapes, BufferGeometry, custom geometry, instancing
+- Read [reference/cameras-controls.md](reference/cameras-controls.md) - Cameras, OrbitControls, FlyControls, viewport
+- Read [reference/materials.md](reference/materials.md) - PBR materials, ShaderMaterial, properties
+- Read [reference/textures.md](reference/textures.md) - Loading, UV mapping, render targets, environment
+- Read [reference/lighting-shadows.md](reference/lighting-shadows.md) - Lights, shadows, IBL, light probes
+- Read [reference/animation.md](reference/animation.md) - Keyframes, skeletal, morph targets, AnimationMixer
+- Read [reference/interaction.md](reference/interaction.md) - Raycasting, selection, drag, coordinate conversion
+- Read [reference/loaders.md](reference/loaders.md) - GLTF, FBX, textures, HDR, compression
+- Read [reference/shaders.md](reference/shaders.md) - GLSL shaders, uniforms, varyings
+- Read [reference/postprocessing.md](reference/postprocessing.md) - Bloom, DOF, SSAO, custom effects
+- Read [reference/performance.md](reference/performance.md) - InstancedMesh, LOD, culling, batching, profiling
+- Read [reference/patterns.md](reference/patterns.md) - Architecture patterns, asset management, state machines
+- Read [reference/math.md](reference/math.md) - Vector3, Matrix4, Quaternion, Box3, curves, MathUtils
+- Read [reference/node-materials.md](reference/node-materials.md) - TSL (Three Shading Language), node-based materials
+- Read [reference/physics-vr.md](reference/physics-vr.md) - Physics engines (Rapier, Cannon), WebXR (VR/AR)
+- Read [reference/webgpu.md](reference/webgpu.md) - WebGPU renderer, compute shaders, modern GPU

package/skills/threejs-guidelines/reference/animation.md

@@ -0,0 +1,26 @@
+# animation: Animation System
+
+**Guideline:** Use AnimationMixer for GLTF keyframe animations; use clock.getDelta() for frame-rate independent procedural animation.
+
+**Rationale:** Mixer efficiently plays complex GLTF animations; delta time ensures consistent speed across frame rates.
+
+**Example:**
+```javascript
+const mixer = new THREE.AnimationMixer(gltf.scene);
+const clip = THREE.AnimationClip.findByName(gltf.animations, 'Walk');
+const action = mixer.clipAction(clip);
+action.play();
+const clock = new THREE.Clock();
+renderer.setAnimationLoop(() => {
+  mixer.update(clock.getDelta());
+  renderer.render(scene, camera);
+});
+```
+
+**Techniques:**
+- AnimationMixer: Create from scene root; plays multiple clips simultaneously
+- AnimationAction: play(), stop(), reset(); loop modes (Repeat, Once, PingPong); timeScale for speed
+- Blending: crossFadeTo(nextAction, duration) for smooth transitions; weight blending for layered animations
+- Procedural: Use elapsed time with Math.sin/cos for smooth curves; delta time for frame-rate independence
+- Keyframe creation: VectorKeyframeTrack (position), QuaternionKeyframeTrack (rotation), AnimationClip (combines tracks)
+- Performance: Single mixer for multiple objects; stopAllAction() and uncacheRoot() for cleanup

package/skills/threejs-guidelines/reference/cameras-controls.md

@@ -0,0 +1,26 @@
+# filename: cameras-controls
+
+**Guideline:** Choose camera type (Perspective, Orthographic, Cube); select controls matching interaction (OrbitControls, FlyControls, PointerLockControls).
+
+**Rationale:** Proper camera frustum prevents z-fighting; tight near/far prevents clipping; controls must match intended interaction pattern.
+
+**Example:**
+```javascript
+const camera = new THREE.PerspectiveCamera(75, w/h, 0.1, 1000);
+camera.position.set(5, 5, 5);
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.enableDamping = true;
+controls.dampingFactor = 0.05;
+controls.target.set(0, 0, 0);
+controls.update();
+```
+
+**Techniques:**
+- Camera types: PerspectiveCamera (3D standard), OrthographicCamera (CAD/isometric), CubeCamera (reflections)
+- Near/far planes: Large scenes use `near=1, far=100000`; small scenes `near=0.001, far=100` to avoid z-fighting
+- OrbitControls: `enableDamping=true` for smooth motion; set `minDistance`/`maxDistance` and polar angle limits
+- FlyControls: Pass `clock.getDelta()` to `.update()` for frame-rate independence
+- PointerLockControls: Call `.lock()` on click; check `.isLocked`; use `.moveForward()`, `.moveRight()`
+- Multi-camera: `.setViewport()`, `.setScissor()`, render twice for split-screen/PIP
+- Coordinate conversion: `.project()` for world→screen; `.unproject()` for screen→world

package/skills/threejs-guidelines/reference/geometry.md

@@ -0,0 +1,22 @@
+# geometry: Geometry and BufferGeometry
+
+**Guideline:** Use built-in geometries for standard shapes; create efficient custom BufferGeometry with position/UV/indices/normals; use InstancedMesh.
+
+**Rationale:** Built-ins are optimized; proper BufferGeometry avoids redundant data; InstancedMesh enables thousands of copies in one draw call.
+
+**Example:**
+```javascript
+const geometry = new THREE.BufferGeometry();
+geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+geometry.setAttribute('uv', new THREE.BufferAttribute(uvs, 2));
+geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+geometry.computeVertexNormals();
+```
+
+**Techniques:**
+- Built-ins: BoxGeometry, SphereGeometry, PlaneGeometry, CylinderGeometry, IcosahedronGeometry, etc.
+- Path-based: LatheGeometry (vases), TubeGeometry (splines), ExtrudeGeometry (2D extrude), TextGeometry (fonts)
+- Custom BufferGeometry: Position (required), UV, indices (reuse vertices), normals, bounds
+- InstancedMesh: Per-instance transforms via setMatrixAt(); per-instance colors via setColorAt()
+- Optimization: Merge geometries with BufferGeometryUtils; dispose with geometry.dispose()
+- Morph targets: Blend multiple shape deformations with morphTargetInfluences

package/skills/threejs-guidelines/reference/interaction.md

@@ -0,0 +1,25 @@
+# interaction: Raycasting and User Interaction
+
+**Guideline:** Convert screen to normalized device coordinates, then raycast; cache raycaster instance and track state for hover/drag.
+
+**Rationale:** Raycasting picks objects; state tracking enables hover highlights and drag interactions; coordinate conversion is essential.
+
+**Example:**
+```javascript
+const raycaster = new THREE.Raycaster();
+const pointer = new THREE.Vector2();
+window.addEventListener('pointermove', (e) => {
+  pointer.x = (e.clientX / innerWidth) * 2 - 1;
+  pointer.y = -(e.clientY / innerHeight) * 2 + 1;
+  raycaster.setFromCamera(pointer, camera);
+  const hits = raycaster.intersectObjects(scene.children, true);
+  if (hits.length > 0) console.log(hits[0].object, hits[0].point);
+});
+```
+
+**Techniques:**
+- NDC conversion: `pointer.x = (clientX / width) * 2 - 1`, `pointer.y = -(clientY / height) * 2 + 1`
+- Intersection properties: object, point (world), distance, uv, face, instanceId
+- Hover effects: Track state, restore original color on exit
+- Drag implementation: pointerdown to start, pointermove to update, pointerup to release
+- Performance: Filter interactive objects before raycast; don't raycast every frame on heavy scenes

package/skills/threejs-guidelines/reference/lighting-shadows.md

@@ -0,0 +1,31 @@
+# filename: lighting-shadows
+
+**Guideline:** Use light types appropriate to scene; keep shadow frustums tight; leverage IBL (Environment maps) for realistic ambient lighting.
+
+**Rationale:** Lighting creates atmosphere; tight shadow frustums improve quality; IBL is more efficient than many point lights for PBR.
+
+**Example:**
+```javascript
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+
+const dirLight = new THREE.DirectionalLight(0xffffff, 1);
+dirLight.castShadow = true;
+dirLight.shadow.camera.left = -10;
+dirLight.shadow.camera.right = 10;
+mesh.castShadow = true;
+mesh.receiveShadow = true;
+
+new RGBELoader().load('env.hdr', (tex) => {
+  tex.mapping = THREE.EquirectangularReflectionMapping;
+  scene.environment = tex;
+});
+```
+
+**Techniques:**
+- Light types: AmbientLight (fill), HemisphereLight (sky/ground outdoors), DirectionalLight (sun), PointLight (bulb), SpotLight (flashlight)
+- Shadow types: PCFSoftShadowMap (best quality); tight frustum (camera.left/right/top/bottom) and mapSize (512-2048)
+- Shadow bias: `.bias = -0.0001`, `.normalBias = 0.02` to fix acne/peter-panning
+- IBL: Load HDR with RGBELoader; set `scene.environment` and `scene.background`
+- Performance: Limit to 3-5 lights; use contact shadows or baked lighting for static scenes
+- Helpers: DirectionalLightHelper, PointLightHelper, CameraHelper for debug

package/skills/threejs-guidelines/reference/loaders.md

@@ -0,0 +1,29 @@
+# filename: loaders
+
+**Guideline:** Use GLTFLoader with Draco compression for 3D models; wrap loaders in async/await; use LoadingManager for progress tracking.
+
+**Rationale:** GLTF/GLB is web standard; Draco reduces file size 90%+; async prevents UI blocking; manager centralizes progress.
+
+**Example:**
+```javascript
+async function loadModel(url) {
+  return new Promise((resolve, reject) => {
+    new GLTFLoader().load(url, resolve, undefined, reject);
+  });
+}
+const gltf = await loadModel('model.glb');
+scene.add(gltf.scene);
+
+// With Draco compression
+const dracoLoader = new DRACOLoader();
+dracoLoader.setDecoderPath('https://www.gstatic.com/draco/v1.5.6/');
+new GLTFLoader().setDRACOLoader(dracoLoader).load('model.glb', ...);
+```
+
+**Techniques:**
+- GLTFLoader: Primary format; animations in `gltf.animations`; use `traverse()` for shadow/material setup
+- Draco: Reduce geometry size 90%+; requires decoder path setup
+- KTX2 textures: Compressed texture format via `ktx2Loader.setTranscoderPath()`
+- LoadingManager: Centralize `onProgress`/`onLoad`/`onError` across multiple loaders
+- Parallel loading: `Promise.all([loadModel(), loadModel()])` for concurrent assets
+- Export best practices: Enable Draco/KTX2 in 3D tools; use `gltf-transform` CLI for compression

package/skills/threejs-guidelines/reference/materials.md

@@ -0,0 +1,25 @@
+# filename: materials
+
+**Guideline:** Choose material type based on performance needs; reuse material instances; handle transparency with proper depth writes and render order.
+
+**Rationale:** Material complexity directly impacts framerate; fewer unique materials reduce draw calls; transparency requires depth-aware rendering.
+
+**Example:**
+```javascript
+const pbr = new THREE.MeshStandardMaterial({
+  color: 0xffffff,
+  roughness: 0.5,
+  metalness: 0.0,
+  map: texture,
+  normalMap: normalTex,
+  envMap: envTex
+});
+// Reuse: mesh1.material = pbr; mesh2.material = pbr;
+```
+
+**Techniques:**
+- Material types: MeshBasicMaterial (fastest, unlit), Lambert (matte), Phong (shiny), Standard/Physical (PBR realistic)
+- PBR properties: roughness 0=mirror/1=diffuse; metalness 0=dielectric/1=metal; use maps for per-pixel variation
+- Transparency: `.alphaTest` for hard edges (fast); `.transparent=true` + `.depthWrite=false` + `.renderOrder` for smooth (slow)
+- Blending: `AdditiveBlending` for glow/fire; `MultiplyBlending` for shadows
+- Performance: Material pooling with Map; reuse instances; use `onBeforeCompile()` for shader hacks; dispose() to prevent leaks

package/skills/threejs-guidelines/reference/math.md

@@ -0,0 +1,27 @@
+# filename: math
+
+**Guideline:** Use Three.js math classes (Vector3, Matrix4, Quaternion) and reuse instances to avoid garbage collection in animation loops.
+
+**Rationale:** Three.js math classes are GPU-optimized; allocating new instances every frame causes GC stalls and framerate drops.
+
+**Example:**
+```javascript
+// Reuse pattern: Define once, mutate in loop
+const v3_1 = new THREE.Vector3();
+for (let i = 0; i < objects.length; i++) {
+  v3_1.copy(objects[i].position).normalize();
+  // Use v3_1...
+}
+
+// Vector operations
+v.add(other); v.multiplyScalar(2); v.lerp(target, 0.5);
+// Quaternion: q.slerp(target, t); Matrix4: m.compose(pos, quat, scale);
+```
+
+**Techniques:**
+- Vector3: `.set()`, `.copy()`, `.add()`, `.multiplyScalar()`, `.normalize()`, `.dot()`, `.cross()`, `.lerp()`
+- Quaternion: `.setFromAxisAngle()`, `.slerp()` for smooth rotation interpolation avoiding gimbal lock
+- Matrix4: `.compose()` combines position/quaternion/scale; use `.invert()` for transforms
+- Color: `.setHSL()`, `.lerp()` for smooth color transitions
+- Bounding volumes: Box3/Sphere for collision detection with `.intersectsBox()`, `.containsPoint()`
+- MathUtils: `degToRad()`, `lerp()`, `clamp()`, `smoothstep()` for common operations

package/skills/threejs-guidelines/reference/node-materials.md

@@ -0,0 +1,32 @@
+# filename: node-materials
+
+**Guideline:** Use TSL (Three Shading Language) for materials that work across WebGL and WebGPU; compose shader nodes instead of writing GLSL.
+
+**Rationale:** TSL provides type-safe, composable nodes compiling to GLSL (WebGL) and WGSL (WebGPU); supports future renderers without code changes.
+
+**Example:**
+```javascript
+import {float, vec3, mix, sin, uniform} from 'three/tsl';
+
+const timeUniform = uniform(float, 'time');
+const material = new THREE.MeshStandardNodeMaterial({
+  color: mix(
+    vec3(1.0, 0.0, 0.0),
+    vec3(0.0, 0.0, 1.0),
+    sin(timeUniform).mul(0.5).add(0.5)
+  ),
+});
+timeUniform.value = clock.getElapsedTime();
+```
+
+**Techniques:**
+- TSL nodes: `float()`, `vec2/3/4()`, `sin()`, `cos()`, `mix()`, `step()`, `normalize()`
+- Uniforms: `uniform(type, name)` for runtime control; update `.value` each frame
+- Varyings: `varying(type)` for vertex→fragment data passing
+- Functions: `Fn([args], returnType, ({params}) => {...})` for reusable shader logic
+- Textures: `texture(textureObject)` for sampling; `storageTexture()` for compute read/write
+- Positions: `positionLocal`, `positionWorld`, `normalWorld` for vertex data
+- Material types: MeshBasicNodeMaterial, MeshStandardNodeMaterial, MeshPhysicalNodeMaterial
+- Lighting: `lightingContext()` for advanced PBR lighting effects
+- Composition: Operators like `.mul()`, `.add()`, `.dot()`, `.cross()` chain naturally
+- WebGPU: TSL materials compile to WGSL automatically; works with both renderers

package/skills/threejs-guidelines/reference/patterns.md

@@ -0,0 +1,29 @@
+# filename: patterns
+
+**Guideline:** Organize scenes in Groups; implement proper cleanup to prevent memory leaks; use delta time for frame-rate independent updates.
+
+**Rationale:** Hierarchical organization enables efficient transforms; cleanup prevents GPU memory exhaustion; delta time ensures consistent movement across devices.
+
+**Example:**
+```javascript
+const scene = new THREE.Scene();
+const clock = new THREE.Clock();
+const world = new THREE.Group();
+world.add(player, enemies, effects);
+scene.add(world);
+
+function animate() {
+  const delta = clock.getDelta();
+  player.position.x += moveSpeed * delta;
+  mesh.rotation.y += angularVelocity * delta;
+  renderer.render(scene, camera);
+}
+```
+
+**Techniques:**
+- Scene hierarchy: Group objects (world → player/enemies/effects) for batch transforms
+- Frame-rate independence: Multiply movement by `clock.getDelta()`; use `getElapsedTime()` for animations
+- Cleanup pattern: Dispose geometry/materials; `mixer.stopAllAction()`, remove listeners, call on `beforeunload`
+- Object pooling: Reuse bullets/particles with `.visible` flag instead of create/destroy for performance
+- Component pattern: Encapsulate entities (Player class with update/takeDamage methods)
+- Event bus: Centralize game events for decoupled communication between systems