openEHR · sebastian-iancu · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "openehr",
-  "description": "AI-assistant plugins for openEHR — official plugin marketplace of the openEHR Foundation.",
+  "description": "AI-assistant plugins for openEHR \u2014 official plugin marketplace of the openEHR Foundation.",
   "owner": {
     "name": "openEHR Foundation",
     "url": "https://openehr.org"
@@ -10,7 +10,7 @@
     {
       "name": "openehr-specs",
       "description": "Skills for creating, editing, and reviewing openEHR specification documents (AsciiDoc and OpenAPI/ITS-REST), managing the specification governance process, and ensuring content quality and convention compliance.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Sebastian Iancu"
       },

diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
@@ -1,6 +1,6 @@
 {
   "name": "openehr",
-  "description": "AI-assistant plugins for openEHR — official plugin marketplace of the openEHR Foundation.",
+  "description": "AI-assistant plugins for openEHR \u2014 official plugin marketplace of the openEHR Foundation.",
   "owner": {
     "name": "openEHR Foundation",
     "url": "https://openehr.org"
@@ -9,7 +9,7 @@
     {
       "name": "openehr-specs",
       "description": "Skills for creating, editing, and reviewing openEHR specification documents (AsciiDoc and OpenAPI/ITS-REST), managing the specification governance process, and ensuring content quality and convention compliance.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Sebastian Iancu"
       },

diff --git a/AGENTS.md b/AGENTS.md
@@ -16,17 +16,20 @@ ai-plugins/
 └── plugins/<plugin-name>/             # One directory per plugin
     ├── .claude-plugin/plugin.json     # Claude Code plugin manifest
     ├── .cursor-plugin/plugin.json     # Cursor plugin manifest
-    ├── README.md                      # Plugin purpose, install, and skill inventory
-    └── skills/<skill-name>/
-        ├── SKILL.md                   # Skill definition (YAML frontmatter + body)
-        └── references/                # Optional supplementary content
+    ├── README.md                      # Plugin purpose, install, and component inventory
+    ├── skills/<skill-name>/           # Knowledge/workflow skills (model- or user-invoked)
+    │   ├── SKILL.md                   # Skill definition (YAML frontmatter + body)
+    │   └── references/                # Optional supplementary content
+    ├── agents/<agent>.md              # Autonomous subagents (context-isolated, multi-file)
+    └── commands/<command>.md          # User-invoked action commands (disable-model-invocation)
 ```
 
-Current plugins: `openehr-specs` (spec authoring, review, governance, content patterns, amendment records, ITS-REST, BMM class generation).
+Current plugins: `openehr-specs` — 7 skills (spec authoring, review, governance, content patterns, amendment records, ITS-REST, BMM class generation), 3 subagents (`spec-reviewer`, `xref-auditor`, `identifier-grounding`), and 3 commands (`amend`, `regen-classes`, `publish`).
 
 ## Key Conventions
 
 - Plugin names: `openehr-<domain>` (mandatory prefix — flat global namespace); skill names: terse activity nouns with no prefix (auto-namespaced as `<plugin>:<skill>`).
+- Component choice follows the *nature of the work*: **skills** = knowledge/workflows (model- or user-invoked); **commands** (`commands/`) = user-initiated actions, marked `disable-model-invocation: true` so they don't compete with knowledge-skill triggering; **subagents** (`agents/`) = context-heavy, multi-file, or adversarial work that would otherwise pollute the main context. Commands/agents reference their sibling knowledge skill rather than duplicating it.
 - Skill `description` frontmatter is lean (~50–75 words): one what+scope sentence → a few representative triggers → short "Not for …" anti-triggers routing to the right sibling/plugin.
 - Keep each `SKILL.md` body a lean overview (quick-reference + pointers); push bulky detail (tables, templates, format specs) into `references/` so it loads only on demand.
 - Versions must stay in sync across both plugin manifests (`.claude-plugin/` and `.cursor-plugin/`), both marketplace entries, and the release tag (`{name}--v{version}`).
@@ -39,11 +42,23 @@ Full details: [docs/skill-authoring.md](docs/skill-authoring.md)
 
 Pure-content repository (JSON manifests + markdown skills) — no build step, package manager, or test suite.
 
-- **Validation**: `python3 scripts/validate.py` (Claude + Cursor manifests, version sync, skill frontmatter, component paths — runs in CI)
+- **Validation**: `python3 scripts/validate.py` (Claude + Cursor manifests, version sync, skill/agent/command frontmatter, component paths — runs in CI)
 - **Local testing**: [docs/testing.md](docs/testing.md); **versioning/releases**: [docs/versioning.md](docs/versioning.md)
 - **End-user installation**: [docs/install.md](docs/install.md)
 - **Generating/editing AsciiDoc for `specifications-XX` repos**: follow [docs/spec-style-guide.md](docs/spec-style-guide.md); skill bodies must agree with it — when changing one, check the other.
 
+## Component Dependencies
+
+The skills are pure content; the subagents and commands rely on external tools and degrade
+gracefully when one is absent (each says so in its prompt):
+
+- **`spec-reviewer`, `xref-auditor`** — need a `specifications-XX` checkout and (for attribute resolution) the sibling `specifications-AA_GLOBAL`.
+- **`xref-auditor`, `identifier-grounding`** — use **WebFetch** to read spec Markdown twins (`.html` → `.md`); `identifier-grounding` additionally prefers the **`openehr-assistant` MCP** (`type_specification_get`) when connected, falling back to the twin.
+- **`regen-classes`** — needs **Docker** (`ghcr.io/openehr/bmm-publisher`).
+- **`publish`** — needs a sibling `specifications-AA_GLOBAL` checkout (`bin/spec_publish.sh`) or the `openehr/asciidoctor` Docker image.
+
+None are bundled (the `openehr-assistant` MCP is interactively authenticated, not redistributable); document them, don't assume them.
+
 ## Relationship to Other Repos
 
 - **`specifications-AA_GLOBAL`**: shared infrastructure (boilerplate, publishing scripts, styles) consumed by all spec repos

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 Notable changes to the plugins in this repository. Format follows [Keep a Changelog](https://keepachangelog.com); versions refer to individual plugins (see [docs/versioning.md](docs/versioning.md)).
 
+## openehr-specs 0.2.0
+
+Adds autonomous subagents and user-invoked commands around the existing seven skills:
+
+- **Subagents** (`agents/`): `spec-reviewer` (runs the full review check catalog across a whole spec document), `xref-auditor` (verifies `{openehr_*}` attributes and cross-spec anchors, using the Markdown-twin of target specs), `identifier-grounding` (fact-checks RM/AM/BASE identifiers in a draft against the published spec).
+- **Commands** (`commands/`, user-invoked): `/openehr-specs:amend`, `/openehr-specs:regen-classes`, `/openehr-specs:publish`.
+- `scripts/validate.py` now also validates agent and command frontmatter.
+
 ## openehr-specs 0.1.0 — 2026-06-05
 
 Initial release. Seven skills for openEHR specification work: `authoring`, `content-patterns`, `amendment-record`, `review`, `governance`, `its-rest`, and `class-generation`. Packaged for the Claude Code and Cursor marketplaces.
diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ Skills are namespaced by the plugin and invoked as `/openehr-specs:<skill>`:
 /openehr-specs:class-generation   # regenerate class tables/diagrams from BMM
 ```
 
-Type `/openehr` in the slash menu to list all skills together, or just describe the task (e.g. "review this openEHR spec before release") and the matching skill activates automatically. See the [plugin README](plugins/openehr-specs/README.md) for the full skill list and invocation details.
+Type `/openehr` in the slash menu to list the available skills and commands, or just describe the task (e.g. "review this openEHR spec before release") and the matching skill activates automatically. The plugin also ships **subagents** (`spec-reviewer`, `xref-auditor`, `identifier-grounding`) that Claude dispatches for heavy, multi-file, or verification work. See the [plugin README](plugins/openehr-specs/README.md) for the full inventory and invocation details.
 
 ## Documentation
 

diff --git a/plugins/openehr-specs/.claude-plugin/plugin.json b/plugins/openehr-specs/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "openehr-specs",
   "displayName": "openEHR Specifications",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Skills for creating, editing, and reviewing openEHR specification documents (AsciiDoc and OpenAPI/ITS-REST), managing the specification governance process, and ensuring content quality and convention compliance.",
   "author": {
     "name": "Sebastian Iancu"

diff --git a/plugins/openehr-specs/.cursor-plugin/plugin.json b/plugins/openehr-specs/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "openehr-specs",
   "displayName": "openEHR Specifications",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Skills for creating, editing, and reviewing openEHR specification documents (AsciiDoc and OpenAPI/ITS-REST), managing the specification governance process, and ensuring content quality and convention compliance.",
   "author": {
     "name": "Sebastian Iancu"

diff --git a/plugins/openehr-specs/README.md b/plugins/openehr-specs/README.md
@@ -1,6 +1,6 @@
 # openEHR Specifications
 
-Skills for authors working in `specifications-XX` and `specifications-ITS-REST` repositories — AsciiDoc structure, amendment records, governance, quality review, prose patterns, ITS-REST OpenAPI sources, and BMM-based class documentation generation.
+Skills, subagents, and commands for authors working in `specifications-XX` and `specifications-ITS-REST` repositories — AsciiDoc structure, amendment records, governance, quality review, prose patterns, ITS-REST OpenAPI sources, and BMM-based class documentation generation.
 
 ## Installation
 
@@ -29,6 +29,26 @@ Add the marketplace from this repository (or a fork), then install `openehr-spec
 | `its-rest` | ITS-REST OpenAPI YAML and operation descriptions |
 | `class-generation` | Generate class tables and UML diagrams from BMM via `bmm-publisher` |
 
+## Subagents
+
+Context-isolated agents for heavy, multi-file, or verification work — dispatched by Claude (or ask for them by name). Each degrades gracefully when an optional dependency is absent.
+
+| Agent | Purpose | Needs |
+|-------|---------|-------|
+| `spec-reviewer` | Runs the full `review` check catalog across an entire spec document, returns a findings report | `specifications-XX` (+ `AA_GLOBAL` for attribute checks) |
+| `xref-auditor` | Verifies every `{openehr_*}` attribute and `<<anchor>>` resolves; checks cross-spec deep-link anchors against the target's Markdown twin | WebFetch (optional) |
+| `identifier-grounding` | Fact-checks every RM/AM/BASE class/attribute a draft names against the published spec; flags invented identifiers | `openehr-assistant` MCP or WebFetch (optional) |
+
+## Commands
+
+User-invoked actions (they do not auto-trigger). Invoke as `/openehr-specs:<command>`.
+
+| Command | Argument | Action |
+|---------|----------|--------|
+| `/openehr-specs:amend` | `<SPECXX-NN — summary>` | Add an amendment-record entry (version bump, anchors, Jira refs) |
+| `/openehr-specs:regen-classes` | `<schema-id>` | Regenerate class tables/diagrams via `bmm-publisher` (needs Docker) |
+| `/openehr-specs:publish` | `<component>` | Build a local HTML preview via the `AA_GLOBAL` publisher |
+
 ## Usage
 
 Each skill is namespaced by the plugin, so it is invoked as **`/openehr-specs:<skill>`**. There are three ways to reach a skill:
@@ -39,8 +59,8 @@ Each skill is namespaced by the plugin, so it is invoked as **`/openehr-specs:<s
    /openehr-specs:review
    /openehr-specs:class-generation
    ```
-2. **Browse the group** — type `/openehr` in the slash menu to list all seven skills together, or fuzzy-type a skill name (e.g. `review`) to jump straight to it.
-3. **Let it trigger automatically** — Claude loads the right skill when your request matches its description. For example, "review this openEHR spec before release" activates `review`, and "regenerate the class tables for specifications-BASE" activates `class-generation` — no command needed.
+2. **Browse the group** — type `/openehr` in the slash menu to list the plugin's skills and commands together, or fuzzy-type a name (e.g. `review`) to jump straight to it.
+3. **Let it trigger automatically** — Claude loads the right skill (or dispatches the right subagent) when your request matches its description. For example, "review this openEHR spec before release" activates `review` / `spec-reviewer`, and "regenerate the class tables for specifications-BASE" activates `class-generation` — no command needed. (Commands like `/openehr-specs:amend` are user-only and never auto-trigger.)
 
 Most skills act on the spec you are working in, so run them from a checkout of a `specifications-XX` repo (or name the target spec/file in your request).
 

diff --git a/plugins/openehr-specs/agents/identifier-grounding.md b/plugins/openehr-specs/agents/identifier-grounding.md
@@ -0,0 +1,76 @@
+---
+name: identifier-grounding
+description: |
+  Use this agent to fact-check the openEHR identifiers in a draft specification chapter — every
+  RM/AM/BASE class name, attribute, and function it claims — against the published specifications,
+  flagging any that may have been invented or misspelled. Dispatch it after drafting or editing
+  spec prose, before committing, whenever correctness of class/attribute names matters. Examples:
+
+  <example>
+  Context: The user drafted a new chapter describing several RM classes.
+  user: "I wrote the new versioning chapter — make sure I didn't make up any class or attribute names"
+  assistant: "I'll dispatch the identifier-grounding agent to extract every class/attribute it names and verify each against the published RM spec."
+  <commentary>
+  Inventing identifiers is the most-violated spec-authoring rule; an adversarial verifier that defaults to "unverified" catches it.
+  </commentary>
+  </example>
+
+  <example>
+  Context: Reviewing a contributor's prose before merge.
+  user: "double-check the COMPOSITION attributes mentioned in this section actually exist"
+  assistant: "I'll launch the identifier-grounding agent to confirm each named attribute against the COMPOSITION class definition."
+  <commentary>
+  Per-class attribute verification is precise lookup work best grounded in the BMM-backed spec, isolated from the main context.
+  </commentary>
+  </example>
+model: inherit
+color: yellow
+---
+
+You are an openEHR identifier fact-checker. You verify that every RM/AM/BASE/LANG identifier a
+specification draft references actually exists in the published specifications, and you report
+unverified or likely-invented identifiers. You are a verifier: **never modify files.**
+
+**Operating principle (adversarial):** default every identifier to `UNVERIFIED`. Promote it to
+`VERIFIED` only when you positively find it in an authoritative source. Inventing or misspelling
+class/attribute names is the single most damaging spec-authoring error, so bias toward flagging.
+
+**Sources, in order of preference:**
+1. **`openehr-assistant` MCP** (if available) — use `type_specification_get` for per-class
+   attribute/function detail (BMM-backed, authoritative). Discover the tool via tool search.
+2. **Markdown twin** — fetch the published spec page as Markdown: take the
+   `specifications.openehr.org/releases/<COMPONENT>/<release>/<spec>.html` URL and swap
+   `.html` → `.md`, then search it for the identifier. (Note: Markdown omits some per-class
+   attribute tables; fall back to source 1 or the HTML for those.)
+3. **Local sibling repos** — if the relevant `specifications-XX` source or BMM-generated
+   `docs/UML/classes/` files are present in the workspace, grep them.
+
+If none of these is reachable, report identifiers as `UNVERIFIED (no source available)` rather than guessing.
+
+**Your Core Responsibilities:**
+1. Extract every openEHR identifier the draft claims: class/type names (UPPER_SNAKE like
+   `COMPOSITION`, `DV_QUANTITY`, generics like `VERSION<T>`), attribute names (italic-monospace
+   like `_uid_`, `_commit_audit_`), and function names (`_function()_`).
+2. For each, determine the owning component/spec and verify it exists — and, for attributes,
+   that it belongs to the class the draft attributes it to.
+3. Report status per identifier with the source that confirmed (or failed to confirm) it.
+
+**Output Format:**
+A table, then a summary.
+
+```
+| Identifier | Claimed context | Status | Source |
+|------------|-----------------|--------|--------|
+| COMPOSITION | RM ehr | VERIFIED | type_specification_get |
+| VERSION._commit_audit_ | RM common | VERIFIED | common.md |
+| COMPOSITION._signature_ | RM ehr | UNVERIFIED — not found on COMPOSITION | type_specification_get |
+| DV_QUANTAS | RM data_types | LIKELY INVENTED — no such type (did you mean DV_QUANTITY?) | data_types.md |
+```
+
+End with: `N identifiers — X verified, Y unverified, Z likely invented`, and list the
+unverified/invented ones first with the suggested correction where obvious.
+
+**Edge Cases:**
+- Identifier defined locally in the same draft (a new type being introduced) → mark `NEW (defined in this draft)`, not invented.
+- Ambiguous attribute shared by several classes → verify against the specific class named; if the draft doesn't qualify it, note the ambiguity.
+- Non-openEHR identifiers (HL7, ISO, FHIR types) → out of scope; list them as `SKIPPED (external)`.