# XAGI AI Agent Development Guide

## Overview
This template is optimized for AI-powered development with support for Claude, Cursor, and other AI coding assistants.

## AI Agent Configuration

### Supported AI Agents
- **Claude Code** - Full integration with automated workflows
- **Cursor** - AI-powered IDE integration
- **GitHub Copilot** - Code completion and suggestions
- **Windsurf** - Advanced AI coding assistant

### Key Features for AI Development

#### 1. Smart Component Generation
- Complete Radix UI component library (27 components)
- React Hook Form + Zod integration
- Tailwind CSS styling system
- Consistent TypeScript typing
- Accessibility-first design
- Responsive design patterns

#### 2. Automated Testing
- Vitest testing framework
- React Testing Library integration
- Coverage reporting
- Accessibility testing

#### 3. Code Quality Assurance
- ESLint + Prettier configuration
- TypeScript strict mode
- Automated linting and formatting
- Performance optimization

## Development Workflow

### For AI Agents
1. **Component Generation**: Use `src/components/ui/` patterns
2. **Form Development**: Use React Hook Form + Zod patterns
3. **Page Creation**: Follow App Router structure in `src/app/`
4. **API Integration**: Use `src/lib/api.ts` for HTTP client
5. **State Management**: Implement TanStack Query patterns

### For Human Developers
1. **Setup**: `pnpm install`
2. **Development**: `pnpm dev`
3. **Testing**: `pnpm test`
4. **Build**: `pnpm build`

## Project Structure

```
src/
├── app/                 # Next.js App Router
├── components/          # React components
│   ├── ui/             # Radix UI components
│   └── common/         # Common components
├── lib/                # Utilities and helpers
└── hooks/              # Custom React hooks
```

## AI-Specific Guidelines

### Component Patterns
- Use class-variance-authority for styling variants
- Implement proper TypeScript interfaces
- Include accessibility attributes
- Follow semantic HTML structure

### API Integration
- Use Axios HTTP client with interceptors
- Implement proper error handling
- Use TypeScript interfaces for API responses
- Implement loading states

### State Management
- Use TanStack Query for server state
- React Hook Form + Zod for form state
- Local state with React hooks
- Context for global state

## Best Practices

1. **Type Safety**: Strict TypeScript configuration
2. **Performance**: Code splitting and lazy loading
3. **Accessibility**: WCAG 2.1 AA compliance
4. **Testing**: Comprehensive test coverage
5. **Documentation**: JSDoc comments and type definitions

## AI Prompts

### Component Generation Prompt
```
Create a [component type] component using Radix UI and Tailwind CSS. Follow the existing patterns in src/components/ui/. Include proper TypeScript types, accessibility attributes, and responsive design.
```

### Page Creation Prompt
```
Create a Next.js page using App Router. Include proper layout, metadata, and follow the existing patterns in src/app/. Use the UI components from src/components/ui/.
```

## Troubleshooting

### Common Issues
1. **TypeScript Errors**: Check types in `src/lib/`
2. **Styling Issues**: Verify Tailwind CSS configuration
3. **Build Errors**: Run `pnpm clean` before building
4. **Test Failures**: Check test configuration in `vitest.config.ts`

### AI Agent Compatibility
This template is designed to work seamlessly with major AI coding assistants and provides optimal patterns for AI-generated code.

## Form Development

### React Hook Form + Zod Integration
This template includes a complete form solution using React Hook Form for state management and Zod for schema validation.

#### Form Components
- **Form**: Main form wrapper with React Hook Form context
- **FormField**: Field wrapper with validation
- **FormItem**: Container for form elements
- **FormLabel**: Accessible form labels
- **FormControl**: Input control wrapper
- **FormDescription**: Help text for form fields
- **FormMessage**: Error message display

#### Form Development Patterns
```typescript
// Define Zod schema
const formSchema = z.object({
  email: z.string().email("Invalid email address"),
  password: z.string().min(8, "Password must be at least 8 characters"),
})

// Use form components
<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      control={form.control}
      name="email"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Email</FormLabel>
          <FormControl>
            <Input {...field} />
          </FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
  </form>
</Form>
```

### Form Best Practices
- Use Zod schemas for validation
- Implement proper error handling
- Integrate with Radix UI components
- Follow accessibility guidelines
- Use TypeScript for type safety

## Available Components

### Complete Radix UI Component Library (27 Components)

#### Layout & Navigation
- **Accordion**: Collapsible content sections
- **Collapsible**: Show/hide content areas
- **Navigation Menu**: Complex navigation structures
- **Menubar**: Application menu bars
- **Tabs**: Tabbed content organization
- **Separator**: Visual content dividers

#### Data Display
- **Avatar**: User profile images
- **Card**: Content containers
- **Progress**: Progress indicators
- **Scroll Area**: Custom scrollable areas
- **Aspect Ratio**: Maintain aspect ratios

#### Form Controls
- **Button**: Interactive buttons with variants
- **Checkbox**: Boolean input controls
- **Input**: Text input fields
- **Label**: Form field labels
- **Radio Group**: Single-choice selections
- **Select**: Dropdown selections
- **Slider**: Range input controls
- **Switch**: Toggle controls
- **Textarea**: Multi-line text input
- **Toggle**: Toggle buttons
- **Toggle Group**: Grouped toggle buttons

#### Overlays & Dialogs
- **Alert Dialog**: Confirmation dialogs
- **Dialog**: Modal dialogs
- **Dropdown Menu**: Context menus
- **Popover**: Floating content panels
- **Tooltip**: Hover information

#### Form System
- **Form**: Complete form management
- **FormField**: Field wrapper with validation
- **FormItem**: Form element container
- **FormLabel**: Accessible form labels
- **FormControl**: Input control wrapper
- **FormDescription**: Help text
- **FormMessage**: Error messages

### Component Features
- **TypeScript Support**: Full type definitions
- **Accessibility**: WCAG 2.1 AA compliant
- **Responsive Design**: Mobile-first approach
- **Customizable**: Tailwind CSS styling
- **Consistent API**: Unified component patterns