--- name: usdl-behaviour description: Section-spanning Skill for authoring or extending behavior.xml, user-invocable as /usdl:behaviour. Trigger this Skill whenever the author wants to "author behavior", work on "behaviour.xml" or "behavior.xml", add a "use case", define a "glossary" term or "actor", or otherwise work on the "behavior section" of a USDL Spec. Holds the section-level interview script for the seven Behavior top-level Element kinds (glossary-term, actor, use-case, rule, invariant, nfr, event), follows the minimum-interview rule (only required slots are asked unconditionally), surfaces See-Also References to usdl:behaviour:usecase and usdl:behaviour:nfr when an Element of that kind is about to be drafted, and self-validates the written behavior.xml via usdl:bin before declaring completion. Realizes beh.bootstrap-section, beh.extend-section, beh.delegate-to-related-skill, and beh.handoff-section. user-invocable: true --- # usdl-behaviour ## What this Skill is for `usdl:behaviour` is the section-spanning Skill for `behavior.xml` — the Behavior axis of a USDL Spec. Behavior answers the reviewer question *"does the running system do what the domain requires?"* and is the first Section authored in any new Spec: every lower Section (Topology, Interfaces, Composition) trusts Behavior as authoritative input. This Skill carries the **section-level Interview Script** that walks the Spec author top-down across every Behavior Element kind, drafts each Element from its Template, runs the result through `usdl validate`, and emits a Section Handoff when validation passes so `usdl:topology` may begin. It does **not** carry per-Element drafting scripts. When a use case or an NFR is about to be drafted, this Skill surfaces a See-Also Reference to the matching element-targeted peer (`usdl:behaviour:usecase`, `usdl:behaviour:nfr`) per `beh.rule.peer-skill-cross-reference` and lets the agent host route there. For the full vocabulary the Spec author needs: - `./sections/behavior.md` — the prose explanation of what Behavior is and how it is laid out. - `./dictionaries/behavior_dictionary.md` — the normative dictionary of every Behavior Element type, required attribute, required child, and reference direction. Load this when interview answers need to be mapped to attribute slots. Both are referenced, never inlined. The body below is the interview surface only. ## The seven Behavior top-level Element kinds Behavior has exactly seven top-level Element kinds. The interview visits them in the order below; each kind has its own See-Also routing when peer-specialised drafting applies. | Kind | Required attributes | Required children | Peer Skill for drafting | |---|---|---|---| | `` | `id`, `term` | `` | (inline — no peer Skill) | | `` | `id`, `kind` | `` | (inline — no peer Skill) | | `` | `id`, `actor` | ``, `` with one or more ``, at least one `` | **`usdl:behaviour:usecase`** | | `` (top-level, EARS) | `id`, `pattern` | text content is the EARS sentence | (inline — no peer Skill) | | `` | `id`, `scope` | `` | (inline — no peer Skill) | | `` | `id`, `quality` (plus `measure` and `threshold` if `quality` is `performance` or `availability`) | one or more `` | **`usdl:behaviour:nfr`** | | `` | `id`, `name` | — (a `` is recommended) | (inline — no peer Skill) | The dictionary section 3 in `behavior_dictionary.md` is the authoritative reference. This Skill defers to it on every attribute and child shape. ## Section-level interview order The Behavior interview runs **top-down**: the more fundamental the Element kind, the earlier it is asked. Each later kind may reference earlier ones; the reverse is forbidden by the dictionary's reference-direction rules. The order is fixed: 1. **Glossary terms** — define the ubiquitous language first. Every later Element's prose, every `` in every ``, must use only terms defined here. Ask the author for the small set of domain nouns and verbs that recur in their description; for each, capture exactly the `term` attribute, the `id`, and one precise `` sentence. 2. **Actors** — name every role that initiates use cases. For each actor, ask only its `id` and its `kind` (`human`, `external-system`, `scheduler`, or `internal-system`), plus a one-paragraph ``. No other attribute is allowed on ``. 3. **Use cases** — the central Behavior Element. For each use case the author wants to add, surface `usdl:behaviour:usecase` as a See-Also Reference (see the next section). Do not inline the use-case Interview Script in this Skill; the peer owns it. 4. **Shared elements** — the four Behavior collections referenced by use cases, in this sub-order: - **Rules** (top-level, EARS) — shared business or domain rules expressed in one of the six EARS patterns (`ubiquitous`, `state-driven`, `event-driven`, `optional-feature`, `unwanted-behavior`, `complex`). - **Invariants** — properties the system must always maintain; each carries a `` and a `scope` naming the fundamental locus (an aggregate, a term, or `system`). - **NFRs** — non-functional / quality requirements in the arc42 scenario shape. For each NFR the author wants to add, surface `usdl:behaviour:nfr` as a See-Also Reference; the peer owns the script. - **Events** — shared domain events (past-tense `name`, optional `aggregate`, optional `triggers`). Defined here once; referenced from any use case via the use case's `` collection. The interview never visits a kind out of order. When the author asks to add an Element of a later kind first, the Skill records the request, finishes the current kind's pass (if mid-pass), and then jumps to the requested kind — but never authors a use case before its referenced rules / invariants / NFRs / events exist as top-level Elements. ## The minimum-interview rule Per `beh.rule.minimum-interview`, the interview asks **only** questions whose answers fill **required** attributes or **required** children of the Element being authored. Optional attributes and optional children surface only when the author indicates interest. For Behavior, that means: - `` — ask only `term` and one ``. The `aliases` attribute and any `` children are surfaced only if the author wants to name synonyms or give concrete instances. - `` — ask only `kind` and one ``. `status`, `since`, `until`, and `x-*` are global optionals and surface only on author interest. - `` — handed off to `usdl:behaviour:usecase`, which carries its own minimum-interview pass. - `` (top-level) — ask only the `pattern` and the EARS sentence text. `enforces` is an optional pointer to invariants / NFRs the rule protects and is surfaced only when the author has named such linkage. - `` — ask only `scope` and the ``. `verifiable-by`, `spec-ref`, and `` are optional. - `` — handed off to `usdl:behaviour:nfr`, which carries its own minimum-interview pass. - `` — ask only `name`. `aggregate`, `triggers`, and the `` are optional but a `` is strongly recommended for non-trivial events; surface it when the event's purpose would not be self-evident from the name alone. Per `beh.rule.escalate-not-fabricate`, when an answer to a required slot is missing, ambiguous, or unparseable, the Skill restates the question once with the legal shape and escalates on the second failure; it does not fabricate a value or omit the attribute. ## See-Also References This Skill names four peers as See-Also References. The agent host decides whether to load them; this Skill never invokes peers directly. ### `usdl:behaviour:usecase` **When to surface.** Surface `usdl:behaviour:usecase` as a See-Also Reference whenever a `` Element is about to be drafted — that is, when the section-level interview reaches the use-case stage of step 3, or when the author asks mid-flow to add another use case. **What the peer owns.** The use-case Interview Script: actor reference, goal, preconditions, main flow, alternative flows, postconditions, one or more acceptance blocks, and the four collections (``, ``, ``, ``) that reference top-level Behavior Elements by id. **Why surface and not inline.** Use-case drafting is the deepest Interview Script in Behavior. Inlining it would inflate this Skill's body into every host conversation regardless of need; the peer is loaded only when a use case is actually about to be drafted. ### `usdl:behaviour:nfr` **When to surface.** Surface `usdl:behaviour:nfr` as a See-Also Reference whenever an `` Element is about to be drafted — that is, when the section-level interview reaches the NFR stage of step 4, or when the author asks mid-flow to add another NFR. **What the peer owns.** The NFR Interview Script: `quality` category (`performance`, `availability`, `security`, `privacy`, `accessibility`, `operability`, `portability`, `maintainability`, `scalability`, `compliance`, `usability`), `measure` and `threshold` when the quality is `performance` or `availability`, `scope`, and the six arc42 scenario fields (``, ``, ``, ``, ``, ``). **Why surface and not inline.** The arc42 quality-scenario shape is verbose enough that authoring one NFR in full inside the section-level interview would dominate the rest of the pass. The peer keeps that drafting scoped to one NFR at a time. ### `usdl:bin` **When to surface.** Surface `usdl:bin` as a See-Also Reference whenever this Skill needs to call the `usdl` CLI rather than manipulate XML directly. In particular, surface it at the self-validation step (see below) so the host loads the Bin wrapper before the validate call. **What the peer owns.** The Bin executable wrapper: explanations of the four subcommands (`validate`, `format`, `describe`, `content`) and the common argv patterns. This Skill prefers Bin over raw XML manipulation for context-budget reasons. ### `usdl:templates` **When to surface.** Surface `usdl:templates` as a See-Also Reference whenever an Element draft must be checked against its Template before being written, or whenever the author needs to know what shape an Element kind takes. Useful in particular when extending an existing Section in `beh.extend-section` mode and the Element being added has not been authored in this session before. **What the peer owns.** The bundled Element Templates (one full-section skeleton plus one per Element kind across all four Sections, including the Behavior kinds listed above) and Element-versus-Template validation. This Skill consults `usdl:templates` rather than reproducing Template content in its own body. ## Drafting and writing one Element For each Element the author commits to: 1. Collect the required attributes and required children via the minimum-interview pass (or via the peer Skill, where one applies). 2. Confirm the gathered answers with the author before drafting. 3. Draft the Element XML matching its Template — see `usdl:templates` and `./templates/behavior/full.xml` for reference shapes. This Skill does **not** inline Template content; the Template peer owns lookup. 4. Insert the Element into `behavior.xml` at the appropriate block (Glossary, then Actors, then Use cases, then the four shared-collection blocks). Existing Element order is preserved. 5. After every Element pass — or at the end of the section pass — proceed to self-validation (next section). If a draft carries any attribute pointing at a Topology unit, an Interfaces operation, a Composition call-flow, or any other lower-level Element, the Skill rejects it per `beh.rule.no-downward-reference`. Behavior references upward to nothing; lower Sections reference Behavior, not the reverse. If a draft contains filenames, function signatures, parameter types, or other code-level details, the Skill rejects it per `beh.rule.no-code-in-spec` and asks the author to rephrase in domain terms using glossary entries. ## Self-validation before declaring completion Per `beh.rule.self-validate-before-done`, this Skill does **not** declare the Behavior Section complete until `usdl validate` reports zero errors. The flow is: 1. The Skill has written one or more Elements to `behavior.xml` and reached either the end of the section pass or a checkpoint the author asked for. 2. The Skill calls Bin via `usdl:bin` — specifically `usdl validate behavior.xml` — and reads the diagnostics. The Bin call goes through `usdl:bin` rather than being made directly so the host can route the call and so the Skill remains description-only. 3. If validation passes (zero errors), proceed to the Section Handoff step (next section). 4. If validation fails with one or more **Trivial** diagnostics (id collision, missing required attribute that the interview answer covers, malformed enum value, duplicate child), the Skill applies the repair and re-runs validate. Repairs are bounded per `beh.rule.repair-bounded`; the limit is configured by the surrounding Agent or by the orchestrator and is not redefined here. 5. If validation fails with one or more **non-Trivial** diagnostics, or if the bounded repair attempts do not converge, the Skill **does not** report completion. It surfaces the remaining Bin diagnostics to the author with file path, line number, the offending Element id, and a short explanation, and asks for guidance. A "task complete" message is never sent while `usdl validate behavior.xml` returns a non-zero status. ## Section Handoff Per `beh.handoff-section`, once `usdl validate behavior.xml` reports zero errors and the author confirms the pass is over, the Skill emits a **Section Handoff signal** naming `behavior` as the completed Section and its validated state. This is the last action in this Skill's lifecycle for the current pass. The Handoff signal is what unblocks `usdl:topology` (and, through it, the Topology authoring Agent). Until the signal is emitted, downstream Section Skills treat Behavior as not-yet-authoritative input and refuse to start per `beh.halt-on-broken-chain`. If validation is still failing at the moment Handoff would normally occur, the Skill withholds the signal, surfaces the diagnostics, and does not declare completion. There is no Handoff without a green Bin validate. ## Extending an existing behavior.xml When `behavior.xml` already exists and validates, the author may invoke this Skill to add one more Element rather than bootstrap the Section. In that mode (`beh.extend-section`): 1. The Skill loads the existing `behavior.xml` (via Bin `content` through `usdl:bin`, if context budget is tight) to know which Element ids already exist. 2. The Skill asks the author which Element kind they want to add and routes to the peer Skill where one applies (`usdl:behaviour:usecase` for a use case, `usdl:behaviour:nfr` for an NFR; otherwise inline). 3. On id collision, the Skill asks the author whether to choose a different id, replace the existing Element, or abort. 4. The same self-validation step runs after the new Element is inserted; no Section Handoff is emitted on extension because Handoff was already emitted on the original section pass. ## What this Skill does not do - It does not draft a use case end-to-end. That work belongs to `usdl:behaviour:usecase`, which this Skill surfaces as a See-Also Reference when a use case is about to be drafted. - It does not draft an NFR end-to-end. That work belongs to `usdl:behaviour:nfr`. - It does not author Topology, Interfaces, or Composition Elements. Other section-spanning Skills own those, and they refuse to start until Behavior is handed off. - It does not invoke Bin commands directly. Bin calls go through `usdl:bin`, which is loaded as a See-Also Reference. - It does not look up Element Templates internally. Template lookup goes through `usdl:templates`. - It carries no executable code. All drafting work is description-only prose; mutation happens via Bin called through `usdl:bin`. - It does not inline `./sections/behavior.md` or `./dictionaries/behavior_dictionary.md`. Both are referenced and loaded only when the author or peer needs full Element-shape detail.

usdl-behaviour

Install this skill

Comments