The Event Modeling HCL plugin
The plugin teaches Claude, Codex, and ChatGPT the Event Modeling method and the .em.hcl language.
With a Git connector, a team can also view, change, and review one shared model through the assistant. Each change goes to a merge request (MR). A person reviews and merges it.
What the plugin contains
The plugin repository holds two Claude plugins in one marketplace. The name of the marketplace is event-modeling-hcl. Both plugins use the Apache-2.0 license and release together under one tag. The current release is v0.2.0. It targets Specification v0.8.0 and needs emhcl v0.17.0 or newer.
| Plugin | Contents | Needs |
|---|---|---|
event-modeling-skills | 32 method skills and the event-modeling-hcl language skill. The method skills discover, review, and plan a business model. The language skill owns HCL syntax and emhcl commands. | Nothing for business modeling. A shell with emhcl to validate HCL. |
event-modeling-hcl-plugin | The em-collaborate skill with six team procedures: em-setup, em-view, em-validate, em-change, em-review, and em-sync. | A shell, network access, and a GitLab or GitHub connector. |
The same skills are also available in two other packages:
| Surface | Modeling guidance | Repository procedures | Diagrams |
|---|---|---|---|
| Claude plugins | 32 method skills and the language skill | Six procedures through the GitLab or GitHub MCP server | Claude artifacts when the app supports them. Otherwise an HTML file. |
| Local Codex CLI and IDE | The same 33 modeling skills | The same six procedures through configured Git MCP tools and a shell | A local HTML file |
| ChatGPT and Codex plugin | The same 33 modeling skills | The same six procedures when a shell and Git MCP tools are available | A local HTML file |
The method text uses original wording based on community ideas. Event Modeling comes from Adam Dymitruk at Adaptech Group. The plugin also credits Martin Dilger.
Install the plugin
Claude Code
Add the marketplace, then install the collaboration plugin:
Claude Code also installs event-modeling-skills as a dependency. If you want only the skills without the Git procedures, install event-modeling-skills@event-modeling-hcl instead.
Claude chat and Cowork
Install the two plugins separately from Customize > Plugins. Add the repository through Add > Add marketplace. Alternatively, upload each plugin folder as its own ZIP file through Add > Upload plugin. Each ZIP file must contain .claude-plugin/plugin.json at its root or inside one top-level folder. Do not upload a ZIP file of the whole marketplace repository.
Local Codex CLI and IDE
You need Python 3. In a checkout of the plugin repository, build the package and install it into your model repository:
The installer puts the 34 skills in .agents/skills/ of that repository. To install them for all projects in ~/.agents/skills/, use --user instead of --project. The installer does not replace a skill that already exists. To upgrade a managed installation, add --update. Restart Codex after the installation.
ChatGPT and Codex plugin
In a checkout of the plugin repository, build the plugin and register the repository as a marketplace:
The builder writes the plugin to dist/chatgpt. The output folder must be absent or empty. Restart the ChatGPT desktop app, select Event Modeling HCL in the Plugins Directory, and install event-modeling-hcl-plugin. To install it in Codex, run:
In Codex, call a plugin skill with its plugin prefix, for example $event-modeling-hcl-plugin:em-collaborate em-view for OWNER/REPOSITORY. Use the plugin or the standalone Codex skills in one session, not both.
The installation does not give access to a repository and does not supply a shell. If the shell, the network, or the Git connector is not available, a repository procedure stops and does not report a result.
Upgrade from the development names
The plugins had other names before v0.1.0. If you installed emhcl@event-modeling-hcl, uninstall it and install event-modeling-hcl-plugin@event-modeling-hcl. If you installed emhcl-skills@event-modeling-hcl, uninstall it and install event-modeling-skills@event-modeling-hcl:
Model a business workflow
Business modeling in plain words needs no HCL file, no shell, and no Git connector. Each method skill owns one part of the model, for example the events, the read models, the lifecycles, or the command scenarios. The skills exchange questions, decisions, and evidence through the model.
Select the skill by the size of the task:
| Task | Skill |
|---|---|
| A complete event model from start to end | eventmodeling-orchestrating-workflow. It runs the gates of the method contract in order. |
| A live workshop with a group | eventmodeling-facilitating-workshop. It manages participants and time. The specialist skills record the model. |
| One part of the model | The specialist that owns the part, for example eventmodeling-brainstorming-events or eventmodeling-writing-command-scenarios. |
| Syntax repair, formatting, conversion, or a language question | event-modeling-hcl. It does not repeat the business discovery. |
Ask in plain words. The assistant selects the skill. For example:
If a discussion follows screens instead of work, ask for a paper-world reset. The skills then follow one real case through its actors, decisions, information, and handoffs.
The language skill targets Specification v0.8.0. It writes the method facts of that version: lifecycles, field sources, evidence, decisions, and dispatch assertions. See Method facts. To validate a model, the language skill runs emhcl v0.17.0 or newer.
A valid model does not prove that it describes the business. A domain expert must review the result. The skills keep an open question as a hotspot and do not invent a business rule to make strict validation pass.
Work on a team model in Git
The collaboration plugin connects the assistant to one model repository on GitLab or GitHub. It does not merge, and it does not write to the default branch.
| Command | What it does | Writes to Git |
|---|---|---|
em-setup | Makes sure that the connector, the validator, and .emhcl.yml are available. If .emhcl.yml is missing, it proposes the file through an MR. | Only an MR |
em-view | Shows a branch as a diagram and answers questions about it. | No |
em-validate | Validates a branch with a profile and explains each diagnostic in plain words. | No |
em-change | Turns a request in plain words into edits, validates them, publishes a diagram, and opens an MR. | A new branch and an MR |
em-review | Validates the head of an MR, lists the changed slices, and publishes a diagram. | One comment |
em-sync | Publishes the shared team diagram again from the default branch. | No |
In Cowork and Claude Code, run a command with the plugin prefix:
In Claude chat, ask in plain words. Claude uses the matching procedure.
Each procedure needs one Git connector:
- GitLab: the official GitLab MCP server.
em-changeneeds GitLab 19.4 or later, because it starts each branch at an exact commit. - GitHub: the GitHub MCP server.
Then ask the assistant to run em-setup for your repository.
Set up a model repository
- Keep the model in one folder. emhcl reads only the
.em.hclfiles directly in that folder and ignores subfolders. If the model is for specification v0.4.0, runemhcl migrate -w <folder>first. - Add
.emhcl.ymlat the root of the repository.em-setupproposes this file. - Add the CI job of your Git host, and use fast-forward merges.
This is the .emhcl.yml of the pet-clinic example:
| Key | Meaning | Value when absent |
|---|---|---|
emhcl_version | The emhcl release that the assistant and CI install. Both validate each commit with the same release. | None. The installer stops. |
model_path | The folder of the model, relative to the repository root. | model |
branch_prefix | The start of the name of each new branch. | model/ |
mr_labels | The labels on each new MR. GitHub pull requests get no labels. | [] |
reviewers_hint | Text in the MR description that names the reviewer to ask. The plugin does not assign reviewers. | "" |
merge_profile | The validation profile of the CI gate. If the model fails it, em-change opens a draft MR. | strict |
draft_profile | The profile of em-view and em-validate when you name no profile. | workshop |
canonical_url | The Pages URL where CI publishes the diagram of the default branch. | "" |
team_artifact_url | The shared Claude artifact that shows the default branch. em-sync publishes to it. | "" |
GitLab CI
Add this include to .gitlab-ci.yml:
Set the merge method to "Fast-forward merge" and turn on "Pipelines must succeed". The job emhcl-validate validates with merge_profile. The job pages publishes the default branch to GitLab Pages.
GitHub Actions
Add this workflow as .github/workflows/model.yml:
On the default branch, require the status check model / emhcl-validate and a linear history.
Diagrams
GitLab Pages or GitHub Pages shows the canonical diagram of the default branch. em-change and em-review publish one proposal diagram for each MR. The title of each diagram names the branch and the short commit SHA.
If the app can publish artifacts, each new artifact is private. To give access to other people, use the Share button on its page. If the app cannot publish artifacts, the procedure returns the HTML file that emhcl diagram wrote. That file has no shared URL.
Language changes go to the specification and to emhcl, not to the plugin.