From 8abc63efdbc0bb96cd6c9aa99d6e9166e0bcabae Mon Sep 17 00:00:00 2001
From: Peter Stone <thepeterstone@gmail.com>
Date: Sun, 22 Mar 2026 23:45:19 +0000
Subject: chore: unify and centralize agent configuration in .agent/

---
 .agent/coding_standards.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 .agent/coding_standards.md

(limited to '.agent/coding_standards.md')

diff --git a/.agent/coding_standards.md b/.agent/coding_standards.md
new file mode 100644
index 0000000..50281d0
--- /dev/null
+++ b/.agent/coding_standards.md
@@ -0,0 +1,70 @@
+# Coding Standards
+
+This document defines the technical standards for the **Doot** project. Adherence to these standards ensures consistency, security, and maintainability.
+
+## 1. Go (Backend)
+
+### Idiomatic Go
+- Follow standard Go idioms (Effective Go).
+- Keep functions small and focused on a single responsibility.
+- Use meaningful, descriptive names for variables, functions, and types.
+
+### Concurrency
+- Use `sync.WaitGroup` and `sync.Mutex` for managing concurrent operations.
+- For parallel API fetching, use a semaphore pattern (e.g., buffered channel) to limit concurrency and avoid rate limits.
+- **Example:** See `internal/api/trello.go` for the 5-request concurrency limit.
+
+### Error Handling
+- Use the "Partial Data / Cache Fallback" pattern: If an API call fails, return cached data (if available) or an empty set with an error logged, rather than failing the entire request.
+- Use structured logging or the `data.Errors` slice in handlers to report non-fatal errors to the UI.
+
+### Database (SQLite)
+- **SQL Injection Prevention:** ALWAYS use parameterized queries (`?` placeholders).
+- **Concurrency:** Enable WAL mode and set `MaxOpenConns(1)` to avoid "database is locked" errors.
+- **Migrations:** All schema changes must be added as a new file in the `migrations/` directory.
+
+### Project Structure
+- `cmd/dashboard/`: Application entry point.
+- `internal/api/`: External service clients (Todoist, Trello, etc.).
+- `internal/auth/`: Authentication logic and middleware.
+- `internal/config/`: Configuration loading and validation.
+- `internal/handlers/`: HTTP request handlers and UI logic.
+- `internal/models/`: Shared data structures.
+- `internal/store/`: Database operations.
+
+## 2. Frontend (HTMX + Tailwind CSS)
+
+### HTMX
+- Use HTMX for all state-changing operations (Create, Update, Delete) and tab switching.
+- **Response Headers:** Use `HX-Trigger` and `HX-Reswap` to coordinate UI updates.
+- **Partial Rendering:** Handlers should return HTML partials (from `web/templates/partials/`) for HTMX requests.
+
+### CSS & Styling
+- Use **Tailwind CSS** for all styling.
+- Maintain a consistent mobile-first responsive design.
+- Follow the Z-index hierarchy defined in `design.md`.
+
+### User Feedback
+- Provide immediate visual feedback for user actions (loading indicators, success/error banners).
+- Ensure all forms clear their inputs upon successful submission.
+
+## 3. Testing Philosophy
+
+### Reproduction First
+- Before fixing a bug, implement a failing test case that reproduces the issue.
+- Verify the fix by ensuring the new test (and all existing tests) passes.
+
+### Coverage Areas
+- **Store:** Unit tests for all SQL operations (`sqlite_test.go`).
+- **Handlers:** Integration tests for critical paths (`handlers_test.go`, `agent_test.go`).
+- **API Clients:** Use mocks or test servers for external API testing (`todoist_test.go`, `trello_test.go`).
+
+## 4. Documentation & Git
+
+### Commit Messages
+- Propose clear, concise messages that explain the "why" behind the change.
+- Match existing style (usually imperative mood).
+
+### File Header
+- Maintain the standardized `SESSION_STATE.md` (now `worklog.md`) format.
+- Document significant architectural changes in `docs/adr/`.
-- 
cgit v1.2.3