AI Guidelines: openEHR Assistant Plugin

This file provides guidance to AI coding assistants working in this repository.

Project Overview

The openEHR Assistant Plugin is an AI plugin by Cadasto B.V. that provides clinical workflow integration with openEHR systems through skills, commands, agents, and hooks. It supports both Claude Code and Cursor from one tree. It is the workflow layer only; tools, prompts, and resources come from the companion MCP server. Out of scope: building that tooling itself (MCP tools, guides, examples), which is the maintainer openehr-assistant-dev plugin. Human pitch and install: README.md.

Domain Context

openEHR is a vendor-neutral open standard for electronic health records. Key concepts:

• Archetypes: reusable clinical content definitions in ADL (Archetype Definition Language) format
• Templates: use-case-specific constraint sets combining archetypes, in four serialisations: OET (.oet, hand-authored source) and Archetype Designer .t.json (AOM2 differential source) compile to an OPT (runtime contract), from which a vendor web template (Better/EHRbase JSON) is derived for FLAT/STRUCTURED data entry. .t.json is a source template, not a web template
• Compositions: runtime clinical data instances conforming to templates
• Reference Model (RM): core data types and structures
• AQL: Archetype Query Language for querying clinical data repositories
• CKM: Clinical Knowledge Manager, the international archetype/template registry

Not all openEHR content lives in CKM: a small convention exists of tagging GitHub repositories that publish archetypes/templates with the openehr-content topic (~14 repos: freshEHR, Apperta-CKM projects, regional programmes, individual modellers). It is a genuine secondary discovery channel, thinner but broader than CKM for templates, and un-governed: no editorial review, no dependable lifecycle_state, no integrity guarantee. Skills reference it only as a fallback after CKM, and only in the main session: no MCP tool searches it, so it needs WebSearch/gh.

Companion MCP Server

The openehr-assistant-mcp server provides:

• 12 MCP tools: CKM search/retrieval, guide access, terminology resolution, type specifications, ADL idiom lookup, curated examples search/retrieval
• 14 MCP prompts: Guided workflows for common tasks, each taking validated arguments
• Resources: Archetypes, templates, AQL, terminology, type specs, a guide registry spanning six categories (archetypes/, templates/, aql/, simplified_formats/, specs/, howto/), and the openehr://examples/{kind}/{name} namespace for curated worked examples (AQL, FLAT, STRUCTURED, reference .adl archetypes)

This plugin is aligned with openehr-assistant-mcp v0.20.0 (see the server's releases). When aligning plugin changes (skills, commands, allowed-tools, guide URIs), keep each plugin version compatible with a specific server version; checklist: CONTRIBUTING.md.

MCP tool names in this plugin use the format: mcp__openehr-assistant__<tool_name>

Calling conventions the server enforces

Since v0.20.0 the server publishes closed input schemas (additionalProperties: false), rejects the empty string for optional enum arguments, and fails loudly rather than degrading silently. These rules follow for anything written here, in skills, or in commands:

• Omit an optional argument, or pass null; never "". kind, category, component and friends are nullable enums; "" is rejected with a JSON-RPC -32602.
• guide_get / examples_get take a canonical URI or an explicit category/kind + name. Write guide_get("openehr://guides/aql/syntax"), not guide_get("aql/syntax"): the bare category/name string is not a resolvable URI and fails with Invalid guide URI.
• ckm_archetype_get needs a CID or a full archetype-id. Pass the CID from ckm_archetype_search (digits and dots, e.g. 1013.1.7850) or an id containing openEHR-; a concept or display name is rejected with an explicit "could not resolve … to a CID" error (it used to be mangled into a doomed request reported as a missing archetype). ckm_template_get takes the template CID.
• terminology_resolve covers openEHR terminology only and throws when it cannot resolve. Never route SNOMED CT / LOINC / ICD codes to it; read those rubrics from the artefact's own term_bindings / term_definitions.
• Search tools return { items, total }. total counts matches before the maxResults cap, so report it when presenting a capped list, and raise maxResults (1–50 for guide_search / ckm_*_search, 1–30 for examples_search) to see more. Out-of-range values are rejected, not clamped.
• An empty guide_search envelope means "rephrase", not "no such guidance exists". Zero-score hits are dropped, and taskType only re-ranks; it never filters.

Guide-First Principle

All skills and commands instruct the AI assistant to load relevant guides from the MCP server before answering. The guides are the authoritative knowledge registry, organised across six categories. A compact offline summary lives at skills/openehr-assistant/reference/openehr-quick-reference.md for use by the clinical-modeler agent and as a quick refresher; the same folder contains minimal ADL and AQL syntax cheatsheets (adl-syntax-cheatsheet.md, aql-syntax-cheatsheet.md) for offline structural/syntax checks, and an RM type reference (rm-type-reference.md) covering 39 commonly archetyped RM types with their attributes for local lint rule 4 (Valid RM Attributes Only) validation. Canonical guides via MCP always take precedence.

• archetypes/: principles, rules, ADL syntax, idioms, structural constraints, terminology, anti-patterns, checklist, language standards, reference formatting (reference-formatting)
• templates/: principles, rules, CGEM framework (cgem-framework), OET syntax, OET idioms, checklist, and the serialisation set (serialization-formats, opt-structure, web-template)
• aql/: principles, syntax, idioms, checklist
• simplified_formats/: principles, rules, idioms, checklist
• specs/: openEHR specification digests covering AM, AM2, BASE, RM (including EHR, Demographic, Common, Data Types, Data Structures), QUERY (AQL), TERM, LANG (including BMM, BMM3, EL, ODIN), CDS (GDL2), PROC (overview, Task Planning, Decision Language), CNF (conformance guide), SM (platform services), ITS-REST. Digests track the openEHR development branch; the former rm/ category has been migrated into this namespace.
• howto/: toolchain how-tos (e.g. spec-lookup for efficient external spec retrieval via llms.txt and Markdown twin URLs).

Curated worked examples

The MCP server (since v0.16) exposes openehr://examples/{kind}/{name} for gold-standard patterns. Skills and commands may consult examples_search / examples_get when a concrete worked example would help; this is a conditional aid, not a mandatory first step. Kinds: aql, flat, structured, archetypes (CKM-published native .adl files).

Syntax and grammar sources

Use these when you need authoritative ADL or AQL syntax (e.g. for the archetype-authoring fix-syntax mode, AQL authoring, or when MCP guides are unavailable). Canonical detail lives in MCP guides and official specs; treat the following as pointers.

• ADL syntax: Official narrative in specifications-AM (e.g. docs/ADL1.4/, appendix C references ANTLR grammars). Normative grammars: adl-antlr (referenced by the spec). Consolidated ANTLR4 grammars (ADL1.4, ADL2): openEHR-antlr4 (reader_adl14, reader_adl2). MCP guide: guide_get("openehr://guides/archetypes/adl-syntax"). Published spec: https://specifications.openehr.org/releases/AM/development/ (see retrieval methodology below).
• AQL syntax: Official narrative and grammar in specifications-QUERY (docs/AQL/). ANTLR4 grammars: openEHR-antlr4 reader_aql. MCP guide: guide_get("openehr://guides/aql/syntax"). Published spec: https://specifications.openehr.org/releases/QUERY/development/ (see retrieval methodology below).

The written ADL1.4 spec points to adl-antlr for grammars; openEHR-antlr4 is the single consolidated ANTLR source for both ADL and AQL and is valid for implementation and tooling.

Retrieving openEHR specifications

The MCP server's guide_get("openehr://guides/howto/spec-lookup") is the canonical reference for efficient spec retrieval. Key points this plugin depends on:

1. Site index: https://specifications.openehr.org/llms.txt enumerates every release, document, and JSON endpoint as a machine-readable list; use it to resolve component/doc phrases to canonical URLs and discover sibling docs.
2. Markdown twin: most *.html spec pages have a .md counterpart at the same path (e.g. releases/RM/development/ehr.html ↔ releases/RM/development/ehr.md); the coverage is not guaranteed, so fall back to the HTML page (or type_specification_get) when a twin 404s rather than concluding the document does not exist. The same payload is obtainable by sending Accept: text/markdown against the HTML URL. Prefer the Markdown twin for prose, rationale, and examples; it is the cheapest textual source.
3. Class-table caveat: the Markdown twin omits per-class attribute, function, and invariant tables. For those, fall through to the HTML page or the MCP's type_specification_get tool, which is backed by the BMM definitions.
4. Structured JSON APIs: /api/components.json, /api/classes.json, /api/releases.json return component enumerations, cross-release class indexes, and release calendars; prefer these over scraping HTML when doing class or release lookups.
5. Development branch, not latest: this plugin targets releases/XX/development/ (mirroring where the MCP's specs/ digests point). Only use a specific release tag (e.g. Release-1.1.0) when the user explicitly asks for a fixed release version.

For spec overview questions ("what does the EHR IM define?", "summarise ADL2"), prefer guide_get(category="specs", name="<component>-<doc>") before fetching the full spec: digests are 250–900 words and link onward to canonical URLs.

Repository Layout

Shared assets (skills, commands, agents, .mcp.json) are used by both hosts. Host-specific manifests and hook configs are separate.

• Claude manifest: .claude-plugin/plugin.json: name, version, description, author; component discovery uses default folders (skills/, commands/, agents/, hooks/, .mcp.json)
• Cursor manifest: .cursor-plugin/plugin.json: name, version, top-level paths (skills, rules, agents, commands, hooks, mcpServers)
• MCP config: .mcp.json: MCP server connection (default: streamable-http to hosted openehr-assistant-mcp); used by both hosts
• Claude hooks: hooks/hooks.json: an object keyed by event ({ "hooks": { "SessionStart": [...], "PostToolUse": [...] } }), each entry holding { "type": "command", "command": "..." }; use ${CLAUDE_PLUGIN_ROOT} in command paths
• Cursor hooks: hooks/cursor-hooks.json: object { "hooks": { "sessionStart": [...] } }; command runs from plugin root
• Shared hook script: hooks/session-start.sh: detects .openehr-project.json, *.adl, *.oet, *.t.json, *.opt/*.optx/*.optj and prints context and the command/skill lines
• Claude-only hook script: hooks/lint-on-save.sh: the PostToolUse handler; reads the tool-use JSON on stdin and prints the /archetype-lint reminder for an .adl write
• Cursor rules: rules/: .mdc files (e.g. openehr-context.mdc) for Cursor-only rule guidance
• Claude settings: .claude/settings.json enables the maintainer plugins used while developing this repo (openehr-assistant-dev, skill-creator, superpowers, plugin-dev, claude-md-management); .claude/CLAUDE.md imports this file via @../AGENTS.md. .claude/settings.local.json is gitignored (personal overrides).
• Validation: scripts/validate.sh (graceful local wrapper; warns and skips if Python is absent) runs scripts/validate.py, which checks both manifests, dual-host parity, declared component paths, the bundled .mcp.json, skill/command/agent frontmatter, agent MCP namespace pairing, and guide_get URI forms. CI pins Python and runs the validator strictly (.github/workflows/validate.yml).
• Prose lint: .vale.ini plus the in-repo vocabulary under styles/config/; downloaded style packages under styles/ are gitignored.
• Contributor docs: docs/ holds committed human-facing references: install, testing, versioning, authoring; .github/ holds issue + PR templates, the validate workflow, and copilot-instructions.md (points to this file).
• Reference material: bulky supplementary content lives inside the consuming skill's references/ subdirectory (e.g. skills/semantic-diff/references/semantic-diff-rubric.md), never under commands/ (see Gotchas).

Components

Skills (8)

Commands (3)

A deliberately small slash surface: multi-step workflows live in the skills (which auto-trigger and are also /-invocable); commands are explicit one-shots. Former commands were merged (search/explain/lookups/diffs), folded into skills (/aql-designer→aql-authoring, /format-data→composition-builder, /archetype-review + /archetype-rationale + /archetype-translate + /archetype-fix-syntax→archetype-authoring, /template-from-form→template-authoring, /rm-structure→/openehr-explain, /guide + /archetype-lint→ the openehr-assistant and archetype-lint skills), or converted to a skill outright (/semantic-diff). Note: /archetype-lint and /semantic-diff still work; they resolve to the user-invocable skills of the same name.

Agents (3)

Hooks (2)

• SessionStart (both hosts): detects openEHR resources in the workspace and displays context
• PostToolUse (Claude Code only): when Write or Edit targets an .adl file, emits a reminder to run /archetype-lint. Cursor's hook schema does not expose a PostToolUse equivalent at the time of writing; Cursor users can trigger the reminder manually.

Development

No build step: pure Markdown + JSON. Validate and dogfood locally:

./scripts/validate.sh                                 # manifests, parity, .mcp.json, frontmatter, MCP pairing, guide URIs (skips without Python)
claude plugin validate .                              # manifest + component structure (no Python needed)
vale sync && vale --minAlertLevel=error .             # prose lint, as the CI prose job runs it (Vale 3.18.0)
claude --plugin-dir /path/to/openehr-assistant-plugin # load locally for one session

Then verify a command (/ckm-search blood pressure) and skill auto-triggering on both hosts. CI (.github/workflows/validate.yml) runs on push to main and on every pull request: the validate job runs scripts/validate.py strictly; the prose job gates on Vale errors. The smoke test and what each check covers: docs/testing.md; installs: docs/install.md.

File Conventions

Detail (naming, skill vs command vs agent, trigger descriptions) is owned by docs/authoring.md. The rules that must hold:

• Skills go in skills/<name>/SKILL.md, commands in commands/<name>.md, agents in agents/<name>.md; contributor reference, plans, specs, and design docs go in docs/
• All markdown files use YAML frontmatter for metadata
• allowed-tools (skills/commands) pre-approves MCP tools to avoid permission prompts; agents use tools: instead (allowed-tools: in an agent file is ignored and the agent silently inherits all tools)
• Skills: auto-invocable / user-invocable in frontmatter as needed; argument-hint and $ARGUMENTS work here too; follow Guide-First (load MCP guides before acting)
• Commands: argument-hint in frontmatter and $ARGUMENTS in body; keep them single-interaction. Prefer a skill for anything multi-step; commands are thin one-shots

Documentation Sync

When adding or renaming components, update: AGENTS.md (component tables), README.md (tables), and hooks/session-start.sh (its Commands: ... and Skills ... lines). Cursor uses the same skills/commands/agents paths; no separate Cursor-only list is required.

CHANGELOG style

• Entries go under ## [Unreleased] while work is in flight and get folded into the next ## [X.Y.Z] - YYYY-MM-DD section at release.
• Use the Keep a Changelog groups in order: Added, Changed, Deprecated, Removed, Fixed, Security. Omit empty groups.
• One line per bullet. Lead with the subsystem (Commands:, Guide URIs:, Cursor rule <path>:) and state the change tersely. Use backticks for file, command, tool, URI, and frontmatter-key names.
• No rationale, no PR links, no restating why; that belongs in commit messages or the PR description. CHANGELOG captures what changed for a reader who wants a compact release delta.
• If a bullet is three lines, it is too long.
• When consolidating accumulated [Unreleased] work into a new release, check git log <last-tag>..HEAD to ensure every commit is represented exactly once across the groups.

Commit Messages

• Follow Conventional Commits, e.g. fix(commands): corrected allowed-tools in archetype-search, feat(skills): added composition-builder skill.
• Scopes: skills, commands, agents, hooks, docs, mcp.

Versioning

Bump rules and release steps are owned by docs/versioning.md. The rules that must hold:

• Plugin version (and, for consistency, description and author) must be kept in sync in both .claude-plugin/plugin.json and .cursor-plugin/plugin.json. Follow Semantic Versioning; update both manifests and CHANGELOG.md when releasing.
• Release naming: git tags and GitHub release titles are exactly vX.Y.Z (annotated tag; no bare X.Y.Z, no descriptive suffix in the title). The release theme belongs in the CHANGELOG section (it becomes the release notes); CHANGELOG headings stay bare ## [X.Y.Z] - YYYY-MM-DD.

Branching

• Use feature branches and pull requests. PR validation runs on every pull request (and on push to main).

Gotchas

• Agents use tools:, not allowed-tools:. allowed-tools: is a skills/commands key; in an agent file it is ignored and the agent silently inherits all tools. Use tools: (a YAML list is fine). See agents/clinical-modeler.md for the correct form.
• An MCP id in agent tools: must be listed under both mount namespaces. tools: entries are matched literally against live tool ids, and an MCP tool's id depends on how the server was mounted: mcp__openehr-assistant__<tool> for a project/user .mcp.json, mcp__plugin_openehr-assistant_openehr-assistant__<tool> when it comes from this plugin's bundled .mcp.json (a claude.ai connector gives a third shape, mcp__claude_ai_<connector>__<tool>). A non-matching entry is dropped silently, and an agent whose entire tools: list resolves to nothing is refused (would be spawned with zero tools). So ckm-scout (MCP-only tools:) failed to spawn at all under a plugin mount, while clinical-modeler and spec-researcher spawned with built-ins only and hit their BLOCKED: … path. All three now list both forms, and scripts/validate.py enforces the pairing. Note the contrast with skills/commands: allowed-tools only pre-approves permissions, so a namespace miss there costs a prompt, not access.
• Never put reference .md files under commands/. Host validators (claude plugin validate) treat every commands/**/*.md as a command and warn on missing frontmatter, so a reference file there is mis-detected. Reference material belongs inside the consuming skill's references/ subdirectory (e.g. skills/semantic-diff/references/semantic-diff-rubric.md); a command that needs bulky reference content is a sign it should be a skill.
• Subagents need the MCP server pre-approved or they silently lose CKM/guide access. Agent frontmatter tools: grants the capability, but the host's permission policy must still allow the server. The repo's .claude/settings.json permissions.allow lists the openehr-assistant server (both the bundled mcp__plugin_openehr-assistant_openehr-assistant and mcp__openehr-assistant namespaces); users who hit "CKM denied in a subagent" should add the same to their project settings. ckm-scout / spec-researcher / clinical-modeler fail loud with BLOCKED: … and route the lookup back to the main session when this isn't in place.
• MCP tool parameters are named, not positional. Skill/command examples use the readable tool("value") shorthand, but the real calls take the server's JSON params, e.g. ckm_archetype_search → keyword, *_get → identifier, type_specification_get → name. When unsure, the tool's loaded schema is authoritative; don't guess { query }.
• Deferred MCP tool schemas load on first use. In review/diff flows that call several MCP tools, reference the tools early so their schemas resolve before the first call (avoids first-call round-trips). This is partly a host concern.
• A self-hosted server advertising stale tools/prompts/guides is a server cache, not a plugin bug. Since MCP v0.20.0 the discovery cache is namespaced by APP_VERSION; upgrading the server without bumping its version keeps the old capability ads. Clear it server-side (MCP repo docs/development.md). The hosted instance in .mcp.json is unaffected.
• The Cursor hook uses a workspace-relative command (bash hooks/session-start.sh), not ${CLAUDE_PLUGIN_ROOT} (a Claude-Code-only variable). Keep both hook configs in step; don't "fix" the Cursor one to use the variable.
• Lint rules have one source of truth: guide_get("openehr://guides/archetypes/rules"). The archetype-lint skill keeps only a compact index; skills/openehr-assistant/reference/lint-rules-complete.md is the offline twin for the clinical-modeler agent. When the guide changes, update the offline twin; don't re-inline full rule text into the skill.
• Register in the marketplace separately, and repin it on every release. Public availability requires an entry in the cadasto marketplace, maintained in Cadasto/plugin-marketplace. That entry is pinned to a release tag, so tagging here ships nothing until the entry's version and source.ref are bumped; see docs/versioning.md.