feat: enhance project structure and update dependencies

- Introduced .editorconfig for consistent coding styles across files.
- Updated pre-commit configuration to use ruff v0.14.8 and adjusted pytest command.
- Enhanced AGENTS.md with additional guidelines on comments and naming conventions.
- Refactored Makefile to streamline commands and updated the main application entry point.
- Upgraded dependencies in pyproject.toml, including pydantic and ty.
- Added initial application logic in src/templates_python and utility functions for settings management.
- Created tests for logging configuration and main application execution.

All changes aim to improve code quality, maintainability, and project usability.

Author: abpai

.codex/commands/summarize.md

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 2
+max_line_length = 88
+
+[*.{yml,yaml,toml,md}]
+indent_style = space
+indent_size = 2

.editorconfig

@@ -19,7 +19,7 @@ jobs:
           key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v5
         with:
           version: "latest"
 
@@ -34,6 +34,31 @@ jobs:
       - name: Run ruff format check
         run: uv run ruff format --check .
 
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run ty type checker
+        run: uv run ty check
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -50,7 +75,7 @@ jobs:
           key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v5
         with:
           version: "latest"
 
@@ -61,4 +86,4 @@ jobs:
         run: uv sync --extra dev
 
       - name: Run tests
-        run: uv run pytest --cov=main --cov=utils --cov-report=xml --cov-report=term-missing
+        run: uv run pytest --cov-report=xml

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ repos:
       - id: check-docstring-first
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.13.3
+    rev: v0.14.8
     hooks:
       - id: ruff
         args: [--fix]
@@ -22,7 +22,7 @@ repos:
     hooks:
       - id: pytest-check
         name: pytest-check
-        entry: bash -c "PYTHONPATH=. uv run pytest --co -q"
+        entry: bash -c "uv run pytest --co -q"
         language: system
         pass_filenames: false
         always_run: true

.pre-commit-config.yaml

@@ -15,12 +15,24 @@ This document provides coding guidelines for AI agents working on this Python pr
 **Format**: 2-space indentation, single quotes, 88-character lines, `snake_case` variables/functions, `PascalCase` classes, boolean flags prefixed with `is_/has_/should_`. Pre-commit hooks ensure code quality on commit.
 
 **Docstrings**:
+
 - Use simple one-line docstrings for most functions - be concise and descriptive
 - Type hints replace Args/Returns documentation - don't duplicate what's in the signature
 - No Examples section - type hints + function name should be self-explanatory
 - Exception: Top-level user-facing APIs may include brief usage notes if necessary
 - Rationale: Modern Python with PEP 484 type hints makes verbose docstrings redundant
 
+**Comments**:
+
+- Avoid narrating the code; prefer clear names and small functions
+- Comments should explain *why* (tradeoffs, invariants, pitfalls), not *what*
+- Delete commented-out code instead of keeping it around
+
+**Naming**:
+
+- Prefer domain-specific, intention-revealing names over generic ones (`process`, `handle`, `manager`, `util`)
+- Keep public API names stable and unsurprising; avoid cleverness
+
 ## Architecture Principles
 
 **Classes for state and lifecycle**, pure functions for transformations. Use classes when managing resources, coordinating operations, or defining interfaces.
@@ -32,6 +44,7 @@ This document provides coding guidelines for AI agents working on this Python pr
 **Factory functions**: Standalone functions (`get_backend()`, `resolve_config()`) that map configurations to implementations.
 
 **Resource management**:
+
 - Reference counting for expensive resources (connections, clients) with acquire/release semantics
 - Context managers (`__enter__`/`__exit__`) for automatic cleanup
 - Track ownership with boolean flags to avoid closing borrowed resources
@@ -44,7 +57,7 @@ This document provides coding guidelines for AI agents working on this Python pr
 
 **Performance**: Use `@dataclass(slots=True)` for frequently-instantiated objects and `TypeVar` for type-safe generic protocols.
 
-**Resilience**: Exponential backoff for network operations, graceful empty returns over exceptions, debug logging for key metrics.
+**Resilience**: Exponential backoff for network operations, graceful empty returns over exceptions, debug logging for key metrics. Keep error handling targeted (catch specific exceptions, add context, re-raise/convert).
 
 ## Best Practices
 
@@ -55,20 +68,22 @@ This document provides coding guidelines for AI agents working on this Python pr
 - Pipeline pattern: chain transformations with clear inputs/outputs
 - No excessive error handling or low-value comments
 
+## Code Quality Bar (What to Avoid)
+
+When generating code, optimize for reviewability and long-term maintainability.
+
+- **Unnecessary comments**: If a comment just restates the code, remove it and improve naming/structure instead
+- **Long docstrings**: Keep most docstrings to a single line; only expand when a public API truly needs usage notes
+- **Overly defensive code**: Don’t add “just in case” checks everywhere; validate at boundaries and trust validated data internally
+- **Broad `try/except`**: Avoid wrapping whole functions; don’t swallow exceptions; catch specific errors only to recover or add context
+- **Deep nesting**: Prefer guard clauses and extraction to keep indentation shallow (avoid multi-level `if/for/try`)
+- **Bad abstractions**: Don’t create classes/protocols/layers without clear value; avoid one-method wrappers and “framework-building”
+- **Vague naming**: Avoid generic verbs (`do`, `process`, `handle`) and generic buckets (`utils`, `helpers`) for core logic
+- **Weak typing / schemas**: Avoid `Any` and unstructured `dict[str, Any]` in core code; prefer Pydantic models (or narrow typed objects) with explicit fields and validation
+- **Noisy error handling**: Prefer a small number of well-placed domain exceptions over many `RuntimeError`/`ValueError` catch-alls
+
 ## Pydantic Commitment
 
 - All interface models use Pydantic `BaseModel` (not dataclasses)
 - Validation, `.model_dump()`, JSON serialization built-in
 - Reserve `@dataclass(slots=True)` only for inner performance-critical helpers (graph traversal caches, etc.)
-
-## 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

@@ -1,6 +1,4 @@
 .PHONY: help install install-dev setup pre-commit-install pre-commit-run lint format typecheck test clean lock-check run
-
-export PYTHONPATH := .
 VENV_DIR = .venv
 
 help:
@@ -37,14 +35,14 @@ format:
 	uv run ruff format .
 
 typecheck: ## Run ty type checker
-		uv run ty check
+	uv run ty check
 
 test: ## Run Pytest
 	uv run pytest
 
 clean: ## Remove caches & pyc files
 	find . -type f -name "*.pyc" -delete
-	find . -type d -name "pycache" -exec rm -rf {} +
+	find . -type d -name "__pycache__" -exec rm -rf {} +
 	find . -type d -name ".pytest_cache" -exec rm -rf {} +
 	find . -type d -name ".ruff_cache" -exec rm -rf {} +
 	rm -rf .pytest_cache .ruff_cache .mypy_cache .coverage
@@ -53,4 +51,4 @@ lock-check: ## Ensure uv.lock is up-to-date
 	uv sync --locked --extra dev
 
 run: ## Run the main application
-	uv run python src/main.py
+	uv run templates-python

Makefile

@@ -1,5 +1,9 @@
 # Python Boilerplate
 
+![CI](https://github.com/abpai/templates.python/actions/workflows/ci.yml/badge.svg)
+![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
 This template is a **lean starting point** for Python projects that use:
 
 - ✅ Ruff – formatting & linting
@@ -44,7 +48,7 @@ This template is a **lean starting point** for Python projects that use:
     make format && make lint && make test
     ```
 
-`src/main.py` is a minimal script with structured logging. Modify it to build your application.
+`src/templates_python/main.py` is a minimal entry point with structured logging. Modify it to build your application.
 
 ---
 
@@ -66,7 +70,7 @@ This template is a **lean starting point** for Python projects that use:
 
 ## Environment Variables
 
-`utils/settings.py` reads variables from a `.env` file or the environment.
+`src/templates_python/utils/settings.py` reads variables from a `.env` file or the environment.
 
 | Variable     | Default   | Description                         |
 | ------------ | --------- | ----------------------------------- |
@@ -83,15 +87,16 @@ Only what you need, nothing more:
 
 ```
 ├── src/
-│   └── main.py               # Main application entry point
-├── utils/
-│   └── settings.py           # Pydantic Settings helper
+│   └── templates_python/
+│       ├── main.py           # Main application entry point
+│       └── utils/
+│           └── settings.py   # Pydantic Settings helper
 ├── tests/
-│   └── test_basic.py         # Single sanity-check test
+│   └── test_settings.py      # Settings validation tests
 ├── Makefile                  # Workflow commands
 ├── pyproject.toml            # Project + dependency config
 ├── uv.lock                   # Locked dependency versions
-└── .github/workflows/        # CI (lint + test)
+└── .github/workflows/        # CI (lint + typecheck + test)
 ```
 
 ---
@@ -124,6 +129,27 @@ Configuration is in `pyproject.toml` under `[tool.ty]`.
 
 ---
 
+## Code Style
+
+This project uses **2-space indentation** and **single quotes** (configured in Ruff). While Python conventionally uses 4-space indentation, 2-space is a deliberate choice for more compact code. The formatter enforces this automatically.
+
+Key style settings:
+- Indent: 2 spaces
+- Quotes: Single (`'`)
+- Line length: 88 characters
+
+---
+
+## First Things To Edit
+
+When copying this template into a new project, update:
+
+- `[project] name`, `description`, `authors`, and `version` in `pyproject.toml`
+- The import package name under `src/` (rename `templates_python/` to your project slug)
+- The CLI entry in `[project.scripts]`
+
+---
+
 ## License
 
 MIT