@canonical/pragma-cli 0.34.0 → 0.36.0

package/bundled-skills/implement-component/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: implement-component
+description: Implement a specified design-system component with pragma create, following the live code standards; also runs as a guided tutorial on a worked example
+---
+
+# Implement Component
+
+Take an APPROVED spec — from `specify-component`, or an existing documented block — to
+working code. The defining discipline: the applicable code standards are pulled and held
+open DURING implementation, so they shape the code as it is written, not only in review.
+
+## Working mode
+
+This skill often runs alongside a senior engineer or designer. When it does, work as
+their assistant: lay out where the flow stands, do the legwork (spec reads, standard
+pulls, scaffolding), and surface decisions rather than absorbing them silently. The
+points to raise with the person rather than decide alone: a thin or ambiguous spec
+field, any deviation from a pulled standard, the target package for a tier outside the
+naming convention, and API naming the spec does not fix. When running fully
+autonomously (only on explicit request), list those judgment calls in the PR.
+
+## When to Use
+
+- An approved spec — from `specify-component`, or an existing documented block — needs
+  working code
+- A scaffolded component needs to be implemented against the live code standards
+
+## When NOT to Use
+
+- No approved spec yet — run `specify-component` first (`specify-pattern` for a pattern)
+- Only the anatomy is missing — that is `anatomy-author`
+- Adopting existing components into an app — the `adoption-a1-styles` /
+  `adoption-a2-components` / `adoption-a3-forms` tracks, not this skill
+
+## Opening move: ask, or offer the tutorial
+
+Activation is an opening, not a starting gun. Unless the first message already names
+the work, ask for the starting point — as a suggestion carrying an example, not as a
+form to fill in:
+
+> To get started, tell me which block to implement — a name like "Badge", or point me
+> at the spec it came out of. If the target framework or package isn't obvious, say
+> that too.
+
+If you are unsure whether the thing is specified at all, take the name anyway:
+pre-flight is what decides, and it routes to `specify-component` when the spec turns
+out not to be there. Ask again only for what the next step genuinely blocks on.
+
+If the activation message already carries the starting point, do not re-ask — say what
+you took it to be, and go.
+
+Offer the tutorial in the same breath, because this skill doubles as one:
+
+> Or if you'd rather see the flow first, I can run it as a tutorial: I'll pick a small
+> documented block from the graph and walk you through it from pre-flight to review.
+
+Tutorial mode is the step narration below, turned up: the same outcome-path-conclusion
+frame, with the reasoning at each decision gate made fully explicit and a check that
+the person is with you before the next step. Stop short of anything that lands — no
+commit, no PR — unless they ask to keep what you built.
+
+## Every step is narrated: outcome, path, conclusion
+
+Every step is addressed to the person — once before it runs, once when it ends. This is
+not tutorial manner. It holds in the ordinary flow too: the person is the design
+authority, and they can only steer a step they saw coming. A decision gate met cold is
+a decision they cannot really make.
+
+**Open** the step with what it is FOR — the outcome it should leave behind — and how
+you are about to get there. **Close** it with a sentence saying what it established and
+what that means for the step after. One sentence each is enough; the failure mode is
+silence, not length, and a step whose outcome looks obvious still gets its sentence
+rather than a shrug.
+
+Do:
+
+> **Pulling the standards, before any code.** The outcome is a shortlist held open
+> while the Badge is written, so the code is shaped by the standards as it is written
+> rather than corrected in review. The path is `pragma standard categories` for the
+> live set, then `standard list --category <name>` for each one that applies.
+>
+> …
+>
+> So: `react`, `storybook` and `testing-unit` are the live shortlist and nothing in
+> them contradicts the spec — implementation can proceed against them, with `css` and
+> `styling` held back for the token work.
+
+Don't:
+
+> Step 3 — Pull the standards NOW
+>
+> Categories exist for: react (16), testing (+coverage/integration/regression/unit),
+> storybook (11), css (15), styling (4).
+
+Both carry the same facts. Only the first says what the step was trying to achieve and
+what it settled — and only the first lets the person cut in with the thing they know
+and the graph does not, which is the whole reason they are here.
+
+## Asked about the skill: methodology and outcomes first
+
+A question about what this skill does — what it covers, what its steps are, how it
+works — is answered in that order: the METHOD it applies and the OUTCOMES it leaves
+the person holding come first, the step-by-step breakdown comes after.
+
+Two or three sentences of method is enough: what the skill treats as its object, the
+discipline that makes it work, and what exists at the end that did not exist before.
+The enumeration then reads as steps in service of something, rather than as a list to
+be got through.
+
+What this prevents is a table of contents standing in for an answer. A reply opening
+with the step names tells someone who already knows the skill nothing new, and someone
+who does not, nothing at all.
+
+So, asked what this skill is:
+
+> It takes an approved spec to working code, and the discipline that defines it is
+> that the applicable code standards are pulled and held open DURING implementation —
+> so they shape the code as it is written, not only in review. You end holding a
+> scaffolded and implemented component, any deviation from a standard recorded next to
+> that standard's name, and an independent review of the result.
+
+Then, and only then, the breakdown.
+
+## Pre-flight
+
+1. **Read the spec.**
+   - Documented block: `pragma block lookup <Name>` — anatomy, modifiers, properties in
+     one read (MCP: block_lookup); `pragma graph inspect <uri>` for the full triple view.
+     A bare name can match blocks in several tiers, and `block lookup` silently picks
+     one — it resolves `ds:name` globally and cannot be steered to a tier. Take the
+     picked block's tier from the lookup's own `- Tier:` line, and check for other
+     tiers carrying the name with the name query below, then address the tier you
+     want by its IRI.
+
+     ```bash
+     pragma graph query "SELECT ?b WHERE { ?b ds:name ?n . FILTER(LCASE(?n) = LCASE('<Name>')) }"   # every tier carrying the name
+     ```
+
+     If the lookup picked the wrong tier's block, read the one you want with
+     `pragma graph inspect <IRI from that row>` instead — step 2 derives the package
+     from the tier of the block confirmed HERE.
+
+     **Check the entry is a spec before building on it — whatever class it is.**
+     A row resolving is not the same as a block being documented: many entries
+     across every class carry an empty `ds:summary`, `ds:usage` and `ds:anatomyDsl`,
+     and `block lookup <Name>` still answers for them with a heading, a blank line
+     and a `- Tier:` row. Judge the BASE DEFINITION: if `ds:summary`, `ds:usage` and
+     `ds:anatomyDsl` all came back filled, the block is documented — implement it,
+     and raise any single thin field (empty guidelines, say) as a gap rather than a
+     blocker. If all three came back empty, there is no spec here to implement: route
+     it to `specify-component`, per the When NOT to Use rules above.
+
+     Then read whatever `ds:documentationStage` tag came back. The tag vocabulary is
+     the graph's, not this skill's, so do not expect a fixed value list; **if the
+     predicate is absent, no stage is recorded for that block** — say so and carry on
+     with what the fields told you. The tag's MEANING is graph data too:
+
+     ```bash
+     pragma graph inspect ds:tag.<name>   # the tag the stage read returned; ds:whenToApply says what it means
+     ```
+
+     Split the action on what `ds:whenToApply` says. A tag meaning the block was
+     rejected or triaged out, or that it is only PROPOSED or postponed — not yet
+     accepted into the system: this is not an approved spec, route it to
+     `specify-component`. A tag meaning the documentation is UNFINISHED: proceed, and
+     say so in the PR — route to `anatomy-author` only the fields that actually came
+     back empty, not the whole block. A tag whose `ds:whenToApply` comes back blank:
+     the meaning is unrecorded — treat it as unknown, and say so.
+
+     If the name has no row and the lookup errors, the block may be a Group — `block list`/`block lookup` cover no groups; the name query above returns its IRI for `pragma graph inspect <IRI>`.
+     Groups are the one UIBlock class `block list` deliberately omits, so the graph
+     entry is their only documentation surface — but the check above is the same
+     check: read the base definition, then the stage.
+
+     The inspect renders `ds:hasProperty` only as opaque blank-node labels; for the
+     property content use the lookup's Properties section — only when the lookup
+     resolved the block you want — or bind the property query to the block confirmed
+     above. (A `block list` row prints the `ds:` form — `graph inspect` takes it
+     as-is, but a SPARQL body needs the full IRI: join `https://ds.canonical.com/`
+     with the row's dotted name, e.g. for the global Button,
+     `<https://ds.canonical.com/global.component.button>`; the name query above
+     prints that full form directly. The bracketed prefixed form `<ds:…>` silently
+     returns an EMPTY table, not an error.)
+
+     ```bash
+     pragma graph query "SELECT ?p ?v WHERE { <https://ds.canonical.com/<dotted name from that row>> ds:hasProperty ?x . ?x ?p ?v }"
+     ```
+   - New block: the `specs/…` file its specify flow produced.
+2. **Confirm the target package and tier.** The spec names its tier; `pragma tier list`
+   shows what exists. Where a package exists for the tier, its name follows a
+   convention — the graph carries no package field: `@canonical/<framework>-ds-global`
+   for the `global` tier, `@canonical/<framework>-ds-app` for the shared `apps` tier,
+   and `@canonical/<framework>-ds-app-<app>` for an app-specific tier
+   (`apps_lxd` → `@canonical/react-ds-app-lxd`). The `<app>` segment is the package's
+   own short name, not always the tier suffix (the `apps_workplaceengineering` tier's
+   package is `@canonical/svelte-ds-app-wpe`) — confirm the derived package actually
+   resolves in the workspace before installing or scaffolding into it. Tiers outside
+   `global`/`apps*` have no package convention today: there the target package is a
+   decision to raise, not to derive.
+3. **Pull the applicable standards NOW.**
+
+   ```bash
+   pragma standard categories                 # what categories exist today
+   pragma standard list --category react      # swap react for the target framework category
+   ```
+
+   > The covered set is whatever the graph answers today. Query it live — never copy its
+   > output into documentation, PRs, or this skill.
+
+   Repeat the `--category` listing for the testing, storybook, css, and styling
+   categories that apply to this component — take the category names from the
+   `standard categories` output, not from memory.
+
+   Then read the shortlisted standards' Do/Don't pairs — few-shot material to keep
+   open in the working context while writing. The pairs live in the graph; pull them
+   per category:
+
+   ```bash
+   pragma graph query "SELECT ?s ?kind ?caption ?code WHERE { ?s cs:hasCategory cs:react . { ?s cs:do ?x . BIND('do' AS ?kind) } UNION { ?s cs:dont ?x . BIND('dont' AS ?kind) } ?x cs:description ?caption . OPTIONAL { ?x cs:code ?code } }"
+   ```
+
+   Keep `cs:code` OPTIONAL as written — some pairs carry a caption and no code
+   snippet, and requiring the code triple silently drops those standards from the
+   result.
+
+   For ONE standard, bind the same query to its IRI. (`pragma graph inspect cs:<id>`
+   shows which predicates a standard carries, but renders `cs:do`/`cs:dont` only as
+   opaque blank-node labels — the pairs come back through the query, not the
+   inspect):
+
+   ```bash
+   pragma graph query "SELECT ?kind ?caption ?code WHERE { BIND(<http://pragma.canonical.com/codestandards#react.component.barrel_exports> AS ?s) { ?s cs:do ?x . BIND('do' AS ?kind) } UNION { ?s cs:dont ?x . BIND('dont' AS ?kind) } ?x cs:description ?caption . OPTIONAL { ?x cs:code ?code } }"
+   ```
+
+   Swap `cs:react` for each shortlisted category, using the category's GRAPH ID — not
+   its display name. `standard categories` prints display names (`testing-coverage`);
+   the graph ids differ (`testing.coverage`), and a display name pasted into the
+   query returns an empty table, not an error. List the exact IRIs with
+   `pragma graph query "SELECT DISTINCT ?c WHERE { ?s cs:hasCategory ?c }"` and paste
+   one in full `<…>` form, e.g.:
+
+   ```bash
+   pragma graph query "SELECT ?s ?kind ?caption ?code WHERE { ?s cs:hasCategory <http://pragma.canonical.com/codestandards#testing.coverage> . { ?s cs:do ?x . BIND('do' AS ?kind) } UNION { ?s cs:dont ?x . BIND('dont' AS ?kind) } ?x cs:description ?caption . OPTIONAL { ?x cs:code ?code } }"
+   ```
+
+   (Inside a SPARQL body a local name with more than one dot does not parse; a
+   single dot — `cs:testing.unit` — is fine.) `pragma standard lookup <name>` and
+   `pragma standard sample` resolve only the standards that carry a `cs:name`
+   title — today only a few do — so for the rest the graph query above is the read
+   path. (MCP: standard_categories / standard_list / graph_query / graph_inspect.)
+
+## Scaffold
+
+```bash
+pragma create component react src/components/Button
+```
+
+- The framework is a tree segment — `pragma create component <framework> <path>` with
+  `react`, `svelte`, or `lit` as the segment; the path's final segment is the
+  PascalCase component name.
+- Run it from inside the target package confirmed in pre-flight step 2 — the path is
+  package-relative (in the ds packages, components live at `src/lib/component/<Name>`,
+  so the path there is `src/lib/component/Button`, not the generic example above).
+- Plan-first: preview with `--dry-run`, apply non-interactively with `--yes`, reverse
+  with `--undo`. Run without `--yes` to answer the generator's prompts interactively.
+- The scaffold's include options (styles, stories, SSR tests) are prompt-derived and
+  discoverable — read them from the leaf's own help, never from a copied table:
+
+  ```bash
+  pragma create component react --help
+  ```
+
+- MCP: the `create_component` tool ({framework, componentPath, …}); it returns a plan
+  unless `confirm: true`.
+
+The same generator is available as `summon component react src/components/Button` —
+`pragma create <args…>` and `summon <args…>` are one machine in two binaries, identical
+grammar. Teach and use the pragma spelling.
+
+## Implement following the pulled standards
+
+Write the component against the open Do/Don't pairs from pre-flight. When a case comes
+up that the shortlist does not cover, widen before improvising: re-run
+`pragma standard categories`, list the further categories that could apply
+(`pragma standard list --category <c>`), and pull their Do/Don't pairs with the same
+graph query as pre-flight. Each surface takes its own spelling: `--category` takes the
+DISPLAY name `standard categories` prints (`testing-coverage`); the SPARQL body takes
+the category's graph id from the `SELECT DISTINCT ?c` read there (`testing.coverage`) —
+never the other way around. An empty pair table has two causes: a display name pasted
+into the query, or a category that records standards but no Do/Don't pairs at all —
+`pragma standard list --category <c>` distinguishes them (it lists the category's
+standards either way; when no pairs exist, work from those standards' descriptions).
+
+A standard you disagree with is feedback for the standards repo, not a license to
+deviate silently.
+
+## Post-flight
+
+- Fill in the stories and tests the scaffold stubbed — the spec's properties, modifiers,
+  and states each get exercised.
+- Register the component per the package's convention (barrel/export registration).
+- Run the package's own `bun run check` and `bun run test` (the repo-standard script
+  names) until green.
+
+## Close: independent review
+
+Finish by invoking the `standards-review` skill as the independent quality gate over the
+diff:
+
+```bash
+pragma skill lookup standards-review
+```
+
+It ships from canonical/web-code-standards once that skill lands; until then the
+lookup will not resolve. Fall back to re-reading the pre-flight Do/Don't material
+against the diff yourself, and say in the PR that the independent gate was
+unavailable.
+
+## Related skills
+
+- `specify-component` — upstream: produces the spec this skill implements
+- `anatomy-author` — the structure contract the implementation must honor
+
+## Support
+
+If this skill leads somewhere broken — a command that errors, guidance that
+contradicts what the live system answers, a gap the flow cannot cover — you are not
+stuck:
+
+- Raise an issue in the pragma repo: https://github.com/canonical/pragma/issues —
+  include the skill name, what was run, and expected vs. actual outcome.
+- Or contact the design-system team owners directly through your organization's
+  professional messaging channels for assistance.

package/bundled-skills/specify-component/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: specify-component
+description: Specify a new design-system component with the knowledge graph, from graph search to a sync-safe spec file; also runs as a guided tutorial on a worked example
+---
+
+# Specify Component
+
+Create a NEW component on the design/spec side, using the full power of the knowledge
+graph. This skill supersedes the retired component-specifier skill (a name that no
+longer resolves) with an eight-step flow: nothing is invented before the graph has been
+searched, the entry shape comes from the ontology, and the output is a standalone spec
+file the data sync cannot destroy.
+
+In a fresh session, orient first:
+
+```bash
+pragma capabilities
+```
+
+## Working mode: assistant to a design authority
+
+Most of the time this skill runs in collaboration with a senior designer or engineer —
+they are the design authority, you are the assistant whose job is to make them
+successful. Default to that mode:
+
+- Lay out the workflow direction: say which step comes next and why, so the person
+  always knows where the flow stands.
+- Do the legwork yourself — graph searches, ontology reads, benchmark research — and
+  bring back digestible findings, not raw dumps.
+- Bring each decision to the person as a recommendation plus a question, never as a
+  fait accompli. They hold context the graph does not — history, intent, naming
+  precedent, roadmap — so ask the questions that draw that knowledge out, and use it.
+
+Full autonomy is the exception, not the default: run the whole flow alone only when
+explicitly asked to. Even then, list every judgment call made unilaterally in the
+final report so a human can revisit them.
+
+Decision gates — in collaboration, pause at each and resolve it WITH the person:
+
+1. The step-1 verdict: exists/extend vs. a named gap.
+2. The step-2 category choice (which `ds:UIBlock` subclass the entry is).
+3. The step-3 boundary: how the definition disambiguates from its neighbors.
+4. The step-4 adopt/reject decisions from the benchmark.
+5. Whether the step-5 state gate fires, and the state model when it does.
+
+## When to Use
+
+- A component is proposed that the design system may not cover yet
+- An existing component needs a formally specified sibling or replacement
+- A gap found during adoption or implementation needs to become a real spec
+
+## When NOT to Use
+
+- Implementing an already-specified component — use `implement-component`
+- Specifying a pattern (a recurring arrangement of components) — use `specify-pattern`
+- Writing only the anatomy for an existing block — use `anatomy-author`
+
+## Opening move: ask, or offer the tutorial
+
+Activation is an opening, not a starting gun. Unless the first message already names
+the work, ask for the starting point — as a suggestion carrying an example, not as a
+form to fill in:
+
+> To get started, tell me the component you'd like to work on — a name if it has one,
+> or just the idea, like "it should let someone pick a date".
+
+Rough is fine, and often better: step 1 turns an idea into a graph search, and the
+search regularly renames the thing. Ask again only for what the next step genuinely
+blocks on.
+
+If the activation message already carries the starting point, do not re-ask — say what
+you took it to be, and go.
+
+Offer the tutorial in the same breath, because this skill doubles as one:
+
+> Or if you'd rather see the flow first, I can run it as a tutorial: I'll take a
+> plausible example — a date picker, say — and walk you through the eight steps on it.
+
+Tutorial mode is the step narration below, turned up: the same outcome-path-conclusion
+frame, with the reasoning at each decision gate made fully explicit and a check that
+the person is with you before the next step. Stop short of anything that lands — no spec
+file written, no proposal filed — unless they ask to keep what you built.
+
+## Every step is narrated: outcome, path, conclusion
+
+Every step is addressed to the person — once before it runs, once when it ends. This is
+not tutorial manner. It holds in the ordinary flow too: the person is the design
+authority, and they can only steer a step they saw coming. A decision gate met cold is
+a decision they cannot really make.
+
+**Open** the step with what it is FOR — the outcome it should leave behind — and how
+you are about to get there. **Close** it with a sentence saying what it established and
+what that means for the step after. One sentence each is enough; the failure mode is
+silence, not length, and a step whose outcome looks obvious still gets its sentence
+rather than a shrug.
+
+Do:
+
+> **Step 1 — search the graph.** The outcome is a verdict: the thing already exists,
+> an existing block should be extended, or there is a named gap worth specifying. The
+> path is `pragma block list` for the catalog, then `block lookup` on the closest
+> candidates.
+>
+> …
+>
+> So: nothing covers date entry, and the nearest neighbour (`Input`) stops at free
+> text — a real gap, and one that step 2 has to place as a component rather than a
+> pattern.
+
+Don't:
+
+> Step 1 — Search the graph
+>
+> 87 blocks. No date picker. Closest: Input, Select.
+
+Both carry the same facts. Only the first says what the step was trying to achieve and
+what it settled — and only the first lets the person cut in with the thing they know
+and the graph does not, which is the whole reason they are here.
+
+## Asked about the skill: methodology and outcomes first
+
+A question about what this skill does — what it covers, what its steps are, how it
+works — is answered in that order: the METHOD it applies and the OUTCOMES it leaves
+the person holding come first, the step-by-step breakdown comes after.
+
+Two or three sentences of method is enough: what the skill treats as its object, the
+discipline that makes it work, and what exists at the end that did not exist before.
+The enumeration then reads as steps in service of something, rather than as a list to
+be got through.
+
+What this prevents is a table of contents standing in for an answer. A reply opening
+with the step names tells someone who already knows the skill nothing new, and someone
+who does not, nothing at all.
+
+So, asked what this skill is:
+
+> It specifies a component against the knowledge graph, and the discipline is that
+> nothing is invented before the graph has been searched: the entry's category comes
+> from the ontology rather than from taste, the boundary is drawn against its real
+> neighbours, and a benchmark decides what is adopted and what is refused. You end
+> holding a standalone spec file the data sync cannot destroy, plus a record of every
+> judgment call it took to get there.
+
+Then, and only then, the breakdown.
+
+## The spec falls under standards too
+
+A spec is Turtle, and Turtle has standards — the `turtle` category, with `ui-blocks`
+governing how blocks are modelled (take the actual set from
+`pragma standard categories`, not from this list). Pull them before writing and hold
+the Do/Don't pairs open; a spec that contradicts a pulled standard carries a DECLARED
+deviation in the proposal, ideally also filed as an issue. The standards apply
+independent of any package dependency and are open to contribution: a missing or
+wrong modelling rule is something to propose a change for, not to silently work
+around.
+
+## The eight steps
+
+### 1. Search the graph
+
+Before anything is invented, find what already exists:
+
+```bash
+pragma block list                  # every component, pattern, layout and subcomponent, with its type and tier
+pragma block lookup <Name-or-glob> # full spec of candidates: anatomy, modifiers, properties (MCP: block_lookup); a glob repeats a multi-tier name once per IRI and every repeat is the SAME block — the fragment query below lists the tiers
+pragma block sample                # real entry shapes — read these BEFORE writing queries
+pragma modifier list               # the modifier families blocks draw from
+pragma tier list                   # the tiers a block can live in
+```
+
+Search by name fragment when the naming is uncertain:
+
+```bash
+pragma graph query "SELECT ?b ?name WHERE { ?b ds:name ?name . FILTER(CONTAINS(LCASE(?name), 'crumb')) }"
+```
+
+> The covered set is whatever the graph answers today. Query it live — never copy its
+> output into documentation, PRs, or this skill.
+
+Outcome gate: **either "exists — stop or extend it" or a NAMED gap.** No spec is written
+without one of those two sentences, naming the blocks that were checked.
+
+### 2. Understand the ontology
+
+Read the shape the entry must satisfy:
+
+```bash
+pragma ontology lookup ds                    # the design-system vocabulary
+pragma ontology lookup ds --class UIBlock    # the block-level properties every entry carries
+pragma ontology lookup ds --class Component  # what Component itself declares
+```
+
+`--class` shows only what a class declares itself — usage, guidelines, properties,
+and tier are declared on `ds:UIBlock` and inherited by its subclasses; `summary` and
+`name` sit further up the chain on `ds:Entity`
+(`pragma ontology lookup ds --class Entity`).
+
+The documented conventions the entry follows:
+
+- `ds:summary` — what the component is, in one or two sentences
+- `ds:usage` — markdown with `### When to use` and `### When not to use` sections
+- `ds:guidelines` — markdown; Accessibility material lives here by convention
+  (contrast, alternative text, keyboard and focus behavior)
+- `ds:hasProperty` — one entry per property: name, type, summary, optional, default,
+  constraints
+- Modifier families the component participates in
+- The tier it belongs to
+- The category definitions — `pragma ontology lookup ds` above lists every `ds:UIBlock` subclass; read what each one means with `pragma graph inspect ds:<Subclass>`
+  (each prints its `skos:definition`; `--class` prints declared properties, not
+  definitions), and state which category the entry belongs to BEFORE writing
+
+Each field's acceptance criteria live on the property itself —
+`pragma graph inspect ds:usage` / `ds:guidelines` print the `ds:acceptanceCriteria`
+the content must satisfy; read them before writing the field.
+
+Do not trust this list over the data: run `pragma block sample` and mirror what real
+entries carry today. The draw is RANDOM and many blocks are near-empty, so a sample can come back content-free and teach you nothing: re-run it until it lands on a filled entry, or inspect a block you already know is documented.
+
+### 3. Define the principles
+
+Write the component's main definition — and write it to DISAMBIGUATE. Name the closest
+existing blocks found in step 1 and state the boundary explicitly: "unlike X, this …".
+A definition that could equally describe a step-1 neighbor is not done.
+
+### 4. Research & benchmark
+
+Study the same affordance or role in other design systems — React Aria, Carbon,
+Material, shadcn (list extensible). Compare:
+
+- API shape
+- Accessibility pattern
+- Naming
+- State model
+- Composition
+
+Output: a short comparison table plus an explicit statement of what pragma adopts, what
+it rejects, and why.
+
+### 5. State-complexity gate
+
+Decide whether the component carries complex, state-machine-like state: many interacting
+modes, async transitions, orchestration across parts.
+
+Calibration: a Button — hover, active, disabled visual states — does NOT fire this
+gate; a Combobox — open/closed, filtering, async loading, selection moving between
+input and list — does.
+
+If YES, write a **"States & interaction"** section INSIDE the guidelines content of the
+spec (the v0 home for the state spec), covering:
+
+- The states
+- Events and transitions between them
+- The initial state
+- Error states
+- Keyboard interactions per state
+
+If NO, say so in the spec and move on.
+
+### 6. Write the documentation (without the anatomy)
+
+Write the spec in markdown or Turtle following the step-2 structure: definition, usage,
+guidelines (including the step-5 section when it fired), properties. The anatomy is
+step 7, not here.
+
+**Output location (hard rule)**: a standalone spec file the sync cannot destroy.
+
+- In canonical/design-system: `specs/<tier>.<type>.<snake_name>.{md,ttl}`
+  (e.g. `specs/global.component.carousel.md` — step 1 must have shown the name to be
+  a genuine gap first)
+- In any other repo: that repo's design-docs location
+
+NEVER write into design-system `data/` — it is regenerated destructively from Coda by
+CI, and hand edits are overwritten by the next sync. Database entry is a separate,
+currently-human step: a person pastes the spec content into Coda.
+
+### 7. Write the anatomy DSL
+
+Delegate to the `anatomy-author` skill:
+
+```bash
+pragma skill lookup anatomy-author
+```
+
+The skill covers named and anonymous nodes, edges with cardinality, slot names, and
+CTI-inspired style keys; the full ANATOMY_DSL_SPEC ships beside it as
+`ANATOMY_DSL_SPEC.md` in the installed `anatomy-author` skill folder (the lookup
+renders SKILL.md only — open that file directly for the complete spec). The produced
+DSL lands in the step-6 spec file
+under `specs/` — in a `.md` spec as its anatomy section, in a `.ttl` spec as the
+block's `ds:anatomyDsl` string literal — never under `data/`; entry into Coda stays
+the human step.
+
+### 8. Pair with tokens — placeholder
+
+**Left blank for now** — token pairing content lands with the token work. Do not invent
+token guidance.
+
+## Response format
+
+Report the spec-file path, then the eight step outcomes as a checklist (the reported
+path ends in `.ttl` instead when step 6 took the Turtle branch):
+
+```markdown
+Spec: specs/<tier>.<type>.<snake_name>.md
+
+- [ ] 1. Graph searched — verdict: exists/extend OR named gap (blocks checked: …)
+- [ ] 2. Ontology shape read (classes and conventions applied)
+- [ ] 3. Principles defined, disambiguated from: …
+- [ ] 4. Benchmarked against: … (adopt/reject decisions stated)
+- [ ] 5. State gate: fired/not fired (States & interaction section: yes/no)
+- [ ] 6. Documentation written to the sync-safe location
+- [ ] 7. Anatomy DSL written via anatomy-author
+- [ ] 8. Token pairing: placeholder (deferred)
+```
+
+## Related skills
+
+- `anatomy-author` — the step-7 engine
+- `specify-pattern` — the same skeleton, context-first, for recurring arrangements
+- `implement-component` — what happens after the spec is approved
+
+## Support
+
+If this skill leads somewhere broken — a command that errors, guidance that
+contradicts what the live system answers, a gap the flow cannot cover — you are not
+stuck:
+
+- Raise an issue in the pragma repo: https://github.com/canonical/pragma/issues —
+  include the skill name, what was run, and expected vs. actual outcome.
+- Or contact the design-system team owners directly through your organization's
+  professional messaging channels for assistance.