pystack-skills

Use when designing or editing aggregates and their repositories in a FastAPI + SQLAlchemy backend: files in `app/models/` and `app/repos/`. Triggers on edits to those directories; on imports from `sqlalchemy.ext.asyncio`, `sqlalchemy.orm`; on user mentions of "aggregate", "repository", "consistency boundary", "ORM model with behavior", "use case loading". Encodes: SA model with behavior (no separate domain layer by default), repos return SA models, YAGNI on repo surface, typed `*Exception` raised from repo, no commit in repo, one repo per aggregate root, named query methods over generic filter objects. Do NOT use for: projects that have an explicit `domain/` directory with pure domain classes — use `python-pure-domain-layer` instead.

Use when wrapping an external HTTP API (CRM, payment gateway, notification service, LLM provider, etc.) into a typed Python client class. Triggers on edits to `app/clients/`; on imports of `httpx`, `tenacity`; on user questions about HTTP clients, retries, mocking external APIs, `MockTransport`, client lifecycle. Encodes: `BaseHTTPClient` with `httpx.AsyncClient` + tenacity retry, per-client `init_X_client` / `cleanup_X_client` async functions, schemas know the wire shape via `from_X` / `to_X`, `httpx.MockTransport` for tests (no aiohttp dep), YAGNI on method surface. Do NOT use for: database access (use python-aggregate-and-repo); internal service-to-service in-process calls (just call the service).

Use when scaffolding or modifying the structure of a FastAPI + SQLAlchemy backend service: `setup.py`, `config.py`, the `db/`, `deps/`, `common/`, `api/` directories, the FastAPI app factory, lifespan, middleware, exception handlers. Triggers on edits to those files; on a new repo that's becoming a FastAPI service; on user questions about app structure, dependency injection setup, lifespan, middleware, exception handling, project layout. Encodes: layered `app/` package, lifespan over event handlers, providers in `app/deps/`, exception handlers grouped by HTTP status, manual `app.state.*` setup in tests. Do NOT use for: scripts, CLIs, libraries, or codebases that aren't FastAPI services.

Use ONLY when the project has an explicit `app/domain/` directory, or the user explicitly asks for "DDD aggregate", "pure domain model", "framework-free invariants", "Cosmic Python style", "separate domain and ORM". Triggers on edits to `app/domain/`; on user mentions of Cosmic Python, ports and adapters, imperative SA mapping, `from_domain` / `to_domain`. Encodes: separate domain classes (frozen dataclass VOs, mutable aggregate roots), SA models that translate to/from domain via `from_domain` / `to_domain` methods, pulling domain events on the aggregate, sync-only domain code. Do NOT use for: default FastAPI + SA services — use `python-aggregate-and-repo` instead. The pure-domain pattern is an opt-in for invariant-dense systems (finance, fulfillment, complex state machines).

Use when designing or editing services and schemas in a FastAPI + SQLAlchemy backend: files in `app/services/` and `app/schemas/`. Triggers on edits to those directories; on definitions of `class *Service`, `class *Command`, `class *Get`; on user mentions of "use case", "service layer", "Pydantic schema", "command", "response shape", "from_model", "to_new_X", "cohesion", "domain service", "policy", "god service", "business rule extraction". Encodes: class-when-state vs function-when-stateless, service returns Pydantic schema (not SA model), top-level service owns the transaction with `AsyncSession.begin()`, composable collaborators do not commit, pure domain services/policies for business rules that do not belong to one aggregate, schema naming (*Get / *Create / *Update / *Command), cohesion methods (`from_<source>` classmethod inbound, `to_<target>` method outbound), Pydantic v2 `from_attributes=True`, no `utils.py` / no free transform functions. Do NOT use for: repos (use python-aggregate-and-repo), routes

Use when setting up logging or writing log calls in a Python service. Triggers on `import logging`, `import structlog`, edits to `app/common/logging.py` or `app/api/middleware/`, on user questions about logging, JSON logs, correlation IDs, structured logging, log levels. Encodes: structlog as the canonical logger, contextvar-based correlation_id propagation, env-driven console-vs-JSON renderer, stdlib bridge so library logs flow through structlog, key=value fields not f-strings. Do NOT use for: print-debugging in scripts; CLI output (use rich or stdout directly).

Use when writing or organizing tests for a FastAPI + SQLAlchemy backend service. Triggers on edits to `tests/`, `conftest.py`, files in `tests/fixtures/`, `tests/doubles/`, `tests/unit/`, `tests/integration/`, `tests/api/`; on imports of `pytest_asyncio`, `httpx.ASGITransport`, `httpx.MockTransport`; on user questions about test fixtures, real-DB tests, external doubles, test layout, pytest setup. Encodes: real Postgres (no testcontainers), session- scoped DB + app, function-scoped session + client, ASGITransport, manual app.state setup in fixtures, httpx.MockTransport for external clients, no unittest.mock / pytest-mock, no factory libs, unit/integration/api split. Do NOT use for: testing libraries, scripts, or non-FastAPI Python.

Use when writing or modifying typed Python code (any project — libraries, services, scripts). Triggers on `.py` files with type annotations; on imports from `typing`, `typing_extensions`, `collections.abc`; on user questions about type hints, Protocol, generics, NewType, PEP 695. Encodes: Protocol over ABC for ports, `Self` for classmethod constructors, `NewType` for ID safety, PEP 695 type aliases and generics, `Annotated` for FastAPI/Pydantic metadata, alternative constructors via `@classmethod from_X(cls, ...) -> Self`, avoiding `Any`, narrowing patterns. Do NOT use for: untyped Python codebases that aren't ready to adopt type hints.

Use when defining domain primitives in any Python project — Money, EmailAddress, Color, Coordinates, IDs, anything where two instances with the same fields should be equal and where the values must satisfy invariants. Triggers on `.py` files defining `@dataclass`, on user questions about value objects, immutability, frozen dataclasses, slots, kw_only. Encodes: frozen + slots + kw_only, `__post_init__` invariants, equality by value, no identity, methods over external utility functions. Do NOT use for: aggregate roots (mutable, identity-based — see python-aggregate-and-repo); Pydantic models for HTTP I/O (see python-service-and-schema-cohesion).

Use when considering a Java/GoF-shaped pattern that agents commonly generate in Python: Singleton, Abstract Factory, or Factory Method. Use when reviewing code defining `class *Singleton`, `class Abstract*Factory`, `*Factory.create(...)`, or when the user asks "is X a good idea in Python?" Encodes: which imported patterns usually add ceremony in Python, what to use instead, and which positive skill has the detail. Do NOT use for: deep dives — this is the quick lookup. Each entry points to the positive skill with the full alternative.

Use when the service is event-driven: publishing or consuming events through a message broker (Kafka, RabbitMQ, Redis Streams, NATS, SQS), or using an in-process bus to decouple side effects from a use case. Triggers on edits to `app/events/`, `app/handlers/`, `app/outbox/`, `app/consumers/`; on imports of `aiokafka`, `aio-pika`, `redis.asyncio`, `aiobotocore`; on user mentions of "message bus", "domain events", "outbox pattern", "event-driven", "saga", "process manager", "Kafka consumer", "publisher". Encodes: in-process message bus, outbox table for at-least-once cross-process delivery, idempotent handlers, consumer layout for inbound subscribers, producer layout for outbound publishers. Do NOT use for: services with one consumer and no cross-process needs — direct function calls are simpler. The skill draws a clear line.

Use when iterating over collections, building lazy pipelines, or modeling tree / recursive structures (filesystems, ASTs, query builders, UI trees). Triggers on imports of `itertools`, `collections.abc`; on `for ... yield ...`, `__iter__`, generators; on tree-shaped data, leaf/composite distinctions, recursive traversal. Encodes: generators over hand-rolled iterators, `itertools` for composition, `AsyncIterator[T]` for async, `Protocol` + dataclass for tree shapes, recursive generators for traversal, `match` for visitor dispatch. Do NOT use for: type-system idioms (use python-typing-idioms); domain primitives (use python-value-objects); aggregates (use python-aggregate-and-repo).