From 0d4c49a6d385674ad315b9d576f5de2391ce02d8 Mon Sep 17 00:00:00 2001
From: Christian Colglazier <christian@cacolglazier.com>
Date: Sun, 8 Feb 2026 16:10:56 -0500
Subject: [PATCH] feat(ai): initial agents file

---
 AGENTS.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8dffa41
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,143 @@
+# AGENTS.md - Coding Guidelines for Agentic Operations
+
+This repository is a personal dotfiles collection managed with [chezmoi](https://www.chezmoi.io). It contains configuration files, shell scripts, and Python utilities for system management.
+
+## Build, Lint & Test Commands
+
+### Running Scripts
+- **Shell scripts**: `bash ./home/bin/executable_<script_name>.sh` or run directly if executable
+- **Python scripts**: `python3 ./home/bin/<script_name>.py`
+- **Install dependencies**: `pip install -r requirements.txt`
+
+### Testing
+No formal test framework is present. Validation is done by:
+- Running scripts manually with test inputs
+- Checking for runtime errors (e.g., `python3 -m py_compile <file>` for syntax)
+- Verifying command outputs match expected behavior
+
+### Single Test/Script Execution
+```bash
+# Run a single Python script
+python3 ./home/bin/i3-mouse.py
+
+# Run a single shell script
+bash ./home/bin/executable_update.sh
+
+# Check Python syntax without running
+python3 -m py_compile ./home/bin/homeassistant.py
+```
+
+## Code Style Guidelines
+
+### Python
+
+#### Imports
+- Use standard library imports first, then third-party imports, then local imports
+- Import order: `os`, `sys`, `time` → `requests`, `i3ipc`, `pyautogui` → local modules
+- Each import on its own line (avoid `import x, y, z`)
+- Example:
+  ```python
+  #!/usr/bin/env python3
+  import os
+  import sys
+  import datetime
+  from requests import get, post
+  import json
+  ```
+
+#### Naming Conventions
+- **Functions**: `snake_case` (e.g., `getPoints()`, `pointsToDirection()`)
+- **Classes**: `PascalCase` (e.g., `HomeAssistant`, `Direction`)
+- **Constants**: `UPPER_SNAKE_CASE`
+- **Private members**: prefix with underscore `_privateVar`
+- Enums use `PascalCase` for class and `UPPER_SNAKE_CASE` for members
+
+#### Formatting
+- Use 4-space indentation (not tabs)
+- Line length: Keep to reasonable length (~80-100 chars) where practical
+- Shebang for executable scripts: `#!/usr/bin/env python3`
+- Blank lines: 2 between top-level definitions, 1 between method definitions
+
+#### Types & Documentation
+- No type hints required (not present in codebase)
+- Add docstring comments for classes and non-obvious functions
+- Comment format: `# description` (no colons at end unless explaining)
+- Example: `# Enum for mouse direction`
+
+#### Error Handling
+- Use `raise` for exceptions in API wrappers (e.g., `response.raise_for_status()`)
+- Return `None` for optional/conditional operations
+- Handle command availability checks: `if command -v <cmd> &> /dev/null`
+
+### Shell Scripts
+
+#### Shebang & Headers
+- Start with: `#!/bin/bash`
+- Add brief comment: `# Script purpose description`
+
+#### Formatting
+- Use 2-space indentation
+- Quote variables: `"${variable}"` or `"$variable"`
+- Use `function name { ... }` syntax for functions
+
+#### Naming & Structure
+- Function names: `snake_case`
+- Variables: lowercase with underscores for clarity
+- Check for command availability before use:
+  ```bash
+  if command -v <cmd> &> /dev/null; then
+      <cmd> <args>
+  fi
+  ```
+
+#### Error Handling
+- Use `set -e` to exit on error when appropriate
+- Check command exit status: `if <command>; then ... fi`
+- Redirect stderr appropriately: `2>/dev/null` or `2>&1`
+
+### Configuration Files
+
+#### chezmoi Templates
+- Dotfiles use chezmoi's templating system
+- Template syntax: `{{ }}` for variables (Chezmoi specific)
+- File naming: `dot_` prefix for dotfiles (e.g., `dot_zshrc`)
+- Executable scripts: `executable_` prefix
+
+#### Comments
+- Use `#` for all config file comments
+- Keep comments concise and descriptive
+
+## Repository Patterns
+
+### Commit Message Format
+Follow conventional commits style:
+- `feat(scope): description` - New feature
+- `fix(scope): description` - Bug fix
+- `refactor(scope): description` - Code refactoring
+- `docs(scope): description` - Documentation changes
+- Example: `feat(zsh): update dotfiles` or `fix(scripts): use correct pass entry`
+
+### File Organization
+- Shell scripts: `home/bin/executable_<name>.sh`
+- Python scripts: `home/bin/<name>.py`
+- Config files: `home/dot_config/<app>/` (following XDG spec)
+- Dependencies: List in `requirements.txt`
+
+## Key Dependencies
+
+- **configparser** - Config file parsing
+- **todoist-python** - Todoist API
+- **tbapy** - TBA API for robotics
+- **holidays** - Holiday detection
+- **i3ipc** - i3 window manager control
+- **pyautogui** - Mouse control
+- **requests** - HTTP library
+- **dateutil** - Date utilities
+
+## Development Notes
+
+- This is a personal configuration repository, not a library
+- Scripts are system-level utilities and automation scripts
+- No CI/CD pipeline present (manual validation)
+- Target OS: Linux (Ubuntu/Fedora compatible)
+- Python version: Python 3.x minimum