OpenAPI 3.1 and AsyncAPI — API-first design.
After installing contracts, API design starts from the contract, not the code. `api-contract` produces a validated OpenAPI 3.1 spec from requirements, user stories, or a domain model. `event-contract` produces an AsyncAPI 2.x spec for event-driven interfaces. Both skills apply a pluggable house standard — the Zalando guidelines by default, your own base + delta bundle without forking the skill.
api-contract1 gateAuthors an OpenAPI 3.1 contract from requirements or user stories — endpoints, request/response schemas, error codes, and the consumer-perspective check built in.
event-contract1 gateAuthors an AsyncAPI 2.x event contract for a stream interface — message shape, channel bindings, and the producer/consumer boundary made explicit.
You describe the API surface — the resources, actions, and consumers. The agent runs api-contract or event-contract with the pluggable house standard configured (Zalando guidelines by default). It produces a first-draft contract: endpoints, request/response schemas, error codes, and the consumer-perspective check.
You: Watch the draft take shape and note corrections as they arise — don’t wait for the full draft to redirect on a naming convention or a missing error case. Small corrections mid-draft are faster than a full re-generate. If you know the consumer will call this API in a specific way, say so before the agent finalizes the response schemas.
After the first complete draft, the agent runs a self-review against the house standard. You review the contract at the G-contract gate — reading from the consumer’s perspective, not the producer’s.
You: Read through the error responses first. The most common failure mode is a contract that specifies the happy path thoroughly but skips error cases — a 200 response with no corresponding 400, 404, or 500. If an error case is missing, name it explicitly: the agent can’t infer which errors are real without domain knowledge. If the schema field names use inconsistent conventions (camelCase in some places, snake_case in others), correct them here before implementation begins.
The ratified contract is emitted as a versioned OpenAPI 3.1 or AsyncAPI 2.x file, ready to commit alongside the implementation it governs.
You: Confirm the contract file is placed alongside the service it governs — not in a separate repository or a documentation folder that would diverge from the service over time. A contract that lives apart from its implementation drifts silently until a consumer discovers the mismatch.
For each gate, everything you need to make a confident decision.
A contract that names all resources, all error codes, and all schemas — and reads from the consumer's perspective, not the implementation's. Every developer who reads it could build a compatible client without asking the author.
A contract that matches an existing implementation exactly — this means the agent described the implementation rather than the agreed surface. Or a contract that omits all 4xx/5xx error cases.
The contract is the implementation brief for every consumer of this API or event stream. A contract approved with missing error codes means every consumer discovers those errors through production failures, not through the spec.
agentbundle install --pack contracts --scope user