API Contract Sync
Use this for every API behavior change. An endpoint is not done until code,
docs, client examples, and behavior specs agree.
Trigger
Run when changing:
- route path, method, auth, ownership, status code, headers, query params,
payload, DTO/schema, error shape, pagination, sorting, filtering
- controller/service business behavior visible through an API
- generated shared types or API client contracts
Contract Layers
Check only layers that exist in the host repo:
- Controller docs:
@ZodResponse, Swagger/OpenAPI decorators, Scalar setup.
- DTO/schema: Zod/class DTO metadata and exported shared types.
- Bruno:
tools/bruno/**/*.bru request examples and payloads.
- Gherkin:
**/*.feature behavior scenarios.
- Mockoon or generated mocks when the repo uses them.
- Frontend/shared API client types when consumers import the changed symbol.
Workflow
- Read host
AGENTS.md, module README.md, command registry, and nearby
specs/features before editing.
- Find every contract layer for the changed route or DTO.
- Update code and contract files in the same task.
- If a layer is missing, report
not present, not skipped.
- Validate with the smallest declared commands: lint, typecheck, relevant API
tests, contract/spec tests, and build only when required by the change.
Review Gate
Before handoff, answer:
- Which endpoints/DTOs changed?
- Which contract layers were updated?
- Which layers were not present?
- Which commands ran, and did they pass?
If code changed but an existing contract layer was not updated, report the task
as partial.
1---2name: api-contract-sync3description: Keep API code and contract layers synced when endpoints, DTOs, payloads, status codes, query params, auth rules, or business transitions change. Use for API work in projects with OpenAPI/Scalar or Swagger, Bruno, Gherkin, shared client types, or generated mocks.4---56# API Contract Sync78Use this for every API behavior change. An endpoint is not done until code,9docs, client examples, and behavior specs agree.1011## Trigger1213Run when changing:1415- route path, method, auth, ownership, status code, headers, query params,16 payload, DTO/schema, error shape, pagination, sorting, filtering17- controller/service business behavior visible through an API18- generated shared types or API client contracts1920## Contract Layers2122Check only layers that exist in the host repo:2324- Controller docs: `@ZodResponse`, Swagger/OpenAPI decorators, Scalar setup.25- DTO/schema: Zod/class DTO metadata and exported shared types.26- Bruno: `tools/bruno/**/*.bru` request examples and payloads.27- Gherkin: `**/*.feature` behavior scenarios.28- Mockoon or generated mocks when the repo uses them.29- Frontend/shared API client types when consumers import the changed symbol.3031## Workflow32331. Read host `AGENTS.md`, module `README.md`, command registry, and nearby34 specs/features before editing.352. Find every contract layer for the changed route or DTO.363. Update code and contract files in the same task.374. If a layer is missing, report `not present`, not `skipped`.385. Validate with the smallest declared commands: lint, typecheck, relevant API39 tests, contract/spec tests, and build only when required by the change.4041## Review Gate4243Before handoff, answer:4445- Which endpoints/DTOs changed?46- Which contract layers were updated?47- Which layers were not present?48- Which commands ran, and did they pass?4950If code changed but an existing contract layer was not updated, report the task51as partial.
me-cedric