ea-ruleset-author

Logic: AI + AI Power Tools checks. Mostly AI (research and rule design); the validator that tests the result is deterministic.

What it is for

Use it to turn a modeling language's standard into rules the validator can run. You end with a ruleset file for the language, with each rule proven to fail on known-bad content and pass on known-good.

ea-ruleset-author is the workflow for building a complete validation ruleset for one modeling language (ArchiMate, BPMN, UML, SysML, a custom MDG): research the specification, plan rule categories, write the YAML, and test it against a model. The output is a single file named for the language, such as ruleset-<lang>/<lang>_rules.yaml, that the ea_validate audit operation runs.

ea-validation covers the validator call and the syntax of one rule. This skill covers the larger job of deciding what a language's rules are and writing enough of them. The ArchiMate 3.1 ruleset (ArchiMate 3.1 ruleset) is the reference implementation, and the skill tells the AI to read it before starting a ruleset for another language.

A ruleset has two top-level parts: a header (language, version, sources, severity legend) and the rules, one per conformance constraint. The engine reads only the rules.

Capabilities it uses

When to use it, and when not

Use it at the start of a ruleset for another language, and keep it open throughout.

The skill produces the ruleset file. A ruleset of your own runs from a local path, rules written inline, or an HTTPS web address on a host you control; see ea-validation.

How it works

The skill is a four-phase workflow, one language at a time.

1. AI Research the language specification. Collect three things before writing a rule: an element-type table (every concept and its structural category), the relationship validity table (which relationship types are allowed between which categories; usually an appendix), and the structural constraints ("a Collaboration must have at least two members"). Cite the specification sections for later use. The skill lists primary sources per language: ArchiMate 3.1 from The Open Group (with the relationship appendix), BPMN 2.0, UML 2.5.1 and SysML 1.6 from OMG; for a custom MDG, the MDG file itself.

2. (AI, you review) Plan rule categories. Group the rules into named categories first, which fixes the id scheme. The suggested scheme, to be adapted:

   Code	Covers	Selector
   REL	Relationship endpoint validity	Connector
   COL	Collaboration or group membership	Element with a connector count
   INT	Interaction assigned to a collaboration	Element with a connector count
   WFR	Well-formedness completeness (orphan checks)	Element with a connector count
   IMP	Special layer or migration structures	Element or connector
   CLR	Cross-layer endpoint patterns	Connector

   Not every language needs every category; BPMN might use SEQ, GWY and EVT. Ids take the form {LANG}-{CAT}-{NNN} with three-digit numbers (AM31-REL-001; for a custom MDG, WBA-TV-002). About 30% of rules are marked as demonstration triggers: those that cover the highest-volume element types and the most common mistakes, and together give a meaningful signal quickly.

3. AI Write the YAML. File and directory names are lowercase, with hyphens in the directory and underscores in the file (ruleset-bpmn2/bpmn2_rules.yaml).

4. (AI Power Tools runs, AI chooses and reads the tests) Test. The validator runs the file; the AI designs the tests (see Testing approach).

Rule grammar, summarized. The header records the language and version, the organization, a family identifier for the technology, a one-paragraph description and the severity legend, with sources in a header comment. Each rule has an id, a name, a description (why it exists, which specification section it comes from, and what a violation means architecturally; cite sources), a category, a severity, a demonstration flag, a selector, a condition and a remediation.

The engine uses the id, the severity (default error), the demonstration flag, the selector, the condition and the remediation sentence. The name, description, category and "auto-fixable" flag are for human readers and are ignored at run time.

Endpoint rules are the most powerful type. List all valid source stereotypes, then all valid targets, erring toward inclusion because EA's MDG may carry inherited subtypes the author does not know about. Severity is error: endpoint violations are structural. Both lists apply to every connector the selector picks.

Count rules. Incoming counts connectors that end at the element (the element is the target); outgoing counts connectors that start there. Draw the arrow in your head before deciding.

Stereotype names: unqualified, but otherwise exactly as EA stores them, measured against a real model. The engine compares exact strings. Leave the technology namespace off (ArchiMate3::...), but do not remove a prefix that is part of the stereotype's own name:

Both were measured on EA 17.1 build 1716. Do not take the name from a specification or from the MDG's display-name attribute (the concept name without the prefix, which is precisely the trap). Ask for the stereotype usage summary, or the distinct stereotypes, against a model built with the technology. Zero violations and zero matched elements look identical; confirm a ruleset matched more than zero elements before calling a model clean.

Other grammar notes from the skill.

• Over-specifying targets on cross-layer rules is a trap: for broad relationship types such as Association, check the source only and leave the other end unrestricted, rather than enumerating dozens of stereotypes.
• Quote a stereotype name in YAML when it contains :, # or &; plain names work either way.
• Use section-header comments to group rules.
• The header is not validated. Always include it and cite sources.

Testing approach. The skill gives three tests. Each is described here with what it actually proves.

1. Zero violations on a clean, known-good model. Run the file against a model that does not use the language's stereotypes, or a conformant one, and expect no violations. If a model that should violate returns violations, or one that should match returns none, compare the stereotype names in the YAML with what EA stores (read one element or connector, or ask for the stored stereotype). This test alone cannot detect a ruleset that selects nothing, because both outcomes read as zero.
2. Fetching by web address works. Once the file is hosted at an HTTPS address, run the audit by address and expect success and a rules-evaluated count equal to the rule count. A fetch failure means the file is not reachable at that address yet; wait until the host serves the raw file in a browser before sharing the link.
3. Rules fire on intentional violations (recommended). Build a scratch package with deliberate violations (an Assignment connector from a data object to a process is a clear endpoint error), run the audit, and verify that exactly the expected rules report. Two cautions: a package scope limits only element rules, while connector rules and connector counts look at the whole model, so an unscoped connector rule can report violations outside the scratch package; and a rule that reports nothing here is evidence it cannot fire.

The shipped ArchiMate 3.1 ruleset adds a fourth approach: a hermetic test that replays the validator's selection against an in-memory copy of the element and connector tables, built from stereotype names measured on a real EA, and fails if any rule selects nothing, if endpoint lists name stereotypes no element can carry, or if the ruleset starts matching elements of other notations. EA is never started. See ArchiMate 3.1 ruleset.

What you get

• A single ruleset file for one language: a header with sources, and rules grouped into named categories with stable ids and cited descriptions.
• A planned set of demonstration triggers (about 30%).
• Test evidence: the file evaluates the expected number of rules, every selector matches candidates, and planted violations are caught by the expected rules and no others.

Tools it relies on

• ea_validate audit, to run the ruleset in tests 1 to 3: ea_validate
• summarize_stereotype_usage, execute_sql, to measure stored stereotype names and count candidates: Summaries, Direct queries
• get_element, get_connector, to read the raw stereotype of one object: Elements, Connectors
• create_element, create_connector, to build the scratch package of deliberate violations: Elements, Connectors
• ea-validation, the syntax and run reference
• ArchiMate 3.1 ruleset, the reference implementation

Sample prompts

1. "Read the ArchiMate 3.1 ruleset and summarize how its rules are organized. I want to build one for our own WBA technology."
2. "Plan a ruleset for the Westbrook Bank technology: categories, id scheme, and which rules should be demonstration triggers. Show me the plan before writing YAML."
3. "Write the tagged-value and endpoint rules for WBA from the stereotypes and tags in its MDG, then test them."
4. "I wrote a ruleset and it says zero violations on a model I know is bad. Debug it."
5. "Write the BPMN 2.0 sequence-flow and gateway rules, citing the spec tables."

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks.

Checking accuracy and completeness

1. Every selector matches something in a model built with the technology. Count candidates with a read-only query on the stored stereotype (elements, or connectors). Red flag: any rule with zero candidates.
2. Every endpoint name exists. Each name in the allowed-source and allowed-target lists is a stereotype EA stores for that technology. A wrong name makes every connector of that type a violation.
3. Planted violations are caught, each by the expected rule and no others.
4. Coverage against the specification. Each relationship type in the specification's validity table has a rule, or is recorded as deliberately omitted; every structural constraint noted in phase 1 has a rule.
5. No false positives on a model known to conform. Review each reported violation on a clean model and explain it.
6. The rule count matches. Rules evaluated equals the number of rules in the file, and the demonstration subset is about 30%.
7. Citations resolve. Each description cites a specification section that says what it claims.
8. A run by web address equals a local run, when the file is hosted.

Limitations

• Five condition types, each bound to one selector type. A rule cannot be made conditional on another property (a rule that applies only when another property holds); one that needs a conditional is written as a check on every connector the selector picks. The shipped ArchiMate set shows the consequence; see ArchiMate 3.1 ruleset.
• Selectors match exact stored strings and one stereotype per element.
• A package scope covers element rules only, so planted-violation tests for connector rules see the whole model.
• Test 1 assumes a model that does not use the language's stereotypes, which makes zero violations the expected result and therefore proves little. Use test 3 and the candidate counts.
• You author the ruleset for any other language with this skill. The ArchiMate 3.1 ruleset is the shipped example.