--- name: usdl-composition description: Section-spanning Skill for authoring and extending the USDL Composition Section (composition.xml) — the "inside each unit, which architectural components are present and which structural rules govern them" layer of a USDL Spec. User-invocable directly as /usdl:composition. Reads behavior.xml, topology.xml, AND interfaces.xml as authoritative input (per the Chain of Trust); refuses to draft any Composition Element when any of those three higher Sections is missing or fails `usdl validate`, surfacing exactly which Section is at fault (the missing-higher-section failure mode of `ifc.skill.composition`). Drives the Section-level interview in the order Stage 6 of how-to-use.md prescribes — for each unit owned, components first (intent → structure → logic → requires → constraints, in that exact child order); then top-level reusable constraints (one of pattern | anti-pattern | naming-rule | rule); then call-flows with for-use-case, in-unit, and at least two `` children. Applies the minimum-interview rule (only required slots asked unconditionally; optional slots surface on author interest). Enforces the `` vs `` distinction at interview time — logic rules are procedural ("validate input before any side effect"); constraints are structural ("the domain layer must not import infrastructure"); both are complementary and may co-exist on one component. Surfaces a See-Also Reference to usdl:composition:skatchbook whenever a component's intent is unclear and the author would benefit from experimenting with candidate code abstractions in the Skatchbook first; the chosen abstraction is translated back into architectural prose without copying any code into the Spec, per `beh.rule.no-code-in-spec`. Self-validates every batch via usdl:bin (`usdl validate composition.xml`) and emits the terminal Section Handoff signal when composition.xml validates — Composition is the bottom of the stack, so no further Section opens. Trigger this Skill when the active task mentions "composition", "composition.xml", "component", "constraint", "call-flow", "structure", "intent", "logic", "architecture", "zone", "in-unit", "pattern", "anti-pattern", "naming-rule", "require/forbid", "author composition", "compose components", or any of the kebab-case `cmp.*`, `con.*`, or `com.flow.*` ids that live in composition.xml. Description-only; no executable code. user-invocable: true --- # usdl-composition ## What this Skill is This is the **section-spanning Skill** that drives authoring (and extending) of one USDL Spec's `composition.xml`. It is the `/usdl:composition` user-invocable Skill the agent host loads when the active task is about the Composition Section: declaring, inside each Topology unit, the small set of named architectural **components** that partition the unit's codebase, plus the reusable typed **constraints** that govern them, plus the **call-flows** that name the component traversal order for each use case handled inside the unit. Composition answers the reviewer question: **Inside a unit, are the right architectural components present, and is each one organised as required?** This Skill makes sure that question can be answered by interview, by Template-checked drafting, and by `usdl validate`. Its job is to: 1. Confirm the **three-Section Chain of Trust** is intact before any drafting — `behavior.xml`, `topology.xml`, AND `interfaces.xml` all exist and all pass `usdl validate`. 2. Drive the Section-level interview in the order Stage 6 of `how-to-use.md` prescribes — for each unit owned, **components first** (with the four facets in exact child order), then **top-level reusable constraints**, then **call-flows**. 3. Enforce the `` vs `` distinction at interview time — procedural rules go into ``, structural rules into reusable top-level `` definitions referenced by ``. 4. Surface a See-Also Reference to `usdl:composition:skatchbook` whenever a component's intent is unclear and candidate abstractions need experimenting before any architectural prose is committed. 5. Reject any draft that smuggles filenames, function signatures, parameter types, or library prescriptions into ``, ``, ``, or `` (`beh.rule.no-code-in-spec`). 6. Self-validate every batch via `usdl:bin` (`usdl validate composition.xml`). 7. Emit the **terminal Section Handoff** signal once `composition.xml` validates cleanly — Composition is the bottom of the stack, so no further section opens. This Skill writes Composition Elements only. It must not author Behavior, Topology, or Interfaces Elements. Component-level Skatchbook experimentation is delegated to `usdl:composition:skatchbook` via a See-Also Reference; the host routes between Skills. This Skill is **user-invocable**. It is also preloaded by `top.agent.composition-author` (the section-authoring Agent), which runs the same interview in isolated context and returns a summary diff (`cmp.composition-author.agent-md`). ## How it fits with peer Skills - **Higher Sections (read-only, authoritative input) — all three:** - `usdl:behaviour` — source of truth for actors, use cases, glossary, shared Behavior Elements. Each `` references a `` via `for-use-case`. - `usdl:topology` — source of truth for the unit inventory. Every `` and every `` carries `in-unit="top.X"` resolving against a real `` in `topology.xml`. - `usdl:interfaces` — source of truth for contracts and operations. Composition itself never references Interfaces; the reverse direction (``) is what closes the loop. The Skill still trusts `interfaces.xml` as input because the Chain-of-Trust validation in step 3 below is mandatory. - **Element-targeted peer (See-Also Reference, surfaced at drafting time):** - `usdl:composition:skatchbook` — opens a Skatchbook entry alongside one Composition component, walks candidate code abstractions (PHP class, Python class, pseudo-code) through small examples, and writes the chosen abstraction's structure / require / forbid description back into the component **without copying any code into the Spec**. Surfaced when a component's intent is unclear and the author would benefit from experimenting first. - **Template authority:** `usdl:templates` — owns the canonical Element Templates under `templates/composition/` (`full.xml`, `component.xml`, `constraint.xml`, `call-flow.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`, `usdl validate topology.xml`, and `usdl validate interfaces.xml` for the three-Section chain-of-trust pre-check, and `usdl validate composition.xml` after every batch and at Section Handoff. - **Lower Sections (none):** Composition is the terminal Section. No further section-spanning Skill awaits its handoff; the Spec is complete once Composition validates. 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:composition:skatchbook`** — when a ``'s intent is unclear and a candidate abstraction needs experimenting before the `` / `` / `` facets are filled in. The peer opens a Skatchbook entry, walks one or more candidate typed shapes through small examples, and translates the chosen shape into architectural prose (no filenames, no signatures) that the parent Skill writes back to `composition.xml`. - **`usdl:bin`** — the wrapper around the `usdl` CLI. Used for the three-Section chain-of-trust pre-check (`usdl validate behavior.xml`, `usdl validate topology.xml`, `usdl validate interfaces.xml`) and the self-validate-before-done step (`usdl validate composition.xml`). - **`usdl:templates`** — the bundled Element Templates and the Element-versus-Template conformance check. Surfaced whenever a ``, ``, or `` draft is being shaped against a Template under `templates/composition/`. - **`usdl:behaviour`** — the section-spanning Skill for `behavior.xml`. Surfaced when the chain-of-trust pre-check identifies Behavior as the missing or invalid higher Section, or when a ``'s `for-use-case` cannot resolve and the author needs to author or fix the use case first. - **`usdl:topology`** — the section-spanning Skill for `topology.xml`. Surfaced when the chain-of-trust pre-check identifies Topology as the missing or invalid higher Section, or when a component's `in-unit` cannot resolve and the author needs to author or fix the unit first. - **`usdl:interfaces`** — the section-spanning Skill for `interfaces.xml`. Surfaced when the chain-of-trust pre-check identifies Interfaces as the missing or invalid higher Section. Also surfaced after Composition handoff, because every `` in `interfaces.xml` that handles a use case realised inside a unit owning a call-flow needs to gain `governed-by="com.flow.X"` — that linkage is filled in `interfaces.xml`, not here. The Skill does not list any lower-Section peer as a See-Also Reference because Composition is the terminal Section; no Section sits below it (`term.reference-direction`, `inv.reference-direction-monotonic`). ## Chain-of-trust pre-check — three higher Sections (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 three-Section chain-of-trust pre-check before authoring a single Composition 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 component to an already-existing `composition.xml`. Composition is the only Section whose chain-of-trust pre-check spans three higher Sections — Behavior, Topology, and Interfaces. The check is the realisation of the `missing-higher-section` failure mode declared on `ifc.skill.composition` (`provider-promise="reports which higher Section is missing or invalid; no composition Element is written"`). Steps, in order: 1. **Confirm `behavior.xml` exists** in the Spec directory. If absent, the Skill halts and reports: **"Composition cannot be authored: `behavior.xml` is missing. Behavior is the topmost higher Section that Composition trusts; please author it first via `usdl:behaviour`."** No further check runs. 2. **Run `usdl validate behavior.xml`** via `usdl:bin`. If Bin exits non-zero, halt and surface the diagnostics verbatim; route the author back to `usdl:behaviour` via a See-Also Reference. 3. **Confirm `topology.xml` exists.** If absent, halt and report Topology as missing; route to `usdl:topology`. No `` may declare an `in-unit` that does not resolve to a real ``; Topology must be in place first. 4. **Run `usdl validate topology.xml`** via `usdl:bin`. If Bin exits non-zero, halt and surface the diagnostics; route to `usdl:topology`. 5. **Confirm `interfaces.xml` exists.** If absent, halt and report Interfaces as missing; route to `usdl:interfaces`. Composition's call-flows are pointed at by operations via `governed-by`; that linkage cannot be honoured if Interfaces does not yet exist. 6. **Run `usdl validate interfaces.xml`** via `usdl:bin`. If Bin exits non-zero, halt and surface the diagnostics; route to `usdl:interfaces`. 7. **Only on three clean passes do further interview steps begin.** Until step 6 passes, the Skill refuses to draft any Composition Element — no ``, no ``, no ``. It also refuses to load or pre-fill any Template. On a halt, the Skill follows `beh.rule.escalate-not-fabricate`: it does not invent missing use cases, units, contracts, or operations to push past the failure; it names which of the three higher Sections is at fault (and, when Bin's diagnostics identify one, which Element id is at fault) and routes the author back to the matching section-spanning Skill 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`, `topology.xml`, or `interfaces.xml` mid-Composition-authoring, the next batch will re-validate all three higher Sections before drafting more Composition Elements. The Chain of Trust does not weaken over time, and Composition's three-Section span does not collapse to "just check the latest one". ## Authoritative inputs Once the three-Section chain-of-trust pre-check passes, the Skill loads: 1. **`behavior.xml`** — read-only, authoritative. Source for use-case ids referenced by `` and the domain vocabulary the interview leans on when interrogating component intent. 2. **`topology.xml`** — read-only, authoritative. Source for `` ids referenced by `` and ``. The Skill iterates over the units the author owns (or is responsible for) and asks for components per unit. 3. **`interfaces.xml`** — read-only, authoritative. The Skill consults operation ids and their `realizes-behavior` lists so that, when call-flows are drafted, the author can be reminded which use cases each operation handles inside which unit (the reverse-linkage hint that lets the author plan call-flows the operations will later point at via `governed-by`). 4. **`composition.xml`**, if it already exists — to detect id collisions on new Elements, to resolve `` and `` against existing ids, and to extend rather than re-create when the author invokes `/usdl:composition` on a partially-authored Section. 5. **`sections/composition.md`** — the Section reference (purpose, the four component facets, the four constraint types, rules of inclusion and exclusion). The Skill **refers to** this file when explaining the Section to the author; it does **not** inline its content. 6. **`dictionaries/composition_dictionary.md`** — the Composition dictionary, source for the closed enum of constraint `type=` values, the normative child order on ``, and the `` vs `` disambiguation table. The Skill **refers to** the dictionary when defending rejections; it does **not** inline its tables. 7. **`templates/composition/full.xml`** plus the per-Element templates (`component.xml`, `constraint.xml`, `call-flow.xml`) — loaded via `usdl:templates`. Element drafts are validated against these Templates before being written. ## Section-level Interview Script (components → constraints → call-flows, per unit) The Skill drives the Section-level interview in **three stages**, matching Stage 6 of `how-to-use.md`. For Composition, the stages are scoped *per unit*: the author is asked to pick one unit (or to iterate through every unit they own), and within that unit the three stages run in order before the next unit begins. Within each stage, the minimum-interview rule (`beh.rule.minimum-interview`) applies. ### Stage A — Components first (per unit) Stage A corresponds to Stage 6 step 1 of `how-to-use.md`: *"For each unit you own, declare the architectural components — directories that have an intent of their own."* The Skill walks the author through each unit's runnable codebase and asks, for each named architectural object, one `` Element. Each component is drafted with its four facets in **strict child order** — out-of-order children are rejected by `usdl validate` and by `usdl:templates`. The order, per `composition_dictionary.md` section 3 and section 7 invariant 10, is: 1. **``** — *required, exactly one.* One short paragraph: what this component is for. The Skill asks first and refuses to advance until an intent is given. If the author cannot articulate the intent, the Skill **surfaces `usdl:composition:skatchbook`** as a See-Also Reference: the peer opens a Skatchbook entry, walks candidate code abstractions through small examples, and the chosen shape translates back into prose for `` (and optionally ``) — **without any filenames or signatures crossing into the Spec** (`beh.rule.no-code-in-spec`). 2. **``** — *optional, zero or one.* Free prose describing the internal high-level abstractions: main classes, modules, roles. Bullets are encouraged. The Skill rejects any draft that contains a filename (`*.py`, `usdl-cli.json`), a function signature (`def foo(x: int) -> Y:`), parameter types, library prescriptions ("uses Pydantic"), or endpoint shapes; those belong in ADRs, in code, or in Interfaces `` documents — not here. 3. **``** — *optional, zero or one.* A container of `` children describing **procedural** rules the code inside the component must follow: call order, validation order, error translation, state transitions. Each `` is free text, one short sentence, no `id`, no `pattern=` attribute. (See *The `` vs `` distinction* below.) A `` with no `` children is dead text and is rejected by `usdl validate` (composition dictionary invariant 8). 4. **``** — *optional, zero or more.* Each entry declares a dependency on another component. The Skill resolves `ref=` against the already-drafted (or already-present) Composition components; unresolved references halt the draft per `beh.rule.escalate-not-fabricate`. 5. **``** — *optional, zero or one.* A container of `` references to top-level `` definitions. **References only** — the actual `` definitions live at the spec root and are authored in Stage B. If the author names a constraint that has not yet been defined, the Skill defers the `` block of that component until Stage B has produced the matching top-level `` definitions, then comes back and fills the references; it never invents the referenced constraint. The Skill also enforces the **non-overlapping-zone rule** at draft time (`composition_dictionary.md` section 4 reference-resolution rule 5; `sections/composition.md` rules-of-inclusion item 6): components inside the same `in-unit` must declare non-overlapping `zone` paths — one file lives in at most one component's zone. The Skill cross-checks every new `zone=` against the unit's existing components and rejects an overlap, asking the author to refine boundaries or to express nested architecture via `` rather than via zone overlap. The Skill does not draft inline when a Skatchbook session would help; instead it surfaces `usdl:composition:skatchbook` and lets the host route. For straightforward components (intent is clear, structure obvious, no abstractions to experiment with), the Skill drafts inline and validates against `templates/composition/component.xml` via `usdl:templates`. At the end of Stage A for one unit, the Skill batches the new components, runs `usdl validate composition.xml` via `usdl:bin`, and only proceeds to Stage B for that unit when validation passes. ### Stage B — Top-level reusable constraints Stage B corresponds to Stage 6 step 2 of `how-to-use.md`: *"For each rule the team needs, declare a `` with `type=` …, ``, optional ``, and `` / `` children."* For each rule the components in Stage A reference (or that the author intends them to reference), the Skill asks the author for one top-level `` Element. The interview gathers, in fixed order: 1. **`id`** — `con.`, unique within the entire Spec. 2. **`type=`** — exactly one of: - **`pattern`** — the component(s) must take this shape. Reach for `pattern` when the rule is "strategy + registry", "state machine", "port-and-adapter", "pipeline", "factory" — a *required structural shape*. Typical children: `` clauses for what must exist, `` clauses naming bypass constructs that would prove the pattern was abandoned. - **`anti-pattern`** — *this specific construct* must not appear. Reach for `anti-pattern` when the prohibited construct is well-known and harmful: string-concatenated SQL, static mutable state, raw PAN in logs. Children are primarily `` slugs backed by a strong `` (anti-patterns benefit most from rationales because the harm avoided may not be obvious). - **`naming-rule`** — entity-name shape: suffix `Repository`, prefix `Out`, suffix `UseCase`, suffix `Port`. Children are usually a single `` stating the name shape. - **`rule`** — anything else: visibility, dependency intent expressed abstractly, layer-import rules that don't fit the other three. The fallback type; children are a mix of `` and ``. 3. **``** — required. One sentence to one paragraph stating what the constraint asserts. 4. **``** — optional, surfaced as an offer. The Skill recommends a rationale unconditionally on `type="anti-pattern"` because the harm being avoided is often non-obvious; for the other three types, the offer is asked once and declines are accepted. 5. **``** and **``** — at least one of either is strongly recommended (a constraint with no `` and no `` is documentation-only and `usdl validate` warns; see composition dictionary section 3). The Skill rejects a `` body that contains a filename or a function signature (`beh.rule.no-code-in-spec`) and rejects a `` `construct=` slug that is not kebab-case. Constraints carry **no scope of their own** — no `in-unit`, no `applies-to`, no `zone`. Their scope is the set of components that reference them via ``. The Skill enforces this by rejecting any attempt to attach an `in-unit`, `applies-to`, or `zone` attribute on a top-level `` Element. The same constraint may be referenced by many components in many units; that is the *point* of the top-level definition. After Stage B for the current unit's needs, the Skill returns to any Stage A components whose `` block was deferred and fills in the now-resolvable `` references. It then batches the new constraints (and the back-filled component references), runs `usdl validate composition.xml` via `usdl:bin`, and only proceeds to Stage C when validation passes. ### Stage C — Call-flows (per unit) Stage C corresponds to Stage 6 step 3 of `how-to-use.md`: *"For each ``, set `for-use-case` and `in-unit` and list the components the request traverses via `` children."* For each use case handled inside the current unit (drawn from `behavior.xml` and cross-checked against `interfaces.xml` operations whose contracts have this unit as `provider`), the Skill asks the author for one `` Element. The interview gathers, in fixed order: 1. **`id`** — `com.flow.`, unique within the Spec. 2. **`in-unit`** — must resolve to a real `` in `topology.xml`. The Skill rejects unresolved ids and routes to `usdl:topology` if the unit needs to be added. 3. **`for-use-case`** — must resolve to a real `` in `behavior.xml`. The Skill rejects unresolved ids and routes to `usdl:behaviour` if the use case needs to be added. 4. **`direction`** — optional, default `inbound`; surfaced as an offer with the legal enum (`inbound | outbound | bidirectional`). 5. **`` children** — required, **two or more**. A one-step call-flow is rejected by `usdl validate` (composition dictionary invariant 3 / section 3). Each `component=` ref must resolve to a real `` already declared (in this unit's Stage A or earlier). The Skill drafts steps in the order the handling traverses them; the same component may appear more than once (round-trips out and back are common). 6. **`optional="true"` on individual ``** — surfaced as an offer per step; marks a step that may be skipped during a particular execution of the flow. The Skill does not yet ask Interfaces to fill in `` — that linkage is authored in `interfaces.xml`, not here. The Section Handoff payload (below) records, for every new `` written, the operation ids whose `realizes-behavior` matches the flow's `for-use-case` and whose contract's `provider` matches the flow's `in-unit`; the author (or `/create-specification`) is expected to return to `usdl:interfaces` after handoff and add `governed-by=` to each. At the end of Stage C for one unit, the Skill batches the new call-flows, runs `usdl validate composition.xml` via `usdl:bin`, and only marks that unit's Composition pass complete when validation passes. The three-stage cycle then repeats for the next unit until every unit the author owns has been covered. ## The `` vs `` distinction (procedural vs structural) This distinction is the single most important interview-time decision inside Composition. The Skill applies it on every component, asks corrective questions when an author proposes a rule under the wrong header, and refuses to write a draft that confuses the two. Per `sections/composition.md` *"`` vs `` — procedural vs structural"* and `dictionaries/composition_dictionary.md` section 6 *"`` vs ``"*: | Aspect | `` | `` | |---|---|---| | What it captures | What the code must **do** (procedurally) | What shape the code must **take** (structurally) | | Body | Collection of `` children (free text, one rule per child) | Collection of `` references to top-level typed rules | | Examples | "Validate input before any side effect." "Translate port errors at the boundary." "Persist before notify." | "The domain layer must not import infrastructure." "Each strategy is its own file." "Repository classes end in `Repository`." | | Reusability of contents | Each `` is local to one component | Each `` is defined once at the top level and reused across components | | Verification stage | Mostly Stage 5 (semantic review); some call-order rules are Stage 2 with AST analysis | Stage 2 (mechanical: ArchUnit, Deptrac, import-linter, AST queries) | The two blocks are **complementary, not alternatives**. Both may appear on the same component; either may be omitted. Most non-trivial components benefit from declaring both — *what the code does* and *what shape the code takes*. **Interview corrections the Skill performs:** - If the author proposes "the domain layer must not import infrastructure" as a ``, the Skill moves it: that is a *structural* fact (an import graph constraint), not a *procedural* one. It belongs in a top-level `` referenced from the component's ``. - If the author proposes "persist before notify" as a top-level ``, the Skill moves it: that is a *procedural* fact (an ordering of runtime operations), not a *structural* one. It belongs in `` on the specific component whose handler does the persisting and the notifying. - If the author proposes "each strategy is its own file" as a ``, the Skill moves it: that is a *structural* fact about source-tree shape. It belongs in a top-level `` referenced from the component's ``. - If the author proposes "validate input before any side effect" as a top-level ``, the Skill moves it: that is *procedural*. It belongs in `` on the input-handling component. Per composition dictionary section 6, the `` inside `` is **disambiguated from Behavior's top-level `` by parent context and by attributes**: Composition's `` is parented by ``, has no `id`, has no `pattern=` attribute, and its body is free text — one short sentence. Behavior's top-level `` is parented by ``, has an `id`, has a required `pattern=` (EARS), and its body uses the EARS template. A linter accepts both shapes; the Skill never tries to make one look like the other. ## No code in spec (`beh.rule.no-code-in-spec`) This Skill enforces `beh.rule.no-code-in-spec` at every drafting step. The rule is absolute for Composition: filenames, function signatures, parameter types, library prescriptions, and endpoint shapes never appear in: - `` — names the architectural object's purpose, not its implementation surface. - `` — names main classes, modules, and roles in prose. *No filenames* (`anthropic.py`, `usdl-cli.json`). *No function signatures* (`def render(template, element) -> text:`). *No parameter types*. *No library prescriptions* ("uses Pydantic"); library choices are ADR-level and may be referenced from a `` on a constraint if useful. - `` and `` — describe shape and prohibited constructs in prose; `construct=` slugs on `` are short kebab-case machine-readable hints (e.g. `static-mutable-state`, `domain-import-of-infrastructure`), not code. - `` — explains *why*, not *how*; code-level detail belongs in code. When the author's intent is unclear and the temptation to "just paste a class" rises, the Skill **surfaces `usdl:composition:skatchbook`** instead. The Skatchbook peer: 1. Opens a Skatchbook scratch entry in `top.skatchbook-store` (outside the Spec store). 2. Drafts one or more candidate typed shapes (PHP class, Python class, pseudo-code) and walks them through small examples. 3. Lets the author pick a shape. 4. Translates the chosen shape's *architectural skeleton* into prose for `` (main classes and roles) and into `` / `` clauses on the relevant top-level constraint — **stripping all code-level detail before emitting the fragment**. 5. The parent Skill then writes the fragment to `composition.xml` via `usdl:bin`. The Skatchbook scratch entry stays in the Skatchbook store; no code ever crosses into the Spec. This is the language-level guarantee that Composition stays at the architectural grain. If a draft slips a filename or a signature through (because the author insisted or the Skatchbook translator missed a detail), `usdl validate` flags it and the Skill rejects the draft per `beh.rule.no-code-in-spec`. The repair is to re-open the Skatchbook session and re-translate. ## 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`, `zone`, `in-unit`, and `` (the only required child). ``, ``, ``, ``, and `status=` are optional and surface as offers; declines are accepted without re-asking. - For ``: `id`, `type=`, and ``. ``, ``, ``, and `status=` are optional; the Skill recommends `` on `type="anti-pattern"` but accepts a decline. - For ``: `id`, `in-unit`, `for-use-case`, and at least two `` children. `direction=` defaults to `inbound`; `optional=` on each step defaults to `false`; both are offered, declines accepted. 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 composition.xml` via `usdl:bin` after each batch — once at the end of Stage A for each unit (components), once at the end of Stage B (constraints, including back-filled component `` references), and once at the end of Stage C for each unit (call-flows). 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, child-order swap inside ``, duplicate child removal, an enum substitution on `type=`), apply the repair and re-run `usdl validate`. 3. For non-Trivial diagnostics (semantic, ambiguous, missing required input, a constraint with no `` and no ``, an overlapping `zone=` between two components in the same `in-unit`, a `` block with no `` children, a `` with fewer than two steps, a filename smuggled into ``), 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 `composition.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 — terminal 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 `composition.xml` for every unit the author owns. 2. The final `usdl validate composition.xml` invocation reports **zero errors** (warnings, including orphan warnings on constraints no component references, 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:composition`, this is the author's direct acknowledgement). Composition is the **terminal** Section: this handoff is the last section-spanning handoff in a top-down authoring pass. No further section-spanning Skill awaits it; the Spec is complete (modulo any return-pass to `usdl:interfaces` to fill `governed-by=` on operations that now have call-flows). The handoff signal names the Section (`composition`), its validated state, and the list of new `` ids the author should now back-link from Interfaces operations via `governed-by`. 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. ## 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 `composition.xml`, with their ids and (for components) the unit they live in. - The current pass/fail status of `usdl validate composition.xml`. - The list of new `` ids the author should back-link from Interfaces operations via `governed-by=` (the return-pass hint to `usdl:interfaces`). - The list of constraints written without a `` or `` (documentation-only constraints — `usdl validate` warns, the Skill surfaces). - The terminal Section Handoff signal when validation passes and the author confirms; otherwise the outstanding diagnostics or open interview questions. A halted invocation (three-Section chain-of-trust pre-check failure, or non-Trivial diagnostic exceeding the repair limit) returns instead: which of the three higher Sections is 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`, `usdl:topology`, or `usdl:interfaces`). No `composition.xml` Element is written under a halt. ## What this Skill does not do - It does not author any Element outside `composition.xml`. Behavior, Topology, and Interfaces are out of scope; the Skill refuses to extend them and escalates if the author asks. - It does not draft a component inline when the author cannot articulate its intent; it surfaces `usdl:composition:skatchbook` and lets the host route to a Skatchbook session. - It does not inline `sections/composition.md`, `dictionaries/composition_dictionary.md`, or any of the `templates/composition/` files into its own body; it refers to them and lets `usdl:templates` and `usdl:composition:skatchbook` carry the heavy lifting. - It does not skip the three-Section chain-of-trust pre-check — not on re-invocation, not on "just one more component" requests, not on the author's verbal assurance that the higher Sections are fine. Bin is the only judge, and all three higher Sections must pass. - It does not accept a draft with filenames, function signatures, parameter types, library prescriptions, or endpoint shapes in ``, ``, ``, ``, or ``. The corrective routing is to `usdl:composition:skatchbook`. - It does not accept a `` that is structural rather than procedural, nor a top-level `` that is procedural rather than structural. The corrective question is asked and the rule is moved to the right block. - It does not accept two components inside the same `in-unit` with overlapping `zone=` declarations. Nested architecture is expressed via ``, not zone overlap. - It does not accept a `` with fewer than two `` children. A one-step flow is not a flow. - It does not emit the Section Handoff signal until `usdl validate composition.xml` passes with zero errors and the author confirms. - 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-composition

Install this skill

Comments