From b2f7d5d56ef751e65d65e471a80ef2d5f7726c7e Mon Sep 17 00:00:00 2001 From: r Date: Fri, 25 Sep 2026 12:56:54 +0000 Subject: [PATCH] skills: Mendix best-practices index, microflow tiers and split-first, mxcli layout finding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - skills/mendix-best-practices-index.md (new): one row per best-practice area — Mendix docs page (17 URLs verified 2026-09-25), bundled assess-quality section, toolkit skill before the write, mxcli lint rule after exec. Index, not a copy. - skills/microflow-preflight.md: Simple / Guided / Split-first tiers decided before any MDL; Split-first posts an orchestrator + SUB_ plan the user confirms first. Records that mxcli layout (v0.24.0, upstream main) arranges domain models only. - agents/mdl-agent.md: never hand back "too difficult" — hand back the split plan; escalate one failing SUB_ after one retry, never the whole script. - bug-logs: the mxcli team's layout-command response on the if-branch overlap draft. - Routing row (all agents, stages 3/5/6, reference) and re-rendered surfaces. Field evidence: mxcli layout --dry-run on a scratch copy of a PoC model (v0.24.0, Mendix 11.12.1): 10 entity moves, no microflow; render-routing --check clean. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw --- CHANGELOG.md | 2 + README.md | 1 + ROUTING.md | 1 + agents/architect-agent.md | 1 + agents/ba-agent.md | 1 + agents/gate-agent.md | 1 + agents/mdl-agent.md | 9 +++ agents/review-agent.md | 1 + agents/test-agent.md | 1 + bin/gate-check.sh | 6 +- bin/lib/skill-routing.tsv | 1 + bug-logs/mxcli-bugs.md | 2 + .../layout-merge-in-if-branch.md | 1 + skills/learned-microflow-patterns.md | 1 + skills/mendix-best-practices-index.md | 62 +++++++++++++++++++ skills/microflow-preflight.md | 42 ++++++++++++- 16 files changed, 128 insertions(+), 5 deletions(-) create mode 100644 skills/mendix-best-practices-index.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 480cc18b..e8769051 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ three commits past it), and a bug report can name a release instead of a sha nob Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- new(skills/mendix-best-practices-index.md): **one row per Mendix best-practice area: the Mendix docs page, the bundled `assess-quality` section, the toolkit skill that applies it before the write, and the `mxcli lint` rule that catches it after exec.** An index, not a copy — the practice text stays on the Mendix pages (17 URLs verified HTTP 200 on 2026-09-25) and in the mxcli-bundled skill; Mendix's own Best Practice Recommender rules (MXP001–016) anchor the performance rows, and four rows say out loud that no lint rule exists and the preflight checklist is the only check. Routed `all` agents, stages 3/5/6, group reference — Maurits Visser +- learn(skills/microflow-preflight.md, agents/mdl-agent.md): **a microflow now gets a tier before any MDL — Simple, Guided or Split-first — and Split-first means a posted split plan (thin orchestrator + one `SUB_` per responsibility, with signatures) that the user confirms first.** Prompted by a colleague's session refusing a long microflow as "too difficult" while the same task went through on a stronger model: the piece was too big, not the task. mdl-agent gains two rules — never hand back "too difficult", hand back the split plan; escalate one failing `SUB_` by name after one retry, never the whole script. Also records the mxcli team's answer on positioning: a standalone `mxcli layout` command — which on v0.24.0 and upstream main (2026-09-25) arranges domain models only (`--dry-run` on a scratch copy of a PoC model: 10 entity moves, no microflow), so the no-`@position` rule and the if-branch workaround stand until a microflow mode ships; noted in the bug ledger and `learned-microflow-patterns.md` — Maurits Visser - learn(bug-logs): **`BUG-DRAFT-layout-merge-in-if-branch`** — the v0.24.0 layout engine (upstream #1154) puts the merge node on top of the activity that follows a loop inside an `if` branch, so `mxcli lint` reports MPR008 on a correct script that carries no `@position`; plain if/else and a branch holding only the loop lay out clean. Paste-ready draft in `bug-logs/pending-github-issues/`, NOT YET FILED. Matters to the lint ratchet (#134): an MPR008 whose two elements are a merge and the activity after a loop in an `if` branch is this bug, fixed by the workaround, never by `--update-baseline`. Measured on mxcli v0.24.0, Mendix 11.12.1, scratch copy of a PoC model — Maurits Visser - new(skills/microflow-preflight.md): **a microflow with a loop, a list built from a list, or more than 20 activities now gets a posted checklist before its first MDL line.** Lint runs only after exec. CONV009/QUAL003 count top-level activities only, so 20 activities inside one loop count as 3. Retrieve, REST and Java calls inside a loop have no lint rule at all. The skill maps each Mendix microflow best practice to the rule that catches it afterwards, or marks it "preflight is the only check". It sets the layout rule to "omit `@position`", which upstream now states too, and adds STOP row 25, a baseline routing row and an mdl-agent bullet. It corrects the stale `reset layout` advice (BUG-28), the commit-in-loop cookbook recipe and the 30–50-activity guideline. Field evidence: measured on mxcli v0.24.0 on a scratch copy of a real model — CONV011 on a commit in a loop, MPR008 on partial and 100 px hand placement, MPR011 on negative loop-body coordinates, and a v0.24.0 auto-layout defect where a loop followed by an activity in an `if` branch puts the merge on that activity (MPR008 on a correct script) — Maurits Visser - fix(project-bin/exec.sh): **the lint ratchet now runs after every clean mxbuild, and its verdict lands in the same BUILD-LOG row.** mxbuild proves the model compiles, not how it is built: on a field project a migration microflow shipped three commits inside loops (`mxcli lint` CONV011) under "✅ applied · mxbuild clean", because lint lived only in the gate-agent definition as an optional step and that agent had been spawned 0 times against 21 `exec.sh` runs. `exec.sh` now calls `bin/lint-gate.sh` after a clean build; a rise vs the committed baseline writes `⚠️ applied, LINT ROSE: ` and exits 1 while keeping the write (shape, not corruption), `SKIP_LINT=` is the only override and is recorded in the row, and a project without `lint-gate.sh` gets `lint not installed` rather than a blank cell. `agents/gate-agent.md` and `agents/agent-roles.md` now read the row instead of treating lint as optional; `learned-detection-gaps.md` gains the register row. Field run: a marketplace guest-group migration, 2026-09-24, ~13 s per run on a 10k-finding project — Maurits Visser diff --git a/README.md b/README.md index 3e3932bb..3d1e7ac8 100644 --- a/README.md +++ b/README.md @@ -700,6 +700,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini | Task | Skill to load | |---|---| +| Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | `skills/mendix-best-practices-index.md` | | Working with the Mendix Epics board programmatically — creating/reading stories and epics, updating workflow state, or integrating BRDs with the portal | `skills/mendix-epics-api.md` | diff --git a/ROUTING.md b/ROUTING.md index 5ebad4d3..84529299 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -257,5 +257,6 @@ picks the row up. That is the whole procedure — there is no second list to rem | Always relevant for | Load this | Agent(s) | Stage(s) | Tier | |---|---|---|---|---| +| Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | `skills/mendix-best-practices-index.md` | all | 3,5,6 | ondemand | | Working with the Mendix Epics board programmatically — creating/reading stories and epics, updating workflow state, or integrating BRDs with the portal | `skills/mendix-epics-api.md` | ba,architect | P,0 | ondemand | diff --git a/agents/architect-agent.md b/agents/architect-agent.md index d3be5b8d..b91b31ba 100644 --- a/agents/architect-agent.md +++ b/agents/architect-agent.md @@ -48,6 +48,7 @@ You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you ne | `skills/checkpoints/checkpoint-build.md` | CAC-5, after design sign-off and before the build plan — build order and slice boundaries. Opens with a brainstorm | | `skills/image-transcription.md` | Images to read listed by images-to-md or the documents index — describe each unique picture once, into its own file, before Stage 2 closes | | `skills/small-project-tier.md` | Stage 0 sign-off when the inventory is at or under 1 module / 8 screens / 25 use cases, or the user says the app is small — declare the tier, then apply its per-stage caps and the three artifact waivers | +| `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `project-bin/check-design-portability.sh` | Before porting ds.css into SCSS, and at the Stage-3 gate — greps the stylesheet for rules that cannot match the HTML Mendix emits (rem against the real root, table/th/td selectors, positional row selectors). mx check, mxcli check and mxcli lint are all blind to CSS | | `project-bin/assemble-prototype.js` | After every wireframe edit: assembles design/wireframes/*.html into design/prototype.html, one hash-routed page a stakeholder can click through instead of twenty separate files. Generated, never edited (design-artifacts.md Step 3) | | `project-bin/check-prototype-links.js` | Before wireframes pass to the build loop, and with --brd before a BRD is signed off: dead #/route links, orphan screens, controls with no data-bind and no data-cut, BRD routes no screen has, screens no use case walks (design-artifacts.md Step 3c, brd-validation.md check 8) | diff --git a/agents/ba-agent.md b/agents/ba-agent.md index a64df0a1..4aa7046e 100644 --- a/agents/ba-agent.md +++ b/agents/ba-agent.md @@ -62,6 +62,7 @@ You run discovery and the interview gates for {{PROJECT}}. You never touch the ` | `bin/triage-report.sh` | Rendering a filled triage.md for review — the triage.html surface Stage 0 names. Renders only; the Stage 0 verdict stays with gate-check and the judgement with source-triage.md | | `bin/extraction-report.sh` | Reviewing what the extraction actually produced — the Stage 1 surface, and the file the Stage 1 gate looks for. Renders a code-extracted and a document knowledge base alike, so a requirements-driven project gets the surface too; prints no zero that a second record does not agree with | | `bin/brd-report.sh` | Reviewing what the BRDs actually say — the Stage 2 surface, for BRDs from any source. Reads every knowledge base at once, and keeps a section that is absent-because-not-applicable apart from one that is absent-because-expected | +| `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `skills/bootstrap-project.md` | Generating a new project's CLAUDE.md — baseline routing plus project-specific facts | | `skills/cloud-dev-environment.md` | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | | `skills/existing-app-change.md` | Changing an EXISTING Mendix app — adding a feature, altering a flow, restructuring a module — when it has no BRDs, no architecture doc and no wireframes: the knowledge base comes from the live model (Path D), stages 2–4 run over what changes plus what it touches, nothing more, and the Track B regression baseline is the precondition; audit-only stays in existing-app-assurance | diff --git a/agents/gate-agent.md b/agents/gate-agent.md index 733e4824..da87938b 100644 --- a/agents/gate-agent.md +++ b/agents/gate-agent.md @@ -48,6 +48,7 @@ own bug log before running anything you have not run here before. | `skills/retesting-learned-rules.md` | Before obeying any learned-* STOP or workaround that costs a detour — probe the binary you actually have, then stamp the verdict back into the rule | | `skills/checkpoints/checkpoint-cutover.md` | CAC-6, after Stage 6 passes and before any cutover step — migration mode only, and a hard gate: every answer lands CONFIRMED, no ASSUMED defaults | | `skills/image-transcription.md` | Images to read listed by images-to-md or the documents index — describe each unique picture once, into its own file, before Stage 2 closes | +| `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `project-bin/check-design-portability.sh` | Before porting ds.css into SCSS, and at the Stage-3 gate — greps the stylesheet for rules that cannot match the HTML Mendix emits (rem against the real root, table/th/td selectors, positional row selectors). mx check, mxcli check and mxcli lint are all blind to CSS | | `bug-logs/mxcli-bugs.md` | Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words | | `skills/cloud-dev-environment.md` | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | diff --git a/agents/mdl-agent.md b/agents/mdl-agent.md index f27caf7b..208b63d0 100644 --- a/agents/mdl-agent.md +++ b/agents/mdl-agent.md @@ -63,6 +63,7 @@ a rule below names an asset (e.g. "the wireframe", "the brief"), it means the pa | `skills/retesting-learned-rules.md` | Before obeying any learned-* STOP or workaround that costs a detour — probe the binary you actually have, then stamp the verdict back into the rule | | `skills/checkpoints/checkpoint-build.md` | CAC-5, after design sign-off and before the build plan — build order and slice boundaries. Opens with a brainstorm | | `skills/image-transcription.md` | Images to read listed by images-to-md or the documents index — describe each unique picture once, into its own file, before Stage 2 closes | +| `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `skills/learned-stylegallery.md` | Building or using the in-app design gallery | | `project-bin/check-design-portability.sh` | Before porting ds.css into SCSS, and at the Stage-3 gate — greps the stylesheet for rules that cannot match the HTML Mendix emits (rem against the real root, table/th/td selectors, positional row selectors). mx check, mxcli check and mxcli lint are all blind to CSS | | `bug-logs/mxcli-bugs.md` | Reading a whole class of tool defects (a retest, a new mxcli release, an audit) — for one CE code or symptom use bin/bug-lookup.sh instead; the ledger is 32k words | @@ -139,6 +140,14 @@ this summary. The hard STOPs below are inline on purpose; never route around the hand back the **filled** confirmed JSON pattern from `learned-mcp-patterns.md`, not just the label. - Annotate selectively (`learned-microflow-patterns.md`); always annotate a CE-error fix. - **Loops / long flows — run `microflow-preflight.md`** and post its checklist before the first MDL line; `microflow-preflight: no trigger` otherwise. +- **Never hand a task back as "too difficult".** A microflow that will not come out clean is a piece + that is too big, not a task beyond you: post the `split-first` plan from `microflow-preflight.md` + (orchestrator + one `SUB_` per responsibility, with signatures) and write the pieces the plan + makes Simple or Guided. Silence or a refusal is a failed preflight; the plan is the deliverable. +- **Escalate one piece, once, after one retry.** If a single `SUB_` still fails `mxcli check` after + one rewrite, report that piece by name with the check output and stop on it — the main session + decides whether to rerun it on a stronger model. Do not retry the whole script, and do not + escalate before the split. - **Pages/snippets — run the full pre-flight in `ui-preflight-pages.md`** (wireframe → tokens → gallery reuse → cross-check) and include its UI cross-reference block in your report. **No wireframe → STOP** — do not guess layout or bindings. Reuse existing gallery components; don't reimplement diff --git a/agents/review-agent.md b/agents/review-agent.md index 74b6f508..8caaaed7 100644 --- a/agents/review-agent.md +++ b/agents/review-agent.md @@ -54,6 +54,7 @@ protects: you have no Write or Edit tool, and you never run `mxcli exec`. | `skills/teamserver-alignment.md` | Any session that will push a model to Mendix Team Server, and BEFORE telling the user a Team Server push is blocked — which remote is authoritative, settle-then-push order, and the four checks that have to fail first | | `skills/retesting-learned-rules.md` | Before obeying any learned-* STOP or workaround that costs a detour — probe the binary you actually have, then stamp the verdict back into the rule | | `skills/image-transcription.md` | Images to read listed by images-to-md or the documents index — describe each unique picture once, into its own file, before Stage 2 closes | +| `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `project-bin/assemble-prototype.js` | After every wireframe edit: assembles design/wireframes/*.html into design/prototype.html, one hash-routed page a stakeholder can click through instead of twenty separate files. Generated, never edited (design-artifacts.md Step 3) | | `project-bin/check-prototype-links.js` | Before wireframes pass to the build loop, and with --brd before a BRD is signed off: dead #/route links, orphan screens, controls with no data-bind and no data-cut, BRD routes no screen has, screens no use case walks (design-artifacts.md Step 3c, brd-validation.md check 8) | | `skills/cloud-dev-environment.md` | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | diff --git a/agents/test-agent.md b/agents/test-agent.md index 4d83c47f..30eedbb0 100644 --- a/agents/test-agent.md +++ b/agents/test-agent.md @@ -39,6 +39,7 @@ and `"DESCRIBE ..."` reads are always fine, and are how you ground every name yo | `skills/retesting-learned-rules.md` | Before obeying any learned-* STOP or workaround that costs a detour — probe the binary you actually have, then stamp the verdict back into the rule | | `skills/checkpoints/checkpoint-cutover.md` | CAC-6, after Stage 6 passes and before any cutover step — migration mode only, and a hard gate: every answer lands CONFIRMED, no ASSUMED defaults | | `skills/image-transcription.md` | Images to read listed by images-to-md or the documents index — describe each unique picture once, into its own file, before Stage 2 closes | +| `skills/mendix-best-practices-index.md` | Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec | | `skills/cloud-dev-environment.md` | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | | `skills/existing-app-assurance.md` | Auditing or regression/e2e-testing an EXISTING app — no intake, no stages, no gates | | `skills/mendix-agent-setup.md` | Standing up a project's GenAI agents in any environment — MxCloud key import, model-to-agent binding, KB indexing and the agent-answers-a-question proof are all UI-only (no MDL/SQL path), driven with Playwright; you need the resource keys handed to you as env vars first | diff --git a/bin/gate-check.sh b/bin/gate-check.sh index dc7fe195..5e24d451 100755 --- a/bin/gate-check.sh +++ b/bin/gate-check.sh @@ -1607,10 +1607,10 @@ stage_protocol_paths() { 0) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-scope.md skills/source-triage.md skills/image-transcription.md skills/small-project-tier.md skills/existing-app-change.md skills/app-analysis.md skills/layering-review.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/assess-migration.md skills/migration-pipeline.md skills/migrate-general.md skills/migrate-outsystems.md skills/source-os11.md skills/os-xml-schema.md skills/source-node-express-react.md skills/document-discovery.md skills/extractor-quality-loop.md skills/qa-loop-goal-pattern.md skills/mendix-epics-api.md skills/corpus-extraction-integrity.md skills/gate-check-file-locations.md" ;; 1) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-extraction.md skills/image-transcription.md skills/small-project-tier.md skills/migration-pipeline.md skills/source-os11.md skills/os-xml-schema.md skills/source-node-express-react.md skills/document-discovery.md skills/extractor-quality-loop.md skills/kb-generation.md skills/corpus-extraction-integrity.md" ;; 2) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-brd.md skills/checkpoints/checkpoint-architecture.md skills/image-transcription.md skills/small-project-tier.md skills/kb-generation.md skills/brd-generation.md skills/brd-validation.md" ;; - 3) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/small-project-tier.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;; + 3) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-design.md skills/small-project-tier.md skills/mendix-best-practices-index.md skills/layering-review.md skills/architecture-blueprint.md skills/modularize-domain.md skills/design-artifacts.md skills/brd-to-build-plan.md skills/workflow-structure-rules.md skills/learned-mdl-cannot-express.md" ;; 4) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-build.md skills/agent-roles.md skills/small-project-tier.md skills/module-brief.md skills/module-folder-convention.md skills/brd-to-build-plan.md skills/coverage-ledger.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/learned-constants-and-secrets.md" ;; - 5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/learned-mcp-patterns.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; - 6) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; + 5|build-ready) echo "skills/interview-protocol.md skills/grill-mode.md skills/agent-roles.md skills/module-brief.md skills/learned-mdl-preflight.md skills/module-folder-convention.md skills/learned-microflow-patterns.md skills/microflow-preflight.md skills/mendix-best-practices-index.md skills/ui-preflight-pages.md skills/design-spacing.md skills/learned-stylegallery.md skills/ui-loop.md skills/learned-mcp-patterns.md skills/module-review.md skills/testing-shape.md skills/microflow-loop-antipatterns.md skills/iterative-build-loop.md skills/mdl-cookbook-microflows.md skills/build/mdl/oneshot-mdl-method.md skills/learned-page-patterns.md skills/oneshot-page-structure-patterns.md skills/mendix-agents.md skills/mendix-agent-ui.md skills/mendix-agent-setup.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/learned-workflow-patterns.md skills/workflow-structure-rules.md skills/rest-integration-first-time-right.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/learned-sidebar-collapse-icons.md skills/learned-popup-navigation.md skills/learned-datagrid-customcontent-binding.md skills/learned-popup-feedback-pattern.md skills/learned-mdl-cannot-express.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-dg2-patterns.md skills/security-is-not-a-later-script.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/preview-over-hub-tunnel.md skills/walking-skeleton.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; + 6) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/mendix-best-practices-index.md skills/module-review.md skills/testing-shape.md skills/existing-app-assurance.md skills/app-analysis.md skills/module-dependency-review.md skills/microflow-loop-antipatterns.md skills/qa-loop-goal-pattern.md skills/mendix-agent-setup.md skills/e2e-harness-base.md skills/learned-db-assertions.md skills/fixture-seeding.md skills/journey-proof.md skills/monkey-test.md skills/learned-skill-ux-audit.md skills/learned-skill-scope-delta.md skills/report-schema.md skills/harness-architecture.md skills/process-coherence-pass.md skills/e2e-evidence-report.md skills/record-demo-video.md skills/share-demo-package.md skills/lint-that-actually-runs.md skills/improvement-register.md skills/journey-examples.md skills/wiring-sweep.md skills/workflow-structure-rules.md skills/bug-submission-checklist.md skills/empty-widget-triage.md skills/anonymize-client-app-for-demo.md skills/learned-css-that-never-applied.md skills/learned-detection-gaps.md skills/learned-local-db-confusion.md skills/full-harness-audit.md skills/test-result-audit.md skills/finding-disposition.md skills/handoff-to-studio-pro.md skills/preview-over-hub-tunnel.md skills/platform-link.md skills/teamserver-alignment.md skills/learned-constants-and-secrets.md" ;; 7) echo "skills/interview-protocol.md skills/grill-mode.md skills/checkpoints/checkpoint-template.md skills/checkpoints/checkpoint-cutover.md skills/close-the-loop.md skills/share-demo-package.md skills/handoff-to-studio-pro.md skills/platform-link.md skills/teamserver-alignment.md skills/deploy-to-sandbox.md" ;; *) echo "" ;; # diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv index ce38ff62..f77eaf32 100644 --- a/bin/lib/skill-routing.tsv +++ b/bin/lib/skill-routing.tsv @@ -94,6 +94,7 @@ learned-mdl-preflight skills/learned-mdl-preflight.md Writing ANY MDL script — module-folder-convention skills/module-folder-convention.md Placing any document in a module — before the first `create`. Feature group, then Pages/Microflows/Services/Resources; the path comes from the brief's folder plan, and the table says which types mxcli can actually place architect,mdl 4,5 baseline architecture learned-microflow-patterns skills/learned-microflow-patterns.md Writing or fixing any microflow — MDL gotchas plus annotation discipline mdl 5 baseline build/mdl microflow-preflight skills/microflow-preflight.md Writing a microflow with any loop, a retrieve/commit/call inside a loop, nested or multiple loops, >20 activities counting loop bodies, or a list built from a list — post the checklist before the first MDL line mdl 5 baseline build/mdl +mendix-best-practices-index skills/mendix-best-practices-index.md Asked "is there a Mendix best practice for this", or mapping a lint rule that rose in the ratchet back to the practice and the skill that prevents it — one row per area: Mendix docs page, bundled assess-quality section, toolkit skill before the write, lint rule after exec all 3,5,6 ondemand reference ui-preflight-pages skills/ui-preflight-pages.md Building any page or snippet — before the first widget. Wireframe, tokens, gallery reuse, cross-check; no wireframe means STOP mdl 5 baseline design design-spacing skills/design-spacing.md Writing or reviewing any page or snippet — the spacing scale (8/16/24/32/48), section rhythm, and the page-header scaffold every full page starts with; sections at 0px apart and pages with no H1 are the defects it retires mdl,review 5 baseline design learned-stylegallery skills/learned-stylegallery.md Building or using the in-app design gallery mdl 5 ondemand design diff --git a/bug-logs/mxcli-bugs.md b/bug-logs/mxcli-bugs.md index 9cce60b6..7962dde1 100644 --- a/bug-logs/mxcli-bugs.md +++ b/bug-logs/mxcli-bugs.md @@ -5689,6 +5689,8 @@ Probe: `mxcli init --tool claude` (v0.22.0) into an empty directory. The generat > **NOT YET FILED** — paste-ready draft in `bug-logs/pending-github-issues/layout-merge-in-if-branch.md`. +> **mxcli team response (2026-09-25):** positioning is meant to be handled by a standalone `mxcli layout` command, not by `create microflow`. On v0.24.0 and upstream `main` at that date the command arranges **domain models only** (`mxcli layout --help`: "Arrange the entities of a domain model"; `--dry-run` on a scratch copy of a PoC model listed 10 entity moves, no microflow). Re-probe `mxcli layout --help` on each release; until a microflow mode ships, the workaround above stands. + **Discovered:** 2026-09-25, measuring the rewritten v0.24.0 layout engine (upstream #1154) for `skills/microflow-preflight.md`, on a scratch copy of a small Mendix 11.12.1 PoC model. **Reproducible:** yes, minimal A/B with two controls that lay out clean, on the same copy. diff --git a/bug-logs/pending-github-issues/layout-merge-in-if-branch.md b/bug-logs/pending-github-issues/layout-merge-in-if-branch.md index 9256cbe4..1c7db874 100644 --- a/bug-logs/pending-github-issues/layout-merge-in-if-branch.md +++ b/bug-logs/pending-github-issues/layout-merge-in-if-branch.md @@ -3,6 +3,7 @@ **Status:** NOT YET FILED **Suggested labels:** bug, layout, lint **Duplicate check:** not yet searched (GitHub API unreachable from the session that drafted this) — search `MPR008 merge` and `#1154` before filing. +**Context from the mxcli team (2026-09-25):** microflow positioning is intended for a standalone `mxcli layout` command; on v0.24.0 that command lays out domain models only, so this report still stands. --- diff --git a/skills/learned-microflow-patterns.md b/skills/learned-microflow-patterns.md index 8a25e7e5..8d42d6fa 100644 --- a/skills/learned-microflow-patterns.md +++ b/skills/learned-microflow-patterns.md @@ -400,6 +400,7 @@ end; - **LESSON-04 — `retrieve $X from $obj/Assoc limit 1` → CE0018 + CE0136 (mxcli BUG):** mxcli generates a "Retrieve by Association" BSON activity with empty `Association` and `Entity` properties. Mendix rejects these with CE0018 ("Association property required") and CE0136 ("Entity property required"). **Fix:** replace with XPath DB retrieve: `retrieve $X from Module.Entity where [AssocPath/Module.Entity/Attr = $var] limit 1;`. **Pre-flight before using XPath:** (1) target entity is persistent (not an NPE), (2) all entities in the XPath path are persistent, (3) all objects being filtered on are committed to the DB — XPath queries the database, not in-memory objects. If any condition fails, use a different approach (pass as parameter, loop retrieve, etc.). - **Microflow canvas layout — omit layout annotations (LESSON-01+02, corrected 2026-09-25):** - **Rule:** write no `@position` at all; mxcli's auto-layout places every statement (start, merges and ends included — `@start`/`@merge` exist and `describe` emits them). Partial hand placement is what breaks: auto-placed neighbours are not measured against hand-placed ones (MPR008/MPR011). If repairing a described flow by hand, annotate every canvas statement or none. + - **`mxcli layout` (v0.24.0) arranges domain models only** — the mxcli team's intended home for auto-positioning, but no microflow mode exists yet on v0.24.0 or upstream main (2026-09-25). Probe `mxcli layout --help` on your binary before relying on it for a flow. - **`reset layout` is a parse error** (`mismatched input 'RESET'`, still on v0.24.0) — BUG-28: never implemented upstream. Never write it. Measurements and the v0.24.0 if-branch defect: `microflow-preflight.md`. - **If/else branch geometry (for future reference when @position is fixed):** true branch (abort) → X > decision, Y < decision (goes up); false branch (main path) → X > decision, Y > decision (goes down). Both branches must have X > the decision diamond's X. diff --git a/skills/mendix-best-practices-index.md b/skills/mendix-best-practices-index.md new file mode 100644 index 00000000..417addde --- /dev/null +++ b/skills/mendix-best-practices-index.md @@ -0,0 +1,62 @@ +# Mendix Best-Practices Index — Where Each Practice Lives, Before and After the Write +**Applies to:** any mxcli project. + +**Purpose:** Answer "is there a Mendix best practice for this, and what enforces it here?" with +one row, not a search. Each row names the Mendix page that states the practice, the section of +the mxcli-bundled `assess-quality` skill that summarises it, the toolkit skill that applies it +**before** the MDL is written, and the `mxcli lint` rule that catches it **after** exec. +This file is an index, never a copy: the practice text stays on the Mendix page and in the +bundled skill (`CLAUDE.md` authoring rule 5). URLs verified 2026-09-25, all HTTP 200. + +--- + +## How to use it + +1. **Before writing** — find the row for the thing you are about to build. Open the toolkit + skill in that row. If the row says "no toolkit skill", read the Mendix page itself. +2. **After exec** — the lint ratchet's BUILD-LOG cell lists the rules that rose. Look each rule + up here to find the practice behind it and the skill that would have prevented it. +3. **When a question has no row** — say so in chat and read the Mendix page under + `Development Best Practices`. Do not answer from memory; add the row afterwards. + +## The index + +Lint IDs are those `mxcli lint --list-rules` prints on v0.24.0. `MXP` numbers are Mendix's +own Best Practice Recommender rules, which Studio Pro also reports. + +| Area | Mendix source (states the practice) | Bundled `assess-quality` | Toolkit skill — before the write | `mxcli lint` — after exec | +|---|---|---|---|---| +| Naming: prefixes, entities, pages, enums, booleans | [Development Best Practices](https://docs.mendix.com/refguide/dev-best-practices/) → App Setup Best Practices | §A Naming Conventions | `learned-mdl-preflight.md` (names are fixed before the first line) | MPR001, CONV001, CONV003, CONV004, CONV005, CUSTOM002 | +| Microflow size and single responsibility | [Extracting and Using Sub-Microflows](https://docs.mendix.com/refguide/extracting-and-using-sub-microflows/) | §D Maintainability | `microflow-preflight.md` (tiers, split-first) | CONV009 (15, top-level), QUAL003 (25, top-level), QUAL001 (McCabe 10) | +| Commit and create inside a loop | [Best Practice Recommender](https://docs.mendix.com/refguide/performance-best-practices/) MXP004, MXP005, MXP012 | §E Performance | `microflow-preflight.md`, `mdl-cookbook-microflows.md` (collect-then-commit) | CONV011 | +| Retrieve, REST or Java call inside a loop | [Community Best Practices for App Performance](https://docs.mendix.com/refguide/community-best-practices-for-app-performance/) → Microflow | §E Performance | `microflow-preflight.md`, `microflow-loop-antipatterns.md` | **none** — the preflight checklist is the only check | +| Bounded lists, batching | [Community Best Practices for App Performance](https://docs.mendix.com/refguide/community-best-practices-for-app-performance/) → Microflow | §E Performance | `microflow-preflight.md` | **none** (`mxcli check` MDL068 catches an unbounded `range` only) | +| Writes late in the flow, one commit | [Best Practice Recommender](https://docs.mendix.com/refguide/performance-best-practices/) MXP014 | §E Performance | `microflow-preflight.md` | none | +| Error handling on external calls | [Error Handling in Microflows](https://docs.mendix.com/refguide/error-handling-in-microflows/) | §G Error Handling | `learned-microflow-patterns.md` (no `on error` inside a loop body, CE0644), `rest-integration-first-time-right.md` | CONV013, CONV014 | +| Validation in `VAL_` flows, not entity rules | [Setting Up Data Validation](https://docs.mendix.com/refguide/setting-up-data-validation/), [Validation Rules](https://docs.mendix.com/refguide/validation-rules/) | §D Maintainability | `mdl-cookbook-microflows.md` | CONV015, MPR004 | +| Event handlers and calculated attributes | [Best Practice Recommender](https://docs.mendix.com/refguide/performance-best-practices/) MXP001, MXP002 | §E Performance | `modularize-domain.md` | CONV016, CONV017 | +| Entity access rules and XPath row scoping | [Access Rules](https://docs.mendix.com/refguide/access-rules/), [Implement Best Practices for App Security](https://docs.mendix.com/howto/security/best-practices-security/) | §C Security | `security-is-not-a-later-script.md` | SEC001, SEC004–SEC009, CONV006, CONV007, CONV008 | +| Indexes for sort and XPath attributes | [Indexes](https://docs.mendix.com/refguide/indexes/), Recommender MXP003, MXP007, MXP016 | §E Performance | `modularize-domain.md` | none | +| Module boundaries, cross-module data on pages | [Community Best Practices for App Performance](https://docs.mendix.com/refguide/community-best-practices-for-app-performance/) → Domain Model | §F Architecture | `modularize-domain.md`, `module-dependency-review.md` | ARCH001, ARCH002, ARCH003, MPR003, DESIGN001 | +| Pages: nesting, grids, forms | [Community Best Practices for App Performance](https://docs.mendix.com/refguide/community-best-practices-for-app-performance/) → Pages, Recommender MXP011 | §I UI Best Practices | `ui-preflight-pages.md`, `learned-dg2-patterns.md`, `learned-page-patterns.md` | MPR005, MPR006, MPR009, MPR010, MPR012 | +| Navigation page security | [Access Rules](https://docs.mendix.com/refguide/access-rules/) | §C Security | `security-is-not-a-later-script.md` | MPR007 | +| Documentation on entities and microflows | [Development Best Practices](https://docs.mendix.com/refguide/dev-best-practices/) | §D Maintainability | `learned-microflow-patterns.md` (annotation discipline) | QUAL002 | +| Microflow canvas layout | [Extracting and Using Sub-Microflows](https://docs.mendix.com/refguide/extracting-and-using-sub-microflows/) (readability) | — | `microflow-preflight.md` → Layout | MPR008, MPR011 | +| Testing | [Testing](https://docs.mendix.com/refguide/testing/) | — | `testing-shape.md`, `learned-db-assertions.md` | none | + +## What is not here, on purpose + +- **The practice text.** Mendix edits these pages; a copy here would be stale within a release. +- **A quality score.** `mxcli report -p app.mpr` scores six categories from the same rules; the + bundled `assess-quality` skill is the full assessment method (`skills/existing-app-assurance.md` + routes there). +- **Rules the binary does not ship.** CUSTOM001/CUSTOM002 and the `example_*` rules come from a + project's `.claude/lint-rules/`; list your own with `mxcli lint -p app.mpr --list-rules`. +- **A knowledge graph of the docs.** The consumer of this file is an agent mid-task; a table + gives it the same routing at no maintenance cost. + +## Keeping it true + +A row is wrong the day a URL 404s or a rule ID is renamed. When you find one: fix the row in the +same commit as the change that surfaced it, and re-check the URL with `curl -sI`. A rule that +rises in the ratchet and has no row here gets a row. diff --git a/skills/microflow-preflight.md b/skills/microflow-preflight.md index 47bc6d40..d743d941 100644 --- a/skills/microflow-preflight.md +++ b/skills/microflow-preflight.md @@ -9,7 +9,34 @@ the advice is the same. --- -## Trigger — run this if ANY of these hold for the microflow you are about to write +## Tier first — Simple, Guided or Split-first + +Decide the tier from the plan, before any MDL. Post the tier with the checklist. + +| Tier | Holds when | What you do | +|---|---|---| +| **Simple** | Linear flow, ≤ 10 activities, no loop, no REST/Java/web-service call, one entity | Post `microflow-preflight: no trigger` and write it | +| **Guided** | Any trigger in the list below, and ≤ 20 activities counting loop bodies, one loop at most | Post the checklist, write it as one flow | +| **Split-first** | More than 20 activities counting loop bodies, or two or more loops, or a nested loop, or a list built from a list, or a REST/Java call inside a loop | Post the checklist **and the split plan** below; the user confirms the plan before the first MDL line | + +**The split plan** is a thin orchestrator plus one `SUB_` per responsibility, each with its +signature, posted in chat: + +``` +split-first: +- ACT_Orchestrator ($Order: Sales.Order) → calls the SUB_s below, shows the page, nothing else +- SUB_RetrieveLines ($Order) returns List of Sales.OrderLine — one retrieve, no loop +- SUB_PriceLines ($Lines) returns List of Sales.OrderLine — the loop; collects into OrderLine_CommitList +- SUB_CommitLines ($Lines) — one commit, on error rollback +Each SUB_ ≤ 15 top-level activities, ≤ 1 loop. +``` + +Why split-first exists: a colleague's session refused a long microflow as "too difficult" and +the same task went through on a stronger model. The task was not hard, the piece was too big. +A `SUB_` per responsibility is what the size table asks for anyway, and each piece is a Simple +or Guided flow that any model writes. + +## Trigger — Guided or Split-first if ANY of these hold 1. It has **any loop** (`loop … in`, or `while`). 2. A **retrieve, commit, delete, REST call, Java action or sub-microflow call** is planned inside a loop. @@ -26,7 +53,7 @@ None applies → post `microflow-preflight: no trigger` in chat and proceed. ## The checklist — post it in chat before the first MDL line ``` -microflow-preflight: +microflow-preflight: — tier: Simple | Guided | Split-first - Loops: N. Per loop: retrieve y/n · commit/delete y/n · call y/n · batch strategy · expected list size - Retrieves inside loops: 0 (else: moved before the loop, find/filter inside) - Commits/deletes inside loops: 0 — collected into _CommitList, one commit after the loop @@ -93,6 +120,16 @@ coordinates are relative to the loop box's top-left corner; n = activities in th | Next activity after the loop | loop centre + 80·n + 180 | | Sequential pitch | 160 | +**`mxcli layout` is a domain-model command.** The mxcli team's answer to microflow +positioning (2026-09-25) is a standalone layout command rather than anything in `create +microflow`. On v0.24.0 and on upstream `main` at that date, `mxcli layout --help` says +*"Arrange the entities of a domain model"*; it moves entities only, and there is no microflow or +nanoflow mode yet. Measured: `mxcli layout -p app.mpr --dry-run` on a scratch copy of a PoC +model listed 10 entity moves and no microflow. **Before relying on it for a microflow, probe +your binary:** `mxcli layout --help` — the capability-probe rule. Until a microflow mode ships, +the remedy for a bad microflow layout stays the one in this file: no `@position`, and the +`SUB_` split for the defect below. + **`RESET LAYOUT` does not parse** on v0.24.0: `mismatched input 'RESET'` (BUG-28, never implemented upstream). Never write it. If you have to repair a flow by hand, annotate **every** canvas statement or none. @@ -135,3 +172,4 @@ clean row proves only the rows lint covers. The checklist is the record for the - Whether a `/** … */` doc comment round-trips into the microflow's Documentation. - Nanoflow-vs-microflow guidance. No current Mendix docs page was found. - Whether upstream fixes the if-branch merge overlap in a later release. +- Whether a later `mxcli layout` release re-lays-out microflows, and whether that run clears the if-branch merge overlap. Re-probe `mxcli layout --help` on each new binary.