version: "1.0.0" name: specx-add-delivery-controller description: 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.

specx Add Delivery Controller

Use this skill at the framework boundary. Read references/controller.md before adding controller code.

Workflow

1. Put controllers under delivery/fastapi/controllers/<scope>.py.
2. Put request and response schemas under delivery/fastapi/schemas/.
3. Use one controller per scoped set of use cases, for example

TasksController for create/get/list task routes.

1. Put controller-only helpers such as auth dependencies, rate limiters, and

request-context readers under delivery/fastapi/services/.

1. Make controllers inherit BaseController, schemas inherit

BaseFastAPISchema, delivery helpers inherit BaseDeliveryService, and FastAPI lifespan managers inherit BaseLifecycle[FastAPI].

1. Add docstrings with scope and a concrete Example: to controllers, schemas,

and delivery services.

1. Inject use cases or delivery services with Injected[...]. A simple

delivery-owned /healthz response needs no core workflow; inject core/health use cases when readiness checks a required external dependency or probe policy is reused across deliveries.

1. Map request schema/path data into the use case's same-file Command or

Query input.

1. Call the use case.
2. Map the result into a response schema.
3. Declare the success status explicitly when it is not 200, such as 201

for a resource-creating POST or 204 for a response with no body.

1. Translate known application exceptions into stable, non-sensitive HTTP

responses. Do not expose raw exception messages.

1. Register full public business route paths such as /api/v1/users. Do not

split API prefixes across routers and route fragments. Operational probes are the only unversioned exception: /healthz and /readyz.

1. For FastAPI apps with long-lived resources, inject FastAPILifecycle into

the app factory and pass it to FastAPI(lifespan=...).

1. Add integration tests at the HTTP boundary, including the declared success

code and each translated application error.

Code Style

Use blank lines as logical separators in all code. Keep related statements together, but separate independent setup, action, assertion, response, branch, and transformation groups so long blocks stay readable.

References

• references/controller.md - FastAPI controller class pattern, app factory

registration, schemas, and tests.