AGENTS.md

@@ -0,0 +1,176 @@
+# Agent Guidelines
+
+This document provides guidelines for AI agents working in this repository.
+
+## Project Overview
+
+This is a minimal repository. When adding new projects, document their structure here.
+
+## Build / Lint / Test Commands
+
+Since the project currently has no build system, these are placeholder guidelines:
+
+```bash
+# Running a single test (example patterns - adjust per project)
+npm test -- --testPathPattern=filename
+pytest tests/test_file.py::TestClass::test_method
+cargo test test_name
+go test -run TestName ./...
+
+# Linting
+npm run lint
+eslint src/
+pylint src/
+golangci-lint run
+
+# Building
+npm run build
+npm run dev
+cargo build
+```
+
+## Code Style Guidelines
+
+### Imports
+
+- Use absolute imports over relative imports when possible
+- Group imports: standard library, third-party, local
+- Sort alphabetically within groups
+- Use explicit imports rather than wildcard imports
+
+### Formatting
+
+- Use 2 or 4 space indentation (match existing project style)
+- Maximum line length: 80-120 characters (per project)
+- Add trailing commas where appropriate
+- Use consistent line endings (LF or CRLF per project)
+
+### Types
+
+- Prefer explicit type annotations for function parameters and return types
+- Use interfaces/types for object shapes
+- Avoid `any` type - use `unknown` if type is truly unknown
+- Enable strict type checking where possible
+
+### Naming Conventions
+
+- **Files**: kebab-case or PascalCase (match project)
+- **Classes**: PascalCase (e.g., `UserService`)
+- **Functions/Variables**: camelCase (e.g., `getUserById`)
+- **Constants**: SCREAMING_SNAKE_CASE (e.g., `MAX_RETRIES`)
+- **Booleans**: Use `is`, `has`, `should` prefixes (e.g., `isActive`)
+
+### Error Handling
+
+- Use specific exception types rather than generic ones
+- Include meaningful error messages with context
+- Log errors with appropriate level (error, warning, debug)
+- Handle async errors with try/catch or .catch()
+- Never silently swallow errors unless explicitly intended
+
+### General Practices
+
+- Keep functions small and focused (single responsibility)
+- Write comments for "why", not "what"
+- Keep code DRY (Don't Repeat Yourself)
+- Use meaningful variable and function names
+- Write tests for new features
+- Follow the existing code style of the project
+
+## Testing Guidelines
+
+- Test file naming: `filename.test.ts` or `filename_spec.ts`
+- Use descriptive test names that explain the scenario
+- Follow AAA pattern: Arrange, Act, Assert
+- Mock external dependencies
+- Test both success and error paths
+- Aim for meaningful coverage, not just high percentage
+
+## Git Conventions
+
+- Write clear, concise commit messages
+- Use feature branches for new work
+- Keep commits atomic and focused
+- Run linters before committing
+- Review changes before pushing
+
+## Documentation
+
+- Update README.md for user-facing changes
+- Add code comments for complex logic
+- Document public APIs with docstrings/type hints
+- Keep documentation close to the code it describes
+
+## Cursor Rules
+
+No Cursor rules found in this repository.
+
+## Copilot Instructions
+
+No Copilot instructions found in this repository.
+
+## Working with This Repository
+
+When working in this repository:
+
+1. **Check existing structure** - Look at existing files and directories to understand the project layout before making changes
+2. **Understand the domain** - Read README.md and any existing documentation
+3. **Follow code style** - Match the existing code style in the project
+4. **Test changes** - Run appropriate tests when available
+5. **Commit responsibly** - Make meaningful commits with clear messages
+
+## Common Tasks
+
+### Running Development Server
+```bash
+# Check for available scripts
+cat package.json  # for Node projects
+cat Makefile      # for generic projects
+```
+
+### Adding Dependencies
+```bash
+npm install <package>  # Node projects
+pip install <package>  # Python projects
+cargo add <package>    # Rust projects
+```
+
+### Running Tests
+```bash
+# Identify test framework first
+npm test               # Node/Jest
+pytest                 # Python
+cargo test             # Rust
+```
+
+## Best Practices for AI Agents
+
+1. **Read first** - Always read existing files before editing
+2. **Verify changes** - Check that changes work as expected
+3. **Handle errors gracefully** - Provide meaningful error messages
+4. **Ask for clarification** - When requirements are unclear, ask the user
+5. **Be proactive** - Suggest improvements when obvious issues are found
+6. **Respect user intent** - Don't make changes beyond what was asked unless clearly beneficial
+
+## File Organization
+
+- Keep related files together
+- Use clear, descriptive file names
+- Follow framework conventions (e.g., components in /components, tests in /tests)
+- Maintain consistent directory structure across the project
+
+## Performance Considerations
+
+- Avoid unnecessary re-renders or computations
+- Use appropriate data structures for the task
+- Consider lazy loading for large modules
+- Optimize database queries and API calls
+- Profile before optimizing
+
+## Security Guidelines
+
+- Never commit secrets, API keys, or credentials
+- Use environment variables for sensitive configuration
+- Validate and sanitize all user inputs
+- Follow OWASP security practices
+- Keep dependencies updated for security patches