agentic-team-templates 0.12.0 → 0.13.1

package/README.md

@@ -147,20 +147,25 @@ npx agentic-team-templates --reset --force
 
 | Template | Description |
 |----------|-------------|
-| `web-frontend` | SPAs, SSR, static sites, PWAs |
-| `web-backend` | REST, GraphQL, microservices |
-| `fullstack` | Full-stack apps (Next.js, Nuxt, etc.) |
-| `mobile` | React Native, Flutter, native iOS/Android |
-| `cli-tools` | Command-line applications and developer tools |
-| `blockchain` | Smart contracts, DeFi, Web3 applications |
-| `ml-ai` | Machine learning systems, model development |
-| `data-engineering` | Data pipelines, ETL, warehousing |
-| `platform-engineering` | Infrastructure as code, Kubernetes, CI/CD |
-| `devops-sre` | Incident management, SLOs, observability |
-| `product-manager` | Product strategy, discovery, OKRs, PRDs |
-| `qa-engineering` | Test strategy, automation, quality gates |
-| `utility-agent` | AI agent utilities, context management |
-| `documentation` | Technical writing, API docs, ADRs |
+| `blockchain` | Smart contracts, DeFi protocols, and Web3 applications (Solidity, Foundry, Viem) |
+| `cli-tools` | Command-line applications and developer tools (Cobra, Commander, Click) |
+| `data-engineering` | Data platforms and pipelines (ETL, data modeling, data quality) |
+| `devops-sre` | DevOps and SRE practices (incident management, observability, SLOs, chaos engineering) |
+| `documentation` | Technical documentation standards (READMEs, API docs, ADRs, code comments) |
+| `fullstack` | Full-stack web applications (Next.js, Nuxt, SvelteKit, Remix) |
+| `golang-expert` | Principal-level Go engineering (concurrency, stdlib, production patterns, testing) |
+| `javascript-expert` | Principal-level JavaScript engineering across Node.js, React, vanilla JS, and testing |
+| `ml-ai` | Machine learning and AI systems (model development, deployment, monitoring) |
+| `mobile` | Mobile applications (React Native, Flutter, native iOS/Android) |
+| `platform-engineering` | Internal developer platforms, infrastructure automation, reliability engineering |
+| `product-manager` | Product management with customer-centric discovery, prioritization, and execution |
+| `python-expert` | Principal-level Python engineering (type system, async, testing, FastAPI, Django) |
+| `qa-engineering` | Quality assurance programs for confident, rapid software delivery |
+| `rust-expert` | Principal-level Rust engineering (ownership, concurrency, unsafe, traits, async) |
+| `testing` | Comprehensive testing practices (TDD, test design, CI/CD integration, performance testing) |
+| `utility-agent` | AI agent utilities with context management and hallucination prevention |
+| `web-backend` | Backend APIs and services (REST, GraphQL, microservices) |
+| `web-frontend` | Frontend web applications (SPAs, SSR, static sites, PWAs) |
 
 ## What Gets Installed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-team-templates",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "AI coding assistant templates for Cursor IDE. Pre-configured rules and guidelines that help AI assistants write better code. - use at your own risk",
   "keywords": [
     "cursor",

package/src/index.js

@@ -60,10 +60,6 @@ const TEMPLATES = {
     description: 'Mobile applications (React Native, Flutter, native iOS/Android)',
     rules: ['navigation.md', 'offline-first.md', 'overview.md', 'performance.md', 'testing.md']
   },
-  'rust-expert': {
-    description: 'Principal-level Rust engineering (ownership, concurrency, unsafe, traits, async)',
-    rules: ['concurrency.md', 'ecosystem-and-tooling.md', 'error-handling.md', 'overview.md', 'ownership-and-borrowing.md', 'performance-and-unsafe.md', 'testing.md', 'traits-and-generics.md']
-  },
   'platform-engineering': {
     description: 'Internal developer platforms, infrastructure automation, and reliability engineering',
     rules: ['ci-cd.md', 'developer-experience.md', 'infrastructure-as-code.md', 'kubernetes.md', 'observability.md', 'overview.md', 'security.md', 'testing.md']
@@ -72,10 +68,18 @@ const TEMPLATES = {
     description: 'Product management with customer-centric discovery, prioritization, and execution',
     rules: ['communication.md', 'discovery.md', 'metrics.md', 'overview.md', 'prioritization.md', 'requirements.md']
   },
+  'python-expert': {
+    description: 'Principal-level Python engineering (type system, async, testing, FastAPI, Django)',
+    rules: ['async-python.md', 'overview.md', 'patterns-and-idioms.md', 'performance.md', 'testing.md', 'tooling.md', 'type-system.md', 'web-and-apis.md']
+  },
   'qa-engineering': {
     description: 'Quality assurance programs for confident, rapid software delivery',
     rules: ['automation.md', 'metrics.md', 'overview.md', 'quality-gates.md', 'test-design.md', 'test-strategy.md']
   },
+  'rust-expert': {
+    description: 'Principal-level Rust engineering (ownership, concurrency, unsafe, traits, async)',
+    rules: ['concurrency.md', 'ecosystem-and-tooling.md', 'error-handling.md', 'overview.md', 'ownership-and-borrowing.md', 'performance-and-unsafe.md', 'testing.md', 'traits-and-generics.md']
+  },
   'testing': {
     description: 'Comprehensive testing practices (TDD, test design, CI/CD integration, performance testing)',
     rules: ['advanced-techniques.md', 'ci-cd-integration.md', 'overview.md', 'performance-testing.md', 'quality-metrics.md', 'reliability.md', 'tdd-methodology.md', 'test-data.md', 'test-design.md', 'test-types.md']
@@ -160,7 +164,7 @@ async function checkForUpdates() {
 function printBanner() {
   console.log(colors.blue(`
 ╔═══════════════════════════════════════════════════════════╗
-║              Cursor Templates Installer                   ║
+║           Agentic Team Templates Installer                ║
 ╚═══════════════════════════════════════════════════════════╝
 `));
 }

package/src/index.test.js

@@ -83,10 +83,11 @@ describe('Constants', () => {
         'javascript-expert',
         'ml-ai',
         'mobile',
-        'rust-expert',
         'platform-engineering',
         'product-manager',
+        'python-expert',
         'qa-engineering',
+        'rust-expert',
         'testing',
         'utility-agent',
         'web-backend',

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

@@ -0,0 +1,214 @@
+# Async Python
+
+Python's `asyncio` enables concurrent I/O-bound operations on a single thread. Understanding the event loop, coroutines, and task lifecycle is essential for building high-performance async services.
+
+## Fundamentals
+
+### Coroutines and Tasks
+
+```python
+import asyncio
+
+# A coroutine is defined with async def
+async def fetch_data(url: str) -> bytes:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.read()
+
+# Coroutines don't run until awaited or wrapped in a task
+coro = fetch_data("https://example.com")  # Nothing happens yet
+data = await coro  # Now it runs
+
+# Tasks run concurrently on the event loop
+async def fetch_all(urls: list[str]) -> list[bytes]:
+    tasks = [asyncio.create_task(fetch_data(url)) for url in urls]
+    return await asyncio.gather(*tasks)
+```
+
+### asyncio.gather vs TaskGroup
+
+```python
+# gather — returns results in order, continues on individual failures (by default)
+results = await asyncio.gather(
+    fetch_users(),
+    fetch_posts(),
+    fetch_comments(),
+)
+users, posts, comments = results
+
+# TaskGroup (3.11+) — structured concurrency, cancels all on first failure
+async with asyncio.TaskGroup() as tg:
+    user_task = tg.create_task(fetch_users())
+    post_task = tg.create_task(fetch_posts())
+
+# All tasks complete or all cancelled if one fails
+users = user_task.result()
+posts = post_task.result()
+```
+
+### Timeouts
+
+```python
+# asyncio.timeout (3.11+)
+async with asyncio.timeout(5.0):
+    data = await fetch_data(url)
+
+# asyncio.wait_for (older approach)
+try:
+    data = await asyncio.wait_for(fetch_data(url), timeout=5.0)
+except asyncio.TimeoutError:
+    logger.warning("fetch timed out", extra={"url": url})
+    raise
+```
+
+### Bounded Concurrency
+
+```python
+# Semaphore for limiting concurrent operations
+async def fetch_all(urls: list[str], max_concurrent: int = 10) -> list[Response]:
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def bounded_fetch(url: str) -> Response:
+        async with semaphore:
+            return await fetch(url)
+
+    async with asyncio.TaskGroup() as tg:
+        tasks = [tg.create_task(bounded_fetch(url)) for url in urls]
+
+    return [task.result() for task in tasks]
+```
+
+## Async Generators and Iteration
+
+```python
+from collections.abc import AsyncIterator
+
+# Async generator
+async def stream_records(query: str) -> AsyncIterator[Record]:
+    async with db.execute(query) as cursor:
+        async for row in cursor:
+            yield Record.from_row(row)
+
+# Async for loop
+async for record in stream_records("SELECT * FROM events"):
+    await process(record)
+
+# Async comprehension
+results = [item async for item in stream_records(query) if item.is_valid()]
+```
+
+## Async Context Managers
+
+```python
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+@asynccontextmanager
+async def managed_pool(url: str, size: int = 10) -> AsyncIterator[Pool]:
+    pool = await create_pool(url, max_size=size)
+    try:
+        yield pool
+    finally:
+        await pool.close()
+
+async def main() -> None:
+    async with managed_pool("postgresql://localhost/db") as pool:
+        async with pool.acquire() as conn:
+            result = await conn.fetch("SELECT 1")
+```
+
+## Event Loop Patterns
+
+```python
+# Main entry point
+async def main() -> None:
+    ...
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+# Running blocking code in async context
+import functools
+
+async def process_file(path: Path) -> Data:
+    # Run CPU-bound or blocking I/O in a thread pool
+    loop = asyncio.get_running_loop()
+    data = await loop.run_in_executor(
+        None,  # Default ThreadPoolExecutor
+        functools.partial(parse_file, path),
+    )
+    return data
+```
+
+## Graceful Shutdown
+
+```python
+import signal
+
+async def main() -> None:
+    loop = asyncio.get_running_loop()
+
+    shutdown_event = asyncio.Event()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(sig, shutdown_event.set)
+
+    server = await start_server()
+
+    await shutdown_event.wait()
+
+    logger.info("shutting down")
+    await server.stop()
+    # Clean up resources
+```
+
+## Async Testing
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_fetch_user() -> None:
+    service = UserService(fake_repo)
+    user = await service.get_by_id("123")
+    assert user.name == "Alice"
+
+# Fixtures
+@pytest.fixture
+async def db_pool():
+    pool = await create_pool(TEST_DATABASE_URL)
+    yield pool
+    await pool.close()
+
+@pytest.fixture
+async def service(db_pool):
+    return UserService(UserRepo(db_pool))
+```
+
+## Anti-Patterns
+
+```python
+# Never: Blocking calls in async code
+async def bad_handler(request: Request) -> Response:
+    data = requests.get(url)  # Blocks the event loop!
+    time.sleep(1)              # Blocks the event loop!
+    # Use aiohttp and asyncio.sleep() instead
+
+# Never: Creating event loops manually (unless you're a framework author)
+loop = asyncio.new_event_loop()  # Use asyncio.run() instead
+
+# Never: Fire-and-forget tasks without error handling
+asyncio.create_task(background_work())  # Who catches the exception?
+# Better:
+task = asyncio.create_task(background_work())
+task.add_done_callback(handle_task_exception)
+
+# Never: Mixing sync and async without run_in_executor
+async def handler():
+    result = cpu_bound_work()  # Blocks event loop
+    # Use: result = await loop.run_in_executor(None, cpu_bound_work)
+
+# Never: Unbounded task spawning
+for item in million_items:
+    asyncio.create_task(process(item))  # OOM risk — use semaphore
+```

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

@@ -0,0 +1,174 @@
+# Python Expert
+
+Guidelines for principal-level Python engineering. Idiomatic Python, production systems, and deep interpreter knowledge.
+
+## Scope
+
+This ruleset applies to:
+- Web services and APIs (Django, FastAPI, Flask)
+- CLI tools and automation scripts
+- Data processing and ETL pipelines
+- Libraries and packages published to PyPI
+- Machine learning infrastructure
+- System administration and DevOps tooling
+- Async services and event-driven architectures
+
+## Core Philosophy
+
+Python's power is in its clarity. The best Python code reads like well-written prose.
+
+- **Readability counts.** The Zen of Python isn't decoration — it's the engineering standard. `import this` and mean it.
+- **Explicit is better than implicit.** Type hints, clear names, no magic. If you need a comment to explain what a variable holds, rename the variable.
+- **Simple is better than complex.** A straightforward `for` loop that's obvious beats a clever one-liner that requires a decoder ring.
+- **Errors should never pass silently.** Bare `except:` is a bug. Swallowing exceptions hides the failures that will wake you up at 3 AM.
+- **The standard library is rich — use it.** `collections`, `itertools`, `pathlib`, `dataclasses`, `contextlib`, `functools` — know them deeply before reaching for PyPI.
+- **If you don't know, say so.** Python's ecosystem is vast. Admitting uncertainty about a niche library or CPython internal is honest and professional.
+
+## Key Principles
+
+### 1. Type Hints Are Not Optional
+
+```python
+# Modern Python is typed Python. Type hints are documentation,
+# tooling enablement, and bug prevention.
+
+# Good: Fully typed function signatures
+def fetch_users(
+    db: Database,
+    *,
+    limit: int = 100,
+    active_only: bool = True,
+) -> list[User]:
+    ...
+
+# Good: Complex types with type aliases
+type UserMap = dict[UserId, User]
+type Handler = Callable[[Request], Awaitable[Response]]
+
+# Bad: No type information
+def fetch_users(db, limit=100, active_only=True):
+    ...  # What does this return? What's db? Nobody knows.
+```
+
+### 2. Dataclasses and Pydantic Over Raw Dicts
+
+```python
+# Good: Structured data with validation
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass(frozen=True, slots=True)
+class User:
+    id: str
+    email: str
+    name: str
+    created_at: datetime = field(default_factory=datetime.now)
+
+# Good: Pydantic for external data validation
+from pydantic import BaseModel, EmailStr
+
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=200)
+
+# Bad: Dict soup
+user = {"id": "123", "email": "a@b.com"}  # No validation, no autocomplete, no safety
+```
+
+### 3. EAFP Over LBYL
+
+```python
+# Easier to Ask Forgiveness than Permission — Pythonic
+# Good: Try it and handle the exception
+try:
+    value = mapping[key]
+except KeyError:
+    value = default
+
+# Also good: Use .get() when it's clearer
+value = mapping.get(key, default)
+
+# Bad: Look Before You Leap (extra lookup, race conditions)
+if key in mapping:
+    value = mapping[key]  # What if it was deleted between check and access?
+```
+
+### 4. Context Managers for Resource Management
+
+```python
+# Always use context managers for resources
+# Good:
+with open("data.json") as f:
+    data = json.load(f)
+
+async with aiohttp.ClientSession() as session:
+    response = await session.get(url)
+
+# Good: Custom context managers
+from contextlib import contextmanager
+
+@contextmanager
+def temporary_directory():
+    path = Path(tempfile.mkdtemp())
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path)
+```
+
+## Project Structure
+
+```
+project/
+├── src/
+│   └── mypackage/
+│       ├── __init__.py
+│       ├── py.typed            # PEP 561 marker
+│       ├── config.py           # Configuration loading
+│       ├── exceptions.py       # Custom exceptions
+│       ├── models/             # Domain models
+│       │   ├── __init__.py
+│       │   └── user.py
+│       ├── services/           # Business logic
+│       │   ├── __init__.py
+│       │   └── user_service.py
+│       ├── repositories/       # Data access
+│       │   ├── __init__.py
+│       │   └── user_repo.py
+│       └── api/                # HTTP/CLI entry points
+│           ├── __init__.py
+│           └── routes.py
+├── tests/
+│   ├── conftest.py             # Shared fixtures
+│   ├── unit/
+│   │   └── test_user_service.py
+│   ├── integration/
+│   │   └── test_user_repo.py
+│   └── e2e/
+│       └── test_api.py
+├── pyproject.toml              # Single source of truth for project config
+├── Makefile
+└── .python-version             # Pin Python version
+```
+
+### Layout Rules
+
+- Use `src/` layout — it prevents accidental imports of uninstalled code
+- `pyproject.toml` is the single config file — no `setup.py`, no `setup.cfg`, no `requirements.txt` for deps
+- Tests mirror source structure but live outside `src/`
+- One concern per module — don't dump everything in `utils.py`
+- `__init__.py` defines the public API for each package
+
+## Definition of Done
+
+A Python feature is complete when:
+- [ ] `mypy --strict` passes with zero errors
+- [ ] `ruff check` passes with zero warnings
+- [ ] `ruff format --check` passes
+- [ ] `pytest` passes with no failures
+- [ ] Test coverage covers meaningful behavior (not just lines)
+- [ ] Error cases are tested, not just happy paths
+- [ ] Docstrings on all public functions and classes
+- [ ] No bare `except:` or `except Exception:` without re-raise
+- [ ] No mutable default arguments
+- [ ] No `# type: ignore` without an inline explanation