--- name: usdl-topology-communication description: Element-targeted Skill that authors one USDL `` Element in topology.xml — the coarse-grained "A talks to B" edge between two ``s. Owns the communication Interview Script that collects the kebab-case id (prefixed `top.com.`), the six mandatory attributes in fixed order (`from`, `to`, `via`, `mode`, `consistency`, `delivery`), and the optional `backpressure` and `carries` cross-references. Enforces the closed enums in `dictionaries/topology_dictionary.md` for `via` (http, grpc, message-queue, pub-sub, websocket, sql, file-system, ipc, signal, ble, serial, custom), `mode` (sync-request-response, async-fire-forget, async-request-callback, async-event-broadcast, stream-push, stream-pull), `consistency` (strong, read-your-writes, eventual, not-applicable), `delivery` (at-most-once, at-least-once, exactly-once-effective, not-applicable), and `backpressure` (block, shed, buffer, not-applicable). Rejects abbreviated modes — `sync` is rejected, the full `sync-request-response` is required. Surfaces the **strong + async-event-broadcast** combination as an interview red flag and asks the author to revisit one of the two before drafting. Trigger this Skill when the active task mentions "communication", "edge", "from", "to", "via", "mode", "sync", "async", "broadcast", "stream", "consistency", "delivery", "A talks to B", or `` in the context of authoring or extending topology.xml. Not user-invocable directly; surfaced as a See-Also Reference from usdl:topology (and preloaded by top.agent.topology-author). Drafts XML matching templates/topology/communication.xml via usdl:templates and the parent skill then calls Bin through usdl:bin to validate. Carries no executable code. --- # usdl-topology-communication ## What this Skill is This is the element-targeted Skill that authors **exactly one `` Element** for `topology.xml`. It owns the communication **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 Element from the communication Template, and hand the draft to the parent skill for validation and writing. It is **not user-invocable directly**. It is surfaced as a **See-Also Reference** from `usdl:topology` (per `beh.rule.peer-skill-cross-reference`) and preloaded by `top.agent.topology-author`. The agent host loads it when `usdl:topology` recognises that a `` Element is about to be drafted. This Skill writes Topology Elements only. It must not author Behavior, Interfaces, or Composition Elements; it must not author other Topology Element kinds (`` is the responsibility of the peer `usdl:topology:services`; `` is the responsibility of the parent `usdl:topology`). ## How it fits with peer Skills - **Parent (See-Also source):** `usdl:topology` — the section-spanning Skill. When the section interview reaches the "now declare how units talk" step, `usdl:topology` names this Skill in its response so the host may load it. - **Template authority:** `usdl:templates` — owns `templates/topology/communication.xml` (the canonical communication Template) 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 a draft, the parent skill calls `usdl validate` through `usdl:bin` to confirm the Section file is structurally sound and references resolve. - **Peer Element Skills (informational only):** `usdl:topology:services`, `usdl:behaviour:usecase`, `usdl:behaviour:nfr`, `usdl:interfaces:contracts`, `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/topology/communication.xml` — the canonical communication Template (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 `topology.xml` (via the parent skill) — to detect id collisions on the new communication's id and to resolve the `from=` and `to=` references against existing `` ids. Per `term.chain-of-trust`, Topology trusts its own unit declarations; the Skill never invents a `top.*` id that does not appear in `topology.xml`. 3. The current `interfaces.xml`, when present (via the parent skill) — to resolve `carries=` references against existing `ifc.*` contract and operation ids. `carries=` is the Topology→Interfaces linkage. If interfaces.xml has not yet been authored at Stage 4, `carries=` is intentionally left blank and the parent skill returns here after Stage 5 fills in operations (per `how-to-use.md` Stage 4: "After Stage 5 fills in operations, return here and add `carries="ifc.X,ifc.Y"`"). 4. The Topology dictionary `` row, its quick-reference required-attributes table, and every closed-enum table for `via`, `mode`, `consistency`, `delivery`, and `backpressure` — encoded in this script's 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. ## The Interview Script (ordered) The Skill runs the questions below in order. **The six mandatory attributes are asked unconditionally and in fixed order: `from`, `to`, `via`, `mode`, `consistency`, `delivery`.** Optional slots are surfaced as offers and asked only when the author signals interest. This implements `beh.rule.minimum-interview`. ### 0. `id` — the communication id (asked first, before the six) Kebab-case, unique across the entire Spec, prefixed `top.com.`. Example question: "What kebab-case id should this communication carry? Convention is `top.com.` — e.g. `top.com.booking-to-payments`, `top.com.checkout-svc-to-stock-worker`." The Skill rejects ids that collide with an existing ``, ``, or `` id in `topology.xml`. ### The six mandatory attributes (asked unconditionally, in this order) #### 1. `from` — source unit Cross-reference to an existing `` id in `topology.xml`. Example question: "Which unit initiates this conversation? Give me an existing `top.*` unit id from `topology.xml`." 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. The parent skill is told: "add the unit in `topology.xml` first (via `usdl:topology:services`); do not invent it inline." #### 2. `to` — destination unit Cross-reference to an existing `` id in `topology.xml`. Example question: "Which unit is the destination of this conversation? Give me an existing `top.*` unit id." Same resolution discipline as `from`. `from` and `to` must differ; a unit talking to itself is not a `` and is rejected with an explanation. #### 3. `via` — transport mechanism Closed enum. The Skill presents the menu and a one-line gloss per value, taken from the dictionary's `via` table. Example question: "What transport carries this conversation? Pick exactly one from the closed enum: - `http` — HTTP (REST, JSON-over-HTTP, generic HTTP). - `grpc` — gRPC over HTTP/2. - `message-queue` — point-to-point queue (RabbitMQ-style, SQS-style). - `pub-sub` — publish-subscribe topic (Kafka, Pulsar, SNS-style). - `websocket` — bidirectional WebSocket. - `sql` — SQL connection to a database. - `file-system` — file-system read/write (shared volume, drop folder). - `ipc` — local inter-process communication (Unix socket, named pipe). - `signal` — hardware signal line / GPIO. - `ble` — Bluetooth Low Energy. - `serial` — serial protocol (UART, RS-232, RS-485). - `custom` — anything not listed; pair with an `x-via-detail="..."` attribute if useful." Answers outside the enum are rejected. The Skill never paraphrases (`"REST"` is recorded as `http`; the Skill restates the question and asks the author to pick the enum value). `tcp` is not a member of the enum; if the author says `tcp`, the Skill restates the menu and asks them to pick the closest legal value (typically `custom` with an `x-via-detail` hint, or `ipc` for a local socket). #### 4. `mode` — interaction shape Closed enum. **Verbosity rule: no abbreviated forms.** `sync` without further qualification is **rejected**; the full `sync-request-response` is required. The dictionary states this explicitly: "No abbreviated forms are allowed. `sync` without further qualification is rejected; the full token is `sync-request-response`. The verbosity is a feature: implicit modes were the failure mode." The Skill enforces this — if the answer is `sync`, `async`, `request`, `event`, or any other shorthand, the Skill restates the menu and asks for the full token. Example question: "What is the interaction shape? Pick exactly one from the closed enum — full token, no abbreviations: - `sync-request-response` — caller blocks until callee returns or fails. - `async-fire-forget` — caller publishes; no reply expected; consumer is decoupled in time. - `async-request-callback` — caller publishes; callee returns asynchronously via callback, webhook, or correlated message. - `async-event-broadcast` — publisher emits an event; multiple unknown subscribers may consume. - `stream-push` — producer pushes a continuous stream to consumer(s). - `stream-pull` — consumer pulls from a continuous source." The Skill records the chosen value verbatim. The same enum is used by `` in Interfaces; spec lint verifies later that an operation's mode matches the mode of the communication carrying it. #### 5. `consistency` — consistency model expected by the consumer Closed enum. The dictionary makes the framing explicit: "Consistency is the model the consumer expects of the result, not the underlying storage technology." The Skill repeats that framing when asking. Example question: "What consistency model does the consumer expect of the result of this conversation? (This is about consumer expectation, not storage technology.) Pick exactly one: - `strong` — reads always see the latest committed write. - `read-your-writes` — a client sees its own writes immediately; other clients may lag. - `eventual` — replicas converge over time; reads may see stale data. - `not-applicable` — the interaction does not have a meaningful consistency model (e.g. fire-forget to an external endpoint, signal lines)." Answers outside the enum are rejected. #### 6. `delivery` — delivery guarantee provided by transport + protocol Closed enum. The dictionary framing: "Delivery is the guarantee the transport plus protocol provides." Example question: "What end-to-end delivery guarantee does this conversation's transport plus protocol provide? Pick exactly one: - `at-most-once` — each message reaches the destination zero or one times; no retransmits. - `at-least-once` — each message reaches the destination one or more times; duplicates possible. - `exactly-once-effective` — the end-to-end effect is observed exactly once (typically via idempotency keys plus at-least-once transport). - `not-applicable` — no discrete-message semantics (e.g. SQL session, continuous serial stream)." Answers outside the enum are rejected. The legal token is `exactly-once-effective` (the dictionary deliberately rejects bare `exactly-once` because end-to-end exactly-once delivery without effective-once handling is a fiction); if the author says `exactly-once`, the Skill restates the legal token and asks for confirmation that effective-once handling is in place. ### The red-flag check (run after the six, before any optional slot) After all six mandatory attributes are gathered and **before** drafting or asking about optional slots, the Skill runs the **strong + async-event-broadcast** red-flag check. **If `consistency="strong"` AND `mode="async-event-broadcast"`, the Skill pauses and asks the corrective question verbatim:** > "These two values together are a red flag. `consistency="strong"` means the consumer expects every read to see the latest committed write. `mode="async-event-broadcast"` means the publisher emits to multiple unknown subscribers, decoupled in time, with no synchronous acknowledgement that every subscriber has applied the write. **This combination is impossible to deliver: a broadcast cannot guarantee strong consistency across unknown subscribers.** This is a sign the author has not settled what they want. Please revisit one of the two before I draft this Element: > > - If the consumer truly needs strong consistency, the interaction is not a broadcast. Consider `mode="sync-request-response"` (caller blocks on a synchronous reply) or model the read path as a separate synchronous communication. > - If the interaction truly is a broadcast, the consumer must accept a weaker consistency model. Consider `consistency="eventual"` (replicas converge over time) or `consistency="not-applicable"` (the broadcast carries an event whose consistency model is not meaningful at the edge level). > > Which value would you like to change, and to what?" This implements the language-level fact that `cmp.topology-communication.skill-md` records (in `composition.xml`) and that `how-to-use.md` Stage 4 calls out as "the most common bug at this stage". The Skill **never silently accepts** the combination, never drafts the Element with both values set, and never normalises one of the two on the author's behalf. It pauses, asks the corrective question, and waits for a second answer to either `consistency` or `mode`. The amended answer is then re-validated against the closed enums. If the author's second answer leaves the combination intact, the Skill escalates to the parent skill with the open question — per `beh.rule.escalate-not-fabricate`, the Skill **does not draft** an Element it knows the language forbids. ### Optional slots (asked after the red-flag check passes) #### 7. `backpressure` — what happens when the destination cannot keep up Optional. Closed enum. Surfaced as an offer: "Want to declare what happens when the destination cannot keep up?" If yes, the Skill presents the menu: - `block` — sender blocks until destination can accept. - `shed` — excess load is dropped at the sender. - `buffer` — excess load is queued, bounded by buffer capacity. - `not-applicable` — the interaction does not have a meaningful backpressure model. Answers outside the enum are rejected. If the author skips, the attribute is omitted (per dictionary, `backpressure=` is optional). #### 8. `carries` — Interfaces contracts/operations that flow over this edge Optional. Comma-separated list of `ifc.*` ids (contract or operation ids from `interfaces.xml`). Surfaced as an offer: "Which Interfaces contracts or operations flow over this edge? (Comma-separated `ifc.*` ids.) If interfaces.xml has not been authored yet, leave this blank — we'll fill `carries=` after Stage 5." The Skill resolves every named id against the current `interfaces.xml`. **Missing referenced ids are escalated, not fabricated**: if the author names `ifc.create-booking` and that operation does not exist in `interfaces.xml`, the Skill pauses and tells the parent skill — add the operation in `interfaces.xml` first (via `usdl:interfaces` and its child `usdl:interfaces:contracts`); do not invent it inline. Per dictionary, communications to databases, external units, identity services, or other endpoints without a documented contract leave `carries=` unset; the Skill never invents an `ifc.*` id to fill the slot. ### Status attribute (asked last, with default) #### 9. `status` Defaults to `accepted`. The Skill confirms ("Set status to `accepted`, `draft`, `proposed`, `deprecated`, or `superseded`? Default is `accepted`.") and only inserts the attribute if the answer differs from the default. ## Forbidden slots — Topology stays at edge grain The Skill **explicitly forbids** every attribute or child that does not belong on a ``. The script never asks for, never accepts, and never emits: - Endpoint paths, message names, payload shapes, class names, function signatures — those live in **Interfaces** and never appear on a ``. The `` declares only the language-level fact that two units talk and the six attributes above; payloads are referenced by `carries=` ids whose schema lives in Interfaces. - A use-case id, a behaviour rule id, a component id — Topology never points down into Behavior, Interfaces (other than `carries=`), or Composition from a ``. Anything else is forbidden. - `` or any other required child — `` has no required children per the dictionary; `` (zero or more) is the only permitted child for non-normative commentary. This implements `beh.rule.no-code-in-spec` and the Topology dictionary's section invariant that "no endpoint paths, message names, payload shapes, class names, or use cases appear in Topology". 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` or `async-broadcast`, the Skill responds: "I need the full token, no abbreviations. From the closed enum, did you mean `sync-request-response`, or one of the four async modes?" If the `via` answer is `REST`, the Skill responds: "`REST` is not in the enum. Did you mean `http`?" 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 `from="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; do not invent it inline. Same discipline for `to=`. 4. **Missing `carries=` ids are escalated, not fabricated.** Same discipline against `interfaces.xml`. 5. **The strong + async-event-broadcast combination is never silently accepted.** It is escalated per the red-flag check above. No draft is produced while the combination stands. The Skill never inserts placeholders (no `TODO`, no `via="http"` as a default, no empty `consistency=`). Missing required input always escalates. ## Drafting and validation Once every required slot has a parseable answer, the red-flag check has passed (or been resolved), and any affirmed optional slots are filled, the Skill drafts the `` Element to match `templates/topology/communication.xml`: 1. **Load the Template** via `usdl:templates`. The Template is the slot map; the Skill fills each slot with the corresponding gathered answer in the order the Template prescribes (`id`, `from`, `to`, `via`, `mode`, `consistency`, `delivery`, optional `backpressure`, optional `carries`). 2. **Validate the draft against the Template** before writing — every required attribute (`id`, `from`, `to`, `via`, `mode`, `consistency`, `delivery`) present, no unknown attributes, attribute values inside their closed enums, no children other than zero or more ``. This is the `usdl:templates` Element-versus-Template conformance check, run on the draft in memory, per `beh.rule.template-validated-element`. 3. **Hand the draft to the parent skill** (`usdl:topology` or the spawning Agent). The parent owns Section-file mutation; this Skill never writes to `topology.xml` itself. 4. **Parent calls Bin via `usdl:bin`** to run `usdl validate` against the updated `topology.xml`. 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/topology/communication.xml`. - 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 `from=`/`to=` but missing from `topology.xml`; operations or contracts the author named in `carries=` but missing from `interfaces.xml`). - A flag indicating whether `carries=` was deliberately left blank pending Stage 5 (so the parent skill remembers to return here after Interfaces is authored). - An empty list when no escalation is needed. An escalation pass returns instead: the open question (including the red-flag corrective question when triggered), 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 ``. Authoring a `` is delegated to the peer `usdl:topology:services`; authoring an `` is delegated to the parent `usdl:topology`. - It does not author Behavior, Interfaces, or Composition Elements. Cross-section additions (missing units, missing operations) are escalated to the parent skill. - It does not write `topology.xml` directly. Mutations go through the parent skill, which uses Bin. - 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 `http`; `sync` is not `sync-request-response`; the Skill restates the menu and asks the author to pick a legal value. - It does not silently accept the **strong + async-event-broadcast** combination. The corrective question is asked every time, and no draft is produced while the combination stands. - 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-topology-communication

Install this skill

Comments