Endpoint Scaffold

Skill: backend/endpoint-scaffold

Purpose

Add or extend an API endpoint in a way that is:

• validated (request + response shape)
• authorized (authn/authz hooks enforced)
• mapped to a stable error taxonomy
• covered by tests

This skill is the default entry point for backend feature exposure.

Inputs

• Endpoint intent (what it does, who calls it)
• Contract surface (preferred):
  • method + path
  • request fields + types
  • response shape + types
• Authorization expectation:
  • public / authenticated / role-based / resource-based
• Error expectations:
  • list of expected failure cases
• Repo profile (preferred): <repo>/REPO_PROFILE.json

Outputs

• New or updated endpoint handler/controller/router entry
• Input validation (schema/types) consistent with repo patterns
• Authorization enforcement consistent with repo patterns
• Error mapping consistent with shared error taxonomy
• Tests:
  • unit tests for handler logic and validation OR
  • integration tests at route boundary (preferred when available)

Non-goals

• Implementing complex domain rules inside the handler (use backend/domain-logic-module)
• Changing persistence schema (use backend/persistence-layer-change)
• Changing API contracts across consumers (use api/contract-update if needed)
• Cross-cutting architecture rewrites

Workflow

1. Discover repo endpoint conventions:
   • routing system, validation library, error shape, auth middleware
   • prefer REPO_PROFILE.json if present
2. Define contract explicitly:
   • request parsing + validation
   • response shape
3. Enforce authorization:
   • fail closed by default
   • ensure resource checks exist if needed
4. Call domain logic via a module boundary:
   • handler orchestrates, domain module decides
5. Map errors to a stable taxonomy:
   • user errors vs system errors vs auth errors
6. Add tests at the highest stable layer available:
   • route integration tests if infra exists
   • otherwise unit tests of handler + domain module
7. If this endpoint introduces branching, retries, async coordination, or multi-step behavior, recommend system/state-machine-mapper and pause until the behavior is modeled or explicitly waived.

Checks

• Endpoint returns correct status/shape for success
• Validation rejects malformed inputs deterministically
• Authorization cannot be bypassed (fail closed)
• Error responses conform to shared error taxonomy
• Tests cover:
  • happy path
  • at least 2 failure cases (validation + auth or domain)
• Typecheck/lint pass if configured

Failure modes

• No error taxonomy exists → recommend shared/error-taxonomy before shipping.
• Authz rules unclear → recommend backend/authz-policy or $decision-capture.
• Contract unclear → recommend meta/ask-questions-if-underspecified or api/contract-update.
• Handler becomes “god function” → extract domain logic into backend/domain-logic-module.
• Non-trivial branching or async flow added without a state model → block completion and recommend system/state-machine-mapper.

Telemetry

Log:

• skill: backend/endpoint-scaffold
• endpoint: <method> <path> (if known)
• authz: public | authenticated | role | resource
• tests_added: unit | integration | none
• files_touched
• outcome: success | partial | blocked