# AGENTS.md

Development guidelines for all agents and contributors working in this repository.

## Core Development Principles

1. **Do not repeat yourself (DRY)** - All development must avoid code duplication. Extract shared logic into reusable functions, modules, or components.
2. **Language best practices** - All development must follow the idiomatic style and best practices for the chosen language.
3. **Well-commented code** - All development must be clearly commented so that someone new to the project can understand the intent and flow of the code.

## Git Workflow

1. **Test before commit** - Changes must be tested locally before they are committed. Do not commit broken or untested code.
2. **No remote push without confirmation** - Changes are committed locally only. Nothing is pushed to the remote repository until explicitly confirmed by the user.
3. **Small atomic commits** - Keep commits focused. One logical change per commit. Do not bundle unrelated changes.
4. **Run the linter before committing** - Always run the project's linting and formatting checks before creating a commit. Fix any warnings or errors.
5. **Failing builds never merge** - No change that breaks the build, tests, or linting may be merged or pushed.

### Commit Messages

Use [Conventional Commits](https://www.conventionalcommits.org/) format:

```
feat: add user authentication
fix: resolve race condition in queue
refactor: extract validation logic
docs: update setup instructions
test: add unit tests for teleport fling
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. Optionally include a scope: `feat(auth): ...`.

## Testing

1. **Test-first development** - Write tests alongside new features. Test coverage should reflect the functionality being added or changed.
2. **Full suite before commit** - Run the complete test suite (not just incremental tests) before committing to ensure nothing is broken.

## Security

1. **Never commit secrets** - No API keys, passwords, tokens, connection strings, or credentials of any kind in code, config files, or git history. Use environment variables or secret management tools.
2. **Review `.gitignore`** - Ensure files containing potential secrets are excluded from version control.

## Documentation

1. **Keep docs in sync** - Update relevant documentation (README, comments, examples) alongside any behavioral change. Documentation that describes outdated behavior is a bug.