openehr-specs: add bmm-authoring skill for writing and checking BMM schemas

[sebastian-iancu]

Summary

Adds bmm-authoring, a skill for writing a component's BMM schema (the P_BMM JSON in computable/BMM/) from scratch or changing one. Until now the plugin only covered generating class tables from a BMM (class-generation).

File	Contents
SKILL.md	The workflow for changing a schema and for writing a new one, including the empty schema that scaffold creates. Also a quick reference from construct to JSON, how to run the checker, and guardrails, such as editing the JSON in place because the published files mix PHP-style escapes with raw characters.
references/p-bmm-json.md	The JSON format. It was checked against the development BMM Persistence spec, the P_BMM classes in the LANG BMM, the published schemas, and what bmm-publisher 0.12.0 reads and renders. It lists what the class tables leave out, the spec features the publisher ignores (indexed containers, ancestor_defs, type_ref value sets) with what to write instead, and how the spec's ODIN and YAML examples map to JSON.
assets/openehr_demo_0.1.0.bmm.json	A worked example with one of each common construct. It passes the checker and renders cleanly.
scripts/check_bmm.py	A read-only checker in standard-library Python 3.8+.

The checker is there because bmm-publisher exits 0 on modelling mistakes such as these, and renders something else in their place. It reports, for example:

• a misspelt or missing _type, or a misspelt key such as is_mandatory;
• a class in no package, or more than four package levels deep, which gets no table;
• {"lower": 2, "upper": 5} without "upper_unbounded": false, which loses its upper limit;
• type nestings that render as List<Any>, print nothing, or crash the publisher;
• a generic argument that does not conform to its parameter's conforms_to_type.

It exits 0 when the check is complete with no errors, 1 on errors, 2 on unreadable input, and 3 when names from an included schema went unchecked because that schema was not passed with -d.

Other changes:

• class-generation, authoring and scaffold send BMM schema edits to bmm-authoring, and so does the AGENTS.md that scaffold writes. Template set revision 3 is not in a plugin release yet, so it was edited in place and its digest recomputed. Its empty schema now uses 4-space indentation, like the published schemas.
• The prompting guide (with a new section for a new component's schema), plugin README, AGENTS.md, docs/testing.md and the CHANGELOG are updated.
• main (with openehr-specs: scaffold a computable/BMM schema in new repositories #9) is merged in.

How it was tested

• Without the skill, two agents did a from-scratch task and an edit task. The from-scratch agent made 35 tool calls, most of them reading parser and publisher source. The edit agent used the persistence spec's own forms, and three of those forms rendered wrong without a warning. With the skill, neither agent read any source code, the new schema passed the checker on its first run, and the edit avoided all three problems.
• /pr-review-toolkit:review-pr (code, tests, documentation, silent failures) ran twice. Each finding was checked against the parser and publisher source, or a publisher run, before it was fixed.
• plugin-dev:skill-reviewer reviewed the skill and its routing in the sibling skills. Fixes made from its findings cover rename and removal, the commit rule, a single schema_revision bump per change set, and the scaffold AGENTS.md routing. A docs-editing prose review covered the CHANGELOG, the docs and this description.
• scripts/test_check_bmm.py has 107 tests (239 in the whole suite). Every finding the checker can report has a test: disabling any one of them makes at least one test fail. The tests' BASE stub copies the real ancestry and generic constraints. A wrongly typed value at any node of the worked example must produce a finding, not a traceback.
• The checker was run over the current schema of each component (BASE 1.3.0, RM 1.2.0, AM 1.4.0 and 2.4.0, LANG 1.1.0 and its BMM3 variant, TERM 3.1.0) with their dependencies. Its errors, and one TERM warning, are the defects listed below. BASE also gets one warning, for an undocumented class.

Defects found in published schemas (not fixed here)

• AM 2.4.0 P_ARCHETYPE_SLOT.includes and excludes: a List with no element type, which the published table shows as List<Any>.
• AM 2.4.0 c_conforms_to(rmcc) in eight classes: FUNCTION<Boolean, TUPLE2<String, String>>. BASE declares FUNCTION<ARGS, RESULT> and the AOM2 text says FUNCTION<<a_type, other_type: String>, Boolean>, so the arguments are in reverse order.
• LANG 1.1.0 BMM3 BMM_CLASS.features and flat_features: a result List with no element type.
• TERM 3.1.0 uses BASE types without listing BASE in includes (a warning).

Checklist

• python3 scripts/validate.py and python3 -m unittest discover -s scripts -p 'test_*.py' pass (239 tests); claude plugin validate plugins/openehr-specs --strict passes
• Skill triggering tested locally in Claude Code: not done. Agents read the skill directly; it was not run from an installed plugin
• Cursor install tested locally: not done
• Both marketplaces updated when plugin metadata changed: no metadata change
• CHANGELOG.md updated under Unreleased; no version bump
• Content grounded in published openEHR specifications: identifiers checked against the persistence spec, the LANG BMM class model and the published schemas; parser and table behaviour checked by running bmm-publisher 0.12.0

🤖 Generated with Claude Code

[SevKohler]

Add exclusions for folders without BMM ITS REST etc.