Skill: Contract Handshake and Freeze
Purpose
Ensure that cross-layer contracts (API, data shapes, auth expectations, integration behavior) are:
- •explicit
- •shared
- •agreed upon
- •intentionally frozen before implementation
This skill prevents implicit assumptions, late-breaking changes, and frontend/backend drift.
Trigger
Use this skill whenever ANY of the following occur:
- •a feature requires frontend–backend integration
- •an API endpoint is introduced, modified, or removed
- •request or response schemas change
- •authentication or authorization behavior changes
- •a contract assumption is questioned during implementation
Authoritative references
This skill treats the following as authoritative:
- •
docs/team/WORKFLOW.md→ defines when contracts must exist - •
docs/team/HANDOFF.md→ records contract state (draft,changing,frozen)
Contracts are not considered valid unless recorded in these artifacts.
Inputs
- •feature design artifacts (
docs/features/<feature-slug>/02-design.md) - •relevant epic context
- •frontend and backend integration requirements
- •existing API or integration contracts (if any)
Outputs
This skill MUST produce all of the following:
- •
Explicit contract definition
- •recorded in the feature design artifact
- •includes:
- •endpoints or interfaces
- •request/response shapes
- •auth requirements
- •error behaviors
- •invariants and guarantees
- •
Contract state update in
docs/team/HANDOFF.md- •
Contract: draft | changing | frozen - •list of endpoints/interfaces in scope
- •
- •
Contract freeze signal
- •explicit indication when the contract is frozen
- •timestamped or phase-bound (implicit via artifact state)
Contract states
Draft
- •contract is being explored or negotiated
- •implementation may NOT begin
- •changes are expected
Changing
- •implementation has begun
- •contract changes are exceptional and must be coordinated
- •all affected agents must be notified via HANDOFF
Frozen
- •contract is stable
- •implementation may proceed independently
- •changes require escalation and justification
What this skill enforces (and nothing more)
Explicitness
- •no implicit request/response assumptions
- •no “we’ll figure it out later”
- •no undocumented defaults
Shared understanding
- •frontend and backend agree on the same contract
- •ambiguities are resolved before freezing
Freeze discipline
- •implementation does not outrun contract clarity
- •late changes are intentional and visible
Explicit non-responsibilities
This skill MUST NOT:
- •design internal backend architecture
- •design frontend UI or state management
- •write serializers, views, or clients
- •optimize performance
- •redefine product scope or value
It governs agreements, not implementations.
Interaction with other skills
This skill frequently works with:
- •
workflow-enforcement
→ ensures contracts exist before implementation - •
handoff-coordination
→ coordinates contract negotiation and freeze state - •
api-contract-design
→ may be used to author schemas or examples - •
integration-slice-orchestration
→ uses frozen contracts to sequence FE/BE work - •
bug-management
→ logs defects caused by contract violations
This skill does not replace any of them.
Failure handling
If a contract cannot be agreed upon:
- •Record the disagreement in
docs/team/HANDOFF.md - •Identify unresolved points explicitly
- •Identify required decision-makers
- •Stop implementation
- •Escalate to the Lead for resolution
If a frozen contract is violated:
- •log a bug
- •classify the injected and detected phase
- •block further work until resolved
Acceptance criteria
This skill is successful when:
- •contracts are defined before implementation
- •FE and BE can work in parallel safely
- •contract changes are rare and intentional
- •late integration surprises decrease over time
- •contract-related bugs shift to earlier phases
Design principle
This skill exists to make integration boring.
If integration feels exciting or surprising, this skill is not being applied correctly.