specx

Design or review Specx core scope boundaries in Python services. Use when deciding where code belongs across packaged scoped foundation bases, optional local foundation extensions, `core/`, capabilities, delivery, infrastructure, `shared/`, and `ioc`; when adding guardrails or splitting use cases, services, DTOs, schemas, ports, and adapters.

Wire dependency injection for a Specx Python service with `diwire`. Use when adding `ioc/container.py`, explicit dependency registrations for capabilities, repositories, gateways, UoW managers, clients, settings, or factories, `Injected[...]` constructor fields, FastAPI app factory/lifecycle composition, test overrides, or rules that keep containers out of core use cases and services.

Create or reshape a Python FastAPI service repo into the Specx clean core/delivery architecture using packaged scoped foundation bases. Use when starting an API backend, adding the first src package, or establishing `AGENTS.md`, `core/`, optional local `foundation/`, `delivery/`, infrastructure, `ioc/`, migrations, and tests.

Add strict Python project tooling for a Specx service. Use when creating or updating `pyproject.toml`, `uv` dependency groups and lock checks, Ruff formatting and linting, mypy strict mode, pytest and HTTPX2 test configuration, Makefile commands, root `AGENTS.md` command guidance, or CI-like local guardrails.

Add or refine tests for Specx Python services. Use when creating unit tests for use cases/services, integration tests for FastAPI controllers or infrastructure adapters, e2e smoke tests, architecture import guardrails, DI override tests, pytest fixtures, or coverage and boundary checks.

Add or refactor a Specx core scope service. Use when implementing focused reusable business/application behavior under a core scope services package, extracting logic from a use case, injecting deterministic collaborators, accepting an active unit of work, choosing between Service and Capability, or keeping business decisions away from delivery and infrastructure.

Add or refactor a Specx core scope use case. Use when implementing an externally meaningful application action under a core scope use_cases package, adding same-file command/query inputs, result DTOs, coordinating services, opening a unit-of-work transaction, or moving behavior out of delivery or infrastructure into class-based application code.

Add delivery controllers for Specx services, especially FastAPI HTTP routes. Use when creating top-level `delivery/` request/response schemas, one controller per scoped use-case set, route registration, FastAPI lifecycle managers, HTTP error translation, delivery-only auth/rate-limit/request services, or integration tests that exercise the delivery edge.

Add technical infrastructure adapters for Specx core scopes. Use when implementing SQLAlchemy repositories and Alembic-backed persistence, Redis stores, HTTP/network clients, file or queue adapters, unit-of-work implementations, gateway implementations for external APIs or SDKs such as OpenAI, or explicit `diwire` bindings for core scope repository and gateway ports.

Use Specx foundation bases in Python services, or add a tiny project-local `foundation/` base for missing categories or stateful framework bases.

Add runtime configuration to Specx Python services with `pydantic-settings`. Use when creating settings classes, environment variables, `.env.example`, injecting settings at delivery, infrastructure, or composition edges, documenting config, mapping configuration into typed core policy collaborators, or removing direct environment reads from core code.

Add or repair Alembic migrations for Specx SQLAlchemy services. Use when adding SQLAlchemy models or repositories, replacing metadata.create_all schema bootstraps, creating async Alembic env.py, adding migration Makefile targets, generating initial revisions, or testing migration drift.