new-module

# New Module: `$ARGUMENTS` Follow this checklist to create a new hardware-isolated module. Use TDD (`/tdd`) for each step that involves code. ## Checklist ### 0. Enter a worktree Before any file edits, make sure the session is in a git worktree. Check `git worktree list` — reuse an existing one via `EnterWorktree(path=...)` if it matches this task, otherwise create a new one via `EnterWorktree(name=...)`. Scaffolding touches `tests/`, `src/logger/`, `main.py`, and often `web.py` and `storage.py` — exactly the kind of multi-file change that collides with other agents sharing the repo. See CLAUDE.md for the full rule. ### 1. Write tests first Create `tests/test_$ARGUMENTS.py` with tests for the module's public API. Use the `storage` fixture from `conftest.py` and mock any external I/O. ### 2. Create the module Create `src/logger/$ARGUMENTS.py`: - Single-purpose, under ~200 lines - All external I/O (HTTP, serial, USB, etc.) isolated in this module - Use dataclasses for structured data - Use `loguru` for logging (never `print()`) - Full type annotations on all functions ### 3. Schema migration (if needed) If the module needs database tables: - Bump `_CURRENT_VERSION` in `storage.py` - Add migration SQL to `_MIGRATIONS` dict - Add async storage methods (CRUD) - Test with the in-memory `storage` fixture ### 4. Web routes (if needed) If the module needs API endpoints or admin UI: - Add to `web.py` following existing patterns - Admin pages: require `require_auth("admin")` - Add nav link in `_nav_html()` - Add web route tests in `test_web.py` ### 5. Wire into main.py - Import the module **only in `main.py`** (hardware isolation principle) - Parse config from env vars - Pass to `_web_loop()` / `create_app()` if needed - Add CLI subcommand if applicable ### 6. Sync dependencies If the module requires new packages: - Add with `uv add <package>` (never edit pyproject.toml manually for deps) - Run `uv sync` and verify the import works - Never use `uv pip install` — it bypasses the lockfile and won't persist ### 7. Update config - Add new env vars to `.env.example` with comments - Update `CLAUDE.md` project structure tree ### 8. Run `/pr-checklist`