git:20260930.dc5adef to git:20260930.a77cb5e

4 added, 1 removed. Audit A to A.

---

name: api-endpoint

description: >

Scaffold a new REST endpoint across the planes. Auto-triggers on:

"add an endpoint", "new API route", "expose this over HTTP", "wire a handler"

allowed-tools: Read, Write, Edit, Bash, Grep, Glob

+ metadata:

+ stage: beta

+ since: "1.0.0"

---

# API Endpoint

- DO NOT add a route before reading the nearest existing handler and the `api-convention` skill.

+ DO NOT add a route before reading the nearest existing handler and `.claude/rules/api-convention.md`.

## 1. Locate

- Which part of the project owns it; find the closest existing endpoint.

- Mirror its file, registration, and owner-scoping pattern.

## 2. Design

- Method, path (`/v1/...`), request/response shape, auth (API-key → identity), per-request owner-scope.

- Cloud/enterprise behavior is flag-gated OFF (`if envBool("FLAG")`, default false).

## 3. Implement

- Handler + route registration + the entry in the project's OpenAPI / API spec.

- Adapter-agnostic: if it touches data, it must hold across every backend the project supports.

## 4. Verify

- Run the relevant check through the project's task runner (detect it with `devil facts`).

- Regenerate SDKs if the spec changed.

- Add a verify gate (a `scripts/verify/` check or CI job) that exercises the route.

## 5. Report

- Files changed, the new route + its auth/owner-scope, and the gate that proves it.