From 34fb7a5e1fe622d8c3d37af0e7bd023b9a7e06ef Mon Sep 17 00:00:00 2001 From: Sebastian Iancu Date: Wed, 7 Oct 2026 22:49:13 +0200 Subject: [PATCH] docs: add quick start and prompting guide, move style guide into authoring Add docs/quick-start.md (tutorial: install, review, fact-check, amendment entry, HTML preview, on a throwaway branch) and docs/prompting-guide.md (how-to: prompts by authoring situation). Remove docs/spec-style-guide.md. Its register, structure, cross-reference and figure conventions already live in content-patterns, authoring and review. Its admonition, code-block and table conventions move to authoring/references/asciidoc-syntax.md, which authoring and content-patterns now point to. Drop the four links to the old file and add the prompting guide to the inventory-sync rule. Co-Authored-By: Claude Sonnet 5.5 --- AGENTS.md | 3 +- CHANGELOG.md | 2 + CONTRIBUTING.md | 3 +- README.md | 3 +- docs/install.md | 5 + docs/prompting-guide.md | 179 ++++++++++++++++++ docs/quick-start.md | 106 +++++++++++ docs/skill-authoring.md | 1 - docs/spec-style-guide.md | 42 ---- plugins/openehr-specs/README.md | 2 +- .../openehr-specs/skills/authoring/SKILL.md | 1 + .../authoring/references/asciidoc-syntax.md | 56 ++++++ .../skills/content-patterns/SKILL.md | 2 + 13 files changed, 356 insertions(+), 49 deletions(-) create mode 100644 docs/prompting-guide.md create mode 100644 docs/quick-start.md delete mode 100644 docs/spec-style-guide.md create mode 100644 plugins/openehr-specs/skills/authoring/references/asciidoc-syntax.md diff --git a/AGENTS.md b/AGENTS.md index 7ab11ad..48a5e24 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,7 @@ ai-plugins/ └── agents/.md # Autonomous subagents (context-isolated, multi-file) ``` -Current plugins: `openehr-specs` (skills, including user-only action skills, and subagents). `plugins/openehr-specs/README.md` is its inventory: update it, and the root `README.md`, whenever a component is added, removed, or renamed. `validate.py` checks neither. +Current plugins: `openehr-specs` (skills, including user-only action skills, and subagents). `plugins/openehr-specs/README.md` is its inventory: update it, the root `README.md`, and the skill and subagent names in `docs/prompting-guide.md`, whenever a component is added, removed, or renamed. `validate.py` checks none of them. ## Key Conventions @@ -49,7 +49,6 @@ Pure-content repository (JSON manifests + markdown skills) — no build step or - **Validation**: `python3 scripts/validate.py` (Claude + Cursor manifests, version sync, required skill/agent frontmatter fields, component paths, and the `scaffold` template set's integrity — runs in CI; it does not check description length, inventories, or the release tag) - **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 diff --git a/CHANGELOG.md b/CHANGELOG.md index d30c317..f15ca9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Notable changes to the plugins in this repository. The format follows [Keep a Ch - `scaffold` skill (user-only, `/openehr-specs:scaffold`): initialises a specification repository, or brings an existing one up to the standard file set. It installs `AGENTS.md` (the `openehr-specs@openehr` plugin table, the Docker build invocation, and commit and branch conventions built around the Jira ticket key, `Changes for SPECXX-NN - `), `.claude/CLAUDE.md`, `.claude/settings.json` (registers the `openehr` marketplace, enables `openehr-specs` and three other plugins, and pre-approves `git add`, `git commit`, `git diff`, WebFetch on `specifications.openehr.org` and three read-only Atlassian MCP calls, as BASE, RM and ITS-REST do today), `manifest.json`, `.gitignore`, `.asciidoctorconfig`, `LICENSE` (CC BY-SA 3.0, or Apache 2.0 for `ITS-*`) and `README.md`. It plans before it writes, reads the component, title, Jira key, BMM schema and licence from the repo, and never overwrites a hand-edited file without being told to. - The file set is versioned: `assets/template-set.json` holds a revision, the variables and a strategy per file (seed, whole, JSON merge, ensure-lines, managed regions in `AGENTS.md`), and each repo records its revision and file hashes in `.claude/scaffold.json`, so a later run calculates the migration path from the recorded revision to the latest. `scripts/scaffold.py` needs `python3` (standard library only). +- `docs/quick-start.md` (a first session, from install to an HTML preview) and `docs/prompting-guide.md` (which prompt to use for each authoring situation). ### Changed @@ -32,6 +33,7 @@ Notable changes to the plugins in this repository. The format follows [Keep a Ch ### Removed +- `docs/spec-style-guide.md`. Most of what it restated (register, document structure, cross-reference and figure conventions) lives in `content-patterns`, `authoring` and `review`, so it was a second copy to keep in step. The conventions that were not in a skill (admonitions, code blocks, tables) moved to `authoring/references/asciidoc-syntax.md`, which `authoring` and `content-patterns` point to. - `/openehr-specs:amend`, folded into `amendment-record`. Use `/openehr-specs:amendment-record ` or a plain request. Removing a user-facing entry point is a major change under [docs/versioning.md](docs/versioning.md); the maintainer decides the bump at release. ## openehr-specs 0.3.0 (2026-10-07) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 45ad739..0ab68a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,6 @@ Test your changes by installing the marketplace locally — see [docs/testing.md ## Conventions - Plugin/skill structure and naming: [docs/skill-authoring.md](docs/skill-authoring.md) -- AsciiDoc style for spec-related content: [docs/spec-style-guide.md](docs/spec-style-guide.md) - Versioning and releases: [docs/versioning.md](docs/versioning.md) - Ground everything in the published [openEHR specifications](https://specifications.openehr.org) — never invent class names, attributes, paths, or identifiers. @@ -34,7 +33,7 @@ Use [Conventional Commits](https://www.conventionalcommits.org): `type(scope): s 1. Branch from `main`. 2. Run the checks locally: `python3 scripts/validate.py` and `python3 -m unittest discover -s scripts -p 'test_*.py'` -3. If you changed plugin content, add a line under `## Unreleased` in [CHANGELOG.md](CHANGELOG.md). Do not bump the version; maintainers do that at release ([docs/versioning.md](docs/versioning.md)). If you added, removed, or renamed a skill or subagent, also update the inventories in the plugin's `README.md` and in the root [README.md](README.md). +3. If you changed plugin content, add a line under `## Unreleased` in [CHANGELOG.md](CHANGELOG.md). Do not bump the version; maintainers do that at release ([docs/versioning.md](docs/versioning.md)). If you added, removed, or renamed a skill or subagent, also update the inventories in the plugin's `README.md` and in the root [README.md](README.md), and the skill and subagent names used in the [prompting guide](docs/prompting-guide.md). 4. Test skill triggering locally ([docs/testing.md](docs/testing.md)). 5. Open the PR and complete the checklist in the template. CI must pass. diff --git a/README.md b/README.md index a974108..978b0fc 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,11 @@ The plugin also ships **subagents** (`spec-reviewer`, `xref-auditor`, `identifie ## Documentation +- [docs/quick-start.md](docs/quick-start.md): a first session, from install to an HTML preview +- [docs/prompting-guide.md](docs/prompting-guide.md): which prompt to use for each authoring situation - [docs/install.md](docs/install.md): installing, updating, and inspecting plugins - [docs/testing.md](docs/testing.md): local testing and validation (contributors) - [docs/skill-authoring.md](docs/skill-authoring.md): plugin and skill authoring conventions -- [docs/spec-style-guide.md](docs/spec-style-guide.md): style guide for openEHR specification documents - [docs/versioning.md](docs/versioning.md): versioning and release process ## Contributing diff --git a/docs/install.md b/docs/install.md index 0446525..d5c87d0 100644 --- a/docs/install.md +++ b/docs/install.md @@ -44,3 +44,8 @@ Cursor installs plugins from the **Customize** page. To add this repository as a See the [Cursor plugin documentation](https://cursor.com/docs/plugins) for the full flow. To try a local copy, see [testing.md](testing.md#local-testing). The repo root contains `.cursor-plugin/marketplace.json`, and each plugin under `plugins//` has its own `.cursor-plugin/plugin.json`. See [plugins/openehr-specs/README.md](../plugins/openehr-specs/README.md) for the component inventory. + +## Next steps + +- [quick-start.md](quick-start.md): a first session on a real specification repository. +- [prompting-guide.md](prompting-guide.md): which prompt to use for each authoring situation. diff --git a/docs/prompting-guide.md b/docs/prompting-guide.md new file mode 100644 index 0000000..68c0279 --- /dev/null +++ b/docs/prompting-guide.md @@ -0,0 +1,179 @@ +# Prompting guide + +Prompts for the situations that come up when you work on an openEHR specification repository with the `openehr-specs` plugin, with what each one triggers and what to check in the result. It assumes the plugin is installed ([install.md](install.md)); the [quick start](quick-start.md) walks through a first session. + +The skills cover the specification sources. For archetypes, templates, AQL and terminology, use the `openehr-assistant` plugin. + +In the prompts, `` is a component id such as `RM`, `BASE` or `AM`, and `` is the name of a directory under `docs/`. Run Claude Code from the spec repository, with two exceptions: `/openehr-specs:publish` needs the parent directory that holds all the `specifications-*` clones, and `/openehr-specs:scaffold` needs the repository root. + +| Situation | Skill, subagent or command | +|-----------|----------------------------| +| [Start a new specification](#start-a-new-specification) | `authoring` | +| [Add or change a chapter, figure or link](#add-or-change-a-chapter-figure-or-link) | `authoring` | +| [Draft or improve spec prose](#draft-or-improve-spec-prose) | `content-patterns` | +| [Record a change in the amendment record](#record-a-change-in-the-amendment-record) | `amendment-record` | +| [Change a class, attribute or invariant](#change-a-class-attribute-or-invariant) | `class-generation`, `/openehr-specs:regen-classes` | +| [Review before you merge](#review-before-you-merge) | `review`, `spec-reviewer`, `xref-auditor`, `identifier-grounding` | +| [Preview the HTML](#preview-the-html) | `/openehr-specs:publish` | +| [Releases, status changes and the CR/PR process](#releases-status-changes-and-the-crpr-process) | `governance` | +| [Edit the ITS-REST API](#edit-the-its-rest-api) | `its-rest` | +| [Set up or upgrade a repository](#set-up-or-upgrade-a-repository) | `/openehr-specs:scaffold` | +| [Write a commit message](#write-a-commit-message) | the repository's `AGENTS.md` | + +## What makes a prompt work + +- **Name the target.** Give the repository, the spec directory or the file, so Claude does not have to ask which spec you mean. +- **Give the ticket key and your name.** The amendment record entry needs the Jira key and the raiser, and the ITS-REST entry needs the ticket, the raiser and the date. Claude asks for what is missing rather than inventing it. +- **Say whether Claude may edit.** The review skill reports findings and edits only when you ask. +- **Force a skill by typing its name.** Claude loads a skill when your request matches its description. If it does not, type `/openehr-specs:`. The three action skills (`publish`, `regen-classes`, `scaffold`) run only when you type them. +- **Read the diff.** The amendment record, class generation, `publish`, `regen-classes` and `scaffold` skills do not commit. The release steps in `governance` do, and Claude asks before it pushes. + +## Start a new specification + +Agree the identifier and placement with the Specifications Editorial Committee (SEC) first; it verifies both for new specs (`governance`). + +```text +Create a new specification document with id in specifications-: manifest_vars.adoc, master.adoc, the amendment record, a preface and an overview chapter, plus its entry in manifest.json. Status is , copyright year . +``` + +Use the status the SEC assigned for `` (for example `DEVELOPMENT`). Claude keeps `spec_status` identical in `manifest.json` and `manifest_vars.adoc`. Check that the chapter files are numbered without gaps and that `master.adoc` includes each one. + +## Add or change a chapter, figure or link + +```text +Add a chapter "Versioning" to the spec in specifications-, numbered and named to follow the existing chapters, and include it in master.adoc. +``` + +```text +Add the diagram docs//diagrams/.svg to the overview chapter as a titled figure with an id. +``` + +```text +Link the first mention of DV_QUANTITY in master04-.adoc to the Data Types spec. +``` + +Cross-spec links use the `{openehr_*}` attributes from `reference_definitions.adoc`, not pasted URLs. When the attribute you need is missing, Claude adds it to `specifications-AA_GLOBAL`, which is a separate repository and a separate commit, and tells you so. + +## Draft or improve spec prose + +```text +Draft the Overview section for the package in master03-.adoc using the package overview pattern: opening paragraph, figure placeholder, then the list of classes. Use only class names that exist in the published RM. +``` + +```text +Rewrite this section in the design rationale pattern: the requirement, the chosen design, and the alternatives rejected. +``` + +The `content-patterns` skill has a catalogue of patterns, among them package overview, class semantics and design rationale. Name the one you want. It writes in the register the library uses: third person, present tense, no contractions. After drafting, ask for a fact-check of the names (see [Review before you merge](#review-before-you-merge)). + +## Record a change in the amendment record + +```text +/openehr-specs:amendment-record SPECRM-142 - add tags to LOCATABLE; addresses SPECPR-401 +``` + +A plain request works as well: "Add an amendment entry for SPECRM-142 to the EHR spec." + +Claude reads the current record, then asks for anything missing, usually the raiser. It picks the version bump (patch for corrections, minor for new content or semantic changes, major for a restructure), adds the entry at the top, moves the `[[latest_issue]]` and `[[latest_issue_date]]` anchors, and uses today's date unless you give one. If you made the change already, Claude checks `git status` and the diff stat first, so the entry describes what changed. It shows the diff and stops. + +To put two changes under one version, say so: "same version as the top entry". + +## Change a class, attribute or invariant + +Class tables in `docs/UML/classes/` are generated from the BMM schema, so the change goes in the BMM and the tables are regenerated. Editing the BMM follows the repository's own `AGENTS.md`; the plugin's skills cover the generation. + +```text +In the BMM for this repo, add an optional attribute of type to class , with documentation, following this repo's AGENTS.md. +``` + +```text +Regenerate the class tables for from the BMM in this checkout, not the copy bundled in the publisher image. Compare with docs/UML/classes and copy over only the tables that changed. +``` + +Say "from this checkout". A bare schema id such as `openehr_base_1.3.0` makes the publisher use the schema bundled in its Docker image, which can lag the repository. The `class-generation` skill covers mounting your own schemas, and the repository's `AGENTS.md` may carry the exact command. Docker is required. + +To see what the image's bundled schemas produce, type: + +```text +/openehr-specs:regen-classes openehr_rm_1.2.0 -d openehr_base_1.3.0 +``` + +It writes to `out/` in the working directory and places nothing in a repository, so run it from a scratch directory. Its output reflects the bundled schemas; for tables to commit, use the previous prompt. + +## Review before you merge + +One chapter, inline: + +```text +Review docs//master03-.adoc against the review checks. Report findings only. +``` + +A whole spec directory, in an isolated context. The `spec-reviewer` subagent also takes a whole component: + +```text +Run the spec-reviewer subagent on docs// and give me the findings table. +``` + +Links, after a large edit: + +```text +Run the xref-auditor subagent on docs//: every {openehr_*} attribute and <>, and the cross-spec deep links. +``` + +Names, after drafting: + +```text +Run the identifier-grounding subagent on master04-.adoc and flag any class, attribute or function name that does not exist in the published specifications. +``` + +The review skill reports each finding as `ERROR`, `WARNING` or `INFO` with a `file:line` location, grouped by check category. It checks sources statically, so missing includes and images show up only in a build ([Preview the HTML](#preview-the-html)). To have Claude apply the fixes, ask: "Fix the ERRORs, leave the warnings for me." + +`xref-auditor` resolves attributes against the sibling `specifications-AA_GLOBAL` checkout and uses web access only for cross-spec deep-link anchors, which it marks `UNCHECKED` without it. `identifier-grounding` checks names through the `openehr-assistant` MCP server, the published Markdown twins or the local sibling repositories, and marks what it cannot verify `UNVERIFIED`. + +## Preview the HTML + +```text +/openehr-specs:publish +``` + +The build mounts the working directory, so run it from the parent directory that holds the `specifications-*` clones. It needs Docker and the sibling `specifications-AA_GLOBAL` checkout, builds the whole component as the `development` release, and reports any file that was not rebuilt and any `ERROR` or `include file not found` line. The build rewrites the tracked `docs/*.html` files; leave them out of your commit. + +## Releases, status changes and the CR/PR process + +```text +Prepare Release- of specifications- with the release checklist. Do the manifest.json and git steps, and stop before pushing. +``` + +```text +The SEC promoted my spec from Development to Trial. What changes in manifest.json and manifest_vars.adoc? +``` + +```text +Should this change be a problem report or a change request, and who can raise it? +``` + +Only SEC members create change requests; anyone can raise a problem report on the `SPECPR` tracker. The Jira steps of a release are yours, and Claude asks you to confirm them. It asks before it pushes. For a fix release it confirms with you first, because the push overwrites the deployed release. The promotion criteria are the SEC's: Claude sets the new status in both files once you confirm that the SEC approved it. + +## Edit the ITS-REST API + +```text +In specifications-ITS-REST, add a _ operation for . Reuse the shared parameters and responses, add or reference the schema, wire it into ehr.openapi.yaml, then bundle and validate. +``` + +Claude asks for the `SPECITS` ticket, the raiser and the date for the amendment record entry. Docker is needed for `make bundle` and `make validate`. The AsciiDoc documents under that repo's `docs/` (`simplified_formats`, `smart_app_launch`) follow `authoring`, not `its-rest`. + +## Set up or upgrade a repository + +```text +/openehr-specs:scaffold +``` + +Run it from the repository root, for a new, empty repository or an existing one. Claude plans first: it shows what it would create, merge or leave alone, and asks about guessed values such as the licence, Jira key and BMM schema. It writes only after you agree. It installs the standard file set, listed in the [plugin README](../plugins/openehr-specs/README.md), and records the revision in `.claude/scaffold.json` so a later run can upgrade the repository. Run it again after a plugin update. It needs `python3` and is written for Claude Code. + +## Write a commit message + +```text +Write the commit message for my staged changes. +``` + +This follows the Conventions section of the repository's `AGENTS.md`, which `/openehr-specs:scaffold` installs: `Changes for SPECXX-NN - `. Claude takes the key from you, then from the branch name (`feat/SPECXX-42-`), and writes no key when it has none, rather than guessing. diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..d0b31ea --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,106 @@ +# Quick start + +Install the `openehr-specs` plugin and use it on a real specification repository. You review a chapter, fact-check the class names in another, add an amendment record entry, and build the HTML preview. Every change is an uncommitted edit on a throwaway branch, and the last step discards it. + +The steps use Claude Code and its slash commands. To install in Cursor, follow [install.md](install.md). + +## Before you start + +- Claude Code, signed in. +- `git`. +- Docker, for step 6 only. Steps 1 to 5 do not need it. +- Network access to GitHub. Step 4 also reads the published specifications. + +Claude Code asks permission before some actions, such as editing a file or running a command it has not been given a standing approval for; allow the ones the steps describe. Claude's wording differs between runs, so each step says what to look for. + +## 1. Clone two repositories side by side + +The example spec is `specifications-BASE`. `specifications-AA_GLOBAL` holds the boilerplate and reference definitions that the preview build and some review checks read, so it must sit next to it. + +```bash +mkdir openehr && cd openehr +git clone https://github.com/openEHR/specifications-AA_GLOBAL.git +git clone https://github.com/openEHR/specifications-BASE.git +git -C specifications-BASE switch -c try/quick-start +``` + +The last command puts BASE on a throwaway branch. + +## 2. Install the plugin + +Start Claude Code in the `openehr` directory: + +```bash +claude +``` + +Install the plugin from the openEHR marketplace: + +```text +/plugin marketplace add openEHR/ai-plugins +/plugin install openehr-specs@openehr +``` + +Exit and start `claude` again from the same directory, because a newly installed plugin loads in the next session. Type `/openehr` and the slash menu lists the plugin's skills. + +## 3. Review a chapter + +Send this prompt: + +```text +Review specifications-BASE/docs/base_types/master02-overview.adoc with the openehr-specs review checks. Report findings only, do not edit. +``` + +Claude applies the `review` skill and answers with a table of findings (ID, severity, location, finding) and a total line. For a single file it also lists the checks it did not run, because they need other files. When no check fails, it says so. Nothing is edited. + +## 4. Fact-check class names + +Send this prompt: + +```text +Fact-check the class and attribute names in specifications-BASE/docs/base_types/master05-identification_package.adoc against the published openEHR specifications. +``` + +Claude dispatches the `identifier-grounding` subagent. It returns one row per identifier with a status: `VERIFIED`, `UNVERIFIED`, `LIKELY INVENTED`, `NEW` or `SKIPPED`. It may ask permission to fetch pages from `specifications.openehr.org`; allow it. + +## 5. Add an amendment record entry + +Send this prompt: + +```text +/openehr-specs:amendment-record SPECBASE-999 - fix a typo in the base_types overview chapter (an exercise: the key is made up) +``` + +For real work, give the key of the Jira ticket. + +Claude asks for the raiser name; answer with your own. It adds a new top entry to `specifications-BASE/docs/base_types/master00-amendment_record.adoc`, bumps the patch number because a typo fix is a patch change, and moves the `[[latest_issue]]` and `[[latest_issue_date]]` anchors to the new entry. Then it shows the diff and stops. It does not commit. Claude Code may ask you to approve the `git` commands it uses to read the diff; allow them. + +## 6. Build the HTML preview + +Make sure Docker is running, then send: + +```text +/openehr-specs:publish BASE +``` + +The first run pulls the `ghcr.io/openehr/asciidoctor` image. The build prints `generated` and exits successfully even when it failed, so Claude compares the modification time of each `docs/*.html` file before and after, and scans the log for `ERROR` and `include file not found`. It reports where the HTML landed, or `NOT BUILT` for any file that did not change, with the errors verbatim. It may ask permission for the `stat` commands it uses. + +The build rewrites the four tracked `docs/*.html` files of BASE. Do not stage them. + +## 7. Discard the exercise + +Exit Claude Code, then run: + +```bash +git -C specifications-BASE restore . +git -C specifications-BASE switch - +git -C specifications-BASE branch -D try/quick-start +git -C specifications-BASE status --short +``` + +The first command discards the edits from steps 5 and 6, and the last prints nothing. + +## Next + +- [Prompting guide](prompting-guide.md): which prompt to use for each authoring situation. +- [Plugin README](../plugins/openehr-specs/README.md): every skill and subagent. diff --git a/docs/skill-authoring.md b/docs/skill-authoring.md index 702b3da..de53d86 100644 --- a/docs/skill-authoring.md +++ b/docs/skill-authoring.md @@ -40,7 +40,6 @@ The plugin manifests, the marketplace entries, and the release tag must all carr - Keep skill content factual and grounded in openEHR specifications; do not invent identifiers, paths, or conventions. - Reference files go in `references/` next to the SKILL.md; keep `SKILL.md` bodies focused (none of the current ones exceeds 300 lines) and push bulky supporting material to `references/`. - A skill may also bundle `scripts/` and `assets/` (the `scaffold` skill does). Call a script as `${CLAUDE_SKILL_DIR}/scripts/` in the body and in `allowed-tools`, keep it to the standard library, say in the skill what it does when the interpreter is missing, and test it under `scripts/test_*.py` in this repo (CI runs them). A skill that installs versioned content states a revision and a migration path, as `scaffold` does in `assets/template-set.json`. -- Skill bodies that generate or review AsciiDoc must agree with the [spec style guide](spec-style-guide.md) — when changing one, check the other. ## Subagent and Action-Skill Authoring diff --git a/docs/spec-style-guide.md b/docs/spec-style-guide.md deleted file mode 100644 index 3b3df35..0000000 --- a/docs/spec-style-guide.md +++ /dev/null @@ -1,42 +0,0 @@ -# openEHR Specification Document Style Guide - -This style guide describes the conventions of the *target* `specifications-XX` repos that the skills operate on — not this repo's own files. Skill bodies must agree with it: when changing one, check the other. - -When generating or editing AsciiDoc content for any `specifications-XX` repo, follow these conventions. They are consistent across all components (RM, AM, BASE, QUERY, SM, PROC, LANG, CNF, TERM, ITS-*). - -## Tone and Register - -- Formal, precise, impersonal technical prose. Third person or passive voice throughout ("The class defines...", "Content is committed...", "This specification describes..."). -- Present tense for describing model semantics and design; past tense only for historical context or amendment records. -- No contractions (use "does not", not "doesn't"). No colloquialisms, no hedging ("perhaps", "maybe"). -- Clinical and standards-aware: assume the reader is a software engineer or informatician who understands object-oriented modelling. - -## Structural Patterns - -- **Preface** (`master01-preface.adoc`) always follows a fixed structure: Purpose, Related Documents, Status, Feedback, Conformance (optional), Tools (optional), Changes from Previous Versions (optional). -- **Chapter files** start with a `= Chapter Title` heading and typically open with an Overview subsection. -- **Package/chapter flow**: Overview first (introduces package purpose, typically with a UML diagram), then requirements or design rationale, then detailed semantics. Class description tables (when present) are auto-generated from UML/BMM — do not hand-write them. -- **Amendment record** (`master00-amendment_record.adoc`): most-recent-first table, release boundaries marked with `4+^h|*XX Release N.N.N*` rows, Jira ticket references using `{spec_tickets}/SPECXX-NNN[SPECXX-NNN^]` syntax. - -## AsciiDoc Conventions - -- **Class/type names** are monospaced: `` `COMPOSITION` ``, `` `DV_TEXT` ``, `` `VERSIONED_OBJECT` `` -- **Attribute names** are italicised inside underscores: `` `_uid_` ``, `` `_value_` ``, `` `_commit_audit_` `` -- **Cross-references to other specs** use attributes from `reference_definitions.adoc`: `{openehr_rm_common}[Common IM^]`, `{openehr_rm_data_types}#dv_quantity[DV_QUANTITY^]` -- **External standards** are linked via predefined attributes: `{iso_8601}[ISO 8601^]`, `{snomed_ct}[SNOMED CT^]`, `{rfc4880}[IETF RFC 4880^]` -- **Figures** use `[.text-center]` with a title line (`.Title`) followed by `image::` with `id=`, `align="center"`, and optional `width=` -- **UML diagrams**: `image::{uml_diagrams_uri}/RM-*.svg[...]`; hand-drawn diagrams: `image::{diagrams_uri}/*.png[...]` or `.svg` -- **TBD markers**: `[.tbd]` role followed by `*TBD*: (description)` -- **Deprecated markers**: `[.deprecated]` role followed by `*Deprecated*: (explanation)` -- **Admonitions**: use `NOTE:`, `WARNING:`, `IMPORTANT:` standard Asciidoctor admonitions -- **Bibliographic citations**: `cite:[Key]` or `citenp:[Key]` (in-text); bibliography rendered with `bibliography::[]` -- **Code blocks**: use `[source, language]` with `--------` delimiters for formal code; triple backticks for informal examples -- **Tables**: use `[cols="...", options="header"]` followed by `|===` block syntax - -## Writing Principles - -- Lead with **what** the model defines, not how the reader should understand it. State facts declaratively. -- Explain **design rationale** where non-obvious: why a class exists, why an alternative was rejected. -- Use **concrete examples** (clinical scenarios, data instances) to illustrate abstract concepts. -- When describing class semantics, address: typing, identification, lifecycle, relationships to other classes, and implementation notes. -- **Never invent** class names, attribute names, terminology codes, archetype paths, or RM types. Always ground in the published openEHR specifications. diff --git a/plugins/openehr-specs/README.md b/plugins/openehr-specs/README.md index 4cae2a5..07013f9 100644 --- a/plugins/openehr-specs/README.md +++ b/plugins/openehr-specs/README.md @@ -64,7 +64,7 @@ In Claude Code, each skill is namespaced by the plugin, so it is invoked as **`/ 2. **Browse the group**: type `/openehr` in the slash menu to list the plugin's skills 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`, with no slash command needed. (The action skills `/openehr-specs:publish`, `/openehr-specs:regen-classes` and `/openehr-specs:scaffold` 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). +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). For a first session, see the [quick start](../../docs/quick-start.md); for example prompts by situation, the [prompting guide](../../docs/prompting-guide.md). > **Note:** newly installed or edited skills become available in the **next** Claude Code session. diff --git a/plugins/openehr-specs/skills/authoring/SKILL.md b/plugins/openehr-specs/skills/authoring/SKILL.md index ec44180..50f76f2 100644 --- a/plugins/openehr-specs/skills/authoring/SKILL.md +++ b/plugins/openehr-specs/skills/authoring/SKILL.md @@ -256,6 +256,7 @@ that the log has no `ERROR` or `include file not found` lines. The build rewrite {openehr_rm_data_types}#dv_quantity[DV_QUANTITY^] ``` - **Cross-references to classes**: Use `{classes_url_root}` for linking to the class index. +- **Admonitions, code blocks, tables**: follow `references/asciidoc-syntax.md` when adding a note, a code example, or a table. - **Jira ticket references**: `{spec_tickets}/SPECRM-87[SPECRM-87^]` - **External references**: Check `reference_definitions.adoc` first — it has hundreds of pre-defined URLs for HL7, W3C, ISO, IETF, Wikipedia, SNOMED, etc. If an attribute is missing, add it to `specifications-AA_GLOBAL/docs/references/reference_definitions.adoc` (a separate repo and commit) following the naming pattern, and tell the user the change spans two repos. diff --git a/plugins/openehr-specs/skills/authoring/references/asciidoc-syntax.md b/plugins/openehr-specs/skills/authoring/references/asciidoc-syntax.md new file mode 100644 index 0000000..1efb4e6 --- /dev/null +++ b/plugins/openehr-specs/skills/authoring/references/asciidoc-syntax.md @@ -0,0 +1,56 @@ +# AsciiDoc syntax conventions + +Conventions shared by the `specifications-XX` repositories for three elements that no other reference +defines: admonitions, code blocks and tables. Read this file when adding a note, a code example or a +table to a chapter. Match the spec you are editing if it differs. + +## Admonitions + +Start the paragraph with the standard Asciidoctor label: `NOTE:`, `WARNING:` or `IMPORTANT:`. + +```asciidoc +NOTE: The identifier is opaque to clients. +``` + +`NOTE:` is by far the most common in the specs. `WARNING:` and `IMPORTANT:` appear rarely. + +## Code blocks + +Formal code, such as a grammar, a query or source code, uses a `[source, ]` line and a +dashed delimiter: + +```asciidoc +[source, ebnf] +-------- +identifier = letter , { letter | digit } ; +-------- +``` + +The RM, AM, LANG and QUERY specs use this form; the languages in use include `ebnf`, `sql` and `java`. +Informal examples, such as a short list of values, use a triple-backtick fence. + +## Tables + +A table starts with a `[cols="..."]` line and a `|===` delimiter. Add `options="header"` when the first +row is a header row: + +```asciidoc +[cols="1,6,2,2", options="header"] +|=== +|Issue|Details|Raiser|Completed +|1.0.0|Initial writing.|A Author|01 Jan 2020 +|=== +``` + +Use `1a` or `2a` in `cols` when a cell needs AsciiDoc block content such as a list. Class definition +tables are generated from the BMM; do not write them by hand (`class-generation` skill). + +## Conventions defined elsewhere + +| Element | Where | +|---------|-------| +| Class and type names in monospace; attribute names in italic monospace | `review` checks ADOC-01 and ADOC-02 | +| `[.tbd]` and `[.deprecated]` markers | `review` checks ADOC-04 and ADOC-05; `content-patterns` pattern 6 | +| Bibliographic citations (`cite:[Key]`, `citenp:[Key]`) | `review` check ADOC-06 | +| Links to other specs and external standards (`{openehr_*}`, `{iso_8601}`) | `cross-references.md` | +| Figures and UML diagrams | `authoring` ("Diagrams"); `review` FIG checks | diff --git a/plugins/openehr-specs/skills/content-patterns/SKILL.md b/plugins/openehr-specs/skills/content-patterns/SKILL.md index 743f4ad..5042039 100644 --- a/plugins/openehr-specs/skills/content-patterns/SKILL.md +++ b/plugins/openehr-specs/skills/content-patterns/SKILL.md @@ -22,6 +22,8 @@ QUERY, CNF, TERM, ITS-*) and the shared infrastructure in `specifications-AA_GLO AsciiDoc template, real example, and conventions for each pattern indexed below. - **Cross-reference attribute guide**: see `../authoring/references/cross-references.md` for how to find and use `{openehr_*}` attributes when writing cross-references in spec prose. +- **Admonitions, code blocks, tables**: see `../authoring/references/asciidoc-syntax.md` for the + syntax of a note, a code example, or a table in a chapter. ## General Principles