agents-config 1.0.0

package/rules/mui.md

@@ -0,0 +1,491 @@
+# Material-UI (MUI) Architecture & Patterns
+
+**Framework Version**: MUI v7.3+  
+**Purpose**: Architectural patterns, constraints, and anti-patterns for building React applications with Material-UI.
+
+---
+
+## Component Extension Philosophy
+
+### When to Extend vs Compose
+
+**Extend MUI Components** when:
+- Adding custom variants to existing MUI components
+- Building a design system with consistent theming
+- Need to preserve all MUI component APIs and behaviors
+- Creating reusable, branded versions (e.g., branded Button, Card)
+
+**Compose MUI Components** when:
+- Building domain-specific components (e.g., UserCard, ProductList)
+- Combining multiple MUI components into a pattern
+- Need custom logic that doesn't fit MUI's API
+- Creating one-off layouts or pages
+
+### Extension Pattern
+
+```tsx
+// ✅ Good: Extend with TypeScript, preserve MUI props
+import { Button, ButtonProps } from '@mui/material/Button';
+
+interface BrandedButtonProps extends ButtonProps {
+  customVariant?: 'primary' | 'secondary' | 'danger';
+}
+
+export const BrandedButton: React.FC<BrandedButtonProps> = ({
+  customVariant,
+  ...muiProps
+}) => {
+  return <Button {...muiProps} />;
+};
+```
+
+```tsx
+// ❌ Bad: Reimplementing MUI functionality
+const BrandedButton = ({ onClick, children }) => {
+  return <div onClick={onClick}>{children}</div>;
+};
+```
+
+---
+
+## Theme Architecture
+
+### Theme Provider Structure
+
+**Rule**: Use MUI's theme provider with `cssVariables` enabled for optimal performance and SSR support.
+
+```tsx
+// ✅ Good: CSS variables for dynamic theming
+import { Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
+
+function App() {
+  return (
+    <CssVarsProvider>
+      {/* Your app */}
+    </CssVarsProvider>
+  );
+}
+```
+
+```tsx
+// ❌ Bad: Traditional theme provider (no CSS variables)
+import { ThemeProvider } from '@mui/material/styles';
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      {/* Your app */}
+    </ThemeProvider>
+  );
+}
+```
+
+### Theme Token Hierarchy
+
+**Rule**: Organize theme tokens in layers of specificity.
+
+1. **Base tokens** - Design primitives (spacing, typography scale, breakpoints)
+2. **Semantic tokens** - Purpose-based (colors.primary, colors.error)
+3. **Component tokens** - Component-specific overrides
+
+```tsx
+// ✅ Good: Layered theme structure
+const theme = createTheme({
+  // Base tokens
+  spacing: 8,
+  typography: {
+    fontFamily: '"Inter", sans-serif',
+  },
+  
+  // Semantic tokens
+  palette: {
+    primary: {
+      main: '#1976d2',
+    },
+  },
+  
+  // Component tokens
+  components: {
+    MuiButton: {
+      styleOverrides: {
+        root: {
+          borderRadius: 8,
+        },
+      },
+    },
+  },
+});
+```
+
+### Dark Mode Implementation
+
+**Rule**: Respect system preference, persist user choice, prevent flash.
+
+```tsx
+// ✅ Good: Proper dark mode setup
+<CssVarsProvider
+  defaultMode="system"
+  modeStorageKey="app-color-mode"
+  disableTransitionOnChange={false}
+>
+```
+
+**Anti-pattern**: Manual class toggling or localStorage reading in components.
+
+---
+
+## Performance Rules
+
+### Import Optimization
+
+**Rule**: Use named imports for tree-shaking, avoid barrel imports.
+
+```tsx
+// ✅ Good: Named imports
+import Button from '@mui/material/Button';
+import TextField from '@mui/material/TextField';
+```
+
+```tsx
+// ❌ Bad: Barrel import (breaks tree-shaking)
+import { Button, TextField } from '@mui/material';
+```
+
+### `sx` Prop Usage
+
+**Rule**: Use `sx` prop for dynamic, one-off styles. Use `styled` for reusable component variants.
+
+```tsx
+// ✅ Good: sx for dynamic styles
+<Box sx={{ 
+  p: isLarge ? 3 : 2,
+  color: error ? 'error.main' : 'text.primary' 
+}} />
+
+// ✅ Good: styled for reusable patterns
+const StyledCard = styled(Card)(({ theme }) => ({
+  borderRadius: theme.spacing(2),
+  boxShadow: theme.shadows[2],
+}));
+```
+
+```tsx
+// ❌ Bad: sx for static, reusable styles
+<Card sx={{ borderRadius: 2, boxShadow: 2 }} />
+<Card sx={{ borderRadius: 2, boxShadow: 2 }} />
+<Card sx={{ borderRadius: 2, boxShadow: 2 }} />
+```
+
+### Theme Caching
+
+**Rule**: Create theme once, memoize custom theme functions.
+
+```tsx
+// ✅ Good: Memoized theme creation
+const theme = useMemo(
+  () => createTheme({
+    palette: { mode: colorMode },
+  }),
+  [colorMode]
+);
+```
+
+```tsx
+// ❌ Bad: Theme recreation on every render
+function App() {
+  const theme = createTheme({ /* ... */ });
+  return <ThemeProvider theme={theme}>...</ThemeProvider>;
+}
+```
+
+---
+
+## Grid System
+
+### Use Grid v2 Syntax
+
+**Rule**: Always use the new Grid2 component for layouts.
+
+```tsx
+// ✅ Good: Grid v2 with container queries
+import Grid from '@mui/material/Unstable_Grid2';
+
+<Grid container spacing={2}>
+  <Grid xs={12} md={6}>Column 1</Grid>
+  <Grid xs={12} md={6}>Column 2</Grid>
+</Grid>
+```
+
+```tsx
+// ❌ Bad: Old Grid syntax
+import Grid from '@mui/material/Grid';
+
+<Grid container spacing={2}>
+  <Grid item xs={12} md={6}>Column 1</Grid>
+</Grid>
+```
+
+---
+
+## Styling Constraints
+
+### CSS Variables Over Inline Styles
+
+**Rule**: Use theme CSS variables instead of hardcoded values.
+
+```tsx
+// ✅ Good: Theme-aware
+<Box sx={{ 
+  bgcolor: 'background.paper',
+  color: 'text.primary',
+  p: 2,
+}} />
+```
+
+```tsx
+// ❌ Bad: Hardcoded values
+<Box sx={{ 
+  backgroundColor: '#fff',
+  color: '#000',
+  padding: '16px',
+}} />
+```
+
+### Component Style Overrides
+
+**Rule**: Override MUI component styles through theme, not inline.
+
+```tsx
+// ✅ Good: Theme-level overrides
+const theme = createTheme({
+  components: {
+    MuiButton: {
+      styleOverrides: {
+        root: {
+          textTransform: 'none',
+        },
+      },
+      defaultProps: {
+        disableRipple: true,
+      },
+    },
+  },
+});
+```
+
+```tsx
+// ❌ Bad: Per-instance overrides
+<Button sx={{ textTransform: 'none' }} disableRipple>Click</Button>
+<Button sx={{ textTransform: 'none' }} disableRipple>Submit</Button>
+```
+
+---
+
+## Icon Usage
+
+### Material Icons
+
+**Rule**: Use `@mui/icons-material` for MUI projects. Use SVG icons for custom designs.
+
+```tsx
+// ✅ Good: MUI icons
+import DeleteIcon from '@mui/icons-material/Delete';
+<IconButton><DeleteIcon /></IconButton>
+```
+
+```tsx
+// ❌ Bad: Icon fonts or inconsistent libraries
+<i className="fa fa-trash"></i>
+```
+
+### Icon Size & Color
+
+**Rule**: Let icons inherit size and color from parent component.
+
+```tsx
+// ✅ Good: Inherited sizing
+<Button startIcon={<AddIcon />}>Add Item</Button>
+```
+
+```tsx
+// ❌ Bad: Manual sizing that breaks consistency
+<Button startIcon={<AddIcon sx={{ fontSize: 20 }} />}>Add Item</Button>
+```
+
+---
+
+## Anti-Patterns
+
+### ❌ Don't Override Internal Class Names
+
+```tsx
+// ❌ Bad: Brittle, breaks with MUI updates
+<Button className="MuiButton-root" />
+```
+
+### ❌ Don't Mix Theme Systems
+
+```tsx
+// ❌ Bad: Mixing MUI theme with external CSS variables
+<Box sx={{ color: 'var(--custom-color)' }} /> // Use MUI theme instead
+```
+
+### ❌ Don't Bypass Theme Provider
+
+```tsx
+// ❌ Bad: Direct theme access without provider
+import { createTheme } from '@mui/material/styles';
+const theme = createTheme();
+<Box sx={{ p: theme.spacing(2) }} />
+```
+
+### ❌ Don't Use `transition: all`
+
+```tsx
+// ❌ Bad: Performance killer
+sx={{ transition: 'all 0.3s' }}
+
+// ✅ Good: Specific properties
+sx={{ transition: 'opacity 0.3s, transform 0.3s' }}
+```
+
+---
+
+## Accessibility Requirements
+
+### Icon-Only Buttons
+
+**Rule**: All icon-only buttons must have `aria-label`.
+
+```tsx
+// ✅ Good
+<IconButton aria-label="Delete item">
+  <DeleteIcon />
+</IconButton>
+
+// ❌ Bad
+<IconButton>
+  <DeleteIcon />
+</IconButton>
+```
+
+### Form Components
+
+**Rule**: All MUI form components require labels.
+
+```tsx
+// ✅ Good: Visible label
+<TextField label="Email" />
+
+// ✅ Good: Accessible without visible label
+<TextField aria-label="Search" placeholder="Search..." />
+
+// ❌ Bad: No label
+<TextField placeholder="Enter email" />
+```
+
+---
+
+## TypeScript Integration
+
+### Extend MUI Types
+
+**Rule**: Augment MUI's module declarations for custom theme properties.
+
+```tsx
+// ✅ Good: Type-safe theme extensions
+declare module '@mui/material/styles' {
+  interface Palette {
+    tertiary: Palette['primary'];
+  }
+  interface PaletteOptions {
+    tertiary?: PaletteOptions['primary'];
+  }
+}
+
+const theme = createTheme({
+  palette: {
+    tertiary: {
+      main: '#ff9800',
+    },
+  },
+});
+```
+
+### Strict Prop Types
+
+**Rule**: Use MUI's provided TypeScript types, extend when needed.
+
+```tsx
+// ✅ Good: Proper typing
+import { ButtonProps } from '@mui/material/Button';
+
+interface CustomButtonProps extends ButtonProps {
+  loading?: boolean;
+}
+```
+
+---
+
+## Testing Considerations
+
+### Theme in Tests
+
+**Rule**: Wrap components with theme provider in tests.
+
+```tsx
+// ✅ Good: Themed test
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+const theme = createTheme();
+render(
+  <ThemeProvider theme={theme}>
+    <MyComponent />
+  </ThemeProvider>
+);
+```
+
+### Snapshot Testing
+
+**Rule**: Mock theme for consistent snapshots.
+
+```tsx
+// ✅ Good: Stable snapshots
+const testTheme = createTheme({
+  palette: { mode: 'light' },
+});
+```
+
+---
+
+## Migration & Compatibility
+
+### Upgrading from MUI v5/v6
+
+**Rule**: Use codemods for safe migrations.
+
+```bash
+# ✅ Good: Automated migration
+npx @mui/codemod v7.0.0/preset-safe <path>
+```
+
+### Deprecated API Usage
+
+**Rule**: Check MUI changelog for deprecated features, replace immediately.
+
+```tsx
+// ❌ Deprecated (v7)
+import { makeStyles } from '@mui/styles';
+
+// ✅ Current
+import { styled } from '@mui/material/styles';
+```
+
+---
+
+## Related Resources
+
+- [MUI Documentation](https://mui.com/material-ui/)
+- [MUI GitHub](https://github.com/mui/material-ui)
+- [CSS Theme Variables Guide](https://mui.com/material-ui/customization/css-theme-variables/usage/)
+- [Dark Mode Best Practices](https://mui.com/material-ui/customization/dark-mode/)

package/rules/react-19-compiler.md

@@ -0,0 +1,26 @@
+---
+description: Guidelines for writing code optimized for the React Compiler (React 19+).
+---
+
+**OBJECTIVE:**
+Writing "Rules of React" compliant code to enable automatic memoization and optimization by the React Compiler.
+
+**REASON:**
+The React Compiler (`babel-plugin-react-compiler`) automatically optimizes components, but only if they follow strict functional purity and reactivity rules.
+
+**DESCRIPTION:**
+Best practices for ensuring components are "Compiler-safe," reducing the need for manual `useMemo` and `useCallback`.
+
+**INSTRUCTIONS:**
+
+### Component Purity
+- **No Mutations in Render**: Never mutate variables or objects during the render phase. Always treat props and state as immutable.
+- **Pure Functions**: Ensure components and hooks are idempotent—calling them multiple times with the same inputs should produce the same results.
+
+### Hook Usage
+- **Standard Hook Patterns**: Only use hooks at the top level and follow the standard React lifecycle. 
+- **Avoid Manual Memoization**: Stop using `useMemo` and `useCallback` for performance optimization; the compiler handles this. Only use them if they are required for stable references in external libraries or deep dependency arrays.
+
+### Compiler Safety
+- **Validate with ESLint**: Ensure `eslint-plugin-react-compiler` is active to catch potential issues that would prevent optimization.
+- **Side Effect Isolation**: Keep side effects strictly inside `useEffect` or event handlers.

package/rules/spec-driven-development.md

@@ -0,0 +1,36 @@
+---
+description: Methodology for Spec-Driven Development (SDD) based on the "Spec Kit" principles.
+---
+
+**OBJECTIVE:**
+Ensuring high-quality implementation by defining technical requirements and intent in a structured "Spec" before writing any code.
+
+**REASON:**
+SDD eliminates "vibe coding" (vague prompting) by providing the AI with a clear technical roadmap, reducing context loss and ensuring alignment with project standards.
+
+**DESCRIPTION:**
+The SDD process involves three distinct phases: Spec Drafting, Implementation, and Verification. The Spec serves as the "source of truth."
+
+**INSTRUCTIONS:**
+
+### 1. Spec Initializing
+- **Before coding starts**, create a `SPEC.md` or equivalent in the component/feature folder.
+- **Spec Content**:
+    - **Intent**: What problem are we solving?
+    - **Usage**: How will the component be used (code examples)?
+    - **Architecture**: Tech stack, state management, and data flow.
+    - **Accessibility**: ARIA roles, focus management, reduced motion.
+    - **Performance**: Soft limits for assets, rendering loop optimizations.
+
+### 2. Implementation Phase
+- **Pure Implementation**: The implementation phase MUST follow the Spec precisely. If the Spec is missing details, the Spec should be updated first.
+- **Incremental Builds**: Build in logical steps (foundation -> features -> polish).
+- **Checkpoints**: Use checkpoints after each major component or feature to verify against the Spec.
+
+### 3. Review & Refinement
+- **Verification**: Cross-reference the final implementation against the "Implementation Checklist" in the Spec.
+- **Zero Vibe Rule**: If the code "feels" right but doesn't meet a spec requirement, it is technically a failure.
+
+### 4. Spec Evolution
+- **Living Document**: The spec is not static. If discoveries are made during OR after execution that change the architecture, update the Spec BEFORE continuing with the code, and/or AFTER final updates are made. Make sure to refactor our spec anytime an additional change or feature is added to the component.
+- **Add Changelog**: Add small and concise summary and timestamp each time the spec changes.

package/rules/supabase.md

@@ -0,0 +1,40 @@
+---
+description: Best practices for integrating Supabase for auth, database, and asset storage.
+---
+
+**OBJECTIVE:**
+Implementing a secure, type-safe, and efficient integration with Supabase for data management and authentication.
+
+**REASON:**
+Ensures centralized client management, leverages TypeScript for end-to-end safety, and optimizes the handling of large 3D assets via Supabase Storage.
+
+**DESCRIPTION:**
+Guidelines for client initialization, authentication state management, and asset coordination between Supabase and Three.js.
+
+**INSTRUCTIONS:**
+
+### Environment Configuration
+- **Standard Naming**: Use `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` in `.env` files.
+- **Validation**: Ensure these variables are present and valid before initializing the client to prevent silent runtime failures.
+
+### Client Management
+- **Singleton Pattern**: Initialize the Supabase client once in a dedicated file (e.g., `src/lib/supabase.ts`) and export it as a singleton.
+- **Type Safety**: Generate TypeScript types using the Supabase CLI (`supabase gen types typescript --project-id ...`) and pass them to the `createClient` function for full IntelliSense support.
+
+### Authentication
+- **Auth Context**: Wrap the application (or relevant branches) in a `SupabaseAuthProvider` to manage user sessions and profiles.
+- **Protecting Routes**: Use specialized hooks (e.g., `useAuth`) to handle redirects for protected versus public views.
+- **Loading States**: Always account for the initial session check to avoid "flash of unauthenticated content."
+
+### Database & RLS
+- **RLS is Mandatory**: Never disable Row Level Security (RLS) in production. Always define specific policies for `SELECT`, `INSERT`, `UPDATE`, and `DELETE`.
+- **Relational Integrity**: Use Foreign Key constraints and appropriate indexes to maintain data quality and query performance.
+
+### Asset Storage (Three.js Specific)
+- **Bucket Organization**: Store 3D models (`.glb`, `.gltf`) and textures (`.webp`, `.ktx2`) in dedicated Supabase Storage buckets.
+- **Signed URLs**: Use signed URLs for private assets or assets requiring temporary access.
+- **Caching**: Leverage Supabase's built-in CDN for public storage buckets to minimize latency when loading 3D scenes.
+
+### Error Handling
+- **User-Friendly Messages**: Transform Supabase error codes into human-readable feedback.
+- **Retry Logic**: Implement exponential backoff for network-related failures, especially when uploading or downloading large assets.

package/rules/tailwind-v4.md

@@ -0,0 +1,29 @@
+---
+description: Best practices for using Tailwind CSS v4 in a performance-oriented React environment.
+---
+
+**OBJECTIVE:**
+Leveraging the CSS-first architecture of Tailwind CSS v4 to build high-performance, maintainable UIs.
+
+**REASON:**
+Tailwind v4 moves configuration into CSS and utilizes a high-performance engine (Lightning CSS), requiring a shift in how themes and utilities are managed compared to v3.
+
+**DESCRIPTION:**
+Guidelines for using Tailwind v4's `@theme` block, CSS variables, and modern engine features while avoiding legacy configuration patterns.
+
+**INSTRUCTIONS:**
+
+### CSS-First Configuration
+- **Use `@theme` in CSS**: Define all theme extensions (colors, fonts, spacing) inside the `@theme` block in your main CSS file, not in a JS configuration file.
+- **Prefer CSS Variables**: Use CSS custom properties defined in `@theme`. Reference them as `var(--name)` when needed in custom styles.
+- **Avoid `tailwind.config.js`**: Do not create or use a `tailwind.config.js` file unless strictly necessary for legacy plugin compatibility.
+
+### Performance & Engine
+- **Leverage Lightning CSS**: Be aware that Tailwind v4 uses Lightning CSS for ultra-fast builds. Avoid complex PostCSS plugins that might slow down the pipeline.
+- **Built-in Modern Features**: Use modern CSS features like `@import "tailwindcss"` and direct variable references which are optimized by the v4 engine.
+
+### Implementation Patterns
+- **Prioritize Container Queries**: Use `@container` queries for component-level styling and layout before resorting to viewport-based media queries whenever a component's layout depends on its parent's width.
+- **Dual Color Palettes**: Always define and implement both **light and dark** color mode palettes within the `@theme` block. Use native CSS color-scheme support and variables to ensure seamless transitions.
+- **Utility First**: Maintain the utility-first mindset, but use standard CSS for complex layouts that utilities cannot cleanly handle.
+- **Modern Color Palettes**: Use the expanded Oklch color space support provided by v4 for better perceptual uniformity in gradients and UI elements.

package/rules/three-js-react.md

@@ -0,0 +1,76 @@
+---
+description: Guidelines for building production-ready React applications with Three.js and AI-powered tools.
+---
+
+**OBJECTIVE:**
+Building production-ready React applications with [Three.js](https://threejs.org/manual/#en/creating-a-scene) and AI-powered APIs and tooling.
+
+**REASON:**
+Ensures high performance, proper resource management, and clean React integration when working with complex 3D scenes in a web environment.
+
+**DESCRIPTION:**
+This rule provides a comprehensive set of best practices for Three.js development within a React ecosystem, focusing on memory management, rendering optimization, and asset handling.
+
+**INSTRUCTIONS:**
+
+### Resource Management
+- **Always dispose** of `Geometry`, `Material`, `Texture`, and `Renderer` objects in component cleanup to prevent WebGL memory leaks.
+- Call `geometry.dispose()`, `material.dispose()`, `texture.dispose()`, and `renderer.dispose()` in the `useEffect` cleanup function.
+- Dispose of post-processing passes and composers when unmounting.
+
+### Performance Optimization
+- **Cap pixel ratio** to `Math.min(window.devicePixelRatio, 2)` to balance quality and performance.
+- Set `powerPreference: "high-performance"` in `WebGLRenderer` options.
+- **Reuse objects** (Vector3, Color, etc.) instead of creating new instances in the animation loop.
+- Use `BufferGeometry` instead of legacy `Geometry`.
+- Limit particle counts and geometry complexity based on device capabilities.
+
+### React Integration
+- Use `useRef` for canvas elements and Three.js objects (scene, camera, renderer).
+- Initialize Three.js in `useEffect` with proper cleanup in the return function.
+- Cancel `requestAnimationFrame` on component unmount to prevent memory leaks.
+- **Avoid storing Three.js objects in React state**; use refs instead.
+
+### Responsive Design
+- Handle window resize events to update camera aspect ratio and renderer size.
+- Update post-processing composer and pass resolutions on resize.
+- Debounce resize handlers if performing expensive recalculations.
+
+### Animation Loop
+- Use `requestAnimationFrame` for smooth 60fps rendering.
+- Store the animation frame ID and cancel it in cleanup.
+- Implement delta time for frame-rate independent animations when needed.
+
+### Scene Organization
+- Use `THREE.Group` to organize related objects for easier transformation and cleanup.
+- Separate static and dynamic objects for optimization opportunities.
+- Use meaningful names for objects to aid debugging (`object.name = "particleSystem"`).
+
+### Asset Loading
+- Use `GLTFLoader` for 3D models (preferred format for web).
+- Implement `LoadingManager` for coordinated loading with progress tracking.
+- Use `DRACOLoader` for compressed GLTF files to reduce file size.
+- Handle loading errors gracefully with user feedback.
+- Consider lazy loading non-critical 3D assets.
+
+### Shaders and Materials
+- Minimize dynamic lights; prefer baked lighting or environment maps (HDRI).
+- Use `ShaderMaterial` for custom effects but keep shaders optimized.
+- Avoid heavy branching and loops in fragment shaders.
+- Use `MeshStandardMaterial` or `MeshPhysicalMaterial` for PBR workflows.
+- Set `depthWrite: false` and `transparent: true` appropriately for particle systems.
+
+### Post-Processing
+- Use `EffectComposer` for post-processing effects.
+- Order passes efficiently (RenderPass → effects → FXAA/SMAA last).
+- Disable unused passes to save performance.
+- Update pass resolutions on window resize.
+
+### Interaction
+- Throttle or debounce mouse/touch event handlers for expensive calculations.
+- Use raycasting efficiently; limit the number of objects tested.
+- Implement smooth camera controls with lerping for better UX.
+
+### Framework Consideration
+- For complex scenes, consider migrating to `@react-three/fiber` and `@react-three/drei` for declarative Three.js in React.
+- These libraries provide React-friendly abstractions, automatic disposal, and helpful hooks.