# Specx Add Delivery Controller

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

- **Type:** Skill
- **Install:** `agentstack add skill-maksimzayats-specx-specx-add-delivery-controller`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [maksimzayats](https://agentstack.voostack.com/s/maksimzayats)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [maksimzayats](https://github.com/maksimzayats)
- **Source:** https://github.com/maksimzayats/specx/tree/main/skills/specx-add-delivery-controller
- **Website:** https://specx.dev

## Install

```sh
agentstack add skill-maksimzayats-specx-specx-add-delivery-controller
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/.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.
4. Put controller-only helpers such as auth dependencies, rate limiters, and
   request-context readers under `delivery/fastapi/services/`.
5. Make controllers inherit `BaseController`, schemas inherit
   `BaseFastAPISchema`, delivery helpers inherit `BaseDeliveryService`, and
   FastAPI lifespan managers inherit `BaseLifecycle[FastAPI]`.
6. Add docstrings with scope and a concrete `Example:` to controllers, schemas,
   and delivery services.
7. 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.
8. Map request schema/path data into the use case's same-file `Command` or
   `Query` input.
9. Call the use case.
10. Map the result into a response schema.
11. 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.
12. Translate known application exceptions into stable, non-sensitive HTTP
    responses. Do not expose raw exception messages.
13. 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`.
14. For FastAPI apps with long-lived resources, inject `FastAPILifecycle` into
   the app factory and pass it to `FastAPI(lifespan=...)`.
15. 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [maksimzayats](https://github.com/maksimzayats)
- **Source:** [maksimzayats/specx](https://github.com/maksimzayats/specx)
- **License:** MIT
- **Homepage:** https://specx.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-maksimzayats-specx-specx-add-delivery-controller
- Seller: https://agentstack.voostack.com/s/maksimzayats
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.