agents-config 1.0.0

package/README.md

@@ -0,0 +1,254 @@
+# agents-config
+
+A comprehensive knowledge base and skill library for building production-grade React applications with AI-powered tools and best practices.
+
+[![npm version](https://img.shields.io/npm/v/agents-config.svg)](https://www.npmjs.com/package/agents-config)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+This package provides curated guidelines, instructions, skills, and rules for developing React/TypeScript applications. It serves as a **single source of truth** for AI-powered development agents and human developers to ensure consistency, accessibility, and performance across all your projects.
+
+## Installation
+
+```bash
+npm install agents-config --save-dev
+```
+
+After installation, run the interactive setup:
+
+```bash
+npx agents-init
+```
+
+This will:
+1. Detect your project's framework, styling, and database
+2. Ask which AI agents you use (Copilot, Claude, Cursor, Gemini, etc.)
+3. Generate adapter files that reference the shared guidelines
+4. Create a `.agents-project.json` for project-specific configuration
+
+### CLI Options
+
+```bash
+npx agents-init              # Interactive mode
+npx agents-init --dry-run    # Preview without writing files
+npx agents-init --force      # Overwrite existing files
+npx agents-init --help       # Show help
+```
+
+## Supported AI Agents
+
+| Agent | Config File | Notes |
+|-------|-------------|-------|
+| **GitHub Copilot** | `.github/copilot-instructions.md` | VS Code, JetBrains |
+| **Claude** | `CLAUDE.md` | Anthropic's Claude |
+| **Cursor** | `.cursorrules` | Cursor IDE |
+| **Gemini** | `.gemini/config.md` | Google Gemini |
+| **Codex** | `.codex/AGENTS.md` | OpenAI Codex |
+| **Windsurf** | `.windsurfrules` | Codeium Windsurf |
+
+## IDE-Specific Caveats
+
+### GitHub Copilot
+- Reads from `.github/copilot-instructions.md`
+- **Context limit**: Keep under 8KB for optimal performance
+- Works in VS Code, JetBrains IDEs, and Neovim
+
+### Claude (Anthropic)
+- Reads `CLAUDE.md` from project root
+- Supports rich markdown with tables and code blocks
+- Excellent for multi-step reasoning tasks
+
+### Cursor
+- Uses `.cursorrules` (no file extension, markdown format)
+- **Context limit**: Keep under 10KB
+- Uses Claude under the hood, same reasoning capabilities
+
+### Gemini (Google)
+- Configuration at `.gemini/config.md`
+- Handles long contexts well
+- Strong multimodal capabilities (can reference images)
+
+### Codex (OpenAI)
+- Reads from `.codex/AGENTS.md` directory
+- Works best with explicit, step-by-step instructions
+
+### Windsurf (Codeium)
+- Uses `.windsurfrules` in project root
+- Fast autocomplete, respects existing code style
+
+## Directory Structure
+
+### 📋 `AGENTS.md`
+Core guidelines for building React applications with AI-powered tools. Establishes the foundational principles and rules for development:
+- Accessibility & performance as first-class features
+- Component architecture patterns
+- TypeScript strict typing
+- State management strategies
+- Form handling and validation
+- Testing and documentation standards
+- Web standards compliance
+
+### 📂 `instructions/`
+Detailed operational guidelines for specific development tasks:
+
+- **`development-standards.instructions.md`** - General development standards and best practices
+- **`github-issue.instructions.md`** - Process for creating and managing GitHub issues
+- **`github-release-notes.instructions.md`** - Guidelines for writing release notes
+- **`mui.instructions.md`** - Material-UI (MUI v7+) specific patterns, theming, and dark mode implementation
+- **`storybook.instructions.md`** - Setting up and maintaining Storybook documentation
+- **`web-interface-guidelines.instructions.md`** - Accessibility and UX standards for web interfaces
+
+### 📂 `rules/`
+Deep-dive technical rules and patterns for specific technologies and approaches:
+
+- **`accessibility.md`** - Comprehensive accessibility guidelines and WCAG compliance
+- **`component-architecture.md`** - Folder-per-component pattern and structure
+- **`spec-driven-development.md`** - Creating technical specifications before implementation
+- **`react-19-compiler.md`** - React 19 compiler integration and optimization
+- **`gemini.md`** - Google Gemini AI integration rules, security constraints, and UX patterns
+- **`mui.md`** - Material-UI architecture patterns, constraints, and anti-patterns
+- **`supabase.md`** - Supabase backend integration patterns
+- **`tailwind-v4.md`** - Tailwind CSS v4 usage and configuration
+- **`three-js-react.md`** - Three.js integration with React
+- **`web-performance.md`** - Performance optimization strategies
+
+### 📂 `prompts/`
+Pre-written prompt templates for AI-powered code generation and assistance:
+
+- **`create-pr.prompt.md`** - Template for generating pull request descriptions
+- **`scaffold-component.prompt.md`** - Template for component scaffolding requests
+
+### 📂 `skills/`
+Reusable skill modules for common development tasks. Each skill includes specific guidance and workflows:
+
+#### **`accessibility-audit/`**
+Verify components meet accessibility standards before marking features as "Done". Includes checklist for:
+- Semantic HTML structure
+- Focus management and keyboard navigation
+- ARIA labels and form associations
+- Dynamic content handling
+
+#### **`scaffold-component/`**
+Create new React components following project constraints. Implements:
+- Spec-Driven Development workflow
+- Framework detection (Tailwind, MUI, Vanilla)
+- Component architecture patterns
+- Framework-specific rules and conventions
+
+#### **`integrate-gemini/`**
+Implement Google Gemini API integration with:
+- Secure API key handling
+- Streaming response patterns
+- Error handling and rate limiting
+- Loading and streaming UI states
+- Attribution and safety requirements
+
+#### **`vercel-react-best-practices/`**
+Performance optimization guidelines from Vercel Engineering. Covers 45+ rules across 8 categories:
+- Eliminating waterfalls (async patterns)
+- Bundle size optimization
+- Server-side performance
+- Client-side data fetching
+- Rendering optimization
+- Re-render prevention
+- Event handling and refs
+- JavaScript optimization
+
+Includes subdirectories:
+- **`rules/`** - Individual rule documents (45+ files organized by category)
+- **`workflows/`** - Task-specific workflows:
+  - `sdd-workflow.md` - Spec-driven development workflow
+  - `setup-orchestration.md` - Project setup orchestration
+
+## Key Principles
+
+1. **Accessibility First** - WCAG compliance and inclusive design are non-negotiable
+2. **Performance Matters** - Optimize for real-world conditions and user experience
+3. **Spec-Driven** - Create specifications before implementation
+4. **Component-Focused** - Folder-per-component architecture for maintainability
+5. **Type Safety** - Strict TypeScript throughout
+6. **Web Standards** - Follow semantic HTML and platform conventions
+
+## Usage
+
+### For AI Agents
+Reference the appropriate skill or rule based on the development task:
+- Use `accessibility-audit` before marking features complete
+- Use `scaffold-component` when creating new components
+- Use `integrate-gemini` for AI feature implementation
+- Reference `vercel-react-best-practices` for performance optimization
+
+### For Developers
+- Start with [AGENTS.md](AGENTS.md) for core principles
+- Reference relevant files in `rules/` and `instructions/` for specific guidance
+- Use `prompts/` as templates for consistent communication
+- Follow the workflows in `skills/` for common tasks
+
+## Integration
+
+This repository is designed to be used as:
+- A knowledge base for AI coding assistants (GitHub Copilot, Claude, etc.)
+- A reference guide for development teams
+- A configuration source for agent-based development workflows
+- A source of truth for coding standards and best practices
+
+## Project Configuration
+
+After running `npx agents-init`, a `.agents-project.json` file is created:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/ericthayer/agents-config/main/schemas/agents-project.schema.json",
+  "version": "1.0.0",
+  "project": {
+    "name": "my-app",
+    "framework": "next",
+    "styling": "tailwind",
+    "database": "supabase"
+  },
+  "agents": ["copilot", "claude", "cursor"],
+  "rules": {
+    "include": ["accessibility", "component-architecture", "tailwind-v4"],
+    "exclude": []
+  },
+  "overrides": {}
+}
+```
+
+### Customization
+
+Add project-specific overrides in the generated adapter files or in `.agents-project.json`:
+
+```json
+{
+  "overrides": {
+    "accessibility": {
+      "minContrastRatio": 7.0
+    },
+    "component-architecture": {
+      "maxComponentSize": 300
+    }
+  }
+}
+```
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/):
+
+- **Major** (1.0.0 → 2.0.0): Breaking changes to rules or agent configurations
+- **Minor** (1.0.0 → 1.1.0): New rules, skills, or agent support added
+- **Patch** (1.0.0 → 1.0.1): Bug fixes, typo corrections, clarifications
+
+## Contributing
+
+Contributions welcome! Please read the guidelines in [AGENTS.md](AGENTS.md) before submitting.
+
+## License
+
+MIT © Eric Thayer
+
+---
+
+**Last Updated:** January 31, 2025

package/adapters/claude.template.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+> Claude (Anthropic) configuration for **{{PROJECT_NAME}}**.
+> Generated by `agents-config` - https://www.npmjs.com/package/agents-config
+
+## Project Context
+
+| Aspect | Technology |
+|--------|------------|
+| Framework | {{FRAMEWORK}} |
+| Styling | {{STYLING}} |
+| Database | {{DATABASE}} |
+
+## Shared Guidelines Reference
+
+This project uses shared agentic configuration. The following rules apply:
+
+### Included Rules
+{{RULES_LIST}}
+
+### Available Skills (in .agents/skills/)
+
+For complex tasks, use these specialized skill workflows:
+
+- `.agents/skills/accessibility-audit/SKILL.md` - Comprehensive accessibility testing
+- `.agents/skills/scaffold-component/SKILL.md` - Component scaffolding with specs
+- `.agents/skills/integrate-gemini/SKILL.md` - AI integration patterns (if enabled)
+- `.agents/skills/vercel-react-best-practices/SKILL.md` - Performance patterns
+
+### Instructions (in .agents/instructions/)
+
+Process guidelines for specific workflows like MUI theming, Storybook, etc.
+
+## Agent Definitions
+
+### 🏗️ Component Scaffolding Agent
+**Trigger**: "scaffold component", "create component"
+**Workflow**: Generate spec → Create component → Add tests → Document in Storybook
+
+### 🔍 Accessibility Audit Agent
+**Trigger**: "audit accessibility", "check a11y"
+**Workflow**: Run automated checks → Manual review → Generate report
+
+### ⚡ Performance Optimization Agent
+**Trigger**: "optimize performance", "improve speed"
+**Workflow**: Analyze bundle → Check renders → Optimize
+
+## Project-Specific Context
+
+<!-- Add project-specific context below -->
+
+### Key Directories
+
+```
+.agents/                    # Project's agent configuration
+├── AGENTS.md               # Core guidelines
+├── rules/                  # Coding standards for this stack
+├── skills/                 # Specialized workflows
+└── instructions/           # Process guidelines
+```
+
+### Development Workflow
+
+1. **Spec-Driven Development** - Write specs before implementation
+2. **Test Coverage** - Maintain 80%+ coverage
+3. **Accessibility** - WCAG 2.2 AA compliance required
+
+## IDE-Specific Caveats
+
+> **Note**: Claude reads this file as `CLAUDE.md` in the project root.
+> For VS Code with Claude extension, ensure this file exists at the root level.
+
+### Claude-Specific Tips
+
+- Claude excels at multi-step reasoning - describe the full context
+- Use structured formats (tables, lists) for clarity
+- Reference specific files and line numbers when asking about code

package/adapters/codex.template.md

@@ -0,0 +1,72 @@
+# Codex Agents Configuration
+
+> OpenAI Codex configuration for **{{PROJECT_NAME}}**.
+> Generated by `agents-config` - https://www.npmjs.com/package/agents-config
+
+## Project Context
+
+- **Framework**: {{FRAMEWORK}}
+- **Styling**: {{STYLING}}
+- **Database**: {{DATABASE}}
+
+## Shared Guidelines
+
+This project follows shared agentic configuration:
+
+### Active Rules
+{{RULES_LIST}}
+
+### Available Skills (in .agents/skills/)
+
+- `.agents/skills/accessibility-audit/SKILL.md` - Accessibility compliance checking
+- `.agents/skills/scaffold-component/SKILL.md` - Component scaffolding workflow
+- `.agents/skills/integrate-gemini/SKILL.md` - AI integration patterns
+- `.agents/skills/vercel-react-best-practices/SKILL.md` - Performance optimization
+
+## Agent Configuration
+
+### Default Behavior
+
+- Follow TypeScript best practices
+- Generate accessible code by default
+- Include comprehensive error handling
+- Add inline documentation
+
+### Code Style
+
+- Use ESLint + Prettier configuration
+- Prefer named exports
+- Use async/await over .then() chains
+- Destructure props in function signatures
+
+### Testing Requirements
+
+- Write tests alongside implementation
+- Use React Testing Library patterns
+- Mock external dependencies
+- Test accessibility with jest-axe
+
+## File Organization
+
+```
+{{PROJECT_NAME}}/
+├── .codex/              # This configuration
+├── src/
+│   ├── components/      # UI components
+│   ├── features/        # Feature modules
+│   ├── hooks/           # Custom hooks
+│   └── lib/             # Utilities
+└── tests/               # Test files
+```
+
+## IDE-Specific Caveats
+
+> **Note**: Codex reads configuration from `.codex/AGENTS.md`.
+> Ensure this directory exists at the project root.
+
+### Codex-Specific Tips
+
+- Codex works well with explicit, step-by-step instructions
+- Include example code when requesting similar patterns
+- Specify language and framework versions explicitly
+- Use comments to guide code generation

package/adapters/copilot.template.md

@@ -0,0 +1,68 @@
+# GitHub Copilot Instructions
+
+> This file configures GitHub Copilot for **{{PROJECT_NAME}}**.
+> Generated by `agents-config` - https://www.npmjs.com/package/agents-config
+
+## Project Context
+
+- **Framework**: {{FRAMEWORK}}
+- **Styling**: {{STYLING}}
+- **Database**: {{DATABASE}}
+
+## Shared Guidelines
+
+This project follows shared agentic configuration guidelines. All rules, skills, and instructions are in the `.agents/` folder:
+
+### Core Rules
+{{RULES_LIST}}
+
+### Skills (in .agents/skills/)
+
+- **accessibility-audit/SKILL.md** - WCAG 2.2 AA compliance auditing
+- **scaffold-component/SKILL.md** - Component scaffolding with accessibility built-in
+- **integrate-gemini/SKILL.md** - AI feature integration patterns (if Gemini enabled)
+- **vercel-react-best-practices/SKILL.md** - Performance optimization patterns
+
+### Instructions (in .agents/instructions/)
+
+Process guidelines for development workflows.
+
+## Project-Specific Guidelines
+
+<!-- Add project-specific guidelines below -->
+
+### Architecture
+
+Follow component architecture patterns defined in the shared rules. Key principles:
+
+1. **Composition over inheritance** - Prefer composable components
+2. **Single responsibility** - Each component has one clear purpose
+3. **Accessibility first** - ARIA attributes and keyboard navigation built-in
+
+### Code Style
+
+- Use TypeScript for type safety
+- Follow React 19+ patterns (use hooks, avoid class components)
+- Prefer Server Components where appropriate
+
+### File Organization
+
+```
+src/
+├── components/     # Reusable UI components
+├── features/       # Feature-specific modules
+├── hooks/          # Custom React hooks
+├── lib/            # Utility functions
+└── types/          # TypeScript type definitions
+```
+
+## IDE-Specific Caveats
+
+> **Note**: GitHub Copilot reads this file from `.github/copilot-instructions.md`.
+> Keep this file focused and under 8KB for optimal context usage.
+
+### Copilot-Specific Tips
+
+- Copilot works best with clear, descriptive comments
+- Use JSDoc annotations for better suggestions
+- Keep files well-organized with clear naming conventions

package/adapters/cursor.template.md

@@ -0,0 +1,69 @@
+# Cursor Rules
+
+> Cursor configuration for **{{PROJECT_NAME}}**.
+> Generated by `agents-config` - https://www.npmjs.com/package/agents-config
+
+## Project Context
+
+- Framework: {{FRAMEWORK}}
+- Styling: {{STYLING}}
+- Database: {{DATABASE}}
+
+## Shared Guidelines
+
+This project follows shared agentic configuration rules:
+
+### Active Rules
+{{RULES_LIST}}
+
+### Skills (in .agents/skills/)
+
+- `.agents/skills/accessibility-audit/SKILL.md` - WCAG compliance checking
+- `.agents/skills/scaffold-component/SKILL.md` - Component generation
+- `.agents/skills/integrate-gemini/SKILL.md` - AI feature patterns
+- `.agents/skills/vercel-react-best-practices/SKILL.md` - Performance optimization
+
+## Code Generation Rules
+
+When generating code, follow these principles:
+
+### Component Structure
+
+- Export named components (not default exports)
+- Use TypeScript with explicit prop types
+- Include JSDoc comments for public APIs
+- Add data-testid attributes for testing
+
+### Accessibility Requirements
+
+- All interactive elements must be keyboard accessible
+- Provide aria-labels for icon-only buttons
+- Ensure color contrast meets WCAG 2.2 AA
+- Include focus indicators
+
+### Performance Considerations
+
+- Use React.memo() for expensive components
+- Lazy load routes and heavy components
+- Avoid inline object/function definitions in JSX
+
+## File Patterns
+
+When creating files:
+
+- Components: `PascalCase.tsx`
+- Hooks: `useCamelCase.ts`
+- Utils: `kebab-case.ts`
+- Tests: `*.test.ts` or `*.spec.ts`
+
+## IDE-Specific Caveats
+
+> **Note**: Cursor reads this file from `.cursorrules` in the project root.
+> This file uses Markdown format but has no file extension.
+
+### Cursor-Specific Tips
+
+- Cursor uses Claude under the hood - same reasoning capabilities
+- Use @-mentions to reference files in chat
+- Cursor's Composer works best with clear, scoped requests
+- Keep .cursorrules under 10KB for optimal performance

package/adapters/gemini.template.md

@@ -0,0 +1,73 @@
+# Gemini Configuration
+
+> Google Gemini configuration for **{{PROJECT_NAME}}**.
+> Generated by `agents-config` - https://www.npmjs.com/package/agents-config
+
+## Project Context
+
+| Setting | Value |
+|---------|-------|
+| Framework | {{FRAMEWORK}} |
+| Styling | {{STYLING}} |
+| Database | {{DATABASE}} |
+
+## Shared Guidelines
+
+This project uses shared agentic configuration:
+
+### Included Rules
+{{RULES_LIST}}
+
+### AI Integration (Gemini-Specific)
+
+When integrating Gemini features into this project, follow the patterns in:
+- `.agents/rules/gemini.md` - Gemini integration guidelines
+- `.agents/skills/integrate-gemini/SKILL.md` - Integration workflow
+
+## Code Generation Preferences
+
+### TypeScript Standards
+
+- Use strict TypeScript configuration
+- Prefer interfaces over type aliases for object shapes
+- Use discriminated unions for state management
+- Avoid `any` - use `unknown` with type guards
+
+### React Patterns
+
+- Functional components with hooks only
+- Server Components by default (Next.js)
+- Client Components marked with 'use client'
+- Suspense boundaries for async operations
+
+### Accessibility
+
+All generated code must include:
+- Semantic HTML elements
+- ARIA attributes where needed
+- Keyboard navigation support
+- Screen reader friendly content
+
+## Project Structure
+
+```
+src/
+├── app/            # Next.js app router
+├── components/     # Shared components
+├── features/       # Feature modules
+├── hooks/          # Custom hooks
+├── lib/            # Utilities
+└── types/          # Type definitions
+```
+
+## IDE-Specific Caveats
+
+> **Note**: Gemini in various IDEs may read configuration differently.
+> This file is placed at `.gemini/config.md` for compatibility.
+
+### Gemini-Specific Tips
+
+- Gemini excels at multimodal tasks - include images/screenshots when helpful
+- Use structured prompts with clear sections
+- Gemini handles long contexts well - include full file contents when needed
+- For code generation, specify the exact file path and format expected

package/adapters/windsurf.template.md

@@ -0,0 +1,81 @@
+# Windsurf Rules
+
+> Windsurf/Codeium configuration for **{{PROJECT_NAME}}**.
+> Generated by `agents-config` - https://www.npmjs.com/package/agents-config
+
+## Project Context
+
+| Aspect | Technology |
+|--------|------------|
+| Framework | {{FRAMEWORK}} |
+| Styling | {{STYLING}} |
+| Database | {{DATABASE}} |
+
+## Shared Guidelines
+
+This project uses shared agentic configuration:
+
+### Included Rules
+{{RULES_LIST}}
+
+### Specialized Skills (in .agents/skills/)
+
+- `.agents/skills/accessibility-audit/SKILL.md` - WCAG 2.2 AA compliance
+- `.agents/skills/scaffold-component/SKILL.md` - Component generation workflow
+- `.agents/skills/integrate-gemini/SKILL.md` - AI integration patterns
+- `.agents/skills/vercel-react-best-practices/SKILL.md` - Performance optimization
+
+## Code Generation Standards
+
+### Component Architecture
+
+1. Use functional components with TypeScript
+2. Define explicit prop interfaces
+3. Include default prop values where sensible
+4. Export named components
+
+### Accessibility (Required)
+
+All generated components must include:
+- Semantic HTML structure
+- ARIA labels for interactive elements
+- Keyboard navigation support
+- Focus management
+- Color contrast compliance
+
+### Performance
+
+- Memoize expensive computations
+- Lazy load non-critical components
+- Optimize re-renders with proper dependencies
+- Use appropriate loading states
+
+## Project Patterns
+
+### Naming Conventions
+
+- Components: `PascalCase`
+- Hooks: `useCamelCase`
+- Utils: `camelCase`
+- Constants: `SCREAMING_SNAKE_CASE`
+- Files: Match export name
+
+### Import Order
+
+1. React/framework imports
+2. Third-party libraries
+3. Internal absolute imports
+4. Relative imports
+5. Styles/assets
+
+## IDE-Specific Caveats
+
+> **Note**: Windsurf reads this file from `.windsurfrules` in the project root.
+> Keep the file size reasonable for optimal context usage.
+
+### Windsurf-Specific Tips
+
+- Windsurf (Codeium) provides fast autocomplete - write clear patterns
+- Use descriptive variable names for better suggestions
+- Include type annotations for improved accuracy
+- Windsurf respects existing code style - maintain consistency