# Agent Guidelines for Light Chat

This document outlines the rules and principles for AI agents (or developers) working on the light_chat codebase.

## Core Principles

1. **Simplicity** - Keep the codebase simple and easy to understand
2. **Modularity** - Separate concerns; each module has a single responsibility
3. **Reusability** - Abstract common functionality for multiple use cases
4. **Test Coverage** - All functions and components must have unit tests

## Git Practices

### Commit Standards
- Write clear, descriptive commit messages (imperative mood: "Add feature" not "Added feature")
- Use conventional commits format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
- Make atomic commits - each commit should represent a single logical change
- Reference issue numbers in commit messages when applicable

### Branch Strategy
- Use `main` as the stable branch
- Create feature branches: `feature/description` or `feat/description`
- Use bugfix branches: `fix/description`
- Delete branches after merging to keep repository clean

### Pull Requests
- Keep PRs small and focused
- Include a clear description of changes and rationale
- Ensure all tests pass before requesting review
- Request code review for all changes (unless trivial)
- Address review feedback promptly

### Before Committing
- Run tests locally to verify functionality
- Check for unnecessary files (node_modules, build artifacts, env files)
- Verify no secrets or sensitive data are committed
- Rebase/squash commits if needed for clean history

### Code History
- Avoid force pushes to shared branches
- Regularly pull latest changes from main to avoid conflicts
- Use `git status` to verify what you're committing

## Coding Standards

### Function Design
- Before creating a new function, check if a similar one exists that can be extended
- Abstract shared logic into utility functions
- Keep functions focused on a single task

### Component Architecture
- Components should be small and composable
- Separate UI from business logic
- Use custom hooks for shared stateful logic

### Testing Requirements
- Every new component needs test coverage
- Mock external dependencies (API calls, storage, etc.)
- Test both success and error cases
- Use descriptive test names

## API Communication Pattern

The LLM API integration should be minimal:
- Simple GET/POST requests
- Extract "content" from responses
- Handle errors gracefully
- Allow custom endpoint configuration

## State Management

- Use React hooks (useState, useContext) for simplicity
- Session data should be persistable
- Maintain connection state (connected/disconnected)

## File Structure

```
src/
  components/     # Reusable UI components
  hooks/          # Custom React hooks
  utils/          # Utility functions and API clients
  services/       # Business logic and API services
  stores/         # State management (if needed)
  tests/          # Unit tests
```

## Workflow for New Features

1. Identify existing similar functionality
2. Abstract common patterns if applicable
3. Implement with test-driven development
4. Write tests first, then code
5. Keep it simple - avoid over-engineering