feat: improve code agents DX

Author: abpai

.codex/commands/summarize.md

@@ -0,0 +1,80 @@
+### Codex Session Notes
+
+**Command**
+
+* Run: `!summarize [slug]`
+
+**Where to write**
+
+* Path: `./.codex/sessions/[slug]-[date].md`
+* `slug`: kebab-case from the session topic (ASCII, ≤40 chars, no spaces).
+* `date`: `YYYY-MM-DD` in UTC.
+
+**Update protocol (when `!summarize` is called)**
+
+1. If the file doesn’t exist, create it with the template below and fill all placeholders.
+2. Update `last_updated` to the current ISO timestamp.
+3. Refresh **TL;DR** (≤120 words) to reflect the latest state.
+4. Append a new entry to **Turn log** with: role, timestamp, what changed (bullets), key code refs/paths touched.
+5. Extend **Actions taken**, **Decisions & rationale**, **Open questions**, **Next actions** as needed (dedupe; prefer edits over repetition).
+6. Keep **Running summary** ≤ \~200 words; compress older detail into Turn log.
+7. Never paste long code; reference files/functions/lines instead.
+
+**Style rules**
+
+* Be concise, factual, and action-oriented. No fluff.
+* Prefer bullets over prose; present tense; avoid “I”.
+* Use explicit file paths (`repo/file.py:func`), commands in single quotes, and UTC timestamps `[YYYY-MM-DD HH:MM]`.
+* No PII, secrets, tokens, or full stack traces. Link or reference instead.
+* Idempotent edits: do not duplicate prior bullets; update in place.
+* Touch only files inside this repo; create directories if missing.
+
+---
+
+### Standard Template (fill all placeholders)
+
+```
+The most recent discussion I had with codex was the following. Please use these notes as informative context, so you can catch up and we can re-start the conversation accordingly.
+
+topic: <short topic>
+slug: <kebab-case-slug>
+date: <YYYY-MM-DD> (UTC)
+last_updated: <UTC ISO 8601>
+participants: [user, assistant]
+
+# TL;DR (≤120 words)
+- <single concise summary capturing goal, current state, next critical step>
+
+# User desires
+- <succinct bullets of outcomes the user wants>
+
+# Specifics of user desires (scope & constraints)
+- <key constraints, definitions of done, non-goals, acceptance criteria>
+
+# Actions taken (chronological)
+1. [YYYY-MM-DD HH:MM] <what was done / command / artifact produced>
+2. <next step> …
+
+# Decisions & rationale
+- [time] Decision: <decision>. Why: <brief reason/impact/tradeoffs>.
+
+# Helpful hints about conversation & relevant code paths
+- Path: <repo/path/file.py:func> — <why it matters>
+- Command: '<cli args>' — <purpose>
+- Link: <url> — <what it answers>
+
+# Open questions / risks
+- <unknown or risk> → <owner/next step to resolve>
+
+# Next actions (checklist)
+- [ ] <next concrete task> (owner, expected outcome)
+- [ ] …
+
+# Turn log (append-only)
+- [YYYY-MM-DD HH:MM] role=assistant — <what changed in this turn; bullets>
+- [YYYY-MM-DD HH:MM] role=user — <key asks/clarifications>
+
+# With this context in mind, I have a follow up query:
+<one crisp question or instruction that advances the work>
+```
+---

.codex/sessions/.gitkeep

@@ -2,25 +2,17 @@
 alwaysApply: true
 ---
 
-## 1. Environment and Dependencies
+## Environment and Dependencies
 - **Tooling**: Use `uv` for all package management.
 
-## 2. Code Style and Formatting
-- **Indentation**: Strictly use 2 spaces for indentation.
-- **Quotes**: Use single quotes (`'`) for all strings. Use double quotes (`"`) only when a string contains a single quote.
-- **Naming Conventions**:
-  - `snake_case` for all variables, functions, methods, files, and directories.
-  - `PascalCase` for all class names (e.g., `Pydantic` models, custom exceptions).
-- **Boolean Variables**: Name boolean variables with an auxiliary verb prefix (e.g., `is_active`, `has_permission`, `should_send_email`).
+## Code Style
 
-## 3. Programming Paradigm and Structure
-- **Functional Approach**: Prefer pure, standalone functions. Avoid classes unless necessary.
-- **Class Usage Exceptions**: Use classes only for:
-  - Data structures (Pydantic models).
-  - Framework requirements (e.g., Django models, FastAPI routers).
-  - Custom exception types.
-- **Modularity (DRY)**: Do not repeat code. Refactor any duplicated logic into reusable functions. Group related utility functions into separate modules (e.g., `utils/data_processing.py`).
+**Format**: 2-space indent, single quotes, `snake_case` vars/functions, `PascalCase` classes, `is_/has_/should_` booleans
 
-## 4. API and Function Design
-- **RORO Pattern**: All service-layer functions and API endpoint handlers must follow the "Receive an Object, Return an Object" pattern.
-- **Data Contracts**: Use Pydantic models to define the "objects" for RORO. The input object should be a single Pydantic model, and the return value should be a single Pydantic model (or `None`).
+**Architecture**:
+- Pure functions preferred; classes for stateful operations (3+ shared params), data structures, framework requirements
+- RORO pattern: service functions receive/return single Pydantic objects
+- Single responsibility: break 150+ line functions into focused 15-25 line methods, early returns, no magic values, explicit dependencies
+- DRY principle: extract utility functions to eliminate code duplication when applicable
+- Pipeline pattern: chain transformations with clear inputs/outputs
+- No excessive error handling or low-value comments

.cursor/rules/general.mdc

@@ -1,24 +1,28 @@
 # General Rules
 
-## 1. Environment and Dependencies
+## Environment and Dependencies
 - **Tooling**: Use `uv` for all package management.
 
-## 2. Code Style and Formatting
-- **Indentation**: Strictly use 2 spaces for indentation.
-- **Quotes**: Use single quotes (`'`) for all strings. Use double quotes (`"`) only when a string contains a single quote.
-- **Naming Conventions**:
-  - `snake_case` for all variables, functions, methods, files, and directories.
-  - `PascalCase` for all class names (e.g., `Pydantic` models, custom exceptions).
-- **Boolean Variables**: Name boolean variables with an auxiliary verb prefix (e.g., `is_active`, `has_permission`, `should_send_email`).
-
-## 3. Programming Paradigm and Structure
-- **Functional Approach**: Prefer pure, standalone functions. Avoid classes unless necessary.
-- **Class Usage Exceptions**: Use classes only for:
-  - Data structures (Pydantic models).
-  - Framework requirements (e.g., Django models, FastAPI routers).
-  - Custom exception types.
-- **Modularity (DRY)**: Do not repeat code. Refactor any duplicated logic into reusable functions. Group related utility functions into separate modules (e.g., `utils/data_processing.py`).
-
-## 4. API and Function Design
-- **RORO Pattern**: All service-layer functions and API endpoint handlers must follow the "Receive an Object, Return an Object" pattern.
-- **Data Contracts**: Use Pydantic models to define the "objects" for RORO. The input object should be a single Pydantic model, and the return value should be a single Pydantic model (or `None`).
+## Code Style
+
+**Format**: 2-space indent, single quotes, `snake_case` vars/functions, `PascalCase` classes, `is_/has_/should_` booleans
+
+**Architecture**:
+- Pure functions preferred; classes for stateful operations (3+ shared params), data structures, framework requirements
+- RORO pattern: service functions receive/return single Pydantic objects
+- Single responsibility: break 150+ line functions into focused 15-25 line methods, early returns, no magic values, explicit dependencies
+- DRY principle: extract utility functions to eliminate code duplication when applicable
+- Pipeline pattern: chain transformations with clear inputs/outputs
+- No excessive error handling or low-value comments
+
+## Codex Commands
+
+Conventions:
+- Any user message that **starts with** `!` is a command.
+- Be non-verbose. For commands, print a single status line (or a short block) on success/failure.
+- Use UTC timestamps. Touch only files inside this repo.
+- If a directory you need doesn’t exist, create it.
+
+Commands:
+
+- `!summarize [slug]`: Read `.codex/commands/summarize.md` for command instructions.

AGENTS.md

@@ -21,7 +21,7 @@ dependencies = [
 dev = [
     "ipykernel>=6.30.1",
     "pre-commit>=4.2.0",
-    "pyright>=1.1.404",
+    "pyright>=1.1.405",
     "pytest>=8.4.1",
     "pytest-cov>=6.2.1",
     "ruff>=0.12.11",