specx-add-delivery-controller

Name: specx-add-delivery-controller
Author: maksimzayats

199stars36forks

How to install specx-add-delivery-controller?

maksimzayats/specx/specx-add-delivery-controller

$npx -y skills add maksimzayats/specx --skill specx-add-delivery-controller

Installs into the current project.

Summary

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-l

Files · 1

View on GitHub

SKILL.md

1	# specx Add Delivery Controller
2
3	Use this skill at the framework boundary. Read `references/controller.md`
4	before adding controller code.
5
6	## Workflow
7
8	1. Put controllers under `delivery/fastapi/controllers/<scope>.py`.
9	2. Put request and response schemas under `delivery/fastapi/schemas/`.
10	3. Use one controller per scoped set of use cases, for example
11	`TasksController` for create/get/list task routes.
12	4. Put controller-only helpers such as auth dependencies, rate limiters, and
13	request-context readers under `delivery/fastapi/services/`.
14	5. Make controllers inherit `BaseController`, schemas inherit
15	`BaseFastAPISchema`, delivery helpers inherit `BaseDeliveryService`, and
16	FastAPI lifespan managers inherit `BaseLifecycle[FastAPI]`.
17	6. Add docstrings with scope and a concrete `Example:` to controllers, schemas,
18	and delivery services.
19	7. Inject use cases or delivery services with `Injected[...]`. A simple
20	delivery-owned `/healthz` response needs no core workflow; inject
21	`core/health` use cases when readiness checks a required external dependency
22	or probe policy is reused across deliveries.
23	8. Map request schema/path data into the use case's same-file `Command` or
24	`Query` input.
25	9. Call the use case.
26	10. Map the result into a response schema.
27	11. Declare the success status explicitly when it is not `200`, such as `201`
28	for a resource-creating `POST` or `204` for a response with no body.
29	12. Translate known application exceptions into stable, non-sensitive HTTP
30	responses. Do not expose raw exception messages.
31	13. Register full public business route paths such as `/api/v1/users`. Do not
32	split API prefixes across routers and route fragments. Operational probes
33	are the only unversioned exception: `/healthz` and `/readyz`.
34	14. For FastAPI apps with long-lived resources, inject `FastAPILifecycle` into
35	the app factory and pass it to `FastAPI(lifespan=...)`.
36	15. Add integration tests at the HTTP boundary, including the declared success
37	code and each translated application error.
38
39	## Code Style
40
41	Use blank lines as logical separators in all code. Keep related statements
42	together, but separate independent setup, action, assertion, response, branch,
43	and transformation groups so long blocks stay readable.
44
45	## References
46
47	- `references/controller.md` - FastAPI controller class pattern, app factory
48	registration, schemas, and tests.

People who liked this also viewed

6 picks

Type

specx-add-delivery-controller

199stars36forks

View on GitHub

How to install specx-add-delivery-controller?

maksimzayats/specx/specx-add-delivery-controller

$npx -y skills add maksimzayats/specx --skill specx-add-delivery-controller

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# specx Add Delivery Controller
2
3	Use this skill at the framework boundary. Read `references/controller.md`
4	before adding controller code.
5
6	## Workflow
7
8	1. Put controllers under `delivery/fastapi/controllers/<scope>.py`.
9	2. Put request and response schemas under `delivery/fastapi/schemas/`.
10	3. Use one controller per scoped set of use cases, for example
11	`TasksController` for create/get/list task routes.
12	4. Put controller-only helpers such as auth dependencies, rate limiters, and
13	request-context readers under `delivery/fastapi/services/`.
14	5. Make controllers inherit `BaseController`, schemas inherit
15	`BaseFastAPISchema`, delivery helpers inherit `BaseDeliveryService`, and
16	FastAPI lifespan managers inherit `BaseLifecycle[FastAPI]`.
17	6. Add docstrings with scope and a concrete `Example:` to controllers, schemas,
18	and delivery services.
19	7. Inject use cases or delivery services with `Injected[...]`. A simple
20	delivery-owned `/healthz` response needs no core workflow; inject
21	`core/health` use cases when readiness checks a required external dependency
22	or probe policy is reused across deliveries.
23	8. Map request schema/path data into the use case's same-file `Command` or
24	`Query` input.
25	9. Call the use case.
26	10. Map the result into a response schema.
27	11. Declare the success status explicitly when it is not `200`, such as `201`
28	for a resource-creating `POST` or `204` for a response with no body.
29	12. Translate known application exceptions into stable, non-sensitive HTTP
30	responses. Do not expose raw exception messages.
31	13. Register full public business route paths such as `/api/v1/users`. Do not
32	split API prefixes across routers and route fragments. Operational probes
33	are the only unversioned exception: `/healthz` and `/readyz`.
34	14. For FastAPI apps with long-lived resources, inject `FastAPILifecycle` into
35	the app factory and pass it to `FastAPI(lifespan=...)`.
36	15. Add integration tests at the HTTP boundary, including the declared success
37	code and each translated application error.
38
39	## Code Style
40
41	Use blank lines as logical separators in all code. Keep related statements
42	together, but separate independent setup, action, assertion, response, branch,
43	and transformation groups so long blocks stay readable.
44
45	## References
46
47	- `references/controller.md` - FastAPI controller class pattern, app factory
48	registration, schemas, and tests.

People who liked this also viewed

6 picks

Type