From 23bd31b2338a7a20589529bebe1a8994da5c5bf8 Mon Sep 17 00:00:00 2001
From: Daniel Wagner <dw@danieljw.net>
Date: Sun, 26 Jul 2026 12:56:11 +1000
Subject: [PATCH] docs: add comprehensive setup and testing guide for agents

- Add Initial Setup section with uv installation and venv creation steps
- Include pre-commit hook setup with clear explanation of automation
- Update Code Style section to mention pre-commit auto-fixing
- Update Running Tests Locally with venv activation and linting commands
- Add note clarifying pre-commit integration in CI/CD workflow

This ensures new developers/agents know how to:
1. Install dependencies properly with uv
2. Set up pre-commit for automatic linting and testing
3. Run tests and linting commands manually when needed
---
 AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f79b117..d04e541 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,6 +52,32 @@ steward/
 
 ## Development Workflow
 
+### Initial Setup
+
+1. **Install uv** (faster Python package manager):
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.local/bin/env  # Add to PATH
+```
+
+2. **Create virtual environment and install dependencies**:
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+3. **Set up pre-commit hooks** (runs ruff + tests on commit):
+```bash
+pre-commit install
+```
+
+From now on, `git commit` will automatically:
+- Run `ruff check` and `ruff format` (with auto-fix)
+- Run `pytest` to ensure tests pass
+
+You can skip hooks with `git commit --no-verify` if needed.
+
 ### Before Making Changes
 
 1. **Understand the Context**
@@ -69,6 +95,7 @@ steward/
    - Line length: 100 characters
    - Use type hints throughout (mypy strict mode)
    - Import order: standard lib → third party → local
+   - Pre-commit will auto-fix most linting issues
 
 ### Making Changes
 
@@ -192,9 +219,11 @@ class Settings(BaseModel):
 
 ### Running Tests Locally
 
+After setting up your venv (see Initial Setup), you can run tests:
+
 ```bash
-# Install dev dependencies
-pip install -e ".[dev]"
+# Activate venv if not already activated
+source .venv/bin/activate
 
 # Run all tests
 pytest tests/ -v
@@ -207,8 +236,17 @@ pytest tests/test_bot.py::test_mytest -v
 
 # Run with coverage
 pytest tests/ --cov=steward --cov-report=html
+
+# Run linting only (pre-commit does this automatically)
+ruff check steward/ tests/
+
+# Auto-fix linting issues
+ruff check steward/ tests/ --fix
+ruff format steward/ tests/
 ```
 
+Note: Pre-commit will run these checks automatically on commit, so you usually don't need to run them manually unless you want to check before committing.
+
 ### Debugging Issues
 
 **Bot not responding:**