@open-domain-specification/skill 0.1.10

package/skill/examples/petstore.md

@@ -0,0 +1,126 @@
+# Patterns from the Petstore example
+
+Excerpts from the ODS example workspace (`models/petstore/src/workspace.ts`
+in the ODS repository). Each shows one pattern worth copying.
+
+## A context serving two subdomains, and a legacy one
+
+```ts
+const inventoryBC = workspace.addBoundedContext("Inventory BC", {
+	description: "Projection for /store/inventory (status→count)",
+	subdomains: [inventorySD, catalogSD],
+	team: petShopTeam,
+});
+const identityBC = usersSD.addBoundedcontext("Identity BC", {
+	description: "Owns User aggregate & user endpoints. Legacy: user status is an untyped int",
+	bigBallOfMud: true,
+	team: platformTeam,
+});
+```
+
+## Attributes backed by value objects, relations with cardinality, invariants on attributes
+
+```ts
+petRoot.addAttribute("id", { type: "int64", identity: true });
+petRoot.addAttribute("status", { type: "PetStatus", valueobject: petStatusVO });
+petRoot.uses(categoryVO, "categorized-as", "0..1");
+petRoot.uses(photoUrlVO, "has-photo", "1..*");
+petAgg
+	.addInvariant("NameRequired", { description: "Pet.name must be non-empty" })
+	.constrains(petRoot.attributes.get("name")!);
+```
+
+## A cross-aggregate reference by identity to the other root
+
+```ts
+orderRoot.references(petRoot, "for-pet", "1");
+```
+
+## Published events with a payload schema, and an internal operation that raises one
+
+```ts
+const petStatusChangedSchema = catalogBC.addSchema("PetStatusChanged");
+petStatusChangedSchema.addAttribute("petId", { type: "int64", identity: true });
+
+const petStatusChanged = petAgg.provides("PetStatusChanged", {
+	description: "Pet status changed (available|pending|sold)",
+	type: "event",
+	pattern: "published-language",
+	schema: petStatusChangedSchema,
+});
+const _changePetStatus = petAgg
+	.provides("ChangePetStatus", {
+		description: "Move a pet between available, pending and sold",
+		type: "operation",
+		internal: true,
+		schema: petStatusChangedSchema,
+	})
+	.raises(petStatusChanged);
+```
+
+## An open-host application service whose operations raise the aggregate's events
+
+```ts
+const petApp = catalogBC.addService("PetApp", {
+	description: "Open-host service for /pet endpoints",
+	type: "application",
+});
+const _addPetOp = petApp
+	.provides("AddPet", {
+		description: "POST /pet",
+		type: "operation",
+		pattern: "open-host-service",
+		schema: registerPetSchema,
+	})
+	.raises(petRegistered);
+```
+
+## A consumption through an anti-corruption layer, and the relationship that explains it
+
+```ts
+orderApp.consumes(getPetSummaryOp, { pattern: "anti-corruption-layer" });
+
+salesBC.downstreamOf(catalogBC, {
+	type: "customer-supplier",
+	upstreamRoles: ["open-host-service"],
+	downstreamRoles: ["anti-corruption-layer"],
+	description: "Sales needs pet availability; Catalog commits to the summary contract",
+});
+```
+
+## Separate ways, on purpose
+
+```ts
+identityBC.separateWaysFrom(
+	salesBC,
+	"Orders are anonymous in Petstore v3; no integration by design",
+);
+```
+
+## A policy reacting to events from two contexts
+
+```ts
+salesBC
+	.addPolicy("Approve when pet available", {
+		description: "When a pet becomes available and an order for it is placed, approve the order",
+	})
+	.on(petStatusChanged, orderPlaced)
+	.then(approveOrder);
+```
+
+## Conformist consumptions feeding a projection
+
+```ts
+inventoryAgg.consumes(petStatusChanged, { pattern: "conformist" });
+inventoryAgg.consumes(orderApproved, { pattern: "conformist" });
+```
+
+## Glossary terms embodied by model elements
+
+```ts
+catalogBC.addTerm("Category", {
+	definition: "The kind of animal a pet is, such as Dogs or Cats",
+	aliases: ["Species"],
+	embodiedBy: categoryVO,
+});
+```

package/skill/examples/validate.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Validates one or more ODS workspace JSON files.
+// Usage: node validate.mjs .ods/petstore.json [.ods/other.json ...]
+// Exits 1 when a file fails to load or has an error-level diagnostic.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(`${process.cwd()}/`);
+let Workspace;
+try {
+	({ Workspace } = require("@open-domain-specification/core"));
+} catch {
+	console.error(
+		"@open-domain-specification/core is not installed here. Run from the project root, install it (npm i -D @open-domain-specification/core), or use: npx -p @open-domain-specification/core node validate.mjs <file>",
+	);
+	process.exit(2);
+}
+
+let failed = false;
+for (const file of process.argv.slice(2)) {
+	let workspace;
+	try {
+		workspace = Workspace.fromSchema(JSON.parse(readFileSync(file, "utf8")));
+	} catch (error) {
+		console.log(
+			`[load-error] ${file}: ${error instanceof Error ? error.message : error}`,
+		);
+		failed = true;
+		continue;
+	}
+	const diagnostics = workspace.validate();
+	console.log(`${file}: ${diagnostics.length} diagnostic(s)`);
+	for (const d of diagnostics) {
+		console.log(`  [${d.severity}] ${d.rule}: ${d.message} (${d.ref})`);
+		if (d.severity === "error") failed = true;
+	}
+}
+process.exit(failed ? 1 : 0);

package/skill/references/ddd-glossary.md

@@ -0,0 +1,56 @@
+# DDD terms in one sentence each
+
+Use these the first time a term comes up, filling the example with the user's own words.
+Never repeat an explanation, and never explain a term the user already used correctly.
+
+- **Domain** — the whole area of business the system exists for, e.g. "running the pet store".
+- **Subdomain** — one slice of that problem, e.g. "the catalogue" or "taking orders"; calling it
+  *core* only marks where your competitive effort goes, *supporting* means needed but ordinary,
+  *generic* means you would buy it.
+- **Bounded context** — a boundary inside which every word has one exact meaning; your billing
+  "Customer" and your support "Customer" being different things is why they get separate
+  contexts.
+- **Ubiquitous language / glossary** — the words a context uses, written down once so code,
+  conversations and documents all mean the same thing by "Order".
+- **Team ownership** — the people who decide what a context means and how it changes.
+- **Big ball of mud** — a context whose model nobody fully controls, flagged so that anything
+  talking to it translates rather than trusts.
+- **Entity** — something that matters because of *which one* it is, like this particular order,
+  so it carries an identity.
+- **Value object** — something that matters only by its values, like an address; two with the
+  same values are interchangeable.
+- **Attribute** — one piece of information an entity, value object or message carries; the
+  identity attribute is the one that tells two entities apart.
+- **Aggregate** — the cluster of things you change together and check rules across, named after
+  its *root*, the one thing you go through to change any of it; the order and its lines.
+- **Invariant** — a rule that must always hold inside an aggregate, such as "quantity is never
+  zero".
+- **Relation** — how one thing points at another: *includes* for parts that cannot exist alone,
+  *uses* for values it carries, *references* for another aggregate's root by identity.
+- **Cardinality** — how many of the other thing: exactly one, at most one, any number, at least
+  one.
+- **Operation** — something you can ask a part of the system to do, like "place an order"; in
+  conversation people often say *command*.
+- **Event** — a fact that already happened, stated in the past tense, like "order placed", that
+  other parts can react to.
+- **Consumable** — an operation or event that a part offers, and **consumption** is another part
+  using it.
+- **Schema** — the shape of the information that travels with an operation or event.
+- **Policy** — a rule of the form "when this event happens, do that operation", possibly across
+  contexts.
+- **Application service** — the part that fronts an API or a screen and turns requests into
+  operations on aggregates.
+- **Domain service** — business logic that does not belong to any single thing, like pricing
+  across several orders.
+- **Upstream / downstream** — the side that is depended on, and the side that depends on it.
+- **Customer-supplier** — a dependency where the downstream side gets a say before the upstream
+  side changes things.
+- **Partnership** — two contexts whose teams plan and release together.
+- **Shared kernel** — code or data two contexts both own and change.
+- **Separate ways** — a deliberate decision that two contexts will not integrate.
+- **Open host service** — the upstream side offers a documented API for anyone to use.
+- **Published language** — the upstream side offers a documented message format everyone
+  agrees on.
+- **Conformist** — the downstream side takes the upstream model as it comes.
+- **Anti-corruption layer** — the downstream side copies and reshapes what it receives into its
+  own terms, so the upstream model cannot leak in.

package/skill/references/dsl-api.md

@@ -0,0 +1,45 @@
+# DSL reference (`@open-domain-specification/core`)
+
+Every class is created through its parent and registers itself there, so `parent.addX(...)`
+is the only call needed. Every attributes object accepts an optional `id` to fix the id
+independently of the name.
+
+| Receiver | Method | Creates / does |
+|---|---|---|
+| — | `new Workspace(name, { odsVersion, description, version, homepage?, logoUrl?, primaryColor?, id? })` | the workspace |
+| `Workspace` | `addDomain(name, { description })` | a domain |
+| `Workspace` | `addTeam(name, { description?, homepage? })` | a team |
+| `Workspace` | `addBoundedContext(name, { description, subdomains?, bigBallOfMud?, team? })` | a context serving zero or more subdomains |
+| `Workspace` | `addRelationship({...})` | a relationship; prefer the context helpers below |
+| `Workspace` | `validate()` | the diagnostics list |
+| `Workspace` | `toSchema()` / `Workspace.fromSchema(json)` | serialise / load |
+| `Domain` | `addSubdomain(name, { type, description })` | a subdomain; `type` is `"core" \| "supporting" \| "generic"` |
+| `Subdomain` | `addBoundedcontext(name, { description, bigBallOfMud?, team? })` | a context serving this subdomain |
+| `BoundedContext` | `serves(subdomain)` | adds a served subdomain |
+| `BoundedContext` | `ownedBy(team)` | sets the owning team |
+| `BoundedContext` | `upstreamOf(other, { type?, upstreamRoles?, downstreamRoles?, description? })` | directed relationship, this side upstream; `type` defaults to `"upstream-downstream"`, or `"customer-supplier"` |
+| `BoundedContext` | `downstreamOf(other, options)` | the same, this side downstream |
+| `BoundedContext` | `partnerOf(other, description?)` | partnership |
+| `BoundedContext` | `sharesKernelWith(other, description?)` | shared kernel |
+| `BoundedContext` | `separateWaysFrom(other, description?)` | separate ways |
+| `BoundedContext` | `addAggregate(name, { description })` | an aggregate |
+| `BoundedContext` | `addService(name, { type, description })` | a service; `type` is `"application" \| "domain"` |
+| `BoundedContext` | `addPolicy(name, { description })` | a policy; chain `.on(...events).then(...operations)` |
+| `BoundedContext` | `addTerm(name, { definition, aliases?, embodiedBy? })` | a glossary term; or chain `.embody(element)` |
+| `BoundedContext` | `addSchema(name, { description? })` | a payload schema; add fields with `addAttribute` |
+| `Aggregate` | `addRootEntity(name, { description })` | the root entity |
+| `Aggregate` | `addEntity(name, { description, root? })` | an entity |
+| `Aggregate` | `addValueObject(name, { description })` | a value object |
+| `Aggregate` | `addInvariant(name, { description })` | an invariant; chain `.constrains(...entities, valueObjects or attributes)` |
+| `Aggregate`, `Service` | `provides(name, { type, description, pattern?, internal?, schema? })` | a consumable; `type` is `"event" \| "operation"`, `pattern` is `"open-host-service" \| "published-language"` |
+| `Aggregate`, `Service` | `consumes(consumable, { pattern? })` | a consumption; `pattern` is `"conformist" \| "anti-corruption-layer"` |
+| `Consumable` | `raises(...events)` | the events an operation raises |
+| `Entity`, `ValueObject`, `DataSchema` | `addAttribute(name, { type, description?, identity?, valueobject? })` | an attribute; `type` is free text |
+| `Entity`, `ValueObject` | `uses(target, label, cardinality?)` | a `uses` relation |
+| `Entity`, `ValueObject` | `includes(target, label, cardinality?)` | an `includes` relation |
+| `Entity`, `ValueObject` | `references(target, label, cardinality?)` | a `references` relation; across aggregates target the root |
+| `Entity`, `ValueObject` | `addRelation(target, { relation, label?, cardinality? })` | any relation explicitly |
+| `Entity` | `.attributes.get("name")` | look an attribute up, e.g. to constrain it |
+
+`cardinality` is `"1" | "0..1" | "*" | "1..*"`. Chainable methods (`raises`, `on`, `then`,
+`constrains`, `embody`, `serves`, `ownedBy`) return their receiver.

package/skill/references/dsl-mode.md

@@ -0,0 +1,63 @@
+# DSL mode
+
+The TypeScript source is the artefact; the JSON under `.ods/` is generated from it. Edit the
+source, run the generator, read the diagnostics it prints.
+
+## Find the generator
+
+Look for a file that imports `Workspace` from `@open-domain-specification/core`, builds the
+model, and writes `workspace.toSchema()` to disk. The canonical shape (from the ODS example
+package) is:
+
+```ts
+import fs from "node:fs";
+import { workspace } from "./petstore/workspace.ts";
+
+for (const d of workspace.validate()) {
+	console.log(`[${d.severity}] ${d.rule}: ${d.message} (${d.ref})`);
+}
+
+fs.mkdirSync(".ods", { recursive: true });
+fs.writeFileSync(
+	".ods/petstore.json",
+	JSON.stringify({ $schema: "./schema.json", ...workspace.toSchema() }, null, 2),
+);
+```
+
+`package.json` usually has a script for it (`build`, `ods`, `generate`, `model`). Node 24 runs
+`.ts` files directly; on older Node use `npx tsx <file>`.
+
+## Loop
+
+1. Edit the model source. Keep the file's existing sections and ordering (domains, teams,
+   contexts, then one section per context).
+2. Run the generator. It validates and rewrites the JSON.
+3. Read every `[error]` and `[warning]` line and explain it to the user with
+   `validation-rules.md`.
+4. Never hand-edit the emitted JSON; the next run overwrites it. If the user edits it, tell
+   them and offer to port the change into the source.
+
+If the generator does not print diagnostics, add the four-line loop above before the write.
+`toSchema()` does not emit `$schema`; spread it back in exactly as shown, so editors and the
+VS Code extension keep the file associated with `schema.json`.
+
+## Ids and renames
+
+Ids are derived from names with `snake_case` unless `id` is passed. Because ids are the JSON
+keys and the ref segments, renaming an element by changing its name silently changes its id
+and breaks anything outside the source that points at it (documentation links, bookmarks,
+other files). When renaming, pass the old id explicitly:
+
+```ts
+// was: catalogBC.addAggregate("Pet", {...})
+catalogBC.addAggregate("Listed Pet", { id: "pet", description: "..." });
+```
+
+## Conventions from the example
+
+- Name the variables after the element and its kind (`petAgg`, `petRoot`, `categoryVO`,
+  `petApp`), so refs read naturally in the code.
+- Prefix a variable with `_` when the element is kept only for its side effect on the model
+  (an operation nobody references again).
+- Create all consumables before the policies and consumptions that point at them.
+- Full DSL surface: `dsl-api.md`. Patterns worth copying: `examples/petstore.md`.

package/skill/references/interview-playbook.md

@@ -0,0 +1,108 @@
+# Interview playbook
+
+You are the facilitator. The user knows their system and their business; you know DDD. Your
+job is to get the model out of their head without making them learn the vocabulary first.
+
+## Ground rules
+
+- One question per turn. Wait for the answer.
+- No DDD word before its one-sentence explanation (see `ddd-glossary.md`), and each term is
+  explained once.
+- After every answer, paraphrase it as the element you would record: "So I'd note ... right?"
+- Write the increment as soon as a context or an aggregate is stable. Do not wait until the
+  whole interview is done; a model in the file beats a model in the chat.
+- Skip any phase the existing workspace already covers. Read first, ask second.
+- Keep the user's words. Descriptions and glossary definitions are written in their language,
+  not in DDD language.
+
+## Phase A: orientation (produces the Workspace)
+
+- "In one or two sentences, what does this system do, and for whom?" → `name`, `description`.
+- "Is there a homepage or logo I should link?" → `homepage`, `logoUrl` (skip if none).
+
+## Phase B: the problem space (produces Domains and Subdomains with a type)
+
+- "What are the big areas of the business this covers? Think of the headings you would put
+  on a whiteboard." → domains.
+- Per area: "What distinct jobs sit inside that area?" → subdomains.
+- Per subdomain: "Is this something that makes you different from competitors, something you
+  need but any sensible way of doing it is fine, or something you would happily buy off the
+  shelf?" → `core` / `supporting` / `generic`.
+- Explain once: a subdomain is one slice of the problem; calling it core only marks where your
+  competitive effort goes.
+
+## Phase C: ownership (produces Teams, Bounded Contexts, `subdomains`, `bigBallOfMud`)
+
+- "Which teams or people work on this, and which parts does each look after?" → teams, and a
+  candidate context per part.
+- "If two teams both say <word>, do they mean exactly the same thing?" If not, that is two
+  contexts. Explain once: a bounded context is a boundary inside which every word has one
+  exact meaning; your billing "Customer" and your support "Customer" being different is why
+  they get separate contexts.
+- "Which of the jobs from before does each part serve?" → `subdomains` refs. One context may
+  serve several.
+- "Is any of these an old system that nobody fully understands, where the data model is a
+  mess?" → `bigBallOfMud: true`. Explain: we flag it so anything talking to it knows to
+  translate rather than trust.
+
+## Phase D: the integration map (produces Relationships and seeds consumptions)
+
+- "Which parts talk to each other? For each pair, who depends on whom?" → `upstream-downstream`
+  with the depended-on side upstream.
+- "When the upstream team changes something, does the downstream team get a say beforehand?"
+  Yes → `customer-supplier`.
+- "Do those two teams plan and release together, as one?" → `partnership`.
+- "Do they share actual code or tables that both change?" → `shared-kernel`.
+- "Are there two parts that you have decided, on purpose, should never integrate?" →
+  `separate-ways`.
+- "How does the downstream side take the data: as it comes, or does it copy and reshape it
+  into its own terms?" → `conformist` / `anti-corruption-layer`. Goes on `downstreamRoles`
+  and on each consumption's `pattern`.
+- "Does the upstream side publish a documented API, or a documented message format?" →
+  `open-host-service` / `published-language`. Goes on `upstreamRoles` and on each exposed
+  consumable's `pattern`.
+
+## Phase E: inside one context (produces Aggregates, Entities, Value Objects, Invariants, Glossary)
+
+Repeat for each context the user wants detailed. Ask which one to start with.
+
+- "Inside <context>, what are the things people talk about? Just list the nouns." → candidate
+  entities and value objects; every noun becomes a glossary term with the user's definition.
+- Per noun: "If two of these had identical details, would they still be two different things?"
+  Yes → entity; no → value object. Explain once: an entity matters because of which one it is
+  (this order, not that one); a value object matters only by its values (an address).
+- "What identifies it: an order number, an email?" → an attribute with `identity: true`.
+- "What details does it carry?" → attributes, with `type` in the user's words.
+- "Which of these do you always change or check together? What must be true across all of
+  them at once?" → the aggregate boundary. The thing they state the rule about is the root.
+  Explain once: an aggregate is the cluster you change together and check rules across; the
+  root is the one you name it after.
+- "What must never be allowed to happen to a <root>?" → invariants, each constraining the
+  entity, value object or attribute it is about.
+- "Does a <root> point at things in another cluster, for example an order pointing at a
+  product?" → `references` to that cluster's root; ask "one or many?" for cardinality.
+- "Does it contain things that cannot exist without it?" → `includes`.
+- "Does it use a value like an address, money or a status?" → `uses`.
+
+## Phase F: behaviour (produces Consumables, `raises`, Policies, Schemas)
+
+- "What can someone ask this part to do?" → `operation` consumables. Put an API entry point on
+  an application service, and a state change of one aggregate on that aggregate.
+- "When that happens, what fact would you announce to the rest of the business?" → `event`
+  consumable, linked from the operation with `raises`. Events are past tense.
+- "Is that something only this part uses, or would other parts care?" → `internal: true`, or
+  an upstream `pattern`.
+- "What information travels with that announcement or request?" → a schema on the context,
+  attached with `schema`.
+- "When <event> happens, what do you then do automatically?" → a policy with `on` the event
+  and `then` the operation. Either side may live in another context.
+- "Who outside this part listens for <event>?" → a consumption on their aggregate or service,
+  with a downstream `pattern`.
+- Close: "Which of the words we used should I define, and does each map to one of the things
+  we modelled?" → glossary terms with `embodiedBy`.
+
+## Phase G: validate and reflect
+
+Run validation. Explain each diagnostic in one plain sentence, propose the fix, and ask before
+applying fixes for warnings. Then summarise what changed, in the user's words, and ask what to
+model next.

package/skill/references/json-mode.md

@@ -0,0 +1,52 @@
+# JSON mode
+
+The workspace files are the artefact. Each `.ods/*.json` file is one complete workspace, and
+the VS Code extension, the docs generator and anyone else load it with `Workspace.fromSchema`.
+
+## Files
+
+- `.ods/` (or the folder named by the VS Code setting `ods.folder`) at the project root.
+- `.ods/schema.json`: the JSON Schema, written by the extension (`ODS: Write schema.json`).
+  Never edit it. If it is missing, copy it from
+  `node_modules/@open-domain-specification/core/dist/workspace.schema.json`.
+- `.ods/<workspace-id>.json`: one workspace per file. The first key is
+  `"$schema": "./schema.json"`; the loader ignores it, editors use it for completion.
+- Keep the file's `id` equal to its basename, and `odsVersion` equal to the other files' (use
+  `"1.0.0"` for a first file).
+
+The smallest valid file is `examples/minimal.ods.json`. Copy it when creating a workspace, then
+grow it.
+
+## Editing rules
+
+- The schema is strict: every required field is present even when empty, and unknown fields
+  are rejected. `references/model-reference.md` lists them.
+- Ids are the object keys. Create them as `snake_case` of the name, then never change them.
+  Renaming is changing `name`.
+- Every `$ref` follows the grammar at the end of `model-reference.md` and points at something
+  that exists. A dangling ref makes the whole file fail to load; the extension then shows
+  "Workspace file could not be loaded" instead of diagnostics.
+- Preserve the key order and two-space indentation of the file so diffs stay readable.
+- Prefer several small edits, each followed by validation, over one large rewrite.
+
+## Validation
+
+There is no CLI. Run `examples/validate.mjs` from the project root:
+
+```sh
+node .claude/skills/ods-authoring/examples/validate.mjs .ods/petstore.json
+```
+
+Or inline:
+
+```sh
+node -e 'const {Workspace}=require("@open-domain-specification/core");const f=process.argv[1];const ws=Workspace.fromSchema(JSON.parse(require("fs").readFileSync(f,"utf8")));for(const d of ws.validate())console.log(`[${d.severity}] ${d.rule}: ${d.message} (${d.ref})`)' .ods/petstore.json
+```
+
+If `@open-domain-specification/core` is not installed, prefix with
+`npx -p @open-domain-specification/core` or install it as a devDependency. The VS Code Problems
+panel shows the same diagnostics (source `ods`, code = rule id) and updates on save.
+
+## Several workspace files
+
+A `.ods` folder may hold several files. Treat each as its own workspace; refs never cross files.