ROUTING.md

Skill routing — the whole table, in one place

Generated. Do not hand-edit the block below. The source of truth is bin/lib/skill-routing.tsv; every routing surface in this repo — this file, the README's two tables, the runbook's baseline block, each agent template, and gate-check.sh's protocol stage map — is rendered from it by bin/render-routing.sh.

edit bin/lib/skill-routing.tsv   →   bin/render-routing.sh   →   review the diff
bin/render-routing.sh --check    →   exit 2 if any surface drifted   (wired into gate-check.sh)

Why this exists. Routing one skill used to take six coordinated edits, plus a seventh copy inside every project's CLAUDE.local.md that no script could reach. Measured on 2026-08-18, before this table: 17 of 43 skills were routed by nothing a project agent reads, bin/facts-lock.sh reached 1 of 6 wired projects, and agent-roles.md and source-triage.md reached 1 each. Adding a skill without adding it here does not fail loudly — it just quietly never reaches anyone, which is why the table is the artifact and the surfaces are output.

Tiers. baseline = always-on; it is written into every project's CLAUDE.local.md (by bin/init-project.sh at scaffold, refreshed in place by bin/sync-project.sh). ondemand = situational; load it when the task calls for it. Keep baseline short — its cost is paid on every session in every project.

Adding a skill: add the file under skills/, add one row here, run the renderer, review the diff, and run bin/sync-project.sh <project> on each live project so its CLAUDE.local.md picks the row up. That is the whole procedure — there is no second list to remember.

Spine — what am I doing, who decides, how do I ask

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Any pipeline work at all — every session, before producing any stage artifact: read §1b plus your own stage's section, not the whole file (gate-check.sh prints the line spans); READMEs and the guide are orientation only	skills/conversion-runbook.md	lead,ba,architect	P,0,1,2,3,4,5,6,7	baseline
Any pipeline work at all, as a helper — every dispatch, before producing anything: run the toolkit's bin/runbook-slice.sh , which prints §1b plus your stage's section of the conversion runbook; never open skills/conversion-runbook.md whole	bin/runbook-slice.sh	mdl,gate,test,review	P,0,1,2,3,4,5,6,7	baseline
Any question before asking the user or writing anything — query the model, then read the source, then ask the human, in that order	skills/query-the-model.md	all	P,0,1,2,3,4,5,6,7	baseline
Script or skill? Before writing any .js or bash/.sh for a check, checker, linter, gate or report, or adding a rule or regex to an existing one — judgement goes in a skill, code only fetches facts a reader cannot	skills/skills-over-scripts.md	all,mdl?,review?	-	baseline
Any pass whose input is missing, stale or unresolvable — before recording UNMEASURED, N/A or a silent skip: name what was missing, say what you assessed against instead, still deliver a verdict	skills/degrade-to-judgement.md	all	-	baseline
Putting a question TO the user — any gate, any stage: ask in chat not in a file, two named options plus your recommendation, one batch per gate then end the turn	skills/interview-protocol.md	lead,ba,architect	P,0,1,2,3,4,5,6,7	baseline
The user gives feedback or asks for a change mid-project — "change X", "it also needs Y" (a field, a column, a button), a remark on a screenshot or the running app, a stakeholder's ask relayed in chat: log a CR row in PROJECT.md ## Change log BEFORE any edit, size it, then edit the highest artifact it alters (BRD, decision, architecture, wireframe), never the MDL first	skills/change-intake.md	lead,ba	2,3,4,5,6,7	baseline
Applying or proving a change request (CR row), a change whose class, size or status is unclear, or a "Change log:" gate line to explain: full class/size/ask tables, the wrong-vs-right example, apply and prove steps, the owners table and what the warn-only gate check counts	skills/change-intake-detail.md	lead,ba,architect	2,3,4,5,6,7	ondemand
Deep, adaptive interview on one topic, on demand, when a checkpoint's 2+1 or a single question batch isn't enough	skills/grill-mode.md	ba,architect	P,0,1,2,3,4,5,6,7	ondemand
Any stage transition — the 2+1 format every CAC uses, and the one-register rule (answers land in PROJECT.md, never in a separate state file). The seven CACs themselves are routed per stage in the situational table	skills/checkpoints/checkpoint-template.md	lead,ba,architect	0,1,2,3,4,6,7	baseline
CAC-1, closing Stage 0 in EVERY entry mode — scope IN: full scope or a slice, and in what order. Opens with a brainstorm, not options	skills/checkpoints/checkpoint-scope.md	ba,architect	0	ondemand
CAC-1b, after Stage 1 — scope OUT: is what extraction produced what you meant. No gate stops you; run it late against the BRDs if it was skipped	skills/checkpoints/checkpoint-extraction.md	ba	1	ondemand
CAC-2, after BRD scaffolding and before enrichment — capability grouping and enrichment order	skills/checkpoints/checkpoint-brd.md	ba	2	ondemand
CAC-3, after BRD validation and before architecture locks — the hidden business rules that are expensive to discover later	skills/checkpoints/checkpoint-architecture.md	ba,architect	2	ondemand
CAC-4, after rearchitect sign-off and before any design artifact — branding and UI direction. Opens with a brainstorm	skills/checkpoints/checkpoint-design.md	architect	3	ondemand
CAC-5, after design sign-off and before the build plan — build order and slice boundaries. Opens with a brainstorm	skills/checkpoints/checkpoint-build.md	architect,mdl	4	ondemand
Going live / cutover: CAC-6, after Stage 6 passes and before any cutover or old-data migration step — migration mode only, and a hard gate: every answer lands CONFIRMED, no ASSUMED defaults	skills/checkpoints/checkpoint-cutover.md	gate,test	6,7	ondemand
Setting up or completing a project's dev-process subagents — once, at project start, not "on demand"	skills/agent-roles.md	lead	P,4,5	baseline
Starting a subagent, sending it a fix round, or reading an agent-stop notice — name the model, fresh not fork, fresh fixer not resume, coalesce notices	skills/dispatching.md	lead	P,1,2,3,4,5,6	baseline
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/small-project-tier.md	ba,architect	0,1,2,3,4	ondemand
Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127	bin/question-kinds.sh	ba	1,2,3	baseline
Generating a new project's CLAUDE.md — baseline routing plus project-specific facts	skills/bootstrap-project.md	ba	P	ondemand
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/cloud-dev-environment.md	all	P	ondemand
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	skills/existing-app-change.md	ba,architect	P,0	ondemand
Splitting an existing Mendix monolith into several apps — strangler, "move module X into its own app", carving out a slice, microservices from one .mpr; choosing the cut, moving a slice by MPK, accounting for every crossing edge, or reporting the level a slice reached	skills/decompose-app.md	lead,architect,mdl	0,3,5,6	ondemand
Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/	skills/company-brain.md	all	-	ondemand
Cutover and retrospective — promoting proven patterns back into the toolkit	skills/close-the-loop.md	all	7	ondemand
Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence, or counting tokens from transcripts — a claim not in the register may not be cited	skills/measured-claims.md	all	-	ondemand
Any review pass that runs more than once — module-review, coherence, monkey, wiring-sweep: findings accumulate across runs, a per-run report cannot show a trend	skills/improvement-register.md	mdl,gate,test,review	5,6	ondemand
The first command of every session, and any time someone asks "where are we" or "what next" — one screen: stage, done/overdue, the ONE next action, from the instruments, never from memory	bin/status.sh	all	P,0,1,2,3,4,5,6,7	baseline
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/retesting-learned-rules.md	all,mdl?	-	baseline

Source — reading a legacy system (migration entry mode)

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Deciding whether to extract at all, before any BRD gets generated	skills/source-triage.md	ba	0	baseline
Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source	bin/source-sufficiency.sh	ba	0,1	baseline
Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does	bin/source-ledger.sh	ba	0,1,2	baseline
HTML in the source corpus — convert once before anyone reads it: bin/html-to-md.sh <project> writes each page as Markdown under analysis/knowledge-base/text/ (3–10× fewer tokens than the raw export; inline images decoded to files; section list with line numbers as the read's denominator) plus documents-index.md over EVERY file, which one ledger glob mark points at. A session that opens a .html itself has skipped this	bin/html-to-md.sh	ba	0,1	baseline
Pictures in the source corpus — decks, Word files, PDFs, screenshots: one worklist of unique images with context, one description file each, coverage checked	bin/images-to-md.sh	ba	0,1,2	baseline
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/image-transcription.md	all	0,1,2	ondemand
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/triage-report.sh	ba	0	ondemand
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/extraction-report.sh	ba	1	ondemand
Assessing or planning a migration up front, before any pipeline is chosen	skills/assess-migration.md	ba	0	ondemand
Running the extraction pipeline	skills/migration-pipeline.md	ba	0,1	ondemand
Rehosting an existing Mendix .mpr into a fresh app — "port this app to a clean Mendix 11 project", re-platforming or rebuilding a whole app from its own model, running pipelines/mendix-mpr/rehost-extract.sh or reading its fidelity ledger	skills/rehost-app.md	lead,ba,mdl	0,1,5,6	ondemand
Migrating from a stack that has no dedicated pipeline	skills/migrate-general.md	ba	0	ondemand
Migrating an OutSystems app	skills/migrate-outsystems.md	ba	0	ondemand
Understanding OutSystems 11 source	skills/source-os11.md	ba	0,1	ondemand
Reading the OutSystems XML export schema	skills/os-xml-schema.md	ba	0,1	ondemand
Understanding Node/Express+React source, its layout assumptions and its gaps	skills/source-node-express-react.md	ba	0,1	ondemand
Scanning or classifying an unstructured document folder	skills/document-discovery.md	ba	0,1	ondemand
Validating an extractor's output before its BRDs are trusted	skills/extractor-quality-loop.md	ba	0,1	ondemand
Extracting Excel/Word/PDF specs into a knowledge base	skills/kb-generation.md	ba	1,2	ondemand

Requirements — what must be built

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Writing BRDs, especially several in parallel — "build" before the fan-out, "check" before any BRD is called done	bin/facts-lock.sh	ba	2	baseline
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	bin/brd-report.sh	ba	2	ondemand
Building any module — before the first script. The mdl-agent's single per-module input	skills/module-brief.md	ba,mdl	4,5	baseline
Validating a new stack pipeline's extraction quality	skills/qa-loop-goal-pattern.md	ba	0,6	ondemand
Writing or enriching a BRD JSON	skills/brd-generation.md	ba	2	ondemand
Validating BRDs against the code and document KB	skills/brd-validation.md	ba	2	ondemand
Turning BRDs plus architecture into a numbered, dependency-ordered build plan	skills/brd-to-build-plan.md	architect	3,4	ondemand
Building the Stage 4 coverage ledger — every requirement either claimed by a build-plan row or catalogued with a reason, never invisible	skills/coverage-ledger.md	architect,gate	4	ondemand
Checking a coverage ledger against its BRD — every scalar leaf CLAIMED, LEDGERED, UNCLAIMED, PHANTOM or DOUBLE-CLAIMED, so coverage is measured rather than remembered	bin/coverage-check.sh	architect,gate	4	ondemand
Writing an actual .journey.json — the worked field-by-field reference for the contract journey-proof.md argues for	skills/journey-examples.md	test,review	5,6	ondemand
Extracting structured requirements from a large delivered document corpus into per-scope knowledge-base files	skills/corpus-extraction-integrity.md	ba	P,0,1	ondemand

Architecture — how it is shaped

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
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	skills/module-folder-convention.md	architect,mdl	4,5	baseline
Collecting the facts an app dossier is written from: forces a full catalog build, module edges through the real module column, strongly connected components, describes every loop-containing microflow and parses the loop bodies; exit 2 on a stale, fast-mode or schema-incomplete catalog, never a verdict	project-bin/app-facts.sh	architect,review	0,6	ondemand
Building or refreshing the standing dossier of an EXISTING app before changing it: inventory, module dependency shape, loop risk patterns, each section with a verdict and a fault where nothing was measured (a standing document; nothing else in the toolkit reads it yet)	skills/app-analysis.md	ba,architect,review	P,0,6	ondemand
Checking whether an EXISTING app's module boundaries still hold: the layer map (bin/app-layer-map.sh) computes the order the modules would stack in and draws only the edges that point back up, so one tangle of N mutually reachable modules becomes a named list of edges with a weight and a ref kind; Stage 3 in existing-app-change mode, and the honest blast radius for a slice	skills/layering-review.md	architect,ba	0,3	ondemand
Judging module tangles, bidirectional pairs, cohesion and hubs from analysis/app-facts/dependencies.json; stock graph_module_* views split names on the first dot and are not trusted	skills/module-dependency-review.md	architect,review	0,6	ondemand
Diagramming target architecture — module defs, wiring, fit-gap, marketplace, security, NFRs, integrations	skills/architecture-blueprint.md	architect	3	ondemand
Deciding module boundaries before "create module"	skills/modularize-domain.md	architect	3	ondemand

Design — how it looks, before any MDL

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Building any page or snippet — before the first widget. Wireframe, tokens, gallery reuse, cross-check; no wireframe means STOP	skills/ui-preflight-pages.md	mdl	5	ondemand
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	skills/design-spacing.md	mdl?,review	5	baseline
Building or using the in-app design gallery	skills/learned-stylegallery.md	mdl	5	ondemand
After every page-building script, and any time the UI looks wrong — the cheap repeatable look during the build: one page, one screenshot, four questions, scored when a wireframe exists. Feeds Gate: UI, never replaces it	skills/ui-loop.md	mdl?,review	5	baseline
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/check-design-portability.sh	architect,mdl,gate	3,5	ondemand
After the FIRST build that follows any design-system port, and before any page is built on it — reads the BUILT stylesheet and reports how many framework knobs point at a design token, how many tokens arrived, how many component classes arrived, each with its denominator. Measured on a real run: 55 tokens ported correctly into the right file, 0 of 35 knobs bound and 0 of 20 classes present, two build phases shipped in the framework's default blue with mx check, mxcli lint, the MDL suite and two e2e journeys all green	project-bin/check-design-reaches-app.sh	architect,mdl,gate,review	3,5	baseline
Before exec'ing ANY page script — compares the drafted MDL's shell against the wireframe's: page column, layout/nav shell, one H1. Measured 0/10 pages on a real first build, repaired wholesale 47 scripts later	project-bin/check-page-shell.sh	mdl,gate,review	5	baseline
After drafting and again after exec'ing any page script — scores the page MDL (or mxcli describe output on stdin) against its wireframe: headings/actions/content/classes, weighted. The scored companion to check-page-shell's binary gate; 32% median measured without it, 90% first-draft with it. Every run is appended to the project's docs/PAGE-FIDELITY.tsv — first non-stub row per page = first-build score of record vs the ≥80% target (forward-reference stubs score with --stub, exempt)	project-bin/page-fidelity.js	mdl,gate,review	5	baseline
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/assemble-prototype.js	architect,review	3	ondemand
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)	project-bin/check-prototype-links.js	architect,review	3	ondemand
Designing the brand and ONE ANNOTATED WIREFRAME PER SCREEN before building pages — the design system alone is half the deliverable	skills/design-artifacts.md	architect	3	ondemand
At Stage 2 close (draft, before the questions are raised) and again after the wireframes (Stage 3 re-render), when a reviewer cannot tell where the open questions and ASSUMED decisions fit: one swimlane map per process, each step on its wireframe, every question pinned to a step (project-bin/process-map.js validate, anchor, build)	skills/process-map.md	architect,review	3	ondemand
Stage 3, after the role model is CONFIRMED and BEFORE THE FIRST WIREFRAME — and any time a page shows ONE object, a menu item or home page is added, or a data source retrieves the current/first record: role homes, inboxes, and per page how it is reached and which object it takes as parameter	skills/interaction-model.md	lead,ba,architect	3	ondemand
Before a wireframe or a design commits to a WIDGET, when a requirement shows a widget to one role and not another, and when a page script hits a parse error that looks like a syntax mistake: the short list of things MDL cannot write at all, and the four-minute probe that answers it at Stage 3 instead of at build time	skills/learned-mdl-cannot-express.md	architect,mdl	3,5	ondemand
A CSS/SCSS or style change that appears to have done nothing (a colour or class that won't show), a focus ring or outline that paints on every page landing or load, or an app still grey after a design port every instrument called green — the three ways a correct rule paints nothing (matches nothing / matches chrome / loses the cascade), the two reads that tell them apart, and the class that arrived in the stylesheet and is bound to no widget	skills/learned-css-that-never-applied.md	mdl?,review,gate	5,6	baseline

Build — the loop itself

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Is the module done? Reviewing any module before calling it done — the ONE pass, the once-over: build, gate, prove, LOOK (is it logical, does it look right, does it match our design, over every page not just the tested ones), confirm with the denominator stated	skills/module-review.md	mdl?,review,test	5,6	baseline
Before any mxcli exec / exec.sh / --mcp write — ask or run? the knob decides	bin/exec-approval.sh	mdl,gate	5,6	baseline
Dispatching a build step to a helper — generate its one-file pack (the brief's Build steps row, mxcli brain brief, live DESCRIBEs, example, folder) and hand over the path instead of a reading list. Measured: 25-38% fewer tool calls and 30-41% less time, same quality; the token saving is not proven	project-bin/context-pack.sh	mdl	5	ondemand
An exec.sh guard refused a write (not a permission prompt), or building a module with mxcli — verified, iterative, coverage-checklist gated; on a refusal: commit, wait or stop, never FORCE_EXEC	skills/iterative-build-loop.md	mdl,gate	5	ondemand
Adding a second language, a language picker or a translation script — and the moment a language picker errors, shows a blank label or changes nothing: source language, enabled languages, the user's starting language, a switch a non-admin role can use	skills/learned-multilingual-app.md	architect,mdl,review	3,5,6	ondemand
After marking a module done, or any time "how much is built vs proven" is asked — renders progress-report.html from done- prefixes and verify-module.sh/improvement-register.md, kept as two honestly separate views; --json writes architecture/build-plan.json parsed from build-plan.md's Phase headings (a plan with no Phase headings gets no file); --refresh keeps an existing build-plan.json current but never creates one	project-bin/build-plan-status.sh	architect,gate,review	4,5,6	ondemand
Turning a client-derived Mendix app into a clean, shareable demo with zero client fingerprint — branding, data, custom widgets	skills/anonymize-client-app-for-demo.md	mdl,review	6	ondemand
Handing a headless-built model to a person — opening it in Studio Pro, a free sandbox, or a colleague's machine: the model travels, the demo data and runtime config (keys, an agent's bound model) do not, and each needs its own re-establish step	skills/handoff-to-studio-pro.md	test,review	6,7	ondemand
Sharing the project with a colleague on Mendix Team Server while the build loop stays on GitHub — content-transplant snapshots between the two clones (status/push/pull); SUPERSEDED by platform-link.md §3 (adopt without rewriting history, field-proven) — only if that path fails; UNPROVEN against a real Team Server	project-bin/ts-sync.sh	mdl,gate	6,7	experimental
Stage 5 start, before the first module of any entry mode — one entity, flow, page, nav, demo user, journey and screenshot proven in the running app, so build/run/look/test are known to work before a module depends on them	skills/walking-skeleton.md	mdl,gate,test	5	ondemand
At project birth (before the first build script) and any time a model needs a platform home: creating the Team Server app, adopting an existing GitHub-born model into it without rewriting history, or deploying; also when the Platform SDK returns 403, git rejects the PAT, a deploy cannot be triggered from a PAT, or the app turns out to be a Free App	skills/platform-link.md	all	P,5,6,7	ondemand
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/teamserver-alignment.md	mdl?,gate,review?	5,6,7	baseline
Promoting an app to a deployed sandbox or cloud node, or before a customer tests a deployment — "it works locally" is not evidence about a deployment; also when a test suite fails only against the remote URL	skills/deploy-to-sandbox.md	all	7	ondemand

Build · MDL — the language and tool reference

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Writing ANY MDL script — before the first line. Step 0 picks the write mode, then the STOP table overrides it for corrupting operations	skills/learned-mdl-preflight.md	mdl?	5	baseline
Writing ANY MDL script — before the first line: run bin/mdl-rules.sh (page, microflow, access, workflow, entity) or --for <draft.mdl>, or read skills/generated/rules-.md, and read ALL of it — the STOP rows, gotchas and preflight sections for the statement kinds the script writes; your PREFLIGHT reports "STOP rows for kinds K: n/n checked"	bin/mdl-rules.sh	mdl	5,6	baseline
Writing or fixing any microflow — MDL gotchas plus annotation discipline	skills/learned-microflow-patterns.md	mdl	5	ondemand
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	skills/microflow-preflight.md	mdl	5	ondemand
Reading what loop bodies do (LOOP_TQ, deferred commit, nested loop, REST in loop, transaction control per item, scheduled-event reachability) from described MDL; the catalog holds top-level activities only and cannot see inside a loop	skills/microflow-loop-antipatterns.md	architect,review,mdl	0,5,6	ondemand
Writing MDL microflow scripts — worked recipes	skills/mdl-cookbook-microflows.md	mdl	5	ondemand
Writing a single MDL script that takes a project from nothing to a working vertical slice — execution order, why it is deliberately non-idempotent, the instrument hierarchy, and the silent failures that pass every check	skills/build/mdl/oneshot-mdl-method.md	mdl	5	ondemand
Writing a popup page's microflow with a retry/validation-failure branch that re-shows the same popup — missing close page stacks duplicate dialogs	skills/learned-popup-navigation.md	mdl	5	ondemand
Writing MDL for a datagrid column with ShowContentAs customContent that needs to display a bound value	skills/learned-datagrid-customcontent-binding.md	mdl	5	ondemand
Writing ANY microflow behind a button that commits, completes a workflow task, or triggers a backend flow — popup or full page: it owes the user a message, a close, and a control that stops offering the action once done	skills/learned-popup-feedback-pattern.md	mdl	5	ondemand

Build · Pages — page-building patterns

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Building and auditing Mendix pages, or starting a UI fix round across many pages — widget patterns, datasource shapes; for a round: SCSS first, four regressions to check	skills/learned-page-patterns.md	mdl	5	ondemand
Generating a whole page tree in one script — the structure patterns that survive it	skills/oneshot-page-structure-patterns.md	mdl	5	ondemand
Building or auditing a collapsible sidebar nav — Atlas Core's collapsed state needs icons assigned per menu item or it silently clips label text	skills/learned-sidebar-collapse-icons.md	mdl	5	ondemand
Building or altering any data grid — native DATAGRID vs pluggable DG2 decision rule, the ALTER PAGE INSERT corruption, sort-by and filter-binding traps	skills/learned-dg2-patterns.md	mdl	5	ondemand
Putting any file upload / attachment / document field on a page, an uploader page failing mx check with CE0463, or an uploader DESCRIBE that will not re-execute — the File Uploader MDL shape proven end to end on v0.23 and v0.24, the widgets mxcli cannot author, and the upload instrument	skills/learned-file-upload-widget.md	mdl,test	5	ondemand

Build · Agents — Mendix AI agents, tools, knowledge bases, chat UI

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Building a Mendix AI agent — the agent is runtime data not a model document, so JSON import, tool microflows, knowledge base chunk loading and the runtime wiring all sit outside MDL, and mxbuild stays green when they are wrong	skills/mendix-agents.md	mdl,architect	5	ondemand
Embedding a copilot chat panel — the frame is yours, ConversationalUI owns the conversation; wireframe to tokens to snippet to page placement	skills/mendix-agent-ui.md	mdl	5	ondemand
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	skills/mendix-agent-setup.md	mdl,test	5,6	ondemand

Build · Workflow

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Writing or debugging a Mendix native Workflow (CREATE WORKFLOW/USER TASK/OUTCOMES) — syntax, the 11 workflow microflow statements, DECISION vs CALL MICROFLOW, and the two corruption classes (binary-version $Type, and create-before-reference)	skills/learned-workflow-patterns.md	mdl	5	ondemand
Designing or reviewing a Workflow's SHAPE before or after the MDL — where a path may end, boundary event vs event sub-process, parallel-split limits, outcome minimums, targeting from the sentence, multi-user decision methods, which edits break running instances; and any CE6689/CE1844/CE1845/MW0012 after a clean mxcli check	skills/workflow-structure-rules.md	architect,mdl,review	3,4,5,6	ondemand

Build · Integration

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Wiring a service seam between two Mendix apps — one app's OData or REST consumed by another, replacing a stub by an external entity, joining data that lives in the other app, or choosing keys and auth for an app-to-app service	skills/mendix-service-seam.md	lead,architect,mdl	3,5	ondemand
Building a REST integration (consumed or published) for the first time on a project — the checks that avoid a rebuild after the first live call	skills/rest-integration-first-time-right.md	mdl	4,5	ondemand
App-to-app REST or microservices: two or more Mendix apps you build that read each other over REST — before the contract, before the first consumer, and before calling an API tested: pull vs push, key+version rule, auth in the operation microflow (BUG-152), honest last-success/stale/"as of", one owner per fact, and the six-rung cross-app test ladder with its per-change/slice/release cadence	skills/rest-between-mendix-apps.md	architect,mdl,test,review	3,4,5,6	ondemand
Adding a constant, installing a marketplace module, deploying to a new environment, or needing a Mendix PAT — where an encryption key, API credential, endpoint or access token gets its value, why a free node has only one channel, and why a token missing from the files you grepped is not missing	skills/learned-constants-and-secrets.md	mdl,architect,gate	4,5,6	ondemand

Build · Security

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Creating any entity, or calling a module security-ready — entity and grants land in one script, and ready means SHOW SECURITY MATRIX proves it	skills/security-is-not-a-later-script.md	mdl?,gate,review	5	baseline

Verify — does it work

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
Before calling any module tested, or before re-running tests after a change — what testing a module means, which re-runs a change owes (UI-only vs logic lane), and the false-green register of confirmed ways a test reports green over a broken feature	skills/testing-shape.md	test,gate,review	5,6	baseline
Finishing any module — before calling it done. One command that runs every instrument and keeps "instrument faulted" apart from "feature failed"; in a wired project run the installed copy at bin/verify-module.sh	project-bin/verify-module.sh	mdl,gate,test,review	5,6	baseline
Auditing or regression/e2e-testing an EXISTING app — no intake, no stages, no gates	skills/existing-app-assurance.md	test,review	6	ondemand
Running the ledger rung alone — recompute every stored ledger status against the live model and catch the STALE rows that claim built for something the model no longer has	project-bin/conformance-check.sh	gate,review	5,6	ondemand
Running the wiring rung alone — a module imported but never reached, an element built but wired to nothing, a boundary crossed; mxbuild and e2e are blind to all three	project-bin/graph-sweep.sh	review,gate	5,6	ondemand
Before any runtime test — brings the stack up unattended and PROVES the thing that answered is this project's app; --check makes it report-only	project-bin/test-stack-up.sh	test,gate	5,6	ondemand
Standing up or extending the Playwright e2e harness	skills/e2e-harness-base.md	test	6	ondemand
Writing DB assertion tests that cross-check UI state against the database	skills/learned-db-assertions.md	test	6	ondemand
Seed data, test data, demo data or fixtures are needed, or pages come up empty — BEFORE a journey run. Explore the data structure, choose rows by use case, scan for reset/delete actions, derive and measure with project-bin/fixture-manifest.sh, interview only the residue, never seed from inside the harness	skills/fixture-seeding.md	test,review	5,6	ondemand
Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red	skills/journey-proof.md	test,review	5,6	ondemand
Writing or running e2e cases beyond the happy journeys (blank/whitespace required fields, over-length, duplicates, cancel, double submit, wrong state, wrong role, backend down, stale write, empty search) — every case cites a requirement first, UNSPECIFIED is re-scored against house rules, GAP counts carry the denominator; runs after journey-proof and before monkey-test	skills/unhappy-path-testing.md	test,review	5,6	ondemand
Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works	skills/monkey-test.md	test,review	5,6	ondemand
Load, performance or stress testing a page ("will it hold 1000 users", concurrent users, k6, JMeter) — record the real /xas/ calls with Playwright and replay them instead of correlating tokens by hand, and report what the number does NOT prove (requests vs users, empty data, whose limit was hit)	skills/load-test.md	lead,test,review	5,6	ondemand
Writing or running a microflow unit test (.test.mdl, mxcli test, @expect) once the project or the user has decided a flow gets one — what is worth a test, equality-only asserts, --list before any run, a scratch copy so the live app survives, and a positive control that must fail	skills/unit-test.md	lead,mdl,test,review	5,6	ondemand
UX audit and screenshot-loop discipline	skills/learned-skill-ux-audit.md	review	6	ondemand
Tracking scope delta between the BRD and the built state	skills/learned-skill-scope-delta.md	review	6	ondemand
Writing or reading docs/report.json — the append-only contract every instrument writes to and every renderer reads; open BEFORE building a new instrument or a second renderer	skills/report-schema.md	test,review,gate	5,6	ondemand
Installing, extending, debugging or porting the verification harness — which part owns what, which parts run standalone, and what a missing part must report	skills/harness-architecture.md	test,review	5,6	ondemand
Checking whether the whole journey hangs together rather than each piece — finds correctly-built components nothing reaches, which per-element conformance and UI tests both miss	skills/process-coherence-pass.md	review	5,6	ondemand
After every module's CONFIRM stage — counts proven modules since the last cluster/full coherence pass and exits DUE once the threshold is reached, so the cadence isn't left to memory	project-bin/coherence-cadence.sh	mdl,gate,review	5,6	ondemand
Turning an already-rigorous run into a narrated proof a stakeholder can trust without running anything	skills/e2e-evidence-report.md	test,review	6	ondemand
Recording a narrated screen-capture demo of a running app for a human to watch — opening on the app instead of a blank frame, and keeping captions synced to the pixels	skills/record-demo-video.md	test	6	ondemand
A demo film someone will watch looks captured, not produced — 25 fps smear, scroll jumps, no visible pointer, a dense page nobody can read: 2x CDP screencast at 60 fps, drawn cursor and click ripple, eased scroll, and a zoom rendered afterwards from the click log (never a CSS transform in the page)	skills/demo-recording-polish.md	test	6	ondemand
Sending a demo guide, screenshots or a quickstart doc OUTSIDE the repo — to a customer, prospect or reviewer: relative image paths and "the name shown above" both break the moment the file travels alone, and the usernames a login panel displays are not the ones it accepts	skills/share-demo-package.md	test,review	6,7	ondemand
Running lint as a gate rather than a report — per-rule ratchet against a committed baseline, plus the crash and collapse guards that stop a blind rule passing	project-bin/lint-gate.sh	mdl,gate	5,6	ondemand
Reading a lint result, or writing/repairing any .star rule — lint's failure mode is a confident clean pass, so 0 findings is a claim needing evidence	skills/lint-that-actually-runs.md	gate,review	5,6	ondemand
Every module before it is called done; buttons, links or actions that do nothing when clicked — does every clickable thing actually do something; run AFTER the happy-path journey is green, never before	skills/wiring-sweep.md	mdl,test,review	5,6	ondemand
The user asks for a full end-to-end test, a click-through proof, or does-everything-actually-work — or you are unsure which harness skill applies; this one routes you	skills/full-harness-audit.md	test,review	5,6	ondemand
End of any build+test cycle that wrote docs/report.json — did the testing itself hold up, not just get filed; one level up from finding-disposition	skills/test-result-audit.md	test,review	5,6	ondemand
Any report from a test/review run is about to be published — no report ends without a disposition for every finding	skills/finding-disposition.md	test,review,gate	5,6	ondemand
Handing the human a batch of steps only they can perform (Stage 7 cutover, browser-only GitHub settings) — generate a paced confirm-and-verify walkthrough script instead of a prose checklist; hypothesis under trial, no field run yet	skills/wizard-walkthrough.md	gate,review	P,7	experimental
Exposing a container-run app at a public URL (mxcli run --hub) — demo/stakeholder preview: the db-name default trap, the runtime REST client ignoring JVM proxy settings (GenAI 403 "Host not in allowlist" that is really a proxy bypass), and stale-app detection	skills/preview-over-hub-tunnel.md	test,review	5,6	ondemand
Starting a hub-tunnelled preview with the flags outbound calls actually need — wraps mxcli run --hub with db-name and the runtime proxy settings from preview-over-hub-tunnel.md	bin/run-hub.sh	test	5,6	ondemand
Before any first deploy to a new environment, and after installing or updating any marketplace module — which constants would be blank where nobody can set them, and which now carry a secret in the model. Never prints a value	project-bin/constants-audit.sh	mdl,gate,architect	5,6	ondemand

Diagnose — something is broken and it may be the tooling

Always relevant for	Load this	Agent(s)	Stage(s)	Tier
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 too large to read whole	bug-logs/mxcli-bugs.md	mdl,gate	5,6	ondemand
An e2e rung reports a UI defect (widget never appeared, click did nothing, screen contradicts the data, fixture count wrong) — check the locator before blaming the app: :visible, click order, poll, derived fixtures	skills/e2e-locators-that-lie.md	test,review	5,6	ondemand
Any time an exit code, a tool's output or a subagent's report is about to become a stated finding — verify before you conclude	skills/tool-output-is-not-ground-truth.md	all	-	baseline
Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing	skills/agent-permission-friction.md	all	-	ondemand
Studio Pro will not load the project, or the .mpr looks gutted — recover before relaunching SP, never git checkout	skills/mpr-corruption-and-sp-load-errors.md	mdl,gate	-	ondemand
Preparing an mxcli/Studio Pro bug for submission — scope pinning, read-back-vs-write-path verification, gate-sensitivity negative controls, severity scoping, before it's called filable	skills/bug-submission-checklist.md	mdl,gate,review	5,6	ondemand
About to open an issue, PR or discussion against mxcli or the toolkit — before drafting, choosing which repo and vehicle it belongs to	skills/upstream-feedback.md	all	-	ondemand
A page/grid/list/combobox renders or shows empty ('0 to 0 of 0', blank cells, zero rows, zero options) during UI review or an e2e run — before assuming a single cause (seed, access rule, datasource, binding)	skills/empty-widget-triage.md	mdl,test,review	5,6	ondemand
doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same	skills/doctor-triage.md	all	-	ondemand
Suspecting an mxcli/mxbuild tool defect and deciding whether to swap a binary — proving it's version-specific without risking the real model	skills/sandbox-ab-tool-defect-probe.md	mdl,gate	-	ondemand
Restarting Studio Pro on macOS — the reopen bug, the port bug, and detecting a real hang vs a slow load	skills/restart-sp-reopen-and-hang-detection.md	mdl,gate	-	ondemand
Driving the whole toolkit pipeline on a real source to find what the written skills don't say — the toolkit is the subject, not the app it builds	skills/field-run.md	all	-	ondemand
Before trusting a green check/exec/DESCRIBE result as proof, or when a runtime symptom appears over a fully green model — the register of constructs that pass early rungs and fail later ones	skills/learned-detection-gaps.md	mdl?,gate,review	5,6	baseline
Needing Studio Pro load evidence without a human at the GUI — direct-binary launch and log capture; a capture technique, NOT a validated pass/fail oracle	skills/scriptable-sp-verification.md	mdl,gate	-	ondemand
A runtime test or seed reads/writes data that then is not there (the test wrote a row, the DB query shows nothing), or vice versa — three local Postgres instances can answer on this box; resolve the real port from the project's own compose file first	skills/learned-local-db-confusion.md	mdl,test,gate	5,6	ondemand
gate-check.sh reports a Stage 0 file not found that plainly exists — ANALYSIS_BASE falls back to project root until Stage 1; move the file, do not debug the script	skills/gate-check-file-locations.md	ba,gate	0	ondemand
A CE error (mx check or mxbuild: CE0066, CE0117…), a cited BUG-n, or behavior that looks like a known mxcli quirk rather than a modeling mistake — bin/bug-lookup.sh CE0117 / BUG-102 / "keyword" / the whole pasted error message (ranked top 3) prints the matching ledger entries, so the session reads one entry, not the whole ledger	bin/bug-lookup.sh	mdl,gate	5,6	baseline
You hit, or worked around, a bug in mxcli or the toolkit — bin/file-bugs.sh (the --add line is in learned-detection-gaps.md) keeps docs/bugs.jsonl, redacts, shows duplicates, is filed only by a human with ! (--file PBUG-NN, y/N, denied to agents), or prints new-issue links (--links, --json)	bin/file-bugs.sh	mdl,gate	5,6	baseline
The user says the toolkit, an exec or the gate is slow, or asks to update the toolkit, run doctor and check whether it can be faster on their machine (werk de toolkit bij, draai doctor, controleer of het sneller kan)	skills/speed-setup.md	lead	-	ondemand

Reference — lookup tables, not method

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