@mrciphersmith/keryx 0.3.5 → 0.3.6

package/src/gdskills/bundled/stacks/fastapi/skills/fastapi-build-fix/evals.json

@@ -0,0 +1,76 @@
+{
+  "triggers": {
+    "positive": [
+      "Our API crashes on boot right after I wired up a new Depends() chain -- what's throwing it off?",
+      "I just wired a new router into main.py and now uvicorn won't even boot -- ImportError somewhere in the chain. Can you track it down?",
+      "One of my FastAPI dependency functions keeps blowing up with 'unable to resolve dependency' at app startup -- mind digging into why?",
+      "mypy is failing on this FastAPI path operation's return type",
+      "ruff check is failing on our FastAPI project, fix the violations",
+      "Got a weird Pydantic error on model instantiation that I can't make sense of -- here's the traceback, can you figure out what's wrong?",
+      "Every request to my new FastAPI endpoints comes back 404 even though I swear I included the router -- what did I mess up?"
+    ],
+    "negative": [
+      "Fix this generic ModuleNotFoundError unrelated to FastAPI's own wiring",
+      "Fix this Django migration conflict blocking makemigrations from running",
+      "Implement a new FastAPI endpoint that lists orders",
+      "Write pytest tests for this FastAPI router",
+      "Review this FastAPI diff for security issues",
+      "Fix the TypeScript build failure in our Node service",
+      "Our pip dependency resolver reports a version conflict between two unrelated packages"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "pydantic-mismatch-not-any",
+      "prompt": "A Pydantic model in our FastAPI project raises `PydanticUserError` at import time -- the message says the model can't use both `Config` and `model_config` -- after someone added `model_config = ConfigDict(...)` to a model that still has its original `class Config:` block. How do you fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer diagnoses the actual cause -- the model defines BOTH the old v1-style `class Config:` block AND the new `model_config = ConfigDict(...)` attribute at the same time, which Pydantic v2 rejects as an error (not merely a deprecation warning) -- and fixes it by removing one of the two, migrating any settings from `class Config:` into `model_config`, rather than making the error disappear by widening field types to Any/dict.",
+          "pass_criteria": [
+            "identifies the root cause: the model defines both `class Config:` and `model_config = ConfigDict(...)` at once, which Pydantic v2 raises an error for -- not that `class Config:` exists at all (using it alone is only a deprecation warning, not this error)",
+            "names the concrete fix: remove the `class Config:` block and move any settings it held into `model_config = ConfigDict(...)` (translating v1 keys to their v2 equivalents, e.g. `orm_mode` -> `from_attributes`), leaving the model with exactly one config mechanism, consistent with the project's actual pinned Pydantic version",
+            "shows or names the specific change (the class body converted, or the settings migrated), not just 'fix the config conflict' in the abstract"
+          ],
+          "fail_criteria": [
+            "proposes retyping the model's fields as `Any`/`dict` (or removing Pydantic validation from the model) to make the error stop, instead of removing the duplicate config mechanism. Mentioning that this would be wrong is not itself a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "This is Pydantic's `config-both` error: the model still has its original `class Config:` block (v1 style), and someone added `model_config = ConfigDict(...)` (v2 style) alongside it without removing the old one -- Pydantic v2 raises `PydanticUserError` when a model carries both at once, since it can't tell which is authoritative. Using `class Config:` on its own is only a deprecation warning; it's having *both* attributes present that turns it into a hard error. The fix is to keep only one: remove the `class Config:` block and fold whatever it set into `model_config`, translating v1 keys to their v2 names (e.g. `orm_mode` becomes `from_attributes`). Once the model has just `model_config = ConfigDict(...)` and no inner `Config` class, rerun the app import to confirm the error is gone, then rerun `mypy`/`pytest` since the merged settings may shift field behavior slightly.",
+        "known_wrong": "Simplest fix: since Pydantic is complaining about the config machinery, just drop strict typing on the affected fields and use `Any` so there's nothing left for the conflicting config to validate:\n\n```python\nclass NotificationSettings(BaseModel):\n    channel: Any\n    retry_limit: Any\n\n    class Config:\n        orm_mode = True\n\n    model_config = ConfigDict(from_attributes=True)\n```\n\nThis doesn't actually touch the `Config`/`model_config` conflict, but since the fields are now untyped the validation errors that were showing up alongside the startup failure go away, which looks like it fixed the problem.",
+        "vague": "Sounds like the model has both old and new Pydantic config styles defined on it at the same time -- keep only one of them instead of leaving both in place.",
+        "subtle_wrong": "Since the complaint is about `model_config` conflicting with something, the fastest fix is to just set `model_config` to an empty dict so it doesn't carry any settings that could clash:\n\n```python\nclass NotificationSettings(BaseModel):\n    channel: str\n    retry_limit: int\n\n    class Config:\n        orm_mode = True\n\n    model_config = ConfigDict()\n```\n\nThat should stop `model_config` from conflicting with anything `Config` sets, since it's empty now. The `class Config:` block is left in place since that's where `orm_mode` still lives."
+      },
+      "anti_patterns": ["`Any`"]
+    },
+    {
+      "id": "dependency-resolution-not-removed",
+      "prompt": "Our FastAPI app fails to start with an error that a dependency function's parameter cannot be resolved. Fix it.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer diagnoses which parameter FastAPI could not resolve and fixes it by giving that parameter a proper Depends()/request-data annotation, rather than removing the Depends() wiring and calling the dependency function directly. Because the prompt supplies no code or exact error text, an answer that first asks for the actual error message and the dependency function's signature, while explicitly ruling out removing Depends() as the eventual fix, is also correct.",
+          "pass_criteria": [
+            "either names the concrete fix -- giving the unresolved parameter a proper `Depends(...)` (or a request-data annotation like `Query(...)`/a plain type FastAPI can parse) -- once the failing signature is known, or asks for the actual error message and the dependency function's signature before proposing a fix, since neither was supplied",
+            "explains that FastAPI couldn't determine how to resolve one of the dependency's own parameters, and that the fix is to give that parameter a source FastAPI understands, not to bypass dependency injection",
+            "commits to keeping `Depends(...)`-based injection in place once the fix is identified or known"
+          ],
+          "fail_criteria": [
+            "proposes removing the `Depends(...)` wiring and calling the dependency function directly (or hard-coding its return value) to make the startup error disappear. Mentioning that this would be wrong is not itself a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "I'd need the actual startup error message and the dependency function's signature to name the exact fix -- FastAPI's error names which parameter it couldn't resolve, and that's the one to look at. In general, this happens when a dependency function has a parameter with no default and no annotation FastAPI recognizes as either request data (a `Query(...)`/`Path(...)`/plain scalar type) or another `Depends(...)`. The fix is to give that specific parameter the annotation it's missing -- e.g. if it's meant to come from another dependency, add `Depends(other_dep)`; if it's meant to come from the request, annotate it with the right FastAPI parameter type. I wouldn't remove `Depends(...)` from the call site to sidestep the error -- that would lose dependency injection (and `app.dependency_overrides` testability) for that value entirely; once the real fix is applied, rerun the app-startup check to confirm it resolves cleanly.",
+        "known_wrong": "Easiest fix: since FastAPI can't figure out how to resolve the parameter, just call the dependency function directly inside the path operation instead of injecting it through `Depends(...)`:\n\n```python\n@router.get(\"/items\")\ndef read_items(user_id: int):\n    db = get_db_session()  # called directly, no Depends()\n    return db.query(Item).filter_by(owner_id=user_id).all()\n```\n\nThis sidesteps FastAPI's dependency resolution entirely, so the startup error goes away immediately and the endpoint still gets a working session. You lose the ability to override it in tests via `app.dependency_overrides`, but that's a minor tradeoff for getting the app running again quickly.",
+        "vague": "Figure out which parameter FastAPI can't resolve and give it the annotation it needs instead of working around the dependency system.",
+        "subtle_wrong": "Since the unresolved parameter is causing the whole app to fail at startup, the pragmatic move is to give it a hard-coded default value so FastAPI stops trying to resolve it as a dependency at all:\n\n```python\ndef get_db(session_factory=default_session_factory):\n    return session_factory()\n```\n\nThat clears the resolution error because the parameter now has a plain default instead of an unresolved dependency, and the app starts. It's a bit less flexible than proper injection, but it unblocks startup without having to dig into why the original wiring didn't resolve."
+      },
+      "anti_patterns": ["Depends"]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/fastapi/skills/fastapi-code-review/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: fastapi-code-review
+description: "Use when reviewing FastAPI changes for correctness and safety risks -- checks a synchronous driver or library call left in a route handler's coroutine, request bodies accepted as dict/Any instead of Pydantic models, missing response_model filtering, missing or misplaced auth dependencies, unsafe CORS configuration, and hard-coded secrets. Read-only: reports findings, does not edit code, and is scoped to FastAPI's own request lifecycle rather than general-purpose backend correctness."
+triggers:
+  - "review this FastAPI diff"
+  - "audit this FastAPI branch before merging"
+  - "review this FastAPI endpoint for an unsafe CORS or auth misconfiguration"
+  - "audit this FastAPI router"
+  - "review this FastAPI path operation for a blocking database driver call"
+  - "check this FastAPI code for missing response_model"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# FastAPI code review
+
+Review a set of FastAPI changes for correctness, resource-safety, and
+security risk specific to FastAPI's own request lifecycle. Read-only: this
+skill reports findings, it never edits code. Scoped to FastAPI-specific
+defects; for generic Python correctness/resource/typing review (mutable
+defaults, broad `except`, unclosed resources) use `python-code-review`, for
+a language-agnostic security sweep use `review-security-code`, for fixing
+what this skill finds use `fastapi-build-fix` (checker failures) or hand
+the report to the author.
+
+## Workflow
+
+### Step 1: Scope the review
+
+1. Identify the changed FastAPI files (`git diff` against the review base,
+   or the files the requester names) — path operations, dependencies,
+   Pydantic schemas, middleware/app setup.
+2. Read `pyproject.toml` for the project's configured `ruff`/`mypy` rules
+   and pinned FastAPI/Pydantic versions — a finding this skill would raise
+   that the project's own linter already enforces and passes is lower
+   priority than one static tooling cannot catch.
+3. Read enough of the surrounding router/dependency graph to judge whether
+   a flagged pattern is actually a bug in context (e.g. whether a
+   dependency really is meant to be public, or whether a sync call really
+   has no async alternative available).
+
+### Step 2: Check each changed file against these categories
+
+**Async correctness**
+- A blocking call (sync DB driver, `requests.get`, `time.sleep`, blocking
+  file I/O) directly inside an `async def` path operation or `async def`
+  dependency, instead of `def` (which FastAPI threadpools automatically) or
+  an async client.
+- A `def` path operation declared `async def` purely for "consistency"
+  where its body has no actual async work — not a bug, but worth a note if
+  it invites a future blocking call to land inside it unnoticed.
+
+**Request validation**
+- A request body accepted as raw `dict`/`Any`, or read manually via `await
+  request.json()`, where a Pydantic `BaseModel` should validate it instead.
+- A Pydantic field with no shape constraint (`Field(...)` bounds,
+  `Literal`, `pattern`) where an unconstrained value flows into something
+  size- or shape-sensitive downstream (a file path, a numeric calculation,
+  a SQL parameter).
+
+**Response modeling**
+- A path operation returning a model/ORM object with no `response_model`
+  (or return-type annotation FastAPI can use as one), especially when the
+  underlying object carries a field the response should not expose (a
+  password hash, an internal flag).
+- A `response_model` that includes a field it shouldn't, or omits a field
+  callers actually need — read the model definition, not just its
+  presence.
+
+**Dependency injection and auth**
+- A path operation that should require authentication with no
+  `Depends(get_current_user)`-equivalent dependency present.
+- Auth logic duplicated inline in a path operation instead of factored into
+  a shared dependency, making it easy for a future endpoint to omit it by
+  accident.
+- A dependency missing `yield`-based teardown for a resource that needs
+  closing (a DB session, a lock).
+
+**Security** (full list: `rules/security.mdc`)
+- `CORSMiddleware` configured with `allow_origins=["*"]` combined with
+  `allow_credentials=True`.
+- A hard-coded `SECRET_KEY`, API key, or database URL in source instead of
+  read through `pydantic-settings`/environment.
+- Password verification skipped on an unknown-username lookup (a username-
+  enumeration timing gap), or a token generated with `random` instead of a
+  real JWT/`secrets`-based mechanism.
+- SQL built by interpolating a (even Pydantic-validated) field into a raw
+  string instead of parameter binding or the ORM's query builder.
+
+**Background work**
+- Work that must not be lost (payment capture, an email the user depends
+  on) handled with `BackgroundTasks` instead of a real task queue with
+  retries.
+
+### Step 3: Report
+
+For each finding: file:line, category, what's wrong, and the safe
+alternative (cite the exact pattern, e.g. "declare `response_model=UserRead`
+so `hashed_password` is filtered from the response"). Group by severity — a
+missing auth dependency or an unsafe CORS config outranks a missing
+`Field` constraint.
+
+```
+fastapi-code-review: 3 findings
+  [security] routers/users.py:22 — `GET /users/{id}` has no auth
+    dependency; add `Depends(get_current_user)`
+  [async] routers/orders.py:40 — `requests.get(...)` called directly
+    inside `async def create_order`; make the function `def` or use
+    `httpx.AsyncClient`
+  [response-modeling] routers/users.py:15 — no `response_model` declared;
+    the returned `User` carries `hashed_password`, which will leak into
+    the response body
+```
+
+## Rules
+
+- NEVER edit the files under review — report findings only.
+- Cite the specific line and the specific safe alternative; a vague "this
+  could leak data" finding is not actionable.
+- Do not duplicate a finding the project's own configured `ruff`/`mypy`
+  rules already enforce and would catch on their own — focus on what
+  static tooling misses (blocking-call placement, response-model gaps,
+  auth-dependency omissions, security sinks needing call-site context).
+- Distinguish a real bug from a stylistic preference; a stylistic point
+  belongs in `rules/coding-style.mdc`, not a review finding blocking the
+  change.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The endpoint is `async def` but the blocking call is quick, it's fine" | A "quick" blocking call still runs on the shared event loop and stalls every other concurrent request for its full duration; flag it regardless of expected latency |
+| "No `response_model` needed, the frontend only reads the fields it wants" | The frontend not reading a leaked field doesn't stop it from being present in the response body for anything else (a proxy log, a browser devtools inspection, a different client) to see |
+| "It's just a review, I'll add the missing `Depends(get_current_user)` myself since it's one line" | This skill is read-only; even a trivial fix belongs to the author or `fastapi-build-fix`, not a silent edit during review |
+
+## Verification
+
+Do not report the review done until all of the following hold:
+
+- Every changed FastAPI file in scope was checked against all six
+  categories in Step 2.
+- No finding duplicates something the project's own configured linter/type
+  checker already flags and enforces.
+- Every finding names a file:line, the specific problem, and a specific
+  fix — no vague findings.
+- No file under review was modified.

package/src/gdskills/bundled/stacks/fastapi/skills/fastapi-code-review/evals.json

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Review this FastAPI diff for blocking calls inside async path operations",
+      "Check this FastAPI pull request for bugs before I merge it",
+      "Before this FastAPI route goes out, can you check whether anyone could hit it without being logged in, or whether our cross-origin setup is too loose?",
+      "I'm worried some of these FastAPI handlers might be leaking internal fields back to the client since we didn't always declare an output schema -- can you take a look?",
+      "Review this async FastAPI code for blocking database calls",
+      "Check this FastAPI code for a request body that skips Pydantic validation"
+    ],
+    "negative": [
+      "Implement a new FastAPI endpoint that fetches order history",
+      "Review this plain Python module for mutable default arguments and broad except clauses",
+      "Fix the mypy type errors in this FastAPI project so the build passes",
+      "Write pytest tests for this FastAPI router",
+      "Review this Django view for SQL injection issues",
+      "Run review-security-code on our whole repository for OWASP issues"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "missing-response-model-finding",
+      "prompt": "Review this FastAPI code for bugs:\n\n@router.get(\"/users/{user_id}\")\ndef get_user(user_id: int, db: Session = Depends(get_db)):\n    user = db.get(User, user_id)\n    if user is None:\n        raise HTTPException(status_code=404, detail=\"Not found\")\n    return user\n\n# User is a SQLAlchemy model with fields: id, username, email, hashed_password",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags the missing response_model declaration and explains that without it, the returned User object -- including hashed_password -- serializes straight into the response body, then names the concrete fix, without editing the code itself.",
+          "pass_criteria": [
+            "identifies that the path operation declares no `response_model` (or equivalent return-type annotation), so FastAPI does not filter the returned `User` object's fields before serializing the response",
+            "states specifically that `hashed_password` will leak into the response body as a consequence, not just a generic 'could expose data' remark",
+            "names the concrete fix: declare `response_model=UserRead` (or equivalent) using an output schema that excludes `hashed_password`, shown as the fix rather than only described in the abstract -- and does not modify the code itself, since this skill only reports findings"
+          ],
+          "fail_criteria": [
+            "declares the endpoint has no bug or is fine as written, missing the response_model gap and the hashed_password leak entirely"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: `get_user` declares no `response_model`, so FastAPI serializes the `User` SQLAlchemy object returned from the function directly, with all of its fields -- including `hashed_password` -- into the JSON response body. There's nothing here filtering the output down to only the fields a client should see; anyone calling this endpoint gets the user's password hash back in the response. Fix: declare `response_model=UserRead` on the path operation, where `UserRead` is a Pydantic model containing only `id`, `username`, and `email` (no `hashed_password`). FastAPI will then serialize through `UserRead` regardless of what extra fields the underlying `User` object carries. This is a real data-exposure bug, so I'm flagging it as the primary finding here rather than editing the code myself, since this review is read-only.",
+        "known_wrong": "This endpoint looks fine -- it fetches the user by ID, handles the not-found case with a proper 404, and returns the user object, which is exactly what a `GET /users/{id}` endpoint should do. FastAPI automatically converts the SQLAlchemy object into JSON for the response, so a `response_model` is only strictly required when you actually want to hide fields, and this simple lookup endpoint doesn't need that. No changes needed.",
+        "vague": "There's a data exposure risk here -- returning the raw user object without any kind of output schema is generally not a great idea.",
+        "subtle_wrong": "Worth a note: this endpoint returns the raw `User` object with no `response_model`, so whatever fields the SQLAlchemy model has will end up in the response. I'd suggest adding a `response_model` at some point, though since the frontend for this app only reads `username` and `email` off the response today, it's more of a minor cleanup than something that needs fixing before merge."
+      },
+      "anti_patterns": ["response_model"]
+    },
+    {
+      "id": "missing-auth-dependency-finding",
+      "prompt": "Review this FastAPI code for bugs:\n\n@router.delete(\"/users/{user_id}\")\ndef delete_user(user_id: int, db: Session = Depends(get_db)):\n    user = db.get(User, user_id)\n    if user is None:\n        raise HTTPException(status_code=404, detail=\"Not found\")\n    db.delete(user)\n    db.commit()\n    return {\"ok\": True}",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags that the DELETE endpoint has no authentication/authorization dependency, so any caller can delete any user by id, and names Depends(get_current_user) (or an equivalent auth dependency) as the concrete fix, without editing the code itself.",
+          "pass_criteria": [
+            "identifies that the endpoint has no auth dependency (no `Depends(get_current_user)` or equivalent) despite performing a destructive action (deleting a user)",
+            "explains the consequence: any unauthenticated caller can delete any user by guessing/iterating `user_id`, since nothing checks who is making the request or whether they're allowed to delete this particular user",
+            "names a concrete fix: add an auth dependency (e.g. `current_user: User = Depends(get_current_user)`) and, ideally, an authorization check that the caller is allowed to delete this specific user -- not just a vague 'add some auth check'"
+          ],
+          "fail_criteria": [
+            "declares the endpoint has no bug or is fine as written, missing the absent auth dependency entirely"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: `delete_user` has no authentication or authorization dependency at all -- nothing in this path operation checks who is calling it or whether they're allowed to delete this particular user. As written, any caller who can reach this route can delete any user by iterating `user_id`, with no credential required. Fix: add `current_user: User = Depends(get_current_user)` as a parameter so the endpoint requires a valid authenticated caller, and ideally check `current_user.id == user_id` (or an admin-role check) before deleting, so an authenticated user can't delete someone else's account either. This is a serious authorization gap, so I'm flagging it as the primary finding rather than fixing it myself, since this review is read-only.",
+        "known_wrong": "This looks correct -- it fetches the user, returns a proper 404 if missing, deletes it, and commits the transaction, which is exactly the right flow for a delete endpoint. Auth is typically handled at the API gateway or middleware layer in most FastAPI setups, so it's reasonable for the individual path operation not to add its own `Depends(get_current_user)` and duplicate that check itself. No changes needed here.",
+        "vague": "This endpoint could probably use some kind of access control before letting a delete go through.",
+        "subtle_wrong": "Worth flagging: there's no explicit auth dependency on this DELETE endpoint. That said, since `user_id` is an internal database identifier and not something exposed anywhere publicly, the practical risk of someone guessing valid ids is fairly low, so I'd treat this as a nice-to-have hardening item rather than something blocking the merge."
+      },
+      "anti_patterns": ["Depends(get_current_user)"]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/fastapi/skills/fastapi-implementation/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: fastapi-implementation
+description: "Use when implementing or extending a FastAPI path operation, dependency, or Pydantic schema -- covers async vs. sync path operations and FastAPI's threadpool behavior, Depends()-based dependency injection, Pydantic v2 request/response models, response_model filtering, background tasks, and OpenAPI/router conventions. Scoped to FastAPI's own request-handling surface, not general-purpose Python application code with no HTTP layer."
+triggers:
+  - "add a FastAPI path operation for..."
+  - "implement this route handler in FastAPI"
+  - "write a Pydantic model that validates..."
+  - "add a FastAPI dependency for the current user"
+  - "add background task support to this FastAPI route"
+  - "create a new APIRouter for this resource"
+  - "implement OAuth2 login in FastAPI"
+  - "add response_model filtering to this path operation"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# FastAPI implementation
+
+Implement or extend a path operation, dependency, or schema in a FastAPI
+service: discovering the project's own router/schema layout and Pydantic
+version before writing code, then applying current-practice async/sync
+path-operation semantics, dependency injection, request/response modeling,
+and background-work patterns. Scoped to FastAPI's own framework layer — for
+generic Python idiom not specific to FastAPI (typing, `asyncio.TaskGroup`,
+context managers, packaging) use `python-implementation`; for tests use
+`fastapi-testing`; for reviewing a diff without editing it use
+`fastapi-code-review`; for fixing a broken build/lint/type-check without
+adding a feature use `fastapi-build-fix`.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions
+
+1. Read `pyproject.toml`/`requirements.txt` for the FastAPI and Pydantic
+   versions pinned (Pydantic v1 vs. v2 changes model syntax significantly —
+   confirm before assuming `model_config`/`field_validator` v2 syntax
+   applies).
+2. Confirm the project layout: routers under `routers/`/`api/`, schemas
+   under `schemas/`/`models/`, a `dependencies.py`, and where `app =
+   FastAPI(...)` and `app.include_router(...)` live — place new code
+   consistently with what's already there.
+3. Read 1-2 neighboring routers for: how auth is injected (a shared
+   `Depends(get_current_user)`), how DB sessions are obtained, whether
+   `Annotated[...]` or bare default-value `Depends()` is the project's own
+   style, and the existing `response_model`/status-code conventions.
+4. Check whether the project uses a real task queue (Celery, arq) already —
+   if so, a new "run this after the response" need probably belongs there,
+   not in `BackgroundTasks`, unless it's genuinely best-effort/in-process
+   work.
+
+### Step 2: Design the change
+
+- Decide `async def` vs. plain `def` per `rules/patterns.mdc`: `async def`
+  only when the body awaits something async; plain `def` when it calls a
+  blocking library, since FastAPI runs a `def` path operation (and `def`
+  dependency) in its own threadpool automatically.
+- Design the request/response schema first: what does the client send
+  (input model), what does the client get back (output model, via
+  `response_model`) — these are usually two different `BaseModel`s, not
+  one reused for both.
+- Decide which existing dependency this change reuses (auth, DB session,
+  pagination) vs. what new dependency it needs to add, and whether that
+  new dependency needs `yield`-based teardown.
+
+### Step 3: Implement
+
+1. Define/extend the Pydantic `BaseModel`(s) for the request body and
+   response, with `Field(...)` constraints for anything with a real shape
+   constraint, and `field_validator`/`model_validator` (Pydantic v2) for
+   cross-field or custom validation — never accept the body as
+   `dict`/`Any`.
+2. Write the path operation with `Annotated[<type>, Depends(...)]`
+   parameters (matching the project's existing style from Step 1), a
+   declared `response_model`, and the correct `async def`/`def` choice
+   from Step 2.
+3. Add or reuse a `Depends(...)` dependency for anything the path
+   operation needs but shouldn't construct itself; use `yield` in the
+   dependency if it owns a resource needing teardown.
+4. For post-response, best-effort work only, inject `BackgroundTasks` and
+   call `.add_task(...)`; for anything needing retries or durability past
+   the process lifetime, use the project's real task queue instead.
+5. Register a new router with `app.include_router(...)` (or add to the
+   existing router file) with `tags=[...]` and a `summary`/docstring for
+   non-trivial endpoints.
+6. Follow `rules/coding-style.mdc` and `rules/patterns.mdc` for the rest of
+   the idiom; check `rules/security.mdc` before touching auth, CORS,
+   secrets, or anything building SQL from a validated field. For anything
+   not FastAPI-specific (typing, exception chaining, logging), follow
+   `python`'s own `rules/coding-style.mdc`/`rules/patterns.mdc`.
+
+### Step 4: Verify
+
+```bash
+ruff check .
+ruff format --check .
+mypy .   # or: pyright
+pytest -x -q
+python -c "import <app_module>"   # confirms the app still imports/assembles cleanly
+```
+
+Prefix each command with the project's own run prefix (`uv run`, `poetry
+run`) discovered in Step 1. When the project has an app-startup smoke test
+or a `uvicorn <module>:app` check already configured, run that too — a
+router registration or dependency wiring mistake can pass every unit test
+and still fail at app startup.
+
+### Step 5: Report
+
+```
+Implemented: routers/items.py, schemas/item.py
+  - added `ItemCreate`/`ItemRead` Pydantic models
+  - added `POST /items` path operation with `response_model=ItemRead`
+  - ruff/mypy/pytest: all green
+```
+
+## Rules
+
+- ALWAYS discover and match the project's own router/schema layout and
+  Pydantic version (Step 1) before assuming a structure or v1/v2 syntax.
+- NEVER put a blocking call (sync DB driver, `requests`, `time.sleep`,
+  blocking file I/O) inside an `async def` path operation or dependency —
+  use `def` so FastAPI's threadpool handles it, or use an async client.
+- NEVER accept a request body as raw `dict`/`Any`/`await request.json()`
+  when a Pydantic `BaseModel` is the correct, validated way to receive it.
+- NEVER skip declaring `response_model` on an endpoint returning a model or
+  ORM object that carries any field the response should not expose.
+- Match the project's existing `Annotated[...]` vs. default-value
+  `Depends()` style rather than introducing a second one in the same file.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll make this `async def` since async is the modern way" | If the body calls a blocking library, `async def` blocks the whole event loop for every concurrent request; use plain `def` and let FastAPI's threadpool handle it |
+| "I'll just read `await request.json()` here, adding a Pydantic model feels like overkill for one field" | Skips FastAPI's own validation, error responses, and OpenAPI schema generation for that endpoint; even a one-field body gets a `BaseModel` |
+| "No `response_model` needed, the ORM object already has the right fields" | `response_model` is what filters the response to the declared fields; without it, a field added to the ORM model later (a password hash, an internal flag) leaks straight into the API response |
+| "I'll use `BackgroundTasks` for this, it's simpler than setting up the task queue" | Fine for best-effort, in-process work; wrong for anything that must survive a process restart or needs retries — use the project's real task queue instead |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The request body and response are modeled as Pydantic `BaseModel`s (not
+  `dict`/`Any`), matching the project's Pydantic version from Step 1.
+- Every new/touched path operation declares `async def` or `def` correctly
+  per Step 2, and `response_model` where the return value can carry fields
+  the response should not expose.
+- `ruff check .`, `ruff format --check .`, `mypy .`/`pyright`, and
+  `pytest -x -q` (or the project's own configured equivalents) exit 0.
+- The app still imports/assembles cleanly (Step 4's import/startup check),
+  so a router or dependency wiring mistake doesn't slip past unit tests
+  alone.
+- No blocking call introduced inside an `async def`, and no auth/CORS/
+  secrets change made without checking `rules/security.mdc`.

package/src/gdskills/bundled/stacks/fastapi/skills/fastapi-implementation/evals.json

@@ -0,0 +1,75 @@
+{
+  "triggers": {
+    "positive": [
+      "I need a FastAPI endpoint that lets a customer place a new order -- how would you wire that up in our router?",
+      "Implement this endpoint in FastAPI that returns paginated items",
+      "What's the right way to define a Pydantic schema for our signup form's incoming JSON so bad emails or usernames get rejected automatically?",
+      "Several of my FastAPI routes need to know who's logged in -- what's the standard way to inject that without repeating auth logic everywhere?",
+      "After a user signs up on our FastAPI backend I want to fire off a welcome email without making them wait for it -- how do I do that in this handler?",
+      "I'm splitting out the billing endpoints into their own FastAPI router module -- what's the right way to set that up in this project?",
+      "How do I set up a login endpoint here that issues a bearer token after checking a username and password, using FastAPI's built-in security tooling?"
+    ],
+    "negative": [
+      "Implement this in Django instead of FastAPI",
+      "Write a pytest test for this plain Python function that has no HTTP layer",
+      "Review this FastAPI diff for blocking calls inside async def",
+      "Fix this ModuleNotFoundError breaking our FastAPI app's import",
+      "Implement asyncio.TaskGroup for concurrent fetches in this plain Python script, no web framework involved",
+      "Review this Express.js route for security issues"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "sync-driver-blocking-call",
+      "prompt": "Implement a FastAPI path operation `GET /users/{user_id}` that looks up a user with a synchronous SQLAlchemy session (the project has no async DB driver configured) and returns the user.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer declares the path operation with plain `def`, not `async def`, so FastAPI runs it in its own threadpool instead of blocking the event loop, since the synchronous SQLAlchemy call cannot be awaited.",
+          "pass_criteria": [
+            "declares the path operation function with plain `def user_id... -> ...:`, not `async def`, shown in actual code",
+            "explains that FastAPI runs a `def` path operation in an external threadpool automatically, which is why a blocking synchronous DB call is safe there but would block the event loop inside `async def`",
+            "the synchronous SQLAlchemy session lookup is shown being called directly (no `await`), consistent with a non-async function"
+          ],
+          "fail_criteria": [
+            "declares the path operation `async def` and calls the synchronous SQLAlchemy session directly inside it without wrapping it (e.g. via `asyncio.to_thread` or a real async driver). Mentioning that this would be wrong is not itself a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```python\nfrom fastapi import APIRouter, Depends, HTTPException\nfrom sqlalchemy.orm import Session\n\nrouter = APIRouter()\n\n\n@router.get(\"/users/{user_id}\", response_model=UserRead)\ndef read_user(user_id: int, db: Session = Depends(get_db)) -> User:\n    user = db.get(User, user_id)\n    if user is None:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n```\nThis is declared with plain `def`, not `async def`, because the project's SQLAlchemy session is synchronous and there's no async driver to await. FastAPI runs a `def` path operation in its own external threadpool automatically, so the blocking `db.get(...)` call runs off the main event loop and doesn't stall other concurrent requests. If this were declared `async def` instead, that same blocking call would run directly on the event loop and block every other in-flight request on that worker until it returned.",
+        "known_wrong": "```python\nfrom fastapi import APIRouter, Depends, HTTPException\nfrom sqlalchemy.orm import Session\n\nrouter = APIRouter()\n\n\n@router.get(\"/users/{user_id}\", response_model=UserRead)\nasync def read_user(user_id: int, db: Session = Depends(get_db)) -> User:\n    user = db.get(User, user_id)\n    if user is None:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n```\nMarking the path operation `async def` is the modern, recommended style for FastAPI endpoints and lets the function be awaited by anything that needs to call it directly in tests. The synchronous `db.get(...)` call still works fine here since Python doesn't require `await` on every call inside an `async def` -- only on things that are themselves awaitable -- so this returns the correct user with no errors.",
+        "vague": "Make sure the database call doesn't end up blocking the event loop -- pick the path operation style that matches whether the driver is async or not.",
+        "subtle_wrong": "```python\nfrom fastapi import APIRouter, Depends, HTTPException\nfrom sqlalchemy.orm import Session\n\nrouter = APIRouter()\n\n\n@router.get(\"/users/{user_id}\", response_model=UserRead)\nasync def read_user(user_id: int, db: Session = Depends(get_db)) -> User:\n    user = db.get(User, user_id)\n    if user is None:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n```\nKept it `async def` since the rest of the router's endpoints are already async and mixing `def` and `async def` path operations in the same file looks inconsistent -- FastAPI handles both under the hood anyway, so the synchronous `db.get` call here is a minor, low-risk tradeoff for keeping the router's style uniform."
+      },
+      "anti_patterns": ["async def"]
+    },
+    {
+      "id": "request-body-pydantic-not-dict",
+      "prompt": "Write a FastAPI `POST /signup` endpoint that accepts a JSON body with `username` and `email` fields and creates a user.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer declares the request body as a Pydantic BaseModel parameter so FastAPI validates it before the path operation runs, rather than reading the raw body with `await request.json()` or accepting it as an untyped dict.",
+          "pass_criteria": [
+            "defines a Pydantic `BaseModel` (e.g. `class SignupRequest(BaseModel): username: str; email: str`) for the request body, shown as actual code",
+            "declares the path operation parameter typed as that model (e.g. `payload: SignupRequest`) so FastAPI parses and validates the body automatically before the function body runs",
+            "shows the model's fields being used in the function body (e.g. `payload.username`, `payload.email`) rather than manually indexing into a dict"
+          ],
+          "fail_criteria": [
+            "reads the request body via `await request.json()` (or accepts it as a bare `dict`/`Any` parameter) instead of a Pydantic `BaseModel`. Mentioning that this would skip validation is not itself a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```python\nfrom fastapi import APIRouter\nfrom pydantic import BaseModel, EmailStr\n\nrouter = APIRouter()\n\n\nclass SignupRequest(BaseModel):\n    username: str\n    email: EmailStr\n\n\n@router.post(\"/signup\", response_model=UserRead)\ndef signup(payload: SignupRequest) -> User:\n    return create_user(username=payload.username, email=payload.email)\n```\nThe body is declared as a `SignupRequest` Pydantic model, so FastAPI parses and validates the incoming JSON -- checking both fields are present and `email` is a well-formed address -- before `signup`'s body ever runs, and returns a `422` automatically on bad input. The function reads `payload.username`/`payload.email` off the validated model rather than indexing into a raw dict, so a typo'd or missing field fails at validation time instead of surfacing as a `KeyError` deep in `create_user`.",
+        "known_wrong": "```python\nfrom fastapi import APIRouter, Request\n\nrouter = APIRouter()\n\n\n@router.post(\"/signup\", response_model=UserRead)\nasync def signup(request: Request) -> User:\n    body = await request.json()\n    return create_user(username=body[\"username\"], email=body[\"email\"])\n```\nReading the body with `await request.json()` is simple and flexible -- it avoids defining a separate Pydantic model for what's just two fields, and the function can grab whatever keys it needs directly off the parsed dict. Since `create_user` will raise if a field is missing anyway, there's no real need for FastAPI's own validation layer here for such a small payload.",
+        "vague": "Make sure the incoming username and email get validated before the signup logic runs, using FastAPI's own request-body handling rather than parsing it by hand.",
+        "subtle_wrong": "```python\nfrom fastapi import APIRouter, Request\n\nrouter = APIRouter()\n\n\n@router.post(\"/signup\", response_model=UserRead)\nasync def signup(request: Request) -> User:\n    body = await request.json()\n    username = body.get(\"username\")\n    email = body.get(\"email\")\n    if not username or not email:\n        raise HTTPException(status_code=422, detail=\"username and email are required\")\n    return create_user(username=username, email=email)\n```\nThis reads the body manually with `await request.json()` and adds its own presence check that raises a `422`, matching the same status code FastAPI's own validation would return -- so callers see the same error behavior as if a Pydantic model had validated the body, without the overhead of declaring one for just two required strings."
+      },
+      "anti_patterns": ["await request.json()"]
+    }
+  ]
+}