Agents Files

AGENTS.md

@@ -0,0 +1,36 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is a small, script-first Python project. `bot.py` is the long-running Twitch IRC bot that controls MPD. `_twitch.py` holds shared Helix auth and token-refresh helpers for the CLI tools. `search-game.py` resolves free-form game queries to Twitch category IDs, and `set-channel.py` updates the channel title and game. `examples/stream.sh` is the interactive pre-stream wrapper that writes `examples/stream.json`. Keep secret-bearing runtime files in `.env` or `.env.broadcaster`; only the `*.example` templates are tracked.
+
+## Build, Test, and Development Commands
+
+There is no package build step. Use direct script execution:
+
+```bash
+pip install python-mpd2
+python3 bot.py
+TWITCH_BOT_DEBUG=1 python3 bot.py
+./search-game.py "DOOM"
+./set-channel.py --dry-run --game-id 517520 "Stream title"
+./examples/stream.sh
+```
+
+`python3 bot.py` runs the chat bot. `TWITCH_BOT_DEBUG=1` dumps raw IRC lines for troubleshooting. The two CLI helpers are intended to be run directly, and `stream.sh` composes them into a guided flow.
+
+## Coding Style & Naming Conventions
+
+Match the existing style: Python 3.10+, standard library first, minimal dependencies, and small top-level scripts instead of packages. Use 4-space indentation in Python and keep helpers simple and explicit. Follow the current naming pattern: `snake_case` for functions and variables, short module names for single-purpose scripts, and uppercase constants such as `SKIP_COOLDOWN`. Shell scripts should keep `set -euo pipefail`.
+
+## Testing Guidelines
+
+There is no automated test suite yet. Before opening a PR, do targeted smoke tests for the code path you changed. Examples: run `python3 bot.py` against a local MPD instance, run `./search-game.py "Heroes"`, or use `./set-channel.py --dry-run ...` to validate argument handling without issuing a PATCH. If you add tests later, place them under a new `tests/` directory and use `test_*.py`.
+
+## Commit & Pull Request Guidelines
+
+Git history is minimal; the current commit style is short and imperative (`Initial version`). Keep commits concise, scoped, and written in the imperative mood. PRs should explain the user-visible behavior change, note any `.env` or token-scope impact, and include terminal output or screenshots when changing interactive flows such as `examples/stream.sh`.
+
+## Security & Configuration Tips
+
+Do not merge `.env` and `.env.broadcaster`. The bot account and broadcaster account require different scopes and are intentionally separated. Never commit live tokens or generated `examples/stream.json`.