velcrafting Skill: api/contract-update
Purpose
Update API request/response contracts in a controlled, explicit way so that:
- producers and consumers remain aligned
- breaking changes are intentional and visible
- schema drift is prevented
This skill owns shape, not behavior.
Inputs
- Endpoint or event identifier
- Old vs new contract (fields added/removed/changed)
- Compatibility requirement:
- backward-compatible
- versioned
- breaking (explicit)
- Repo profile (preferred):
<repo>/REPO_PROFILE.json
Outputs
- Updated contract definition(s):
- OpenAPI / schema / types / DTOs (repo-specific)
- Client wiring updates if co-located
- Compatibility notes in code comments or docs (if repo standard)
Non-goals
- Implementing backend behavior
- Implementing frontend UI logic
- Persistence changes
Workflow
- Locate canonical contract source (schema/types/spec).
- Apply change using additive-first strategy when possible.
- Mark deprecated fields explicitly if supported.
- Update generated or handwritten client bindings if present.
- Ensure no behavior assumptions leak into the contract.
- Run schema/type validation if available.
If the contract change introduces conditional behavior or stateful flows,
recommend system/state-machine-mapper.
Checks
- Contract compiles/validates
- Consumers still typecheck (or explicit break documented)
- No behavior encoded in schema comments
Failure modes
- Breaking change without versioning → block and escalate.
- Contract ambiguity → recommend
meta/spec-sculptor.
Telemetry
Log:
- skill:
api/contract-update - change_type:
additive | breaking | versioned - endpoints_affected
- outcome