Workflow

Trace the affected route, request, resource, service, and contract test before changing the API surface.
When route, payload, or resource shape changes, update contract metadata, generated artifacts, and gate tests in the same batch.
Prefer additive changes. If a breaking change is required, call it out explicitly and update docs or runbooks.
Treat generated artifacts and route inventories as reviewed outputs, not scratch files.
Keep release and runtime gates green after contract changes.

Guardrails

Do not hand-edit generated API outputs unless the generator explicitly requires it.
Minimize route alias churn; preserve compatibility when possible.
Keep controllers thin and let request or resource objects own validation and shaping concerns.
Contract drift across routes, OpenAPI artifacts, and tests counts as a bug even if the feature test still passes.

Read AGENTS.md, .codex/AGENTS.md, and references/paths.md before editing.

Trace the affected route, request, resource, service, and contract test before changing the API surface.
When route, payload, or resource shape changes, update contract metadata, generated artifacts, and gate tests in the same batch.
Prefer additive changes. If a breaking change is required, call it out explicitly and update docs or runbooks.
Treat generated artifacts and route inventories as reviewed outputs, not scratch files.
Keep release and runtime gates green after contract changes.

Do not hand-edit generated API outputs unless the generator explicitly requires it.
Minimize route alias churn; preserve compatibility when possible.
Keep controllers thin and let request or resource objects own validation and shaping concerns.
Contract drift across routes, OpenAPI artifacts, and tests counts as a bug even if the feature test still passes.