light_chat/AGENTS.md

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