Add AI Skills for OIE plugin development and code review#2
Open
MichaelLeeHobbs wants to merge 4 commits into
Open
Add AI Skills for OIE plugin development and code review#2MichaelLeeHobbs wants to merge 4 commits into
MichaelLeeHobbs wants to merge 4 commits into
Conversation
Three SKILL.md-format skills to help AI coding agents build and review OIE plugins and channels: - oie-plugin-development — build a plugin end to end: Maven layout, plugin.xml, server/client/shared classes, REST servlets, DB migrations, packaging & signing, plus a dedicated reference for source/destination connectors (subclassing a stock connector, Administrator-panel styling, live testing, and staying compatible with TLS plugins via the protocol-keyed TcpConfiguration hook). - oie-plugin-code-review — review Java/plugin code: smells, thread/resource safety, JDBC & migrations, security/PHI, plugin lifecycle, tests. - oie-channel-code-review — review channel/template JavaScript on the Rhino runtime: block-scoping traps, E4X/HL7 field access, scope-map lifetime, per-message cost, PHI in logs. Adapted from @pacmano1's OIE Plugin Development Guide and "Irritable Developer Check" review checklist (reorganized into the skill format), plus field notes from building an OIE connector.
There was a problem hiding this comment.
Pull request overview
Adds a new AI Skills/ documentation area containing SKILL.md-format “skills” intended to guide contributors (and AI agents) in developing OIE/Mirth plugins and reviewing plugin Java and channel/template Rhino JavaScript.
Changes:
- Introduces a top-level index (
AI Skills/README.md) describing available skills and installation. - Adds an end-to-end plugin development skill with topic-split reference docs (Maven layout,
plugin.xml, REST, DB, packaging/signing/XStream, connector specifics). - Adds two review skills: one for Java/plugin code review and one for Rhino channel/template JavaScript review.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| AI Skills/README.md | Adds an entrypoint/index for the skills and basic install guidance. |
| AI Skills/oie-plugin-development/SKILL.md | Adds the “plugin development” skill map pointing to detailed reference topics. |
| AI Skills/oie-plugin-development/references/project-structure.md | Documents prerequisites and standard Maven module layout/scaffolding. |
| AI Skills/oie-plugin-development/references/maven-poms.md | Provides example root/module POM patterns and build commands. |
| AI Skills/oie-plugin-development/references/plugin-descriptor.md | Documents plugin.xml structure and key wiring points. |
| AI Skills/oie-plugin-development/references/server-plugin.md | Documents server-side plugin patterns and servlet-based REST API wiring. |
| AI Skills/oie-plugin-development/references/client-and-shared.md | Documents client-side (Administrator) plugin patterns and shared DTO guidance. |
| AI Skills/oie-plugin-development/references/database.md | Documents Migrator + iBATIS/MyBatis 2-style mapping patterns. |
| AI Skills/oie-plugin-development/references/packaging-signing-serialization.md | Documents packaging/assembly, signing workflow, and XStream allowlisting. |
| AI Skills/oie-plugin-development/references/gotchas-and-example.md | Captures common pitfalls and a minimal working example outline. |
| AI Skills/oie-plugin-development/references/connector-plugins.md | Adds connector-specific field notes (descriptor wiring, protocol/TLS compatibility, UI styling, live testing). |
| AI Skills/oie-plugin-code-review/SKILL.md | Adds a Java/plugin-focused review checklist skill. |
| AI Skills/oie-channel-code-review/SKILL.md | Adds a Rhino/channel-JS-focused review checklist skill. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+64
to
+65
| - This skill covers **building the plugin**. For JavaScript that runs *inside a channel* (transformers, | ||
| filters, code templates), that's a different context — see an OIE channel/template `AGENTS.md` instead. |
|
|
||
| ### Self-signed dev signing (fast path) | ||
|
|
||
| 1. Generate a self-signed keystore — Mirth requires the proprietary **JKS** format: |
Comment on lines
+207
to
+208
| - Commit the dev keystore (it's a throwaway self-signed cert) so `-Psigning` works out of the box; it is | ||
| **not** a release key. |
Comment on lines
+17
to
+19
| > **Note for review:** the `const`/`let` rule below has been **changed** from the original ("`var` only, | ||
| > never `const`/`let`") to target the *actual* Rhino bug while keeping modern block scoping. Reconcile with | ||
| > pacmano1 before this ships. |
Comment on lines
+48
to
+54
| - **Block scoping inside loops — the one real trap.** Default to `const`/`let` (modern best practice: no | ||
| hoisting surprises, no accidental reassignment). The *forced* exception: Rhino mis-compiles a `const`/`let` | ||
| **declared inside a loop body and reused across iterations** — it hoists the binding to function scope, so | ||
| every iteration silently shares one value, with no error thrown (canonical case: a `while` loop over HTTP | ||
| response headers returned six identical `Date` values). **Flag `const` declared inside a loop body; require | ||
| `let` there** so the per-iteration assignment takes effect. Do **not** flag `const`/`let` at function | ||
| scope, and do **not** rewrite working code to `var` — that discards block-scoping safety to dodge one bug. |
Comment on lines
+57
to
+60
| - **No template literals, `async`/`await`, `Promise`, optional chaining `?.`, nullish `??`, spread, or | ||
| `for...of`** — Rhino's partial ES6. Flag these as runtime-breakers; use `+`/`.join()`, callbacks/retries, | ||
| a `$t(() => …)` try/catch helper, `||`, and indexed/`.forEach()` loops instead. (These are forced | ||
| deviations, not style — see the principle above.) |
Comment on lines
+3
to
+5
| Skills for AI coding agents that read `SKILL.md` files — they help you **build and review** Open | ||
| Integration Engine plugins and channels. Each skill is a folder; a `SKILL.md` holds the instructions and | ||
| (where present) a `references/` folder holds detail loaded on demand. |
- Strengthen the pacmano1 credit in both review skills; drop the "reconcile before this ships" release-gating note (the rule's rationale is stated inline). - Rewrite the Rhino loop block-scoping rule to be internally consistent: const is the real bug (non-reassignable shared binding / redeclaration), let is reassigned per iteration so it's the fix, and closures-in-loops need .forEach(); note that OIE defaults Rhino to ES6 so let/const/arrow work. - Drop the undefined `$t(() => …)` helper reference; recommend plain try/catch. - oie-plugin-development: point channel-JS readers to the companion oie-channel-code-review skill instead of a non-existent AGENTS.md. - Signing ref: call JKS a "legacy Java keystore format" (not "proprietary"); stop recommending committing the keystore — generate locally + gitignore, commit only a public cert if anything. - README: note that the optional frontmatter tool-control keys are ignored by agents that don't use them.
Author
|
Thanks for the review — pushed
|
…ests New field lesson from testing a connector: OIE's POST /api/channels accepts a structurally-incomplete channel without normalizing it, deploys it "healthy", and it partially works — a programmatically serialized channel (base FrameModeProperties instead of MLLPModeProperties, no pluginProperties, queueBufferSize=0) delivers fine with a RAW datatype but sends the literal string "undefined" on the wire with HL7 v2.x. The Administrator normalizes on save. So: build the channel in the Administrator, export it, strip the <list> wrapper + <exportData>, and commit that as the fixture (you can still edit your own connector's properties, e.g. the endpoint list). Also pin the OIE image tag, not :latest.
The engine replaced its Ant build with Gradle (engine 24c96f5, 2026-06-11). Plugin builds are unaffected -- they resolve engine artifacts from a Maven repo -- so make that explicit rather than leaving a stale Ant reference.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
A small set of agent-neutral skills (in the
SKILL.mdformat) underAI Skills/, to help contributorsbuild and review OIE plugins and channels with AI coding agents.
Why
The engine has real, non-obvious conventions — Maven module layout (vs the Ant engine build), the
plugin.xmldescriptor, XStream allowlisting, connector descriptors, code-signing for the AdministratorLauncher, and the Rhino channel-JS quirks. Newcomers (and their AI agents) tend to rediscover these the hard
way. Packaging the knowledge as loadable skills makes it repeatable and reviewable.
Contents
oie-plugin-development/— build a plugin end to end: Maven layout,plugin.xml, server/client/sharedclasses, REST servlets, DB migrations, packaging & signing. Includes a dedicated
references/connector-plugins.mdfor source/destination connectors — subclassing a stock connector,Administrator-panel styling, live testing, and staying compatible with TLS plugins via the protocol-keyed
TcpConfigurationhook.oie-plugin-code-review/— review Java/plugin code: smells, thread/resource safety, JDBC & migrations,security/PHI, plugin lifecycle, tests.
oie-channel-code-review/— review channel/template JavaScript on the Rhino runtime: block-scopingtraps, E4X/HL7 field access, scope-map lifetime, per-message cost, PHI in logs.
The two review skills are deliberately separate because plugin Java and channel JavaScript are different
runtimes with different rules. Each skill is a folder with a
SKILL.md;oie-plugin-developmentalso has areferences/folder loaded on demand.Agent-neutral: references point to
AGENTS.md(no vendor-specific instruction file), and the content isusable by any agent that reads
SKILL.md-format skills. No new build/runtime dependencies — docs only.Credit
Adapted from @pacmano1's OIE Plugin Development Guide and "Irritable Developer Check" review checklist
(reorganized into the skill format), plus field notes from building an OIE connector.
Open to feedback
Happy to relocate/rename the folder (e.g. drop the space in
AI Skills/), split this into smaller PRs, oradjust scope per maintainer preference.