home / skills / velcrafting / codex-skills / contract-update

contract-update skill

This skill updates API contracts and client wiring to keep producers and consumers aligned, preventing schema drift and surfacing breaking changes clearly.

npx playbooks add skill velcrafting/codex-skills --skill contract-update

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.9 KB

---
name: contract-update
description: Update request/response API contracts and client wiring without business logic.
metadata:
  short-description: API contract evolution
  layer: api
  mode: write
  idempotent: false
---

# 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
1) Locate canonical contract source (schema/types/spec).
2) Apply change using additive-first strategy when possible.
3) Mark deprecated fields explicitly if supported.
4) Update generated or handwritten client bindings if present.
5) Ensure no behavior assumptions leak into the contract.
6) 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

Overview

This skill updates API request/response contracts and related client wiring while keeping business logic untouched. It ensures producers and consumers remain aligned, makes breaking changes explicit, and prevents schema drift through controlled, auditable edits. The skill focuses on shape and types rather than behavior or persistence.

How this skill works

The skill locates the canonical contract source (schema, types, or spec) and applies changes using an additive-first strategy when possible. It marks deprecated fields explicitly, updates co-located client bindings, and runs schema/type validation to ensure the contract compiles and consumers still typecheck. Telemetry records change type, affected endpoints, and outcome for governance and auditing.

When to use it

Adding new fields, endpoints, or event properties without changing behavior
Introducing a deliberate, documented breaking change that requires versioning
Deprecating fields while keeping backward compatibility for consumers
Synchronizing client DTOs or generated clients after a contract change
Validating that schema updates do not encode runtime behavior or state

Best practices

Prefer additive changes and mark deprecated fields rather than removing them immediately
Document explicit breaking changes and increment versioning according to the repo standard
Update client wiring only for contract-related mappings; avoid adding business logic
Run automated schema/type validation and consumer typechecks before merging
Log change_type, endpoints_affected, and outcome for auditability

Example use cases

Add a new optional property to a response DTO and update generated clients
Deprecate an old request field, add its replacement, and annotate both in the contract
Introduce a versioned endpoint when a request shape must change incompatibly
Synchronize type definitions across services to prevent schema drift
Reject a proposed breaking change and escalate for cross-team coordination

FAQ

Will this skill change backend behavior?

No. It only changes shapes, schemas, and client wiring. Implementing business logic remains out of scope.

How are breaking changes handled?

Breaking changes must be explicit and versioned. The skill blocks unversioned breaking edits and logs the issue for escalation.

What validation runs after a contract update?

Schema and type compilation/validation run when available, plus optional consumer typechecks to ensure compatibility.