mx-entity-add

name

mx-entity-add

description

GATED WRITE. Add a new entity (or attribute on an existing entity, or association) to a Mendix project by wrapping mxcli's create commands with the 8 safety pillars. Hard precondition: a fresh /mx-discover inventory must exist (≤24h old) so we can verify the new name doesn't collide. Pre-tag, clean-tree, Studio Pro lock, version, pre/post mx check, auto-restore on fail. Migration risk is flagged before the write. Invocable as /mx-entity-add.

mx-entity-add

Highest-stakes write skill in the suite. Adding entities triggers domain-model migrations that can wipe dev data and lock the project into a one-way schema change. The safety harness is non-negotiable.

North star

Schemas migrate forward, not back. Verify everything before the write.

When to invoke

Auto-invoke when:

• A /mx-feature-spec proposes a new entity / attribute / association AND a /mx-design-review has APPROVED the design.
• Neo explicitly asks to add an entity / attribute / association.

Do not invoke for:

• Renaming existing entities (different operation; not yet supported by a dedicated skill -- talk to Neo).
• Changing an attribute type (use Studio Pro for now; the post-conversion is fragile in mxcli).
• Removing entities / attributes (different operation; needs /mx-impact first to see who breaks).

What it does

The skill is the safety harness. The mxcli call is one line in the middle.

Phase 0 -- Inventory freshness:

0. Inventory check. A /mx-discover inventory must exist for the target module and be <24h old. If not, refuse and tell the parent session to run /mx-discover first. Reason: collision detection (pillar -1 below) requires fresh data.

Phase 1 -- Collision + design-approval gates (additional to the 8 pillars):

A. Naming collision. Cross-check the proposed entity / attribute / association name against the inventory. If any collision exists, refuse. Suggest a non-colliding name. B. Design-review approval. A /mx-design-review verdict of APPROVE for the design containing this entity must exist in conversation history or be linked to a written approval. If only REQUEST CHANGES exists, refuse.

Phase 2 -- Run all 7 safety pillars (from rules/mendix-safety.md). Hard rule: NO git on the Mendix project.

This skill MUST go through the shadow-write engine ~/.claude/lib/Invoke-MendixShadowWrite.ps1. Do not implement the pillars inline; call the engine. The engine enforces:

1. Pillar 1: Studio Pro lock check. Refuse if Studio Pro has the project open. Suggest /close-studio-pro <project>.
2. Pillar 2: Pre-write byte-level snapshot of the .mpr to ~/.claude/backups/<project>/<timestamp>/ (replaces the old git-tag pillar; matches the no-git rule).
3. Pillar 3: Mendix version >= 11.6.
4. Pillar 4: Pre-write mx check clean (zero errors). Captures baseline counts.
5. Pillar 5: Diff preview. For entity / attribute / association writes, mxcli diff reports domain-model changes — use it. Get Neo's explicit confirmation before the engine proceeds.
6. Migration-risk flag (additional gate before the engine applies): Examine the proposed change:
   • New entity? Always triggers a migration -- low risk but log it.
   • New required attribute on existing entity? HIGH RISK -- existing rows need a default value. Refuse unless Neo explicitly provides a default in the spec.
   • New optional attribute? Low risk.
   • New association? Medium risk -- may require data migration on the dependent entity.

Phase 3 -- Apply the write (via shadow-write engine):

7. Engine applies the script-block to the SHADOW .mpr (live untouched):

   Invoke-MendixShadowWrite -ProjectRoot $proj -OperationName 'create-entity' -Script {
     param($ShadowMpr)
     & mxcli create entity <Module.Entity> -p $ShadowMpr [attributes...]
   }
   

8. Pillar 6: Post-write mx check runs against the SHADOW. If error count grows, the engine discards the shadow (live remained untouched).
9. Pillar 7: Atomic swap if shadow validates; otherwise discard.

Phase 4 -- On post-check failure (handled by the engine):

• Engine discards the shadow. Live .mpr is mathematically untouched (no restore needed).
• Catastrophic-only fallback: restore live .mpr from the Pillar 2 snapshot at ~/.claude/backups/....
• Engine logs to ~/.claude/logs/mendix-shadow-write.log and emits the standard failure block.
• Never run any git command to recover.

Phase 5 -- On success:

10. Report (the engine emits this):

## /mx-entity-add: SUCCESS

**Created:** <Module.Entity> (or attribute / association)
**Pillar 2 snapshot (external):** ~/.claude/backups/<project>/<ts>/
**Backup of previous mpr (in-project, sibling file):** <path>.bak.<ts>
**Migration risk:** <classification + brief reason>
**mx check:** <baseline> -> <post> (no regression)
**Next steps:**
- Open Studio Pro and verify the entity in the domain model viewer.
- Wire up access rules in security if not done in the spec.
- Run /mx-impact <new-entity> after wiring to see initial dependents.

Hard rules (additional to the 7 pillars)

• Inventory must be <24h old. Stale inventory = collision detection is unreliable. Refuse otherwise.
• Design review APPROVE required for entity-creating writes. The cost of an entity that shouldn't exist is high.
• New REQUIRED attributes on existing entities require an explicit default in the spec. Otherwise existing rows can't migrate. Refuse otherwise.
• No bulk operations. One entity / attribute / association per invocation. Bulk operations compound risk; do them one at a time.
• Never run git on the Mendix project. Recovery is via shadow-write + Pillar 2 byte-level snapshot. The Pillar 2 snapshot is permanent until Neo deletes it.
• If mxcli's create command produces an error but the .mpr is modified anyway (alpha behavior), trust the post-check (which runs against the SHADOW, so the live remains untouched regardless) -- don't trust mxcli's exit code alone.

Cross-reference

• Safety pillars: ~/.claude/rules/mendix-safety.md.
• Inventory: ~/.claude/skills/mx-discover/SKILL.md.
• Design review: ~/.claude/skills/mx-design-review/SKILL.md.
• Impact (run after a successful add): ~/.claude/skills/mx-impact/SKILL.md.
• Spec primitive: ~/.claude/skills/mx-feature-spec/SKILL.md.