agents-config 1.0.0

package/rules/component-architecture.md

@@ -0,0 +1,34 @@
+---
+description: Standardized directory and file structure for React components in this workspace.
+---
+
+**OBJECTIVE:**
+Maintaining a consistent, scalable, and discoverable component architecture.
+
+**REASON:**
+As the project grows, a standardized folder structure prevents "file sprawl" and makes it easier to locate styles, tests, and assets related to a specific component.
+
+**DESCRIPTION:**
+The "Folder-per-Component" pattern used throughout the `src/components` directory.
+
+**INSTRUCTIONS:**
+
+### Directory Structure
+- **Component Folders**: Every major component should live in its own folder under `src/components/`.
+- **Primary File**: The main component file must be named `ComponentName.tsx` (PascalCase).
+- **Associated Files**: Styles, local assets, and sub-components should reside within the same component folder.
+
+Example:
+```
+src/components/Hero/
+├── Hero.tsx
+├── Hero.css (if not using Tailwind)
+└── HeroBackground.tsx (local child component)
+```
+
+### Exports
+- **Named Exports**: Prefer named exports for components to ensure better IDE support and tree-shaking.
+- **Clear Boundaries**: Avoid importing local child components (e.g., `HeroBackground`) from outside their parent's folder. If a component is reused elsewhere, move it to the root of `src/components/`.
+
+### Prop Types
+- **Interfaces over Types**: Use `interface` for component props to allow for better extensibility and cleaner error messages.

package/rules/gemini.md

@@ -0,0 +1,547 @@
+# Google Gemini AI Integration Rules
+
+**Purpose**: Architectural constraints, security requirements, and UX patterns for integrating Google Gemini API into React applications.
+
+**Related Skill**: [integrate_gemini](../skills/integrate_gemini/SKILL.md)
+
+---
+
+## AI Integration Philosophy
+
+### When to Use AI Features
+
+**Use Gemini when**:
+- Generating creative content (text, summaries, translations)
+- Providing conversational interfaces
+- Analyzing user-provided content
+- Offering intelligent suggestions or recommendations
+- Processing natural language queries
+
+**Don't Use Gemini when**:
+- Deterministic logic is required (use regular code)
+- Real-time responses are critical (< 100ms)
+- Offline functionality is needed
+- Simple rule-based logic suffices
+- User expects instant, predictable results
+
+### Human-in-the-Loop Principle
+
+**Rule**: AI should augment, not replace, human decision-making.
+
+```tsx
+// ✅ Good: AI suggests, user decides
+<SuggestionList 
+  suggestions={aiSuggestions}
+  onAccept={handleAccept}
+  onReject={handleReject}
+  onEdit={handleEdit}
+/>
+
+// ❌ Bad: AI acts without user confirmation
+useEffect(() => {
+  if (aiResponse) {
+    saveToDatabase(aiResponse); // No user review!
+  }
+}, [aiResponse]);
+```
+
+### Graceful Degradation
+
+**Rule**: Application must function without AI when it fails.
+
+```tsx
+// ✅ Good: Fallback when AI unavailable
+const content = aiGenerated || defaultContent;
+
+// ❌ Bad: Broken UI when AI fails
+{aiGenerated && <Content>{aiGenerated}</Content>}
+```
+
+---
+
+## Security & Safety Rules
+
+### API Key Security
+
+**MUST**: Never expose API keys in client-side code.
+
+```tsx
+// ✅ Good: Environment variable
+const apiKey = import.meta.env.VITE_GEMINI_API_KEY;
+
+// ❌ CRITICAL: Hardcoded key
+const apiKey = "AIzaSyD..."; // NEVER DO THIS
+```
+
+**MUST**: Use server-side proxy for production.
+
+```tsx
+// ✅ Good: Server-side API route
+const response = await fetch('/api/gemini', {
+  method: 'POST',
+  body: JSON.stringify({ prompt }),
+});
+
+// ❌ Bad: Direct client-side API call in production
+const genAI = new GoogleGenerativeAI(apiKey);
+```
+
+### Prompt Injection Prevention
+
+**Rule**: Sanitize and validate all user inputs before sending to Gemini.
+
+```tsx
+// ✅ Good: Input validation
+const sanitizedPrompt = prompt
+  .trim()
+  .slice(0, MAX_PROMPT_LENGTH)
+  .replace(/[<>]/g, ''); // Remove potential injection chars
+
+// ❌ Bad: Raw user input
+const response = await model.generateContent(userInput);
+```
+
+### Content Safety
+
+**Rule**: Implement content filtering for user-facing AI responses.
+
+```tsx
+// ✅ Good: Safety settings
+const model = genAI.getGenerativeModel({
+  model: "gemini-pro",
+  safetySettings: [
+    {
+      category: HarmCategory.HARM_CATEGORY_HARASSMENT,
+      threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
+    },
+    {
+      category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+      threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
+    },
+  ],
+});
+```
+
+**Rule**: Handle safety blocks gracefully.
+
+```tsx
+// ✅ Good: Safety block handling
+if (result.response.promptFeedback?.blockReason) {
+  setError('Content was blocked for safety reasons. Please rephrase your request.');
+  return;
+}
+```
+
+---
+
+## UX Requirements
+
+### Streaming Response Pattern
+
+**MUST**: Use streaming for all text generation over 50 words.
+
+```tsx
+// ✅ Good: Streaming for better UX
+const result = await model.generateContentStream(prompt);
+for await (const chunk of result.stream) {
+  setText(prev => prev + chunk.text());
+}
+
+// ❌ Bad: Blocking until complete response
+const result = await model.generateContent(prompt);
+setText(result.response.text());
+```
+
+### Loading States
+
+**MUST**: Show loading indicators during AI generation.
+
+```tsx
+// ✅ Good: Clear loading state
+{isLoading && (
+  <div role="status" aria-live="polite">
+    <Spinner />
+    <span>Generating response...</span>
+  </div>
+)}
+
+// ❌ Bad: No feedback during generation
+{response && <div>{response}</div>}
+```
+
+### Streaming UI States
+
+**MUST**: Use `aria-live` for streaming content.
+
+```tsx
+// ✅ Good: Accessible streaming
+<div aria-live="polite" aria-atomic="false">
+  {streamingText}
+</div>
+
+// ❌ Bad: Screen reader can't track updates
+<div>{streamingText}</div>
+```
+
+### Error Handling UX
+
+**MUST**: Provide actionable error messages with retry options.
+
+```tsx
+// ✅ Good: User-friendly error handling
+{error && (
+  <Alert severity="error">
+    <AlertTitle>Unable to generate response</AlertTitle>
+    {error.message}
+    <Button onClick={handleRetry}>Try Again</Button>
+  </Alert>
+)}
+
+// ❌ Bad: Technical error dump
+{error && <div>Error: {error.toString()}</div>}
+```
+
+### AI Attribution
+
+**MUST**: Clearly indicate AI-generated content.
+
+```tsx
+// ✅ Good: Clear attribution
+<div>
+  <p>{aiContent}</p>
+  <small>Generated by AI • Please verify accuracy</small>
+</div>
+
+// ❌ Bad: No indication content is AI-generated
+<div>{aiContent}</div>
+```
+
+---
+
+## Performance Rules
+
+### Response Caching
+
+**Rule**: Cache responses for identical prompts.
+
+```tsx
+// ✅ Good: Cache frequent queries
+const cacheKey = hashPrompt(prompt);
+const cached = cache.get(cacheKey);
+if (cached) return cached;
+
+const response = await generateContent(prompt);
+cache.set(cacheKey, response, { ttl: 3600 });
+```
+
+### Rate Limiting
+
+**MUST**: Implement client-side rate limiting to prevent quota exhaustion.
+
+```tsx
+// ✅ Good: Rate limit user requests
+const rateLimiter = new RateLimiter({
+  maxRequests: 10,
+  windowMs: 60000, // 10 requests per minute
+});
+
+if (!rateLimiter.check(userId)) {
+  throw new Error('Rate limit exceeded. Please try again later.');
+}
+```
+
+### Timeout Handling
+
+**MUST**: Set reasonable timeouts for AI requests.
+
+```tsx
+// ✅ Good: Timeout protection
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), 30000);
+
+try {
+  const response = await fetch('/api/gemini', {
+    signal: controller.signal,
+  });
+} catch (error) {
+  if (error.name === 'AbortError') {
+    setError('Request timed out. Please try again.');
+  }
+} finally {
+  clearTimeout(timeoutId);
+}
+```
+
+### Token Optimization
+
+**Rule**: Minimize token usage for cost and performance.
+
+```tsx
+// ✅ Good: Concise system instructions
+const systemInstruction = "Summarize in 2-3 sentences.";
+
+// ❌ Bad: Verbose, wasteful prompting
+const systemInstruction = `
+  Please provide a comprehensive summary of the following text. 
+  Make sure to include all key points and important details. 
+  The summary should be well-structured and easy to read.
+  Please keep it concise but informative.
+`;
+```
+
+---
+
+## Ethical Guidelines
+
+### Transparency
+
+**MUST**: Users must know they're interacting with AI.
+
+```tsx
+// ✅ Good: Clear AI disclosure
+<Chatbot>
+  <Header>AI Assistant</Header>
+  <Disclaimer>
+    This is an AI chatbot. Responses may contain errors.
+  </Disclaimer>
+</Chatbot>
+
+// ❌ Bad: Misleading as human
+<Chatbot>
+  <Header>Customer Support</Header>
+</Chatbot>
+```
+
+### Bias Awareness
+
+**Rule**: Acknowledge potential AI biases in documentation.
+
+```tsx
+// ✅ Good: Bias disclaimer
+<TermsOfService>
+  AI-generated content may reflect biases present in training data. 
+  Use critical judgment when evaluating suggestions.
+</TermsOfService>
+```
+
+### Data Privacy
+
+**MUST**: Inform users about data sent to Gemini API.
+
+```tsx
+// ✅ Good: Privacy notice
+<PrivacyNotice>
+  Your input will be sent to Google's Gemini API for processing.
+  <Link to="/privacy">Learn more about data handling</Link>
+</PrivacyNotice>
+```
+
+**MUST**: Respect user consent for data sharing.
+
+```tsx
+// ✅ Good: Opt-in consent
+const [aiConsent, setAiConsent] = useState(false);
+
+if (!aiConsent) {
+  return <ConsentDialog onAccept={() => setAiConsent(true)} />;
+}
+```
+
+### Content Responsibility
+
+**Rule**: Verify critical AI-generated content before using.
+
+```tsx
+// ✅ Good: Verification step for critical content
+<GeneratedContent>
+  {content}
+  <Warning>
+    This content was AI-generated and should be reviewed for accuracy.
+  </Warning>
+  <Button onClick={handleVerify}>Mark as Verified</Button>
+</GeneratedContent>
+```
+
+---
+
+## Anti-Patterns
+
+### ❌ Blocking UI During Generation
+
+```tsx
+// ❌ Bad: Freezes entire UI
+const response = await model.generateContent(longPrompt);
+setContent(response);
+
+// ✅ Good: Non-blocking with streaming
+const stream = await model.generateContentStream(longPrompt);
+for await (const chunk of stream) {
+  setContent(prev => prev + chunk.text());
+}
+```
+
+### ❌ No Loading Indicators
+
+```tsx
+// ❌ Bad: Silent loading
+const handleGenerate = async () => {
+  const result = await generateAI(prompt);
+  setResult(result);
+};
+
+// ✅ Good: Clear feedback
+const handleGenerate = async () => {
+  setLoading(true);
+  try {
+    const result = await generateAI(prompt);
+    setResult(result);
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+### ❌ Hardcoded Prompts
+
+```tsx
+// ❌ Bad: Inflexible hardcoded prompts
+const prompt = "Write a blog post about React";
+
+// ✅ Good: Configurable prompt templates
+const prompt = promptTemplate
+  .replace('{{topic}}', topic)
+  .replace('{{tone}}', tone)
+  .replace('{{length}}', length);
+```
+
+### ❌ No Error Recovery
+
+```tsx
+// ❌ Bad: Crash on error
+const result = await model.generateContent(prompt);
+setText(result.text());
+
+// ✅ Good: Graceful error handling
+try {
+  const result = await model.generateContent(prompt);
+  setText(result.text());
+} catch (error) {
+  setError(error);
+  setText(fallbackContent);
+}
+```
+
+### ❌ Missing AI Attribution
+
+```tsx
+// ❌ Bad: Presented as human-written
+<ArticleContent>{aiGeneratedText}</ArticleContent>
+
+// ✅ Good: Clear AI attribution
+<ArticleContent>
+  {aiGeneratedText}
+  <Attribution>Content generated with AI assistance</Attribution>
+</ArticleContent>
+```
+
+### ❌ Infinite Retry Loops
+
+```tsx
+// ❌ Bad: Unlimited retries
+const generateWithRetry = async () => {
+  try {
+    return await generate();
+  } catch {
+    return generateWithRetry(); // Infinite loop!
+  }
+};
+
+// ✅ Good: Limited retry attempts
+const generateWithRetry = async (maxRetries = 3) => {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await generate();
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
+    }
+  }
+};
+```
+
+---
+
+## Testing Considerations
+
+### Mock AI Responses
+
+**Rule**: Mock Gemini API in tests for reliability.
+
+```tsx
+// ✅ Good: Mocked AI for tests
+jest.mock('@google/generative-ai', () => ({
+  GoogleGenerativeAI: jest.fn().mockImplementation(() => ({
+    getGenerativeModel: () => ({
+      generateContent: async () => ({
+        response: { text: () => 'Mocked AI response' },
+      }),
+    }),
+  })),
+}));
+```
+
+### Test Error Scenarios
+
+**Rule**: Test all AI failure modes.
+
+```tsx
+// ✅ Good: Comprehensive error testing
+describe('AI Generation', () => {
+  it('handles network errors', async () => {
+    mockAPI.mockRejectedValue(new NetworkError());
+    await expect(generate()).rejects.toThrow();
+  });
+
+  it('handles rate limiting', async () => {
+    mockAPI.mockRejectedValue(new RateLimitError());
+    // Assert error UI shown
+  });
+
+  it('handles content blocking', async () => {
+    mockAPI.mockResolvedValue({ blockReason: 'SAFETY' });
+    // Assert safety message shown
+  });
+});
+```
+
+---
+
+## Related Resources
+
+- [Google Gemini API Documentation](https://ai.google.dev/docs)
+- [Generative AI Safety Guidelines](https://ai.google.dev/gemini-api/docs/safety-settings)
+- [Best Practices for Prompting](https://ai.google.dev/gemini-api/docs/prompting-strategies)
+- [Rate Limits and Quotas](https://ai.google.dev/gemini-api/docs/quota)
+- [Responsible AI Practices](https://ai.google.dev/responsible)
+
+---
+
+## Integration Checklist
+
+Before deploying Gemini integration:
+
+- [ ] API keys stored securely (environment variables, never hardcoded)
+- [ ] Safety settings configured
+- [ ] Rate limiting implemented
+- [ ] Timeout handling in place
+- [ ] Loading states for all AI operations
+- [ ] Error handling with user-friendly messages
+- [ ] Retry logic with exponential backoff
+- [ ] AI attribution visible on all generated content
+- [ ] Privacy notice provided to users
+- [ ] Content verification workflow for critical use cases
+- [ ] Streaming implemented for long-form content
+- [ ] Accessible ARIA labels for dynamic content
+- [ ] Response caching for repeated queries
+- [ ] Tests covering error scenarios
+- [ ] Monitoring/logging for AI requests