cfsa-antigravity 1.0.0

package/template/.agent/skill-library/meta/tmux-processes/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: tmux-processes
+description: Patterns for running long-lived processes in tmux. Use when starting dev servers, watchers, tilt, or any process expected to outlive the conversation.
+---
+
+# tmux Process Management
+
+## Interactive Shell Requirement
+
+**Use send-keys pattern for reliable shell initialization.** Creating a session spawns an interactive shell automatically. Use `send-keys` to run commands within that shell, ensuring PATH, direnv, and other initialization runs properly.
+
+```bash
+# WRONG - inline command bypasses shell init, breaks PATH/direnv
+tmux new-session -d -s "$SESSION" -n main 'tilt up'
+
+# CORRECT - create session, then send command to interactive shell
+tmux new-session -d -s "$SESSION" -n main
+tmux send-keys -t "$SESSION:main" 'tilt up' Enter
+```
+
+## Session Naming Convention
+
+Always derive session name from the project:
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+```
+
+For multiple processes in one project, use windows not separate sessions:
+- Session: `myapp`
+- Windows: `server`, `tests`, `logs`
+
+## Starting Processes
+
+### Single Process
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Create session with named window, then send command
+tmux new-session -d -s "$SESSION" -n main
+tmux send-keys -t "$SESSION:main" '<command>' Enter
+```
+
+### Idempotent Start
+
+Check if already running before starting:
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+  tmux new-session -d -s "$SESSION" -n main
+  tmux send-keys -t "$SESSION:main" '<command>' Enter
+else
+  echo "Session $SESSION already exists"
+fi
+```
+
+### Adding Windows to Existing Session
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Add a new window if it doesn't exist
+if ! tmux list-windows -t "$SESSION" -F '#{window_name}' | grep -q "^server$"; then
+  tmux new-window -t "$SESSION" -n server
+  tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
+else
+  echo "Window 'server' already exists"
+fi
+```
+
+### Multiple Processes (Windows)
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Create session with first process
+tmux new-session -d -s "$SESSION" -n server
+tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
+
+# Add more windows
+tmux new-window -t "$SESSION" -n tests
+tmux send-keys -t "$SESSION:tests" 'npm run test:watch' Enter
+
+tmux new-window -t "$SESSION" -n logs
+tmux send-keys -t "$SESSION:logs" 'tail -f logs/app.log' Enter
+```
+
+## Monitoring Output
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Last 50 lines from first window
+tmux capture-pane -p -t "$SESSION" -S -50
+
+# From specific window
+tmux capture-pane -p -t "$SESSION:server" -S -50
+
+# Check for errors
+tmux capture-pane -p -t "$SESSION" -S -100 | rg -i "error|fail|exception"
+
+# Check for ready indicators
+tmux capture-pane -p -t "$SESSION:server" -S -50 | rg -i "listening|ready|started"
+```
+
+## Lifecycle Management
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# List all sessions (see what exists)
+tmux ls
+
+# List windows in current session
+tmux list-windows -t "$SESSION"
+
+# Kill only this project's session
+tmux kill-session -t "$SESSION"
+
+# Kill specific window
+tmux kill-window -t "$SESSION:tests"
+
+# Send keys to a window (e.g., Ctrl+C to stop)
+tmux send-keys -t "$SESSION:server" C-c
+```
+
+## Isolation Rules
+
+- **Never** use `tmux kill-server`
+- **Never** kill sessions not matching current project
+- **Always** derive session name from git root or pwd
+- **Always** verify session name before kill operations
+- Other Claude Code instances may have their own sessions running
+
+## When to Use tmux
+
+| Scenario | Use tmux? |
+|----------|-----------|
+| `tilt up` | Yes, always |
+| Dev server (`npm run dev`, `rails s`) | Yes |
+| File watcher (`npm run watch`) | Yes |
+| Test watcher (`npm run test:watch`) | Yes |
+| Database server | Yes |
+| One-shot build (`npm run build`) | No |
+| Quick command (<10s) | No |
+| Need stdout directly in conversation | No |
+
+## Checking Process Status
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Check session exists
+tmux has-session -t "$SESSION" 2>/dev/null && echo "session exists" || echo "no session"
+
+# List windows and their status
+tmux list-windows -t "$SESSION" -F '#{window_name}: #{pane_current_command}'
+
+# Check if specific window exists
+tmux list-windows -t "$SESSION" -F '#{window_name}' | grep -q "^server$" && echo "server window exists"
+```
+
+## Restarting a Process
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Send Ctrl+C then restart command
+tmux send-keys -t "$SESSION:server" C-c
+sleep 1
+tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
+```
+
+## Common Patterns
+
+### Start dev server if not running
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+if ! tmux has-session -t "$SESSION" 2>/dev/null; then
+  tmux new-session -d -s "$SESSION" -n server
+  tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
+  echo "Started dev server in tmux session: $SESSION"
+elif ! tmux list-windows -t "$SESSION" -F '#{window_name}' | grep -q "^server$"; then
+  tmux new-window -t "$SESSION" -n server
+  tmux send-keys -t "$SESSION:server" 'npm run dev' Enter
+  echo "Added server window to session: $SESSION"
+else
+  echo "Server already running in session: $SESSION"
+fi
+```
+
+### Wait for server ready
+
+```bash
+SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
+
+# Poll for ready message
+for i in {1..30}; do
+  if tmux capture-pane -p -t "$SESSION:server" -S -20 | rg -q "listening|ready"; then
+    echo "Server ready"
+    break
+  fi
+  sleep 1
+done
+```

package/template/.agent/skill-library/meta/using-tmux-for-interactive-commands/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: using-tmux-for-interactive-commands
+description: Use when you need to run interactive CLI tools (vim, git rebase -i, Python REPL, etc.) that require real-time input/output - provides tmux-based approach for controlling interactive sessions through detached sessions and send-keys
+---
+
+# Using tmux for Interactive Commands
+
+## Overview
+
+Interactive CLI tools (vim, interactive git rebase, REPLs, etc.) cannot be controlled through standard bash because they require a real terminal. tmux provides detached sessions that can be controlled programmatically via `send-keys` and `capture-pane`.
+
+## When to Use
+
+**Use tmux when:**
+- Running vim, nano, or other text editors programmatically
+- Controlling interactive REPLs (Python, Node, etc.)
+- Handling interactive git commands (`git rebase -i`, `git add -p`)
+- Working with full-screen terminal apps (htop, etc.)
+- Commands that require terminal control codes or readline
+
+**Don't use for:**
+- Simple non-interactive commands (use regular Bash tool)
+- Commands that accept input via stdin redirection
+- One-shot commands that don't need interaction
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Start session | `tmux new-session -d -s <name> <command>` |
+| Send input | `tmux send-keys -t <name> 'text' Enter` |
+| Capture output | `tmux capture-pane -t <name> -p` |
+| Stop session | `tmux kill-session -t <name>` |
+| List sessions | `tmux list-sessions` |
+
+## Core Pattern
+
+### Before (Won't Work)
+```bash
+# This hangs because vim expects interactive terminal
+bash -c "vim file.txt"
+```
+
+### After (Works)
+```bash
+# Create detached tmux session
+tmux new-session -d -s edit_session vim file.txt
+
+# Send commands (Enter, Escape are tmux key names)
+tmux send-keys -t edit_session 'i' 'Hello World' Escape ':wq' Enter
+
+# Capture what's on screen
+tmux capture-pane -t edit_session -p
+
+# Clean up
+tmux kill-session -t edit_session
+```
+
+## Implementation
+
+### Basic Workflow
+
+1. **Create detached session** with the interactive command
+2. **Wait briefly** for initialization (100-500ms depending on command)
+3. **Send input** using `send-keys` (can send special keys like Enter, Escape)
+4. **Capture output** using `capture-pane -p` to see current screen state
+5. **Repeat** steps 3-4 as needed
+6. **Terminate** session when done
+
+### Special Keys
+
+Common tmux key names:
+- `Enter` - Return/newline
+- `Escape` - ESC key
+- `C-c` - Ctrl+C
+- `C-x` - Ctrl+X
+- `Up`, `Down`, `Left`, `Right` - Arrow keys
+- `Space` - Space bar
+- `BSpace` - Backspace
+
+### Working Directory
+
+Specify working directory when creating session:
+```bash
+tmux new-session -d -s git_session -c /path/to/repo git rebase -i HEAD~3
+```
+
+### Helper Wrapper
+
+For easier use, see `/home/jesse/git/interactive-command/tmux-wrapper.sh`:
+```bash
+# Start session
+/path/to/tmux-wrapper.sh start <session-name> <command> [args...]
+
+# Send input
+/path/to/tmux-wrapper.sh send <session-name> 'text' Enter
+
+# Capture current state
+/path/to/tmux-wrapper.sh capture <session-name>
+
+# Stop
+/path/to/tmux-wrapper.sh stop <session-name>
+```
+
+## Common Patterns
+
+### Python REPL
+```bash
+tmux new-session -d -s python python3 -i
+tmux send-keys -t python 'import math' Enter
+tmux send-keys -t python 'print(math.pi)' Enter
+tmux capture-pane -t python -p  # See output
+tmux kill-session -t python
+```
+
+### Vim Editing
+```bash
+tmux new-session -d -s vim vim /tmp/file.txt
+sleep 0.3  # Wait for vim to start
+tmux send-keys -t vim 'i' 'New content' Escape ':wq' Enter
+# File is now saved
+```
+
+### Interactive Git Rebase
+```bash
+tmux new-session -d -s rebase -c /repo/path git rebase -i HEAD~3
+sleep 0.5
+tmux capture-pane -t rebase -p  # See rebase editor
+# Send commands to modify rebase instructions
+tmux send-keys -t rebase 'Down' 'Home' 'squash' Escape
+tmux send-keys -t rebase ':wq' Enter
+```
+
+## Common Mistakes
+
+### Not Waiting After Session Start
+**Problem:** Capturing immediately after `new-session` shows blank screen
+
+**Fix:** Add brief sleep (100-500ms) before first capture
+```bash
+tmux new-session -d -s sess command
+sleep 0.3  # Let command initialize
+tmux capture-pane -t sess -p
+```
+
+### Forgetting Enter Key
+**Problem:** Commands typed but not executed
+
+**Fix:** Explicitly send Enter
+```bash
+tmux send-keys -t sess 'print("hello")' Enter  # Note: Enter is separate argument
+```
+
+### Using Wrong Key Names
+**Problem:** `tmux send-keys -t sess '\n'` doesn't work
+
+**Fix:** Use tmux key names: `Enter`, not `\n`
+```bash
+tmux send-keys -t sess 'text' Enter  # ✓
+tmux send-keys -t sess 'text\n'      # ✗
+```
+
+### Not Cleaning Up Sessions
+**Problem:** Orphaned tmux sessions accumulate
+
+**Fix:** Always kill sessions when done
+```bash
+tmux kill-session -t session_name
+# Or check for existing: tmux has-session -t name 2>/dev/null
+```
+
+## Real-World Impact
+
+- Enables programmatic control of vim/nano for file editing
+- Allows automation of interactive git workflows (rebase, add -p)
+- Makes REPL-based testing/debugging possible
+- Unblocks any tool that requires terminal interaction
+- No need to build custom PTY management - tmux handles it all

package/template/.agent/skill-library/stack/3d/threejs-pro/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: threejs-pro
+description: Expert in 3D web graphics using Three.js, React Three Fiber (R3F), and WebGL shaders.
+---
+
+# Three.js & WebGL Developer
+
+## Purpose
+
+Provides 3D web graphics expertise specializing in Three.js, React Three Fiber (R3F), and custom GLSL shader development. Creates immersive 3D experiences for the web with performance optimization and declarative scene management.
+
+## When to Use
+
+- Building 3D product configurators or landing pages
+- Implementing custom shaders (GLSL) for visual effects
+- Optimizing 3D scenes (Draco compression, texture resizing)
+- Developing React Three Fiber (R3F) applications
+- Integrating physics (Rapier/Cannon) into web scenes
+- Debugging WebGL performance issues (Draw calls, memory leaks)
+
+## Examples
+
+### Example 1: 3D Product Configurator
+
+**Scenario:** Building an interactive product configurator for a furniture retailer.
+
+**Implementation:**
+1. Created R3F component for 3D product display
+2. Implemented texture/material swapping system
+3. Added camera controls and lighting setup
+4. Optimized 3D model with Draco compression
+5. Added accessibility alternatives for non-3D users
+
+**Results:**
+- 40% increase in conversion rate
+- Average session duration increased 2x
+- Load time under 2 seconds
+- Works on mobile devices
+
+### Example 2: Custom Shader Effects
+
+**Scenario:** Creating immersive visual effects for a gaming landing page.
+
+**Implementation:**
+1. Wrote custom GLSL vertex and fragment shaders
+2. Implemented post-processing effects (bloom, DOF)
+3. Added interactive elements responding to user input
+4. Optimized shader performance for real-time rendering
+5. Created fallback for WebGL-incapable devices
+
+**Results:**
+- Stunning visual experience with 60fps
+- Viral marketing campaign success
+- Industry recognition for visual design
+- Maintained performance on mid-tier devices
+
+### Example 3: E-Commerce 3D Integration
+
+**Scenario:** Integrating Three.js into existing React e-commerce site.
+
+**Implementation:**
+1. Created isolated 3D canvas component
+2. Implemented lazy loading for 3D content
+3. Added proper state management between React and Three.js
+4. Implemented proper cleanup on component unmount
+5. Added error boundaries and fallback content
+
+**Results:**
+- Zero impact on existing page performance
+- Improved SEO with proper lazy loading
+- Graceful degradation for unsupported browsers
+- Clean codebase following React patterns
+
+## Best Practices
+
+### Performance Optimization
+
+- **Geometry Merging**: Reduce draw calls with merged geometries
+- **Texture Optimization**: Use compressed formats, proper sizing
+- **Dispose Properly**: Clean up geometries and materials
+- **Level of Detail**: Use LOD for distant objects
+
+### React Three Fiber
+
+- **Declarative**: Use R3F component tree, not imperative code
+- **Hooks**: Use useFrame, useThree, useLoader properly
+- **State Management**: Use Zustand for global 3D state
+- **Components**: Break scene into reusable components
+
+### Shaders and Effects
+
+- **Custom Shaders**: Use when built-ins aren't enough
+- **Post-Processing**: Add effects without performance cost
+- **Optimization**: Profile shader performance
+- **Fallbacks**: Provide alternatives for low-end devices
+
+### Development Workflow
+
+- **Hot Reload**: Use HMR for rapid iteration
+- **Debug Tools**: Use drei's helpers and controls
+- **Accessibility**: Provide alternatives for 3D content
+- **Testing**: Test on multiple devices and browsers
+
+---
+---
+
+## 2. Decision Framework
+
+### Tech Stack Selection
+
+```
+What is the project scope?
+│
+├─ **React Integration?**
+│  ├─ Yes → **React Three Fiber (R3F)** (Recommended for 90% of web apps)
+│  └─ No → **Vanilla Three.js**
+│
+├─ **Performance Critical?**
+│  ├─ Massive Object Count? → **InstancedMesh**
+│  ├─ Complex Physics? → **Rapier (WASM)**
+│  └─ Post-Processing? → **EffectComposer / R3F Postprocessing**
+│
+└─ **Visual Style?**
+   ├─ Realistic? → **PBR Materials + HDR Lighting**
+   ├─ Cartoon? → **Toon Shader / Outline Pass**
+   └─ Abstract? → **Custom GLSL Shaders**
+```
+
+### Optimization Checklist (The 60FPS Rule)
+
+1.  **Geometry:** Use `Draco` or `Meshopt` compression.
+2.  **Textures:** Use `.webp` or `.ktx2`. Max size 2048x2048.
+3.  **Lighting:** Bake lighting where possible. Max 1-2 real-time shadows.
+4.  **Draw Calls:** Merge geometries or use Instancing.
+5.  **Render Loop:** Avoid object creation in the `useFrame` loop.
+
+**Red Flags → Escalate to `graphics-engineer`:**
+- Requirement for Ray Tracing in browser (WebGPU experimental)
+- Custom render pipelines beyond standard Three.js capabilities
+- Low-level WebGL API calls needed directly
+
+---
+---
+
+## 3. Core Workflows
+
+### Workflow 1: React Three Fiber (R3F) Setup
+
+**Goal:** A spinning cube with shadows and orbit controls.
+
+**Steps:**
+
+1.  **Setup**
+    ```bash
+    npm install three @types/three @react-three/fiber @react-three/drei
+    ```
+
+2.  **Scene Component (`Scene.tsx`)**
+    ```tsx
+    import { Canvas } from '@react-three/fiber';
+    import { OrbitControls, Stage } from '@react-three/drei';
+    
+    export default function Scene() {
+      return (
+        <Canvas shadows camera={{ position: [0, 0, 5] }}>
+          <color attach="background" args={['#101010']} />
+          <ambientLight intensity={0.5} />
+          <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} castShadow />
+          
+          <mesh castShadow receiveShadow rotation={[0, 1, 0]}>
+            <boxGeometry args={[1, 1, 1]} />
+            <meshStandardMaterial color="orange" />
+          </mesh>
+          
+          <OrbitControls />
+        </Canvas>
+      );
+    }
+    ```
+
+---
+---
+
+### Workflow 3: Model Loading & Optimization
+
+**Goal:** Load a heavy GLTF model efficiently.
+
+**Steps:**
+
+1.  **Compression**
+    -   Use `gltf-pipeline` or `gltf-transform`.
+    -   `gltf-transform optimize input.glb output.glb --compress draco`.
+
+2.  **Loading (R3F)**
+    ```tsx
+    import { useGLTF } from '@react-three/drei';
+    
+    export function Model(props) {
+      const { nodes, materials } = useGLTF('/optimized-model.glb');
+      return (
+        <group {...props} dispose={null}>
+          <mesh geometry={nodes.Cube.geometry} material={materials.Metal} />
+        </group>
+      );
+    }
+    useGLTF.preload('/optimized-model.glb');
+    ```
+
+---
+---
+
+## 5. Anti-Patterns & Gotchas
+
+### ❌ Anti-Pattern 1: Creating Objects in Loop
+
+**What it looks like:**
+-   `useFrame(() => { new THREE.Vector3(...) })`
+
+**Why it fails:**
+-   Garbage Collection (GC) stutter.
+-   60fps requires 16ms/frame. Allocating memory kills performance.
+
+**Correct approach:**
+-   Reuse global/module-level variables.
+-   `const vec = new THREE.Vector3(); useFrame(() => vec.set(...))`
+
+### ❌ Anti-Pattern 2: Huge Textures
+
+**What it looks like:**
+-   Loading 4k `.png` textures (10MB each) for a background object.
+
+**Why it fails:**
+-   Slow load time.
+-   GPU memory exhaustion (mobile crash).
+
+**Correct approach:**
+-   Use `1k` or `2k` textures.
+-   Use `.jpg` for color maps, `.png` only if alpha needed.
+-   Use Basis/KTX2 for GPU compression.
+
+### ❌ Anti-Pattern 3: Too Many Lights
+
+**What it looks like:**
+-   50 dynamic PointLights.
+
+**Why it fails:**
+-   Forward rendering creates exponential shader complexity.
+
+**Correct approach:**
+-   **Bake Lighting** (Lightmaps) in Blender.
+-   Use `AmbientLight` + 1 `DirectionalLight` (Sun).
+
+---
+---
+
+## 7. Quality Checklist
+
+**Performance:**
+-   [ ] **FPS:** Stable 60fps on average laptop.
+-   [ ] **Draw Calls:** < 100 ideally.
+-   [ ] **Memory:** Geometries/Materials disposed when unmounted.
+
+**Visuals:**
+-   [ ] **Shadows:** Soft shadows configured (ContactShadows or PCSS).
+-   [ ] **Antialiasing:** Enabled (default in R3F) or SMAA via post-proc.
+-   [ ] **Responsiveness:** Canvas resizes correctly on window resize.
+
+**Code:**
+-   [ ] **Declarative:** Used R3F component tree, not imperative `scene.add()`.
+-   [ ] **Optimization:** `useMemo` used for expensive calculations.
+
+## Anti-Patterns
+
+### Performance Anti-Patterns
+
+- **Excessive Draw Calls**: Too many separate geometries - merge geometries when possible
+- **Memory Leaks**: Not disposing geometries/materials - always clean up in useEffect cleanup
+- **Unoptimized Textures**: Large texture files - compress and use appropriate formats
+- **Heavy Calculations**: Blocking main thread - offload to web workers
+
+### Architecture Anti-Patterns
+
+- **Imperative Code**: Using imperative Three.js in React - use declarative R3F patterns
+- **Prop Drilling**: Passing props through many levels - use context and stores
+- **State Sprawl**: Scattered state management - use centralized state (Zustand)
+- **Component Bloat**: Large single components - break into focused components
+
+### 3D Modeling Anti-Patterns
+
+- **High Poly Models**: Unoptimized model geometry - use LOD and decimation
+- **Mismatched Scales**: Inconsistent scale units - normalize model scales
+- **Missing Colliders**: No collision geometry - add invisible colliders for interactions
+- **Improper Lighting**: Too many lights - use baked lighting and light probes
+
+### Development Anti-Patterns
+
+- **No Progressive Loading**: Large scenes loading slowly - implement loading states
+- **Missing Fallbacks**: No graceful degradation - provide fallback experiences
+- **Accessibility Ignored**: 3D content not accessible - add alternative content
+- **No Performance Budget**: No performance targets - establish and monitor budgets