agentic-team-templates 0.12.1 → 0.13.1

package/templates/python-expert/.cursorrules/patterns-and-idioms.md

@@ -0,0 +1,251 @@
+# Python Patterns and Idioms
+
+Idiomatic Python leverages the language's strengths — duck typing, protocols, generators, decorators, and the data model. Write Pythonic code, not Java-in-Python.
+
+## Data Model (Dunder Methods)
+
+```python
+from functools import total_ordering
+
+@total_ordering
+@dataclass(frozen=True, slots=True)
+class Money:
+    amount: Decimal
+    currency: str
+
+    def __add__(self, other: Money) -> Money:
+        if self.currency != other.currency:
+            raise ValueError(f"Cannot add {self.currency} and {other.currency}")
+        return Money(self.amount + other.amount, self.currency)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Money):
+            return NotImplemented
+        return self.amount == other.amount and self.currency == other.currency
+
+    def __lt__(self, other: Money) -> bool:
+        if self.currency != other.currency:
+            raise ValueError(f"Cannot compare {self.currency} and {other.currency}")
+        return self.amount < other.amount
+
+    def __str__(self) -> str:
+        return f"{self.currency} {self.amount:.2f}"
+
+    def __repr__(self) -> str:
+        return f"Money(amount={self.amount!r}, currency={self.currency!r})"
+
+    def __bool__(self) -> bool:
+        return self.amount != 0
+```
+
+## Generators and Iterators
+
+```python
+from collections.abc import Iterator, Generator
+
+# Generators for lazy evaluation — process one item at a time
+def read_large_file(path: Path) -> Iterator[str]:
+    with open(path) as f:
+        for line in f:
+            yield line.strip()
+
+# Generator expressions over list comprehensions when you iterate once
+total = sum(order.total for order in orders)  # No intermediate list
+
+# Generator pipelines
+def pipeline(path: Path) -> Iterator[Record]:
+    lines = read_large_file(path)
+    parsed = (parse_record(line) for line in lines)
+    valid = (record for record in parsed if record.is_valid())
+    yield from valid
+
+# itertools for complex iteration
+from itertools import chain, islice, groupby, batched
+
+# Process in batches (3.12+)
+for batch in batched(items, 100):
+    process_batch(batch)
+
+# Chain multiple iterables
+for item in chain(list_a, list_b, list_c):
+    process(item)
+```
+
+## Decorators
+
+```python
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# Properly typed decorator that preserves signatures
+def retry(max_attempts: int = 3, delay: float = 1.0):
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            last_error: Exception | None = None
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    last_error = e
+                    if attempt < max_attempts - 1:
+                        time.sleep(delay * (2 ** attempt))
+            raise last_error  # type: ignore[misc]
+        return wrapper
+    return decorator
+
+@retry(max_attempts=3, delay=0.5)
+def call_api(url: str) -> Response:
+    ...
+
+# Class-based decorator for complex state
+class CachedProperty:
+    """Descriptor that caches the result of a method call."""
+    def __init__(self, func: Callable[..., Any]) -> None:
+        self.func = func
+        self.attrname: str | None = None
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.attrname = name
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> Any:
+        if obj is None:
+            return self
+        assert self.attrname is not None
+        cache = obj.__dict__
+        if self.attrname not in cache:
+            cache[self.attrname] = self.func(obj)
+        return cache[self.attrname]
+
+# Or just use functools.cached_property — it's built in
+```
+
+## Context Managers
+
+```python
+from contextlib import contextmanager, asynccontextmanager
+
+# Synchronous context manager
+@contextmanager
+def timed_operation(name: str) -> Iterator[None]:
+    start = time.monotonic()
+    try:
+        yield
+    finally:
+        elapsed = time.monotonic() - start
+        logger.info(f"{name} took {elapsed:.3f}s")
+
+with timed_operation("database query"):
+    results = db.execute(query)
+
+# Async context manager
+@asynccontextmanager
+async def managed_connection(url: str) -> AsyncIterator[Connection]:
+    conn = await connect(url)
+    try:
+        yield conn
+    finally:
+        await conn.close()
+
+# contextlib.suppress for intentionally ignored exceptions
+from contextlib import suppress
+
+with suppress(FileNotFoundError):
+    os.remove(temp_file)
+
+# ExitStack for dynamic resource management
+from contextlib import ExitStack
+
+with ExitStack() as stack:
+    files = [stack.enter_context(open(f)) for f in file_paths]
+    process_all(files)
+```
+
+## Descriptors
+
+```python
+# Descriptors power properties, classmethods, staticmethods
+class Validated:
+    """Descriptor that validates on assignment."""
+    def __init__(self, validator: Callable[[Any], bool], message: str) -> None:
+        self.validator = validator
+        self.message = message
+        self.attr_name = ""
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.attr_name = name
+
+    def __set__(self, obj: Any, value: Any) -> None:
+        if not self.validator(value):
+            raise ValueError(f"{self.attr_name}: {self.message}")
+        obj.__dict__[self.attr_name] = value
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> Any:
+        if obj is None:
+            return self
+        return obj.__dict__.get(self.attr_name)
+
+class User:
+    name = Validated(lambda v: isinstance(v, str) and len(v) > 0, "must be non-empty string")
+    age = Validated(lambda v: isinstance(v, int) and 0 <= v <= 150, "must be 0-150")
+```
+
+## collections Module
+
+```python
+from collections import defaultdict, Counter, deque, OrderedDict
+
+# defaultdict — avoid KeyError boilerplate
+word_counts: defaultdict[str, int] = defaultdict(int)
+for word in words:
+    word_counts[word] += 1
+
+# Counter — counting and most common
+counter = Counter(words)
+top_10 = counter.most_common(10)
+
+# deque — O(1) append/pop from both ends
+recent: deque[Event] = deque(maxlen=100)
+recent.append(event)  # Oldest auto-evicted when full
+
+# Named tuples for lightweight immutable records (prefer dataclasses for new code)
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    x: float
+    y: float
+```
+
+## Anti-Patterns
+
+```python
+# Never: Mutable default arguments
+def append(item, target=[]):  # Shared across all calls!
+    target.append(item)
+    return target
+
+# Never: Bare except
+try:
+    risky()
+except:  # Catches KeyboardInterrupt, SystemExit — everything
+    pass
+
+# Never: String formatting with % or .format() for f-string-eligible code
+name = "world"
+greeting = f"hello, {name}"  # Not "hello, %s" % name
+
+# Never: Using type() for type checks
+if type(x) == int:  # Fails for subclasses
+    ...
+if isinstance(x, int):  # Correct
+    ...
+
+# Never: Global mutable state
+_cache = {}  # Module-level mutable dict — test nightmare
+
+# Never: Star imports
+from os.path import *  # Pollutes namespace, hides origins
+```

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

@@ -0,0 +1,208 @@
+# Python Performance
+
+Python is not the fastest language. It doesn't need to be. Know where the bottlenecks are, profile before optimizing, and reach for the right tool when raw speed matters.
+
+## Profile First
+
+```python
+# cProfile for function-level profiling
+import cProfile
+cProfile.run("main()", sort="cumulative")
+
+# line_profiler for line-by-line analysis
+# @profile decorator (after pip install line-profiler)
+# kernprof -l -v script.py
+
+# memory_profiler for memory usage
+# @profile decorator (after pip install memory-profiler)
+# python -m memory_profiler script.py
+
+# py-spy for production profiling without code changes
+# py-spy record -o profile.svg -- python myapp.py
+
+# timeit for micro-benchmarks
+import timeit
+timeit.timeit("sorted(data)", globals={"data": list(range(1000))}, number=10000)
+```
+
+## Data Structures
+
+```python
+# Choose the right data structure for the access pattern
+
+# dict — O(1) lookup, insertion, deletion
+# Use when: key-value mapping with frequent lookups
+cache: dict[str, Result] = {}
+
+# set — O(1) membership testing
+# Use when: uniqueness checks, set operations
+seen: set[str] = set()
+if item_id not in seen:
+    process(item)
+    seen.add(item_id)
+
+# deque — O(1) append/pop from both ends
+# Use when: queue, sliding window, bounded history
+from collections import deque
+recent_events: deque[Event] = deque(maxlen=1000)
+
+# heapq — O(log n) push/pop for priority queue
+# Use when: top-N, scheduling, priority processing
+import heapq
+top_10 = heapq.nlargest(10, items, key=lambda x: x.score)
+
+# bisect — O(log n) search in sorted lists
+# Use when: maintaining sorted order with insertions
+import bisect
+bisect.insort(sorted_list, new_item)
+```
+
+## Avoiding Common Bottlenecks
+
+```python
+# String concatenation — use join, not +=
+# Bad: O(n²) — creates new string each iteration
+result = ""
+for chunk in chunks:
+    result += chunk
+
+# Good: O(n)
+result = "".join(chunks)
+
+# List comprehensions over loops for simple transforms
+# Good: Faster due to C-level optimization
+squares = [x * x for x in range(1000)]
+
+# Generator expressions when you don't need the full list
+total = sum(x * x for x in range(1_000_000))  # No intermediate list
+
+# dict.get() over try/except for missing keys (in tight loops)
+value = mapping.get(key, default)
+
+# Local variable lookup is faster than global/attribute
+# In hot loops, alias frequently accessed attributes
+append = result.append  # Local lookup in loop body
+for item in items:
+    append(transform(item))
+```
+
+## Concurrency Models
+
+```python
+# I/O-bound: asyncio or threading
+# CPU-bound: multiprocessing or native extensions
+
+# Threading for I/O parallelism (GIL is released during I/O)
+from concurrent.futures import ThreadPoolExecutor
+
+with ThreadPoolExecutor(max_workers=10) as executor:
+    results = list(executor.map(fetch_url, urls))
+
+# Multiprocessing for CPU parallelism (bypasses GIL)
+from concurrent.futures import ProcessPoolExecutor
+
+with ProcessPoolExecutor() as executor:
+    results = list(executor.map(cpu_intensive_work, data_chunks))
+
+# asyncio for high-concurrency I/O (thousands of connections)
+# See async-python.md for patterns
+```
+
+## Caching
+
+```python
+from functools import lru_cache, cache
+
+# lru_cache for expensive pure function calls
+@lru_cache(maxsize=256)
+def fibonacci(n: int) -> int:
+    if n < 2:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+# cache (3.9+) — unlimited cache, simpler API
+@cache
+def load_schema(name: str) -> Schema:
+    return Schema.from_file(f"schemas/{name}.json")
+
+# Manual caching with TTL
+from time import monotonic
+
+class TTLCache:
+    def __init__(self, ttl: float) -> None:
+        self._cache: dict[str, tuple[float, Any]] = {}
+        self._ttl = ttl
+
+    def get(self, key: str) -> Any | None:
+        if key in self._cache:
+            expiry, value = self._cache[key]
+            if monotonic() < expiry:
+                return value
+            del self._cache[key]
+        return None
+
+    def set(self, key: str, value: Any) -> None:
+        self._cache[key] = (monotonic() + self._ttl, value)
+```
+
+## Slots and Memory
+
+```python
+# __slots__ reduces memory per instance and speeds up attribute access
+@dataclass(slots=True)
+class Point:
+    x: float
+    y: float
+
+# Without slots: ~200 bytes per instance (dict overhead)
+# With slots: ~56 bytes per instance
+# Matters when you have millions of instances
+
+# sys.getsizeof for memory inspection
+import sys
+sys.getsizeof(my_object)
+
+# tracemalloc for tracking allocations
+import tracemalloc
+tracemalloc.start()
+# ... run code ...
+snapshot = tracemalloc.take_snapshot()
+for stat in snapshot.statistics("lineno")[:10]:
+    print(stat)
+```
+
+## When Python Isn't Fast Enough
+
+```python
+# 1. NumPy/Pandas for vectorized numeric operations
+import numpy as np
+result = np.sum(array * weights)  # C-level loop, orders of magnitude faster
+
+# 2. Polars for DataFrames (faster than Pandas, Rust backend)
+import polars as pl
+df.filter(pl.col("age") > 30).group_by("city").agg(pl.col("salary").mean())
+
+# 3. Cython or mypyc for compiling Python to C
+# 4. PyO3/maturin for writing critical paths in Rust
+# 5. ctypes/cffi for calling existing C libraries
+```
+
+## Anti-Patterns
+
+```python
+# Never: Premature optimization
+# Profile first. The bottleneck is almost never where you think.
+
+# Never: Optimizing readability away
+# A 10% speedup that makes code unmaintainable is a net loss.
+
+# Never: Global imports of large modules in hot paths
+def process():
+    import pandas as pd  # Import overhead on every call
+# Import at module level instead
+
+# Never: Creating regex objects in loops
+for line in lines:
+    match = re.search(r"pattern", line)  # Recompiles every iteration
+# Compile once: pattern = re.compile(r"pattern")
+```

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

@@ -0,0 +1,238 @@
+# Python Testing
+
+pytest is the standard. Tests are not optional. Every behavior has a test. Every bug fix starts with a failing test.
+
+## Fundamentals
+
+### Test Structure
+
+```python
+# Arrange-Act-Assert
+def test_user_creation() -> None:
+    # Arrange
+    repo = FakeUserRepo()
+    service = UserService(repo)
+    input_data = CreateUserInput(name="Alice", email="alice@example.com")
+
+    # Act
+    user = service.create(input_data)
+
+    # Assert
+    assert user.name == "Alice"
+    assert user.email == "alice@example.com"
+    assert user.id is not None
+```
+
+### Naming
+
+```python
+# Test names describe the scenario and expected outcome
+def test_create_user_with_valid_input_returns_user() -> None: ...
+def test_create_user_with_duplicate_email_raises_conflict() -> None: ...
+def test_create_user_with_empty_name_raises_validation_error() -> None: ...
+
+# Not:
+def test_create() -> None: ...  # Create what? What scenario?
+def test_1() -> None: ...       # Meaningless
+```
+
+## Fixtures
+
+```python
+import pytest
+
+@pytest.fixture
+def user_repo() -> FakeUserRepo:
+    return FakeUserRepo()
+
+@pytest.fixture
+def user_service(user_repo: FakeUserRepo) -> UserService:
+    return UserService(user_repo)
+
+@pytest.fixture
+def sample_user() -> User:
+    return User(id="123", name="Alice", email="alice@example.com")
+
+# Fixtures with cleanup
+@pytest.fixture
+def temp_db():
+    db = create_test_database()
+    yield db
+    db.drop()
+
+# Session-scoped fixtures for expensive setup
+@pytest.fixture(scope="session")
+def docker_postgres():
+    container = start_postgres_container()
+    yield container.connection_string
+    container.stop()
+```
+
+## Parametrize
+
+```python
+@pytest.mark.parametrize(
+    "input_str, expected",
+    [
+        ("hello world", "hello-world"),
+        ("  spaces  ", "spaces"),
+        ("UPPER CASE", "upper-case"),
+        ("special!@#chars", "specialchars"),
+        ("already-slugified", "already-slugified"),
+        ("", ""),
+    ],
+)
+def test_slugify(input_str: str, expected: str) -> None:
+    assert slugify(input_str) == expected
+
+# Parametrize with IDs for clear test output
+@pytest.mark.parametrize(
+    "status_code, expected_error",
+    [
+        pytest.param(400, ValidationError, id="bad-request"),
+        pytest.param(404, NotFoundError, id="not-found"),
+        pytest.param(500, ServerError, id="server-error"),
+    ],
+)
+def test_error_mapping(status_code: int, expected_error: type[Exception]) -> None:
+    with pytest.raises(expected_error):
+        handle_response(MockResponse(status_code))
+```
+
+## Testing Exceptions
+
+```python
+def test_division_by_zero_raises_value_error() -> None:
+    with pytest.raises(ValueError, match="divisor must be non-zero"):
+        divide(10, 0)
+
+def test_missing_config_key_raises_key_error() -> None:
+    config = Config({})
+    with pytest.raises(KeyError) as exc_info:
+        config.get_required("missing_key")
+    assert "missing_key" in str(exc_info.value)
+```
+
+## Mocking
+
+```python
+from unittest.mock import Mock, AsyncMock, patch, MagicMock
+
+# Prefer dependency injection over patching
+# Good: Inject the dependency
+class UserService:
+    def __init__(self, repo: UserRepository, notifier: Notifier) -> None:
+        self.repo = repo
+        self.notifier = notifier
+
+def test_create_user_sends_notification() -> None:
+    repo = FakeUserRepo()
+    notifier = Mock(spec=Notifier)
+
+    service = UserService(repo, notifier)
+    service.create(CreateUserInput(name="Alice", email="a@b.com"))
+
+    notifier.send_welcome.assert_called_once_with("a@b.com")
+
+# When you must patch (third-party code, module-level functions)
+@patch("mypackage.services.user_service.send_email")
+def test_sends_email_on_signup(mock_send: Mock) -> None:
+    service = UserService(FakeUserRepo())
+    service.signup(email="test@example.com")
+    mock_send.assert_called_once_with(to="test@example.com", template="welcome")
+
+# Async mocking
+async def test_async_fetch() -> None:
+    client = AsyncMock(spec=HttpClient)
+    client.get.return_value = Response(status=200, body=b'{"ok": true}')
+
+    result = await fetch_data(client, "/api/data")
+    assert result == {"ok": True}
+```
+
+## Integration Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.fixture
+async def app():
+    """Create test application with test database."""
+    test_app = create_app(testing=True)
+    async with test_app.lifespan():
+        yield test_app
+
+@pytest.fixture
+async def client(app) -> AsyncClient:
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_create_and_retrieve_user(client: AsyncClient) -> None:
+    # Create
+    response = await client.post("/users", json={"name": "Alice", "email": "a@b.com"})
+    assert response.status_code == 201
+    user_id = response.json()["id"]
+
+    # Retrieve
+    response = await client.get(f"/users/{user_id}")
+    assert response.status_code == 200
+    assert response.json()["name"] == "Alice"
+```
+
+## Snapshot Testing
+
+```python
+# Using syrupy or inline-snapshot
+def test_api_response_format(snapshot) -> None:
+    response = generate_api_response(sample_data)
+    assert response == snapshot
+```
+
+## conftest.py Patterns
+
+```python
+# tests/conftest.py — shared across all tests
+import pytest
+
+@pytest.fixture(autouse=True)
+def _reset_singletons():
+    """Reset module-level singletons between tests."""
+    yield
+    SingletonClass._instance = None
+
+@pytest.fixture
+def freeze_time():
+    """Fixture that freezes time for deterministic tests."""
+    from freezegun import freeze_time
+    with freeze_time("2025-01-01T12:00:00Z") as frozen:
+        yield frozen
+```
+
+## Anti-Patterns
+
+```python
+# Never: Tests that depend on execution order
+# Each test must be independently runnable
+
+# Never: Assertions without messages in complex tests
+assert result  # What is result? What did we expect?
+# Better:
+assert result.status == "active", f"Expected active, got {result.status}"
+
+# Never: Testing implementation details
+assert service._internal_cache == {"key": "value"}  # Private API!
+# Test through the public interface
+
+# Never: Excessive mocking
+# If you're mocking 5+ dependencies, the unit is too large — refactor
+
+# Never: time.sleep() for synchronization in tests
+time.sleep(1)  # Slow AND flaky
+# Use polling, events, or mock the clock
+
+# Never: Tests without assertions
+def test_user_creation() -> None:
+    service.create_user(data)  # What are we verifying? Nothing.
+```