agentic-team-templates 0.12.1 → 0.13.2

package/templates/python-expert/.cursorrules/tooling.md

@@ -0,0 +1,240 @@
+# Python Tooling
+
+Modern Python tooling is fast, integrated, and opinionated. Use it all.
+
+## Project Configuration
+
+### pyproject.toml (Single Source of Truth)
+
+```toml
+[project]
+name = "mypackage"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.110",
+    "pydantic>=2.0",
+    "sqlalchemy>=2.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "pre-commit>=3.7",
+]
+
+[project.scripts]
+myapp = "mypackage.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+## uv (Package Manager)
+
+```bash
+# uv is the modern Python package manager — fast, reliable, replaces pip/pip-tools/venv
+uv venv                     # Create virtual environment
+uv pip install -e ".[dev]"  # Install with dev dependencies
+uv pip compile pyproject.toml -o requirements.lock  # Lock dependencies
+uv run pytest               # Run in the project's environment
+uv tool install ruff        # Install CLI tools globally
+```
+
+## Ruff (Linter + Formatter)
+
+```toml
+# pyproject.toml
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "TCH",  # flake8-type-checking
+    "RUF",  # ruff-specific rules
+    "S",    # flake8-bandit (security)
+    "DTZ",  # flake8-datetimez
+    "PT",   # flake8-pytest-style
+    "ERA",  # eradicate (commented-out code)
+    "ARG",  # flake8-unused-arguments
+    "PTH",  # flake8-use-pathlib
+    "PERF", # perflint
+]
+ignore = [
+    "E501",   # line length handled by formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]  # Allow assert in tests
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+```
+
+```bash
+ruff check .              # Lint
+ruff check --fix .        # Lint with auto-fix
+ruff format .             # Format
+ruff format --check .     # Check formatting
+```
+
+## mypy
+
+```toml
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+```
+
+```bash
+mypy .                    # Type check everything
+mypy --strict .           # Strictest mode
+```
+
+## pytest
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = [
+    "-ra",              # Show summary of all non-passing tests
+    "--strict-markers",  # Undefined markers are errors
+    "--strict-config",   # Warn about unknown config options
+    "-x",               # Stop on first failure during development
+]
+markers = [
+    "integration: marks integration tests",
+    "slow: marks slow tests",
+]
+```
+
+```bash
+pytest                           # Run all tests
+pytest tests/unit/               # Run subset
+pytest -k "test_create"          # Run by name pattern
+pytest --cov=mypackage --cov-report=html  # Coverage
+pytest -m "not integration"      # Skip integration tests
+```
+
+## Coverage
+
+```toml
+[tool.coverage.run]
+source = ["src/mypackage"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.",
+    "@overload",
+    "raise NotImplementedError",
+]
+```
+
+## Pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests]
+```
+
+## Makefile
+
+```makefile
+.PHONY: check test lint format typecheck
+
+check: format lint typecheck test
+
+format:
+	ruff format .
+
+lint:
+	ruff check .
+
+typecheck:
+	mypy .
+
+test:
+	pytest --cov=src/mypackage --cov-report=term-missing
+
+test-all:
+	pytest -m "" --cov=src/mypackage
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -rf .pytest_cache .mypy_cache .ruff_cache dist build *.egg-info
+```
+
+## CI/CD
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv venv && uv pip install -e ".[dev]"
+      - run: ruff format --check .
+      - run: ruff check .
+      - run: mypy .
+      - run: pytest --cov --cov-report=xml
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install pip-audit
+      - run: pip-audit .
+```
+
+## Dependency Hygiene
+
+- **Pin for applications**: exact versions in lock file
+- **Range for libraries**: `>=1.0,<2.0` in pyproject.toml
+- **Audit regularly**: `pip-audit` for security advisories
+- **Minimize dependencies**: every dep is attack surface and maintenance burden
+- **Prefer stdlib**: `pathlib` over `os.path`, `dataclasses` over attrs (for simple cases), `tomllib` over `toml`

package/templates/python-expert/.cursorrules/type-system.md

@@ -0,0 +1,203 @@
+# Python Type System
+
+Modern Python is typed Python. Type hints enable tooling, prevent bugs, and serve as living documentation. `mypy --strict` is the baseline.
+
+## Core Typing
+
+### Function Signatures
+
+```python
+from collections.abc import Sequence, Mapping, Callable, Awaitable, Iterator
+from typing import Any, TypeVar, overload
+
+# All parameters and return types annotated
+def process_items(
+    items: Sequence[Item],
+    *,
+    transform: Callable[[Item], Result],
+    max_retries: int = 3,
+) -> list[Result]:
+    ...
+
+# Use None return type explicitly
+def log_event(event: Event) -> None:
+    logger.info("event", extra={"event": event})
+
+# Async functions
+async def fetch_user(user_id: str) -> User | None:
+    ...
+```
+
+### Modern Syntax (3.10+)
+
+```python
+# Union types with |
+def parse(value: str | int) -> Data:
+    ...
+
+# Optional is just T | None
+def find_user(email: str) -> User | None:
+    ...
+
+# Built-in generics — no need to import List, Dict, etc.
+names: list[str] = []
+config: dict[str, Any] = {}
+coordinates: tuple[float, float] = (0.0, 0.0)
+```
+
+### TypeVar and Generics
+
+```python
+from typing import TypeVar, Generic
+
+T = TypeVar("T")
+
+# Generic container
+class Stack(Generic[T]):
+    def __init__(self) -> None:
+        self._items: list[T] = []
+
+    def push(self, item: T) -> None:
+        self._items.append(item)
+
+    def pop(self) -> T:
+        if not self._items:
+            raise IndexError("pop from empty stack")
+        return self._items.pop()
+
+# Bounded TypeVar
+from typing import SupportsFloat
+N = TypeVar("N", bound=SupportsFloat)
+
+def average(values: Sequence[N]) -> float:
+    return sum(float(v) for v in values) / len(values)
+
+# Python 3.12+ syntax
+def first[T](items: Sequence[T]) -> T:
+    return items[0]
+
+class Stack[T]:
+    ...
+```
+
+### Protocol (Structural Subtyping)
+
+```python
+from typing import Protocol, runtime_checkable
+
+# Define what you need, not what you depend on
+class Renderable(Protocol):
+    def render(self) -> str: ...
+
+class HTMLWidget:
+    def render(self) -> str:
+        return "<div>widget</div>"
+
+# HTMLWidget satisfies Renderable without inheriting from it
+def display(item: Renderable) -> None:
+    print(item.render())
+
+display(HTMLWidget())  # Works — structural match
+
+# runtime_checkable for isinstance() checks
+@runtime_checkable
+class Closeable(Protocol):
+    def close(self) -> None: ...
+
+if isinstance(resource, Closeable):
+    resource.close()
+```
+
+### TypedDict
+
+```python
+from typing import TypedDict, Required, NotRequired
+
+class UserDict(TypedDict):
+    id: str
+    email: str
+    name: Required[str]
+    bio: NotRequired[str]
+
+# Useful for JSON responses, config dicts, and legacy code
+# Prefer dataclasses/Pydantic for new code
+```
+
+### Literal and Final
+
+```python
+from typing import Literal, Final
+
+# Restrict to specific values
+def set_log_level(level: Literal["debug", "info", "warn", "error"]) -> None:
+    ...
+
+# Constants that shouldn't be reassigned
+MAX_RETRIES: Final = 3
+API_VERSION: Final[str] = "v2"
+```
+
+### Overloads
+
+```python
+from typing import overload
+
+@overload
+def get(key: str, default: None = None) -> str | None: ...
+@overload
+def get(key: str, default: str) -> str: ...
+
+def get(key: str, default: str | None = None) -> str | None:
+    value = store.get(key)
+    return value if value is not None else default
+```
+
+## mypy Configuration
+
+```toml
+# pyproject.toml
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+# Per-module overrides for third-party libs without stubs
+[[tool.mypy.overrides]]
+module = "some_untyped_lib.*"
+ignore_missing_imports = true
+```
+
+## Anti-Patterns
+
+```python
+# Never: Any as a crutch
+def process(data: Any) -> Any:  # This is just untyped Python with extra steps
+    ...
+
+# Never: type: ignore without explanation
+result = sketchy_call()  # type: ignore
+# Better:
+result = sketchy_call()  # type: ignore[no-untyped-call]  # library lacks stubs
+
+# Never: Mutable default in typed signatures
+def append_to(item: str, target: list[str] = []) -> list[str]:  # BUG
+    ...
+# Fix:
+def append_to(item: str, target: list[str] | None = None) -> list[str]:
+    if target is None:
+        target = []
+    target.append(item)
+    return target
+
+# Never: cast() to lie to the type checker
+from typing import cast
+user = cast(User, random_dict)  # This doesn't validate anything at runtime
+# Use Pydantic or manual validation instead
+```

package/templates/python-expert/.cursorrules/web-and-apis.md

@@ -0,0 +1,231 @@
+# Python Web and APIs
+
+Patterns for building production-grade web services and APIs in Python.
+
+## FastAPI
+
+### Application Structure
+
+```python
+from fastapi import FastAPI, Depends, HTTPException, status
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    app.state.db = await create_pool(settings.database_url)
+    yield
+    # Shutdown
+    await app.state.db.close()
+
+app = FastAPI(
+    title="My Service",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+```
+
+### Dependency Injection
+
+```python
+from fastapi import Depends
+from typing import Annotated
+
+async def get_db(request: Request) -> AsyncGenerator[Database, None]:
+    async with request.app.state.db.acquire() as conn:
+        yield Database(conn)
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: Annotated[Database, Depends(get_db)],
+) -> User:
+    user = await db.get_user_by_token(token)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return user
+
+# Type alias for common dependencies
+CurrentUser = Annotated[User, Depends(get_current_user)]
+DB = Annotated[Database, Depends(get_db)]
+
+@app.get("/users/me")
+async def get_me(user: CurrentUser) -> UserResponse:
+    return UserResponse.model_validate(user)
+```
+
+### Request/Response Models
+
+```python
+from pydantic import BaseModel, Field, EmailStr, ConfigDict
+
+class CreateUserRequest(BaseModel):
+    model_config = ConfigDict(strict=True)
+
+    name: str = Field(min_length=1, max_length=200)
+    email: EmailStr
+    role: Literal["admin", "user"] = "user"
+
+class UserResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    name: str
+    email: str
+    created_at: datetime
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    per_page: int
+```
+
+### Error Handling
+
+```python
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+class AppError(Exception):
+    def __init__(self, message: str, status_code: int = 500) -> None:
+        self.message = message
+        self.status_code = status_code
+
+class NotFoundError(AppError):
+    def __init__(self, entity: str, id: str) -> None:
+        super().__init__(f"{entity} not found: {id}", status_code=404)
+
+class ValidationError(AppError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status_code=400)
+
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.message},
+    )
+```
+
+### Middleware
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+import time
+
+class TimingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        start = time.monotonic()
+        response = await call_next(request)
+        duration = time.monotonic() - start
+        response.headers["X-Process-Time"] = f"{duration:.4f}"
+        return response
+
+app.add_middleware(TimingMiddleware)
+```
+
+## Django Patterns
+
+### Fat Models, Thin Views
+
+```python
+# Business logic lives in models and services, not views
+class Order(models.Model):
+    status = models.CharField(max_length=20)
+    total = models.DecimalField(max_digits=10, decimal_places=2)
+
+    def can_cancel(self) -> bool:
+        return self.status in ("pending", "confirmed")
+
+    def cancel(self) -> None:
+        if not self.can_cancel():
+            raise ValueError(f"Cannot cancel order in {self.status} state")
+        self.status = "cancelled"
+        self.save()
+
+# Views are thin — delegate to models/services
+class OrderCancelView(View):
+    def post(self, request, order_id):
+        order = get_object_or_404(Order, id=order_id)
+        try:
+            order.cancel()
+        except ValueError as e:
+            return JsonResponse({"error": str(e)}, status=400)
+        return JsonResponse({"status": "cancelled"})
+```
+
+### QuerySet Optimization
+
+```python
+# Select only needed fields
+users = User.objects.only("id", "name", "email")
+
+# Prefetch related objects to avoid N+1 queries
+orders = Order.objects.select_related("user").prefetch_related("items")
+
+# Use exists() instead of count() for boolean checks
+if Order.objects.filter(user=user, status="pending").exists():
+    ...
+
+# Use iterator() for large querysets
+for user in User.objects.all().iterator(chunk_size=1000):
+    process(user)
+```
+
+## Configuration
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    model_config = ConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    database_url: str
+    redis_url: str = "redis://localhost:6379"
+    debug: bool = False
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    allowed_origins: list[str] = ["http://localhost:3000"]
+
+# Validate at import time — fail fast
+settings = Settings()
+```
+
+## Observability
+
+```python
+import structlog
+
+# Structured logging
+logger = structlog.get_logger()
+
+logger.info(
+    "request_completed",
+    method=request.method,
+    path=request.url.path,
+    status=response.status_code,
+    duration_ms=round(duration * 1000, 2),
+    request_id=request.state.request_id,
+)
+
+# Never log sensitive data (passwords, tokens, PII)
+# Never log at ERROR for expected conditions (404, validation failures)
+```
+
+## Anti-Patterns
+
+```python
+# Never: Business logic in views/routes
+@app.post("/orders")
+async def create_order(data: OrderInput, db: DB) -> OrderResponse:
+    # Don't put 50 lines of business logic here
+    # Delegate to a service
+    return await order_service.create(data)
+
+# Never: Raw SQL without parameterization
+cursor.execute(f"SELECT * FROM users WHERE id = '{user_id}'")  # SQL INJECTION
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))  # Safe
+
+# Never: Synchronous HTTP calls in async handlers
+response = requests.get(url)  # Blocks the event loop
+response = await httpx_client.get(url)  # Non-blocking
+```