--- name: usdl-topology description: Section-spanning Skill for authoring and extending the USDL Topology Section (topology.xml) — the "what runs and how runnable things talk" layer of a USDL Spec. User-invocable directly as /usdl:topology. Reads behavior.xml as authoritative input (per the Chain of Trust); refuses to draft any topology Element when behavior.xml is missing or fails `usdl validate`, surfacing exactly which Section is at fault (the missing-higher-section failure mode of `ifc.skill.topology`). Drives the Section-level interview in the order Stage 3/4 of how-to-use.md prescribes — units first, then communications, then environments — and applies the minimum-interview rule (only required slots are asked unconditionally; optional slots surface on author interest). For each Element kind, surfaces a See-Also Reference to the matching element-targeted peer: usdl:topology:services when a `` is about to be drafted, usdl:topology:communication when a `` is about to be drafted. Surfaces the strong + async-event-broadcast combination on any `` as a red flag, refuses to draft while the combination stands, and asks the author to revisit either `consistency` or `mode` (mirrors usdl:topology:communication's interview rule and Stage 4 of how-to-use.md). Self-validates every batch via usdl:bin (`usdl validate topology.xml`) and emits the Section Handoff signal only after validation passes — releasing usdl:interfaces to begin. Trigger this Skill when the active task mentions "topology", "topology.xml", "unit", "service", "communication", "deployment", "deploy unit", "from to via", "environment", "topology section", "author topology", or any of the kebab-case `top.*` ids that live in topology.xml. Description-only; no executable code. user-invocable: true --- # usdl-topology ## What this Skill is This is the **section-spanning Skill** that drives authoring (and extending) of one USDL Spec's `topology.xml`. It is the `/usdl:topology` user-invocable Skill the agent host loads when the active task is about the Topology Section: declaring what runs, how runnable things talk at the unit grain, and which units appear in which named deployment environment. Its job is to: 1. Confirm that the **Chain of Trust** is intact before any drafting (`behavior.xml` exists and passes `usdl validate`). 2. Drive the Section-level interview in the order Stage 3/4 of `how-to-use.md` prescribes — **units → communications → environments**. 3. Surface a See-Also Reference to the right element-targeted peer Skill whenever an individual Element is about to be drafted. 4. Catch the language-level red flag at the Section level — **`consistency="strong"` paired with `mode="async-event-broadcast"`** — even before the element-targeted peer sees the answer. 5. Self-validate every batch via `usdl:bin` (`usdl validate`). 6. Emit a **Section Handoff** signal once `topology.xml` validates cleanly, releasing `usdl:interfaces` to begin. This Skill writes Topology Elements only. It must not author Behavior, Interfaces, or Composition Elements. Individual Element drafting (one ``, one ``) is delegated to the matching element-targeted peer Skill via See-Also References; the host routes between Skills. This Skill is **user-invocable**. It also is preloaded by `top.agent.topology-author` (the section-authoring Agent), which runs the same interview in isolated context and returns a summary diff. ## How it fits with peer Skills - **Higher Section (read-only, authoritative input):** `usdl:behaviour` — the source of truth for actors, use cases, glossary, shared Behavior Elements. Topology trusts Behavior unconditionally per `term.chain-of-trust` and `inv.section-chain-of-trust`. - **Element-targeted peers (See-Also References, surfaced at drafting time):** - `usdl:topology:services` — authors one `` Element. Surfaced when the interview is about to draft a unit. - `usdl:topology:communication` — authors one `` Element, owns the six-attribute Interview Script, and re-runs the strong + async-event-broadcast red-flag check. Surfaced when the interview is about to draft a communication. - **Template authority:** `usdl:templates` — owns the canonical Element Templates under `templates/topology/` (`full.xml`, `unit.xml`, `communication.xml`, `environment.xml`). Every draft validates against its Template before being written. - **Persistence and structural validation:** `usdl:bin` — wraps the `usdl` CLI. Used to run `usdl validate behavior.xml` for the chain-of-trust pre-check and `usdl validate topology.xml` after every batch and at Section Handoff. - **Lower Sections (downstream consumers):** `usdl:interfaces`, `usdl:composition` — they read `topology.xml` as authoritative input once this Skill emits the Section Handoff signal. This Skill does not call them. This Skill never invokes peers directly; it surfaces See-Also References so the host can route, per `beh.rule.peer-skill-cross-reference`. ## See-Also References This Skill lists the following peer Skills as See-Also References, per `beh.rule.peer-skill-cross-reference`: - **`usdl:topology:services`** — when the active interview is about to draft a `` Element. The peer owns the unit Interview Script (kind, owner, internal-or-external, description) and drafts XML matching `templates/topology/unit.xml`. - **`usdl:topology:communication`** — when the active interview is about to draft a `` Element. The peer owns the communication Interview Script (the six mandatory attributes in fixed order plus optional `backpressure` and `carries`) and re-runs the strong + async-event-broadcast red-flag check at element grain. Drafts XML matching `templates/topology/communication.xml`. - **`usdl:bin`** — the wrapper around the `usdl` CLI. Used for the chain-of-trust pre-check (`usdl validate behavior.xml`) and the self-validate-before-done step (`usdl validate topology.xml`). Surfaced whenever the Skill needs the CLI. - **`usdl:templates`** — the bundled Element Templates and the Element-versus-Template conformance check. Surfaced whenever a draft is being shaped against a Template. - **`usdl:behaviour`** — the section-spanning Skill for `behavior.xml`. Surfaced because Topology references Behavior (the Chain of Trust runs Topology → Behavior): if the chain-of-trust pre-check fails, the author is routed back to `usdl:behaviour` to fix or complete the higher Section before any topology Element is drafted. The Skill does not list `usdl:interfaces`, `usdl:composition`, or any lower-Section peer as a See-Also Reference, because references in the Spec flow upward only (`term.reference-direction`, `inv.reference-direction-monotonic`). ## Chain-of-trust pre-check (run before any drafting) Per `beh.rule.chain-of-trust`, `beh.halt-on-broken-chain`, and `inv.section-chain-of-trust`, this Skill **always** runs the chain-of-trust pre-check before authoring a single topology Element. The pre-check is non-negotiable: it is the Skill's first action on every invocation, including when the author asks to add a single Element to an already-existing `topology.xml`. The pre-check is the realisation of the `missing-higher-section` failure mode declared on `ifc.skill.topology` (`provider-promise="reports behavior.xml as missing or invalid; no topology Element is written"`). Steps, in order: 1. **Confirm `behavior.xml` exists** in the Spec directory at the path the host has been pointed at. The Skill reads the directory listing (or asks the parent skill / Agent to read it) and looks for `behavior.xml`. If the file is absent, the Skill halts immediately. No further check runs. The Skill reports: **"Topology cannot be authored: `behavior.xml` is missing. Behavior is the higher Section that Topology trusts; please author it first via `usdl:behaviour`."** 2. **Run `usdl validate behavior.xml`** via `usdl:bin`. The Skill does not parse `behavior.xml` itself; it delegates structural validation to Bin (per `beh.rule.self-validate-before-done` applied to the higher Section). If Bin exits non-zero, the Skill halts and surfaces the Bin diagnostics verbatim, including file path, line number, and the unresolved or malformed Element id. The Skill reports: **"Topology cannot be authored: `behavior.xml` fails `usdl validate`. Please fix the diagnostics below via `usdl:behaviour` and re-invoke `/usdl:topology` once Behavior validates cleanly."** 3. **Only on a clean pass do further interview steps begin.** Until step 2 passes, the Skill refuses to draft any topology Element — no ``, no ``, no ``. It also refuses to load or pre-fill any Template. This is the language-level guarantee that broken Behavior never silently contaminates a downstream Section. On a halt, the Skill follows `beh.rule.escalate-not-fabricate`: it does not invent missing actors, use cases, or events to push past the failure; it names the Behavior Element at fault (when Bin's diagnostics identify one) and routes the author back to `usdl:behaviour` via a See-Also Reference. The halt is final for this invocation; the Skill exits without writing. The pre-check is also re-run **at every re-invocation** during a long authoring session — if the author edits `behavior.xml` mid-Topology-authoring, the next batch will re-validate Behavior before drafting more topology Elements. The Chain of Trust does not weaken over time. ## Authoritative inputs Once the chain-of-trust pre-check passes, the Skill loads: 1. **`behavior.xml`** — read-only, authoritative. Provides the domain vocabulary (``), the actors, the use cases, and the shared Behavior Elements. The Skill uses Behavior as the source of truth for *what the system does*; Topology models *which runnable things do it and how they talk*. Topology Elements never reference Behavior Elements directly from `` / `` / `` attributes (cross-section references flow upward from Interfaces and Composition, not from Topology directly), but the interview uses Behavior to choose unit boundaries (one use case typically maps to one or more units that realise it). 2. **`topology.xml`**, if it already exists — to detect id collisions on new Elements, to resolve `from=`/`to=` references against existing `` ids, and to extend rather than re-create when the author invokes `/usdl:topology` on a partially-authored Section. 3. **`sections/topology.md`** — the Section reference (purpose, what belongs, what does not belong, rules of inclusion and exclusion). The Skill **refers to** this file when explaining the Section to the author; it does **not** inline its content into the SKILL.md body. 4. **`dictionaries/topology_dictionary.md`** — the Topology dictionary, source of the closed enums for `via`, `mode`, `consistency`, `delivery`, `backpressure`, and the common `kind=` values. The Skill **refers to** the dictionary when offering enum menus and when defending rejections; it does **not** inline the dictionary's tables. 5. **`templates/topology/full.xml`** plus the per-Element templates (`unit.xml`, `communication.xml`, `environment.xml`) — loaded via `usdl:templates`. Element drafts are validated against these Templates before being written. ## Section-level Interview Script (units → communications → environments) The Skill drives the Section-level interview in **three stages**, matching Stage 3 → Stage 4 of `how-to-use.md`. Within each stage, the minimum-interview rule (`beh.rule.minimum-interview`) applies: required slots are asked unconditionally; optional slots are surfaced as offers and asked only when the author signals interest. ### Stage A — Units first (units → communications → environments) This stage corresponds to Stage 3 of `how-to-use.md`: *"Identify the runnable things the system needs. A CLI is a unit; a scheduled job is a unit; an external API the system calls is a unit (with `internal="false"`)."* The Skill walks the author through the system's runnable inventory, drawing on `behavior.xml`'s actors and use cases as prompts ("the booking actor's `beh.create-booking` use case — what runnable thing executes that flow?"). Each runnable thing becomes one `` Element. The Skill does **not** draft units inline. Instead: 1. **Surface `usdl:topology:services` as a See-Also Reference** before the first unit is drafted, and again whenever a new unit is about to be authored mid-Section. The peer owns the unit Interview Script (kind, owner, internal-or-external, description) and drafts XML matching `templates/topology/unit.xml`. 2. **Track unit ids** as they are written so the Communication stage can resolve `from=` and `to=` against the real Topology inventory. 3. **No communications are declared yet.** The interview deliberately defers edges until every unit the author has in mind exists; Stage 4 of `how-to-use.md` is explicit on this ordering. 4. **External units** (`internal="false"`) are surfaced as a category — third-party APIs, customer-supplied integrations, supplier endpoints. The Skill prompts the author to list them too; they belong in Topology even though their contracts live with the external party. At the end of Stage A, the Skill batches the new units, runs `usdl validate topology.xml` via `usdl:bin`, and only proceeds when validation passes. ### Stage B — Communications second This stage corresponds to Stage 4 of `how-to-use.md`: *"For every conversation between two units, declare a `` with all six required attributes: `from`, `to`, `via`, `mode`, `consistency`, `delivery`."* The Skill walks the author through every "A talks to B" edge implied by the use cases in `behavior.xml`, drawing edges with the units now in place. Each edge becomes one `` Element. The Skill does **not** draft communications inline. Instead: 1. **Surface `usdl:topology:communication` as a See-Also Reference** before the first communication is drafted, and again whenever a new edge is about to be authored mid-Section. The peer owns the six-attribute Interview Script in fixed order (`from`, `to`, `via`, `mode`, `consistency`, `delivery`), the optional `backpressure` and `carries` offers, and the rejection of abbreviated enum values (`sync` is not a legal `mode`). 2. **Apply the section-level red-flag check** (see *The red-flag check* below) on every `` whose attributes are visible to this Skill — at the moment the author proposes the six values, before the element-targeted peer drafts. The same red flag is re-checked by `usdl:topology:communication`; this Skill's check is a Section-grain safety net so the language-level fact is caught as early as possible. 3. **Defer `carries=`** until Stage 5 (Interfaces) per `how-to-use.md` Stage 4: *"After Stage 5 fills in operations, return here and add `carries="ifc.X,ifc.Y"` on each communication whose contract is documented."* If `interfaces.xml` does not yet exist, the Skill leaves `carries=` unset on every communication and notes (in the Section Handoff payload) that a return pass to Stage 4 will be needed after Interfaces is authored. 4. **All six attributes are mandatory**, per the Topology dictionary and the Section's rules of inclusion. The Skill never accepts a communication missing any of the six; the peer Skill rejects abbreviated tokens; both layers refuse to write a malformed edge. At the end of Stage B, the Skill batches the new communications, runs `usdl validate topology.xml` via `usdl:bin`, and only proceeds when validation passes. ### Stage C — Environments last This stage covers `` Elements — each named deployment topology (`dev`, `staging`, `prod-eu`, `prod-us`, `edge-class-A`, ...). The Skill asks the author to list every named deployment context the system runs in and, for each, which of the now-declared units appear (or, by inversion, which are excluded). Environments come last because they reference the unit inventory, not the other way around. The Skill drafts each `` Element inline (no element-targeted peer Skill exists for environments — the parent owns this kind), validating against `templates/topology/environment.xml` via `usdl:templates`. The minimum-interview rule applies: `id` and `name` are required; `excludes=` (or an `includes=` style note) and `` children are optional and surface only when the author signals interest. At the end of Stage C, the Skill batches the new environments, runs `usdl validate topology.xml` via `usdl:bin`, and proceeds to the Section Handoff step only when validation passes. ## The red-flag check — strong + async-event-broadcast This Skill surfaces, at the **Section grain**, the same red flag that `usdl:topology:communication` enforces at the element grain. The language-level fact is recorded in `composition.xml` (`cmp.topology-communication.skill-md`) and called out in `how-to-use.md` Stage 4 as *"the most common bug at this stage"*. **Rule:** when the author proposes a `` whose attributes include both `consistency="strong"` and `mode="async-event-broadcast"`, the Skill pauses and asks the corrective question before any draft is produced. The corrective question explains both halves of the language-level fact: - `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. - **The combination is impossible to deliver:** a broadcast cannot guarantee strong consistency across unknown subscribers. The Skill asks the author to revisit one of the two values: - If the consumer truly needs strong consistency, the interaction is not a broadcast — consider `mode="sync-request-response"` 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"` or `consistency="not-applicable"`. The Skill **never silently accepts** the combination, **never** drafts the Element while it stands, and **never** normalises one of the two values on the author's behalf. It pauses, asks the corrective question, and either records the amended value or — if the author insists on the combination — escalates per `beh.rule.escalate-not-fabricate` and refuses to draft. The element-targeted peer (`usdl:topology:communication`) re-runs the same check; both layers refuse to write the malformed edge. This is the only language-level "impossible attribute combination" the Topology Section enforces at the section-spanning grain. Other illegal answers (abbreviated `mode` values, unresolved `from=`/`to=` ids, payload-shaped attributes that belong in Interfaces) are caught either by the element-targeted peer Skills, by `usdl:templates`' Template conformance check, or by `usdl validate`. ## Minimum-interview rule Per `beh.rule.minimum-interview`, this Skill asks unconditionally only those questions whose answers fill **required** attributes or **required** children of the Element being authored: - For ``: `id`, `kind`, `owner`, and ``. `internal=` is required only when the unit is external (default `true`). - For ``: the six mandatory attributes (`from`, `to`, `via`, `mode`, `consistency`, `delivery`) plus `id`. `backpressure=`, `carries=`, `status=`, and `` are optional. - For ``: `id` and `name`. `excludes=` and `` are optional. Optional slots are surfaced as offers — short prompts the author can decline ("want to declare which units are excluded from this environment?"). If the author declines, the attribute or child is omitted. This minimises the author's cognitive load per `nfr.author-cognitive-load`. The Skill never invents an answer to satisfy an optional slot, never inserts placeholders, and never asks an optional question more than once per Element. ## Self-validate via usdl:bin (after each batch) Per `beh.rule.self-validate-before-done` and the `inv.spec-section-validity` invariant, this Skill runs `usdl validate topology.xml` via `usdl:bin` after each batch — once at the end of Stage A (units), once at the end of Stage B (communications), and once at the end of Stage C (environments). The Skill does not declare a batch complete until validation passes. On a Bin failure: 1. Classify each diagnostic as Trivial or non-Trivial per `beh.attempt-trivial-repair`. 2. For Trivial diagnostics (id collision with a numeric-suffix rename, enum substitution, duplicate child removal), apply the repair and re-run `usdl validate`. 3. For non-Trivial diagnostics (semantic, ambiguous, missing required input), escalate to the author per `beh.rule.escalate-not-fabricate` — re-open the interview slot the diagnostic points at, ask the corrective question with the legal shape, and re-run validation once the answer is in. 4. Bounded retries per `beh.rule.repair-bounded`; on exceeding the limit, the Skill halts and surfaces the remaining diagnostics without declaring the Section complete. The Skill itself does **not** mutate `topology.xml` directly. Mutations go through `usdl:bin` (or, when the host runs Write/Edit on its behalf, through a tool call the parent / Agent makes); this Skill describes the flow and surfaces the validation discipline. ## Section Handoff (releases usdl:interfaces) Per `beh.handoff-section` and `inv.section-chain-of-trust`, this Skill emits the **Section Handoff** signal exactly when: 1. Every batched Stage (A, B, C) has been written to `topology.xml`. 2. The final `usdl validate topology.xml` invocation reports **zero errors** (warnings, including orphan warnings, are reported to the author but do not block handoff). 3. The author has confirmed the diff for this authoring pass (when running under `/create-specification`, this is the orchestrator's confirmation; when running standalone via `/usdl:topology`, this is the author's direct acknowledgement). The handoff signal names the Section (`topology`), its validated state, and any deferred work — most commonly, the list of `` Elements whose `carries=` was deliberately left blank pending Stage 5 (Interfaces). The handoff is the moment `usdl:interfaces` may be invoked with `behavior.xml` and `topology.xml` both loaded as authoritative input. The Skill withholds the handoff signal if validation still reports errors at the moment handoff would normally occur. In that case it surfaces the diagnostics, refuses to declare completion, and waits for the author to either correct the offending input or accept an escalation that defers the failing Element. The handoff is the language-level commitment that downstream Sections may trust this Section; this Skill never signals it under false pretences. ## Response shape A successful invocation returns to the parent (`/create-specification` or the spec author directly): - A summary of every ``, ``, and `` Element written or modified in `topology.xml`, with their ids. - The current pass/fail status of `usdl validate topology.xml`. - The list of communications whose `carries=` was deliberately left blank pending Stage 5 (so a future `/usdl:topology` invocation, after `usdl:interfaces` has run, can complete the linkage). - The Section Handoff signal when validation passes and the author confirms; otherwise the outstanding diagnostics or open interview questions. A halted invocation (chain-of-trust pre-check failure, or non-Trivial diagnostic exceeding the repair limit) returns instead: the Section at fault (when the halt is upstream), the Bin diagnostics, and a See-Also Reference to the Skill that owns the broken input (`usdl:behaviour` when `behavior.xml` is the cause; `usdl:topology:services` or `usdl:topology:communication` when an element-grain answer is the cause). No `topology.xml` Element is written under a halt. ## What this Skill does not do - It does not author any Element outside `topology.xml`. Behavior, Interfaces, and Composition are out of scope; the Skill refuses to extend them and escalates if the author asks. - It does not draft individual `` or `` Elements inline when the element-targeted peer Skill is available; it surfaces the See-Also Reference and lets the host route. (Environments are drafted inline because no peer Skill exists for them.) - It does not inline `sections/topology.md` or `dictionaries/topology_dictionary.md` into its own body; it refers to them and lets `usdl:templates` and the element-targeted peers carry the dictionary's enum tables. - It does not copy template XML into the body. Templates live under `templates/topology/` and are loaded via `usdl:templates`. - It does not skip the chain-of-trust pre-check — not on re-invocation, not on "just one more unit" requests, not on the author's verbal assurance that `behavior.xml` is fine. Bin is the only judge. - It does not silently accept the strong + async-event-broadcast combination. The corrective question is asked every time; the Skill refuses to draft while the combination stands. - It does not emit the Section Handoff signal until `usdl validate topology.xml` passes with zero errors. - It does not invoke peer Skills. Routing between Skills is the host's responsibility, informed by the See-Also References declared above. - It does not carry executable code (`con.no-implementation-code-in-skill-md`). Everything above is prose describing what to check, in what order, and what to forbid.

usdl-topology

Install this skill

Comments