api-designlisted

# API Design: $ARGUMENTS ## Principle A public contract is the kit's heaviest door: once a consumer you don't control depends on it, every field name is permanent and every quirk is load-bearing (Hyrum's law — with enough consumers, *all* observable behavior becomes the contract, including your bugs). So the design order is fixed: **consumers and compatibility promise first, then the resource model, then the mechanics** — and consistency with the house's existing API beats global best practice every time: one project, one dialect. ## Phase 0 — Load context Read `.claude/PROJECT.md` (Architecture — where API code lives; Domain; Integrations), `CONTEXT.md` (names come from the ubiquitous language), and — decisive — **grep the existing API surface**: current endpoints/commands, their casing, envelope shape, error format, auth pattern. Missing/TEMPLATE profile → fall back to the root `CLAUDE.md` (always in context) when it carries the architecture/integrations (note you're running without a kit profile); STOP for `/bootstrap` first only if *neither* has them — the API-surface grep runs regardless. An `/analyst` spec for the feature is the ideal input; without one, get WHAT/WHY first. ## Phase 1 — Consumers and the compatibility promise - **Who calls this** — own frontend / other internal services / third parties / public? Each step outward hardens the door (`core.md`). - **Can you break them?** Sets the promise: internal-only (coordinated change possible) vs versioned-p