Skip to content
Docs menu

Contract-first work between agents

Split a change that spans two components into a contract slice and two parallel slices, so a producer and a consumer agent never wait on each other.

View .md

When a change spans two components (a server endpoint and its client, a daemon and the cloud), one agent waiting on the other stalls both. Land the interface first, then build both halves against it in parallel. The contract is the only thing the halves share. Spec to pull requests proposes slices in this shape on its own.

The sequence

  1. Contract slice (a small PR that merges alone). Commit the interface and nothing that implements it:

    • the prose in the normative document,
    • the machine form: JSON Schema, TypeScript types or OpenAPI,
    • fixtures: one valid example per request, response and error, plus a few invalid ones.

    Contract tests read the fixtures against the schema, so this PR is green by itself and changes no behaviour.

  2. Two slices in parallel. Each side branches from the contract commit and builds only against the fixtures:

    • the producer returns the fixture bodies and rejects the invalid ones;
    • the consumer is tested with the fixtures standing in for the producer, with no live server.

    Neither slice edits the contract. A needed change goes back to a new contract PR, and both sides rebase.

  3. Join. A conformance check runs the real producer against the real consumer, or replays the same fixtures through both. It gates the second merge.

Example: a new endpoint

A team adds GET /v1/invoices/{id} to a server and a page that shows it.

PR 1  contract   openapi.yaml: the operation and Invoice schema
                 fixtures/invoice-get.json, fixtures/invoice-get-404.json, fixtures/invoice-bad.json
PR 2  producer   the handler, tested to return the fixture bodies       (starts after PR 1 merges)
PR 3  consumer   the page, tested with the fixtures as a fake server    (starts after PR 1 merges)
join             a conformance test runs the page's client against the real handler

Where venom's own contracts live

Surface Contract Both sides test it
Venom Cloud mesh (daemon and cloud) JSON Schema, TS types, fixtures and timing constants in the cloud's contracts folder the cloud's contract tests and the Go daemon's
venom serve packages/harness-server/openapi.yaml (the harness server API reference, /docs/api/harness-server) the server tests and the Python client's parity test
The /v1 OpenAI surface the official OpenAI SDKs make conformance

Rules

  • The contract PR changes no behaviour, so it needs no feature flag and cannot regress anything.
  • Change the prose, the schema and the fixtures together, never one alone.
  • A fixture is the spec for both sides. If the two implementations disagree, the fixture wins.
  • Agents splitting work on an issue board start the producer and consumer slices together (at most 3 at once); the join slice is the one whose gate runs the conformance check.