--- name: usdl-interfaces-contracts description: Element-targeted Skill that authors exactly one `` + `` pair (and optionally one ``) inside `interfaces.xml`, plus the operation's wire schema. Owns the contracts Interview Script that collects the contract's `id`, `provider` (an internal `top.*` unit), optional `consumers`, mandatory `style` (rest, graphql, grpc, event-stream, command-bus, query-bus, sql-schema, file-format, cli, hardware-protocol, custom), and optional `spec-ref`; then for the operation collects the seven mandatory attributes in fixed order (`id`, `contract`, `name`, `intent`, `mode`, `consistency`, `delivery`, `idempotency`), the optional `realizes-behavior` and `governed-by` cross-references, one or more `` children (with `role` ∈ input/output/error/event/state and `format` ∈ json-schema/openapi/asyncapi/protobuf/avro/xsd/cddl/cap-n-proto/custom), and `` blocks for every failure the consumer must handle. When no authoritative external schema yet exists, the Skill drafts a typed code abstraction (PHP class, Python class, or pseudo-code) in the Skatchbook, invokes the bundled `scripts/schema-derivation/dispatcher.py` (which dispatches to `derive_from_python.py`, `derive_from_php.py`, or `derive_from_pseudo.py`) to derive a JSON Schema, AsyncAPI, or Protobuf document, and has the parent skill write the schema to `./schemas//.` via Bin — never the script directly (per `con.skatchbook-no-direct-spec-writes`). Refuses to declare contracts whose provider is external — those live with the external party (per `how-to-use.md` Stage 5). Trigger this Skill when the active task mentions "contract", "operation", "wire schema", "JSON Schema", "OpenAPI", "AsyncAPI", "Protobuf", "schema derivation", "schema-ref", "failure mode", or `` / `` in the context of authoring or extending `interfaces.xml`. Not user-invocable directly; surfaced as a See-Also Reference from `usdl:interfaces` (and preloaded by `top.agent.interfaces-author`). Drafts XML matching `templates/interfaces/contract.xml` and `templates/interfaces/operation.xml` via `usdl:templates`, and the parent skill then calls Bin through `usdl:bin` to validate. Carries no executable code. --- # usdl-interfaces-contracts ## What this Skill is This is the element-targeted Skill that authors **exactly one `` + `` pair** (and, when the contract style demands it, one accompanying ``) inside `interfaces.xml`, together with the operation's wire schema. It owns the contracts **Interview Script** (`term.interview-script`): the ordered sequence of questions an element-targeted Skill asks the Spec author to fill one Element kind. Its sole job is to gather every required Template slot, draft the Elements from the contract and operation Templates, optionally drive a Skatchbook session that derives the operation's wire schema, and hand the drafts to the parent skill for validation and writing. It is **not user-invocable directly**. It is surfaced as a **See-Also Reference** from `usdl:interfaces` (per `beh.rule.peer-skill-cross-reference`) and preloaded by `top.agent.interfaces-author`. The agent host loads it when `usdl:interfaces` recognises that a `` + `` pair is about to be drafted. This Skill writes Interfaces Elements only. It must not author Behavior, Topology, or Composition Elements; cross-section additions (a missing `top.*` unit referenced by `provider=`, a missing `beh.*` use case referenced by `realizes-behavior=`, a missing `com.flow.*` call-flow referenced by `governed-by=`) are escalated, not fabricated. ## How it fits with peer Skills - **Parent (See-Also source):** `usdl:interfaces` — the section-spanning Skill. When the section interview reaches the "now declare one exposed contract" step, `usdl:interfaces` names this Skill in its response so the host may load it. - **Template authority:** `usdl:templates` — owns `templates/interfaces/contract.xml`, `templates/interfaces/operation.xml`, and `templates/interfaces/channel.xml` (the canonical Templates) and the Element-versus-Template conformance check. Every draft this Skill produces is validated against the Template before being written. - **Persistence and structural validation:** `usdl:bin` — wraps the `usdl` CLI. After this Skill emits drafts (and after the schema file is written), the parent skill calls `usdl validate` through `usdl:bin` to confirm the Section file is structurally sound and every reference resolves. - **Peer Element Skills (informational only):** `usdl:topology:services`, `usdl:topology:communication`, `usdl:behaviour:usecase`, `usdl:behaviour:nfr`, `usdl:composition:skatchbook` are siblings; none are called by this Skill. Routing between Skills is the host's job. This Skill does not invoke peers. It surfaces information so the host can route, per `beh.rule.peer-skill-cross-reference`. ## Authoritative inputs Before asking a single question, the Skill loads: 1. `templates/interfaces/contract.xml`, `templates/interfaces/operation.xml`, and (only when needed) `templates/interfaces/channel.xml` — the canonical contract, operation, and channel Templates (via `usdl:templates`). Every required Template slot becomes a required interview question; every optional slot becomes an optional question (asked only after the author signals interest). 2. The current `interfaces.xml` (via the parent skill) — to detect id collisions on the new contract's and operation's ids. 3. The current `topology.xml` (via the parent skill) — to resolve `provider=` and `consumers=` references against existing `` ids, and to confirm the named provider unit is **internal** (`internal="true"` or default). Per `term.chain-of-trust`, Interfaces trusts Topology's unit declarations; the Skill never invents a `top.*` id that does not appear in `topology.xml`. 4. The current `behavior.xml` (via the parent skill) — to resolve `realizes-behavior=` references against existing `` ids. 5. The current `composition.xml` when present (via the parent skill) — to resolve `governed-by=` references against existing `` ids. If Composition has not yet been authored, `governed-by=` is intentionally left blank and the parent skill returns here after Stage 6 fills in call-flows (per `how-to-use.md`). 6. The Interfaces dictionary ``, ``, ``, ``, and `` rows, with every closed-enum table for `style`, `mode`, `consistency`, `delivery`, `idempotency`, `role`, `format`, `caller-action`, and `ordering` — encoded in the required-slot list and the enum menus below. The Skill never asks for an attribute or child the Template does not declare, and never omits one the Template requires. ## Scope boundary — internal contracts only Per `how-to-use.md` Stage 5 and the Interfaces dictionary's scope rule, **the Interfaces Section documents only contracts whose `provider` is an internal unit**. Contracts the system consumes from external parties (third-party APIs the system calls out to) are out of scope: the external party owns its own contract, restating it here creates a second source of truth, and caller-side verification happens via consumer-driven contract tests against the external party's authoritative schema. The Skill therefore **refuses** to declare a contract whose proposed `provider=` resolves to a Topology unit with `internal="false"`. The corrective response names the rule and points the author elsewhere: > "The unit `top.X` is declared `internal="false"` in `topology.xml`. Contracts whose provider is external live with the external party, not in this Spec. The fact that the system reaches out is already captured by the Topology `` edge to `top.X`; the consumer-side handling belongs in Composition (the outbound adapter component's constraints) and in Behavior (the use case's alternative flows). I am not going to draft a `` for this provider." The Skill never silently rewrites the proposed provider, never picks a different internal unit on the author's behalf, and never produces a partial draft while the violation stands. ## The Interview Script — Part A: the `` The Skill runs the questions below in order. Required attributes are asked unconditionally; optional slots are surfaced as offers and asked only when the author signals interest. This implements `beh.rule.minimum-interview`. ### A0. `id` — the contract id (asked first) Kebab-case, unique across the entire Spec, prefixed `ifc.`. Example question: "What kebab-case id should this contract carry? Convention is `ifc.` — e.g. `ifc.booking-api`, `ifc.payment-events`." The Skill rejects ids that collide with any existing element id in the Spec. ### A1. `provider` — the internal unit that exposes the contract Cross-reference to an existing `` id in `topology.xml`, with `internal="true"` (or default). Example question: "Which internal `top.*` unit exposes this contract?" The Skill resolves the answer against `topology.xml`. If the named unit does not exist, the Skill escalates per `beh.rule.escalate-not-fabricate` — it does not invent the unit. If the named unit exists but is `internal="false"`, the Skill applies the scope-boundary refusal above. ### A2. `consumers` — comma-separated unit (or actor) ids Required by the dictionary. Example question: "Which units (or actors, for CLI-style contracts) consume this contract? Comma-separated `top.*` or `actor.*` ids." The Skill resolves each id against `topology.xml` (units) or `behavior.xml` (actors). Missing referenced ids are escalated, not fabricated. ### A3. `style` — contract style (closed enum) Required. The Skill presents the menu and a one-line gloss per value, taken from the Interfaces dictionary: - `rest` — HTTP REST API. - `graphql` — GraphQL API. - `grpc` — gRPC service. - `event-stream` — publish-subscribe event stream (topic, broker). - `command-bus` — asynchronous command surface. - `query-bus` — asynchronous query surface. - `sql-schema` — SQL schema exposed as an interface. - `file-format` — producer of a file format consumed by others. - `cli` — command-line interface. - `hardware-protocol` — wire-level hardware protocol. - `custom` — anything else; the `spec-ref` carries the authoritative definition. Answers outside the enum are rejected. The chosen `style` is what the dispatcher later uses to pick a schema format: `rest`/`graphql` map to `json-schema` (or `openapi` when an external OpenAPI doc is authoritative); `event-stream`/`command-bus`/`query-bus` map to `asyncapi`; `grpc` maps to `protobuf`; everything else uses `custom`. ### A4. `spec-ref` — optional pointer to an authoritative external spec Optional. Surfaced as an offer: "Is there already an authoritative external spec for this contract (an OpenAPI YAML, an AsyncAPI YAML, a `.proto`, …)? If yes, give me the relative path." If yes, the Skill records it; if no, the Skill notes that the Skatchbook → derivation flow (see below) will produce the schema instead. ## The Interview Script — Part B: the `` After the contract slots are gathered, the Skill runs the operation questions. **The seven mandatory operation attributes are asked unconditionally and in fixed order: `id`, `contract`, `name`, `intent`, `mode`, `consistency`, `delivery`, `idempotency`.** The `contract=` slot is filled automatically from Part A's id; the other six are gathered from the author. ### B0. `id` — the operation id Kebab-case, unique across the entire Spec, prefixed `ifc.`. Example: `ifc.create-booking`, `ifc.booking-created`. Collision-checked against `interfaces.xml`. ### B1. `contract` — owning contract Filled automatically from Part A. Example value: `ifc.booking-api`. ### B2. `name` — stable operation name String. Example question: "What is the stable operation name on the wire? Examples: `POST /bookings`, `BookingCreated`, `RPC.ChargePayment`, `CreateBookingCommand`." The Skill does not paraphrase; the name is recorded verbatim. ### B3. `intent` — short imperative sentence in domain terms Required. The Skill repeats the dictionary framing when asking: "Give me a one-sentence imperative description of what this operation *means* in domain terms — **not** a paraphrase of the URL or the message name." The Skill rejects answers that are obvious paraphrases of `name=` (e.g. for `name="POST /bookings"`, an `intent="POST a booking"` is rejected with a restate). `` does not carry a `` child — the domain meaning lives in the `intent` attribute. ### B4. `mode` — interaction shape (closed enum) **Verbosity rule: no abbreviated forms.** `sync` is rejected; the full `sync-request-response` is required. The same enum is used on Topology ``; spec lint verifies later that the operation's mode matches the mode of the communication carrying it. The menu: - `sync-request-response` - `async-fire-forget` - `async-request-callback` - `async-event-broadcast` - `stream-push` - `stream-pull` Answers outside the enum, or in shorthand, are restated against the menu. ### B5. `consistency` — consistency expected of the result (closed enum) - `strong` - `read-your-writes` - `eventual` - `not-applicable` The Skill records the framing — this is the model the consumer expects of the *result*, not of the underlying storage. The strong + async-event-broadcast red flag from Topology applies here too: if the operation pairs `consistency="strong"` with `mode="async-event-broadcast"`, the Skill pauses and asks the author to revisit one of the two before drafting. ### B6. `delivery` — delivery guarantee on the wire (closed enum) - `at-most-once` - `at-least-once` - `exactly-once-effective` - `not-applicable` `exactly-once` (without the `-effective` suffix) is rejected; the legal token is `exactly-once-effective`. ### B7. `idempotency` — whether retries are safe (closed enum) Required on every operation (no implicit default). Example menu: - `required` — the operation must be safe to retry; the caller may attach an idempotency key. - `inherent` — the operation is idempotent by construction (e.g. a pure read). - `not-required` — retries are not safe; callers must not blindly retry. - `not-applicable` — the operation has no meaningful idempotency claim. Answers outside the enum are rejected. If `delivery="at-least-once"` and `idempotency="not-required"` are paired, the Skill flags the combination as a red flag and asks the author to revisit one of the two — at-least-once delivery with non-idempotent handling is a known consumer footgun. ### B8. `realizes-behavior` — optional behavior linkage Optional. Comma-separated `` ids from `behavior.xml`. Surfaced as an offer: "Which use cases does this operation participate in?" The Skill resolves each id against `behavior.xml`. Missing referenced ids are escalated, not fabricated. ### B9. `governed-by` — optional composition linkage Optional. Comma-separated `` ids from `composition.xml`. Filled only when Composition has been authored; otherwise left blank and the parent skill returns here after Stage 6. The Skill resolves each id against `composition.xml`; spec lint later verifies that each call-flow's `in-unit` equals the operation's contract's `provider` and each call-flow's `for-use-case` is in the operation's `realizes-behavior`. ## The Interview Script — Part C: `` children Every `` has one or more `` children. The Skill walks the author through one role at a time. ### C1. Required roles for this operation The Skill consults `mode` to set a baseline: - For `sync-request-response`, `async-request-callback`, `stream-pull`: at minimum one `` and one ``. - For `async-fire-forget`, `async-event-broadcast`, `stream-push`: at minimum one ``. - For any operation that can fail in a structured way: one or more ``. - `state` is offered when the operation describes resource state directly. ### C2. Per ``: `role`, `format`, and `uri` For each declared role, the Skill collects three slots: - `role` — closed enum: `input` | `output` | `event` | `state` | `error`. - `format` — closed enum: `openapi` | `asyncapi` | `json-schema` | `protobuf` | `avro` | `xsd` | `cddl` | `cap-n-proto` | `custom`. The Skill suggests a default from the contract's `style` (rest → `json-schema` or `openapi`; event-stream/command-bus/query-bus → `asyncapi`; grpc → `protobuf`; sql-schema → `custom`). - `uri` — relative path under `./schemas/`, optionally with a `#`-fragment. Convention: `./schemas//.` where `` is `.schema.json`, `.openapi.yaml`, `.asyncapi.yaml`, or `.proto` according to `format`. If `spec-ref` on the contract already names an authoritative external schema (alternative flow `external-schema-already-authoritative` in `beh.generate-wire-schema`), the Skill skips the Skatchbook flow and the `` simply points at a fragment inside the existing spec. Otherwise the Skill runs the Skatchbook → derivation flow below. ## The Skatchbook → derivation flow (per `beh.rule.schema-from-scratchbook`) When no authoritative external schema yet exists for the target operation, `beh.rule.schema-from-scratchbook` requires the system to use the Skatchbook to draft a typed abstraction, derive a schema from it, persist the schema to the Spec's schemas directory, and attach it to the operation via `` children. This Skill orchestrates that flow in five steps: 1. **Open a Skatchbook entry.** The Skill asks the parent skill to allocate a Skatchbook entry tagged with the contract id and the operation id. The entry's working directory is the Skatchbook store (per `top.com.interfaces-skill-uses-skatchbook`), never a Spec section directory. 2. **Draft a typed code abstraction.** The Skill asks the author which source language they prefer (PHP class, Python class, or pseudo-code) and which roles need shapes (input, output, event, error, state). The Skill drafts one typed shape per role inside the Skatchbook entry: a `*.py` for Python, a `*.php` for PHP, a `*.pseudo` for pseudo-code. Drafting captures field names, types, optionality, and a one-line per-field comment in domain terms. The Skill never copies code or filenames into the Spec — only the Skatchbook holds the draft. 3. **Invoke the schema-derivation script.** The Skill instructs the parent skill to invoke `scripts/schema-derivation/dispatcher.py` with `--input ` and `--target ` chosen from the contract `style`. The dispatcher picks the right per-language derivation script (`derive_from_python.py`, `derive_from_php.py`, or `derive_from_pseudo.py`) from the input file's extension or an explicit `--source-lang` flag, runs it, and emits the derived schema to stdout (or to a path passed via `--output`). The script reads from the Skatchbook store only and never touches `interfaces.xml`. 4. **Parent skill writes the schema via Bin.** Per `con.skatchbook-no-direct-spec-writes`, the derivation script never writes a Spec section file and never writes the schema file directly. The parent skill takes the script's stdout, places it at `./schemas//.`, and then calls `usdl:bin` to validate. This routes every Spec mutation through Bin and preserves a single point of validation, diff presentation, and confirmation. 5. **Attach `` children.** The Skill emits one `` per role declared in Part C, with `uri=` pointing at the schema file the parent skill just wrote. The operation draft is now complete. After step 5, `evt.contract-schema-generated` is conceptually emitted; the Spec carries no event-log artifact, but downstream Skills may observe the new schema in `./schemas/`. ## The Interview Script — Part D: `` blocks Every failure the consumer must handle gets a `` child on the operation. The Skill prompts: "Which structured failures does a consumer of this operation need to handle? For each, give me a condition slug (`timeout`, `validation-failure`, `upstream-5xx`, `duplicate-request`, `network-partition`, `quota-exceeded`, `schema-mismatch`, `poison-message`, …)." For each declared failure, the Skill collects: - `condition` — string slug, free-form per the dictionary but conventionally drawn from the examples above. - `caller-action` — closed enum: `retry-with-backoff` | `circuit-break` | `dead-letter` | `fail-fast` | `compensate` | `fallback-to-degraded`. - `provider-promise` — optional string describing what the provider guarantees on this failure (e.g. `no-side-effect-on-failure`, `effect-idempotent-on-retry`, `at-least-attempted`). The Skill enforces internal consistency: if `idempotency="required"` was declared on the operation, at least one failure mode whose `condition="duplicate-request"` or whose `provider-promise="effect-idempotent-on-retry"` is expected; the Skill surfaces the gap as an interview note rather than silently completing. ## The Interview Script — Part E: optional `` Only asked when the contract `style` is `event-stream` (or, less commonly, `command-bus`/`query-bus`). The Skill drafts one `` matching `templates/interfaces/channel.xml`, with required `contract`, `name`, `delivery`, and optional `ordering` and `retention`, plus its own `` and `` children. The channel reuses the same Skatchbook → derivation flow when no external schema exists. ## Forbidden slots — Interfaces stays at the wire-surface grain The Skill **explicitly forbids** every attribute or child that does not belong on a ``, ``, ``, ``, or ``. The script never asks for, never accepts, and never emits: - Inline payload schemas — schemas live in `./schemas/` and are referenced by ``. Inlining a JSON Schema body inside the operation Element is rejected. - Implementation filenames, class names, function signatures, parameter lists — those belong in the Skatchbook draft only. The Spec captures roles, formats, and URIs, never code-level details. This implements `beh.rule.no-code-in-spec`. - A `` child on `` — the dictionary is explicit: `` has no ``; the domain meaning lives in the `intent` attribute. - A `carries=` attribute — that belongs on Topology ``, not on Interfaces elements. - A `realized-by=` or `governed-by=` attribute on a use case — references flow only from the lower-level element upward. If the Skill detects a forbidden slot proposed by the author or by upstream context, it refuses the slot and explains the section-boundary rule. ## Escalate-not-fabricate The Skill follows `beh.rule.escalate-not-fabricate` for every slot. The flow on an unparseable, ambiguous, or missing answer: 1. **Restate once with the legal shape.** If the `mode` answer is `sync`, the Skill responds: "I need the full token, no abbreviations. Did you mean `sync-request-response`?" If the `style` answer is `REST`, the Skill responds: "`REST` is not in the enum. Did you mean `rest`?" 2. **If the second answer is still unparseable, escalate and pause.** The Skill returns to the parent skill with the open question, the slot it belongs to, and the legal shapes; it does not invent a placeholder, omit the slot, or write a malformed draft. 3. **Missing unit ids are escalated, not fabricated.** If the author says `provider="top.booking-svc"` but that unit does not exist in `topology.xml`, the Skill pauses and tells the parent skill: add the unit in `topology.xml` first (via `usdl:topology:services`); do not invent it inline. Same discipline for `consumers=`. 4. **Missing `realizes-behavior=` ids are escalated, not fabricated** — same discipline against `behavior.xml`. 5. **Missing `governed-by=` ids are escalated, not fabricated** — same discipline against `composition.xml`. Or, if Composition has not yet been authored, the attribute is deliberately left blank and the parent skill is told to return here after Stage 6. 6. **External-provider violations are refused, not rewritten.** Per the scope boundary above, the Skill never silently substitutes a different provider. 7. **Skatchbook scripts never write Spec section files.** The derivation scripts only read from the Skatchbook store and only emit to stdout or to a path passed by the parent skill (which writes via Bin). The Skill refuses any flow that would have a derivation script touch `interfaces.xml` directly — that is exactly the construct `con.skatchbook-no-direct-spec-writes` forbids. The Skill never inserts placeholders (no `TODO`, no `mode="sync-request-response"` as a default, no empty `intent=`). Missing required input always escalates. ## Drafting and validation Once every required slot has a parseable answer, every cross-reference resolves (or has been deliberately deferred), the Skatchbook → derivation flow has produced a schema file (or the alternative flow has reused an authoritative external schema), and any affirmed optional slots are filled, the Skill drafts the `` and `` Elements to match `templates/interfaces/contract.xml` and `templates/interfaces/operation.xml`: 1. **Load the Templates** via `usdl:templates`. Each Template is the slot map; the Skill fills each slot with the corresponding gathered answer in the order the Template prescribes. 2. **Validate the drafts against the Templates** before writing — every required attribute present (contract: `id`, `provider`, `consumers`, `style`; operation: `id`, `contract`, `name`, `intent`, `mode`, `consistency`, `delivery`, `idempotency`), no unknown attributes, attribute values inside their closed enums, at least one `` child on every ``. This is the `usdl:templates` Element-versus-Template conformance check, run on the drafts in memory, per `beh.rule.template-validated-element`. 3. **Hand the drafts to the parent skill** (`usdl:interfaces` or the spawning Agent). The parent owns Section-file mutation; this Skill never writes to `interfaces.xml` itself. The parent also owns the schema-file write at `./schemas//.`, performed via Bin. 4. **Parent calls Bin via `usdl:bin`** to run `usdl validate` against the updated `interfaces.xml` and the new schema file. Per `beh.rule.self-validate-before-done`, completion is reported only after validation passes; on failure the parent applies trivial repair or escalates back into this Skill's script for the offending slot. ## Response shape A successful pass returns to the parent skill: - The drafted `` XML, conforming to `templates/interfaces/contract.xml`. - The drafted `` XML (and `` XML when applicable), conforming to its Template. - The derived schema content for each role for which the Skatchbook flow ran, paired with its target relative path under `./schemas/`. - The set of gathered answers, keyed by slot name. - The list of any **referenced ids that need to be added first** (units the author named in `provider=` or `consumers=` but missing from `topology.xml`; use cases named in `realizes-behavior=` but missing from `behavior.xml`; call-flows named in `governed-by=` but missing from `composition.xml`). - A flag indicating whether `governed-by=` was deliberately left blank pending Stage 6 (so the parent skill remembers to return here after Composition is authored). - An empty list when no escalation is needed. An escalation pass returns instead: the open question (including the scope-boundary refusal when the provider is external), the legal shape that was rejected, the slot it belongs to, and the partial draft (never written). ## What this Skill does not do - It does not author any Element other than one `` + one `` (and optionally one ``). Authoring other contracts and operations requires re-loading this Skill for each pair. - It does not author Behavior, Topology, or Composition Elements. Cross-section additions are escalated to the parent skill. - It does not write `interfaces.xml` directly. Mutations go through the parent skill, which uses Bin. - It does not write schema files directly. The parent skill writes them at `./schemas//.` via Bin, using the derivation script's stdout as content. - It does not call `usdl:bin` itself. Bin invocation is the parent's responsibility. - It does not invoke peer Skills. Routing is the host's job. - It does not normalise, paraphrase, or coerce answers into the closed enums. `REST` is not `rest`; `sync` is not `sync-request-response`; the Skill restates the menu and asks the author to pick a legal value. - It does not let derivation scripts write to `interfaces.xml` or to any Spec section file. Per `con.skatchbook-no-direct-spec-writes`, derivation scripts read only from the Skatchbook store and write only to stdout or to a parent-supplied path inside `./schemas/`. - It does not declare contracts whose provider is external. Those live with the external party (per `how-to-use.md` Stage 5). - It carries no executable code (`con.no-implementation-code-in-skill-md`). Everything above is prose describing what to ask, in what order, and what to forbid.

usdl-interfaces-contracts

Install this skill

Comments