npm - agents-config - Versions diffs - 1.0.0 - Mend

agents-config 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/rules/web-performance.md ADDED Viewed

@@ -0,0 +1,29 @@
+---
+trigger: always_on
+description: Web performance and Core Web Vitals optimization guidelines.
+---
+**OBJECTIVE:**
+Ensuring fast load times, smooth interactions, and stable layouts for both 3D and standard web content.
+**REASON:**
+Large 3D assets can easily degrade performance, leading to poor Core Web Vitals scores and high bounce rates, especially on mobile devices.
+**DESCRIPTION:**
+Rules for asset budgeting, layout stability, and resource prioritization.
+**INSTRUCTIONS:**
+### Core Web Vitals
+- **Prevent Layout Shifts (CLS)**: Always set explicit `width` and `height` dimensions (or aspect ratio) on the canvas container to reserve space before the scene initializes.
+- **Optimize LCP**: Identify the largest above-fold element (often a hero texture or font), and utilize the CSS property, [content visibility](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/content-visibility) to help with more performant rendering. Use `<link rel="preload">` for these critical assets and **Inline Critical CSS** in the HTML `<head>` for a near-instant first paint.
+### Asset Budgeting
+- **Texture Compression**: Use `.webp` or `.ktx2` for textures. Avoid large 4K textures unless viewed up close; 1K or 2K is usually sufficient for web.
+- **Geometry Optimization**: Use Draco compression for GLTF models. Aim for a total initial bundle size (including models) under 5MB for the primary interactive state.
+- **Lazy Loading**: Use dynamic imports `React.lazy()` or the `useLoader` cleanup mechanism for non-critical assets (e.g., objects in future scenes or footer elements).
+### Rendering Performance
+- **Font Display**: Use `font-display: swap` for all web fonts to ensure text is visible while the custom font (and 3D scene) loads.
+- **Avoid Long Tasks**: Ensure that Three.js initialization or heavy computations don't block the main thread for more than 50ms. Use `setTimeout` or `requestIdleCallback` to chunk initialization if necessary.
+- **Asset Caching**: Leverage service workers or strong Cache-Control headers for 3D assets that don't change frequently.

package/schemas/agents-project.schema.json ADDED Viewed

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/ericthayer/agents-config/main/schemas/agents-project.schema.json",
+  "title": "Agents Project Configuration",
+  "description": "Configuration schema for project-specific AI agent settings",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "description": "Configuration version (semver)",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "project": {
+      "type": "object",
+      "description": "Project metadata",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Project name"
+        },
+        "framework": {
+          "type": "string",
+          "enum": ["next", "react", "remix", "astro", "vue", "svelte", "other"],
+          "description": "Primary framework"
+        },
+        "styling": {
+          "type": "string",
+          "enum": ["tailwind", "mui", "vanilla", "styled", "emotion", "css-modules", "other"],
+          "description": "Styling approach"
+        },
+        "database": {
+          "type": "string",
+          "enum": ["supabase", "firebase", "prisma", "drizzle", "none", "other"],
+          "description": "Database/backend"
+        }
+      },
+      "required": ["name"]
+    },
+    "agents": {
+      "type": "array",
+      "description": "AI agents to configure",
+      "items": {
+        "type": "string",
+        "enum": ["copilot", "claude", "cursor", "gemini", "codex", "windsurf"]
+      }
+    },
+    "rules": {
+      "type": "object",
+      "description": "Rule configuration",
+      "properties": {
+        "include": {
+          "type": "array",
+          "description": "Rules to include (by filename without extension)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "description": "Rules to exclude",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "overrides": {
+      "type": "object",
+      "description": "Project-specific rule overrides",
+      "additionalProperties": true
+    }
+  },
+  "required": ["version", "project"]
+}

package/skills/accessibility-audit/SKILL.md ADDED Viewed

@@ -0,0 +1,39 @@
+---
+name: accessibility-audit
+description: Verify that a component or page meets the high accessibility standards defined in AGENTS.md.
+---
+# `accessibility-audit`
+Use this skill before marking any feature as "Done". It helps you catch common accessibility issues that are strictly forbidden by [AGENTS.md](../../AGENTS.md).
+## Checklist
+### 1. Semantic Structure
+- [ ] Are buttons used for actions (`<button>`) and links for navigation (`<a>`)?
+- [ ] Do headings (`h1`-`h6`) follow a logical hierarchy? (Only one `h1` per page).
+- [ ] Are lists (`ul`, `ol`) used for grouped items?
+### 2. Interactive Elements
+- [ ] **Focus**: Can you tab to every interactive element?
+- [ ] **Visual Focus**: Does every element have a visible focus ring? (No `outline: none` without replacement).
+- [ ] **Labels**: Do all icon-only buttons have `aria-label`?
+- [ ] **Forms**: Do all inputs have a linked `<label>` or `aria-label`?
+### 3. Images & Media
+- [ ] Do all images have `alt` text (or `alt=""` if decorative)?
+- [ ] do user-uploaded or AI-generated images have proper error states?
+- [ ] Are explicit `width` and `height` attributes set to prevent layout shifts?
+### 4. Dynamic Content
+- [ ] **Loading**: Are loading states announced? (e.g., `aria-busy="true"` or `role="status"`).
+- [ ] **Streaming**: Is the streaming text container using `aria-live="polite"`?
+- [ ] **Updates**: Do dynamic updates trigger screen reader notifications?
+### 5. Motion & Validation
+- [ ] **Reduced Motion**: Is `prefers-reduced-motion` respected?
+- [ ] **Validation**: Are form errors linked to inputs via `aria-describedby`?
+- [ ] **Focus Management**: Is focus moved to the error summary or first error on submit failure?
+## Failure Conditions
+If any of the above are "No", the feature is **NOT** ready. Stop and fix it.

package/skills/integrate-gemini/SKILL.md ADDED Viewed

@@ -0,0 +1,124 @@
+---
+name: integrate-gemini
+description: Implement robust Google Gemini API integration with streaming, error handling, and type safety.
+---
+# `integrate-gemini`
+Use this skill when the user wants to "connect to Gemini", "add AI features", or "fix API generation".
+## Requirements (from rules/gemini.md)
+1.  **Safety**: NEVER hardcode API keys. Use `import.meta.env` or similar.
+2.  **UX**: Always show Loading / Streaming states.
+3.  **Reliability**: Handle errors gracefully (network, blocking, rate limits).
+4.  **Attribution**: AI content must be labeled.
+## Usage
+1.  **Check for Client Library**: Ensure `@google/generative-ai` is installed. If not, install it.
+2.  **Create the Hook**: Create `hooks/useGemini.ts` (or similar).
+3.  **Implement Logic**: Use the pattern below to handle the complexities of streaming.
+## Code Pattern: `useGemini` Hook
+```typescript
+import { useState, useCallback } from 'react';
+import { GoogleGenerativeAI, GenerativeModel } from '@google/generative-ai';
+// Initialize outside component if key is static, or inside if dynamic
+// const genAI = new GoogleGenerativeAI(import.meta.env.VITE_GEMINI_API_KEY);
+interface UseGeminiOptions {
+  modelName?: string;
+  // Gemini 3 Thinking Config
+  useThinking?: boolean;
+  thinkingBudget?: number; // e.g., 16384
+  onError?: (error: Error) => void;
+}
+export const useGemini = ({
+  modelName = "gemini-3-pro-preview", // Updated default to Gemini 3
+  useThinking = false,
+  thinkingBudget = 16384,
+  onError
+}: UseGeminiOptions = {}) => {
+  const [response, setResponse] = useState<string>('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const generate = useCallback(async (prompt: string, images?: File[]) => {
+    setIsLoading(true);
+    setIsStreaming(false);
+    setError(null);
+    setResponse('');
+    try {
+      const genAI = new GoogleGenerativeAI(import.meta.env.VITE_GEMINI_API_KEY);
+      // Determine configuration based on Thinking
+      const generationConfig: any = {};
+      if (useThinking) {
+        generationConfig.thinkingConfig = { thinkingBudget };
+        // Must increase maxOutputTokens to accommodate thinking process
+        generationConfig.maxOutputTokens = thinkingBudget + 8192;
+      }
+      const model = genAI.getGenerativeModel({
+        model: modelName,
+        generationConfig
+      });
+      // Prepare contents (Text + optional Images)
+      let contents: any[] = [{ text: prompt }];
+      if (images && images.length > 0) {
+        // Simple example for adding images (implementation varies by input format)
+        // Ideally convert File -> Base64 here
+        // const imageParts = await Promise.all(images.map(fileToGenerativePart));
+        // contents = [...imageParts, { text: prompt }];
+      }
+      // Use streaming for better UX
+      const result = await model.generateContentStream(contents);
+      setIsLoading(false); // Initial wait is over, now we stream
+      setIsStreaming(true);
+      let fullText = '';
+      for await (const chunk of result.stream) {
+        const chunkText = chunk.text();
+        fullText += chunkText;
+        setResponse(prev => prev + chunkText);
+      }
+      setIsStreaming(false);
+      return fullText;
+    } catch (err: any) {
+      const errorObj = err instanceof Error ? err : new Error(String(err));
+      setError(errorObj);
+      setIsLoading(false);
+      setIsStreaming(false);
+      if (onError) onError(errorObj);
+      console.error("Gemini API Error:", err);
+    }
+  }, [modelName, useThinking, thinkingBudget, onError]);
+  return {
+    generate,
+    response,
+    isLoading,
+    isStreaming,
+    error,
+    attribution: "Generated by Google Gemini"
+  };
+};
+```
+## UI Implementation Tips
+- **Thinking UI**: If `useThinking` is true, the `isLoading` state might be longer. Considering adding a "Reasoning..." label.
+- **Cancel Support**: Consider passing an `AbortSignal` to `generate` for long-running thinking tasks.
+- **Images**: If using `gemini-3-pro-image-preview`, use standard `generateContent` (not stream) and handle base64 output.
+- **Disable Submit**: `disabled={isLoading || isStreaming}`
+- **Loading Spinner**: Show when `isLoading` is true.
+- **Cursor/Typewriter**: Show when `isStreaming` is true.
+- **Error Banner**: Display `error.message` if `error` exists.

package/skills/scaffold-component/SKILL.md ADDED Viewed

@@ -0,0 +1,77 @@
+---
+name: scaffold-component
+description: Create a new React component following project constraints (Tailwind, MUI, or Vanilla).
+---
+# `scaffold-component` (Global Fallback)
+Use this skill when the user asks to "create a component". This skill is designed to be framework-agnostic and will adapt to the current project's stack. Adhere to the following process and development philosophy and approach.
+## Development Process
+**Philosophy & Approach**
+- **Spec-Driven Development (SDD)**: Always start by creating a technical specification using the [sdd-workflow](../workflows/sdd-workflow.md) template. Adhere to the `spec-driven-development.md` global rule.
+  - Create the spec as `[ComponentName].spec.md` within the component folder before starting implementation.
+  - **Living Document**: Refactor the spec for every new feature or discovery and maintain a timestamped **Changelog** at the bottom.
+- **Component Architecture**: Follow the `component-architecture.md` global rule (Folder-per-Component).
+## Usage
+1.  **Draft the Spec**: Follow the [sdd-workflow](../workflows/sdd-workflow.md) template and create `src/components/[ComponentName]/[ComponentName].spec.md`. Initialize the **Changelog** section.
+2.  **Detect Framework & Stack**: Check `package.json` for dependencies (e.g., `@mui/material`, `tailwindcss`, `react` version). Adhere to project-specific rules like `three-js-react.md` if applicable.
+3.  **Implement & Update**: Follow the spec strictly. If architecture changes during build, update the spec and the changelog **before** proceeding.
+## Framework-Specific Rules
+### If MUI is detected:
+- Use MUI components (`Box`, `Typography`, `Grid`).
+- Use the `sx` prop for custom styling.
+- Use `Grid` (v2) if on MUI v6+.
+- Follow [mui.md](../../rules/mui.md) architecture patterns.
+### If Tailwind CSS is detected:
+- Use standard HTML tags (`div`, `header`, `main`).
+- Use `className` with Tailwind utility classes.
+- Follow mobile-first responsive patterns (e.g., `sm:`, `md:`, `lg:`).
+- Follow [tailwind-v4.md](../../rules/tailwind-v4.md) patterns.
+### Default (Vanilla React/CSS):
+- Use standard HTML tags.
+- Use CSS Modules or standard CSS
+- Use CSS Custom Properties to build a light/dark theme.
+## Base Template
+```tsx
+import React from 'react';
+/**
+ * Props for the [ComponentName] component.
+ */
+export interface [ComponentName]Props {
+  /** ARIA label for accessibility */
+  'aria-label'?: string;
+  title?: string;
+  children?: React.ReactNode;
+}
+/**
+ * [Brief description of the component]
+ */
+export const [ComponentName]: React.FC<[ComponentName]Props> = ({
+  'aria-label': ariaLabel,
+  title,
+  children,
+  ...props
+}) => {
+  // IMPLEMENTATION: Adapt based on detected framework (MUI vs Tailwind)
+  return (
+    <div className="[component-name-kebab-case]" {...props}>
+      {title && <h2>{title}</h2>}
+      <div role="region" aria-label={ariaLabel || "[Default Label]"}>
+        {children || <p>New component: [ComponentName]</p>}
+      </div>
+    </div>
+  );
+};
+```