api-contract

Purpose

Detects field-name, type, and nullable/optional mismatches across the layers defining an API entity: the ORM schema (apps/<mainApp>/src/lib/db/schema.ts), the Zod schema, the route handler's JSON response, and the SQL migrations in the infrastructure repo. Examples use Drizzle and Flyway-style migrations — adapt to the project's stack (project.json -> stack.db). Read-only: fixes go to @implementation-agent or a developer.

Rules (never violate)

• Read-only skill (Read, Grep, Glob) — never auto-fix a mismatch; refuse if asked.
• Every finding cites file:line and carries a severity; findings below 80% confidence are marked [LOW-CONFIDENCE].
• The report contains zero placeholder text and ends with CONTRACT-ISSUES: {entity} | CRITICAL: {n} | HIGH: {n} | MEDIUM: {n} | LOW: {n}.
• A field name that differs between layers is this skill's job; a naming convention preference belongs to code-standards.
• Do not flag Zod .optional() vs ORM .default(), migration-tool bookkeeping tables, or vendored/generated files; wire-protocol fields keep UPPER_SNAKE_CASE.
• Stop and ask on an ORM type with no Zod equivalent, or >10 Critical findings in one entity.

Resources

• Read resources/verification-procedure.md when running a check — the 7-step procedure, output template, severity criteria, self-check, escalation, and failure modes.
• Read resources/worked-example-device.md when you need a full end-to-end example with real code across all four layers.

How to use

What it does

Checks that one API entity means the same thing in every layer: it reads the ORM table, the Zod schema, the route handler's JSON response, and the SQL migration, then compares them field by field and reports every mismatch with a file:line citation, a severity, and a suggested fix. It never edits code.

When to use it

• You added, renamed, or retyped an ORM column and want to know what drifted.
• You changed a route handler's response shape or wrote a new Zod schema.
• A SQL migration landed and the ORM table definition needs verification.