Bootstrap App

Bootstrap a Mendix App in an Empty Repo

When to Use This Skill

Use this when a repo has no Mendix project yet and you have been asked to provision one with mxcli — typically from the empty-repo seed prompt, which does nothing but install mxcli, run mxcli init --sync-skills, and send you here.

Everything the seed prompt used to spell out lives here instead, so the prompt stays short enough to paste from a phone and this procedure can be fixed by shipping a new mxcli rather than by re-pasting a longer prompt.

If an .mpr already exists, this is the wrong skill: run mxcli init in the app folder and go straight to the work.

Related skills: run-local (the warm dev loop this ends in), mdl-entities and create-page (building the model you propose at the end), migrate-design-prototype (when a design was handed to you), assess-quality (reading the report this takes a baseline with), test-microflows and test-app (the two gates that prove behaviour rather than syntax).

Step 0 — interview, and WAIT for the answers

Ask all of these in ONE message, numbered, each with the default you would pick, so the user can reply "defaults" or answer only what they care about. Do not provision anything until they reply.

The interview comes first for a reason: the app name becomes the .mpr file name, the Studio Pro app name and the path baked into the SessionStart hook, so it is far cheaper to ask than to rename afterwards. The rest of the answers are the brief — they get written into the repo, so the session that resumes after an idle reap knows what it is building.

1. One app, or a solution of several? One Mendix app is the default. "Solution" means several apps in one repo — e.g. a backend that owns the data and publishes OData/REST, and a frontend that consumes it. If so, ask for each app's name and one line on what it owns, and follow "If this is a solution" below.

2. App name. Becomes the .mpr file name, the app name in Studio Pro, and the path in the session hook, so it is awkward to change later. One PascalCase word, letters and digits only — OrderPortal, FieldService, ClubAdmin. Propose one derived from the answer to Q3.

3. What is the app for? One or two sentences: who uses it, and what it lets them do. If the answer is vague ("a tool for work"), ask one follow-up — everything below is derived from this.

4. What does it keep track of? Three to six nouns that will become entities, and a word on how they relate (e.g. "a Job has many Visits; each Visit has Photos"). For a solution, also ask which app owns each noun. Ask two follow-ups here, because both change the model rather than decorate it: does anything go through steps someone has to act on (approval, hand-off, review, a deadline), and is there a number or count across records anyone needs to see. The first is a workflow and the second a view entity — see "Two choices to make deliberately" below.

5. Who logs in? The user roles, and roughly what each may do (e.g. "Requester creates and sees their own; Approver sees everything and approves").

6. Look and feel. One of the bundled themes: signal (light, high contrast), ledger (light, dense, data-heavy), console (dark), or none for stock Atlas. Default signal.

7. Mendix version. Default to whatever the session environment already provides — see below — and otherwise the newest version on the CDN (today 11.14.0).

8. Do you have requirements to work from? A specification document, a prototype, a wireframe, a long description — anything that is the source of truth but is not in this repo. Default: yes, record them. If they say yes, ask them to paste or point at it; if they say "just build it", say in one line that you will record the slices you derive as you go, and carry on.

   This one is not cosmetic. Requirements that live in a Word document, a Figma file or a chat window leave no trace in git: not in an issue, not in a commit message. A session that resumes after an idle reap has no idea what it was building towards, and neither does the next person. Recording them costs a minute now and is unrecoverable later.

If the user says "defaults" or ignores a question, choose something sensible for it, say what you chose in one line, and keep going — do not block on them twice.

Choosing the Mendix version

Prefer a version the environment already has. A Claude Code session image may bake in an MxBuild, and using it turns a multi-hundred-MB download into no download at all. There is no environment variable for this — the cache directory is the signal:

ls ~/.mxcli/mxbuild/ 2>/dev/null | sort -V | tail -1   # e.g. 11.13.0, or empty

If that names a version, use it and say so in one line ("using 11.13.0, already cached in this environment"). If the user asked for a specific version, they win — check it on the CDN as below and accept the download.

Otherwise take the newest version on the CDN. Everything mxcli does starts with downloading MxBuild, so "supported" means "on the CDN", and run --local needs the runtime tarball as well. At the time of writing the newest is 11.14.0 (11.15.0 is not published). Do not trust that number — it ages. Confirm the one you land on, and walk backwards a minor if it 404s:

V=11.14.0
curl -sI -o /dev/null -w '%{http_code}\n' https://cdn.mendix.com/runtime/mxbuild-$V.tar.gz
curl -sI -o /dev/null -w '%{http_code}\n' https://cdn.mendix.com/runtime/mendix-$V.tar.gz

Both have to answer 200. Run the same check for any version the user names.

In a solution, give every app the same version: they share the ~/.mxcli/mxbuild cache, and a mismatch means a second multi-hundred-MB download and two runtimes to keep straight — which also means the cached-version rule applies to the solution as a whole, not per app.

Provision

Substitute the answers for <AppName>, <version> and <theme> throughout. For a solution, do steps 1–3 once per app and read "If this is a solution" first. The commands below say ./mxcli because that is where the seed prompt puts the binary — drop the ./ if it came pre-installed on PATH.

1. Create the app at the repo root — that is where .claude/ and the ./mxcli binary have to live for future sessions to self-bootstrap. mxcli new refuses to write into a directory that is not empty, and a git repo always has .git, so create it in a subfolder and move it up:

   ./mxcli new <AppName> --version <version> --theme <theme>
   rm -f <AppName>/mxcli        # a hardlink to the ./mxcli you just ran; mv would
                                # refuse it as "the same file". Still needed when
                                # mxcli is already on PATH — `new` hardlinks it
                                # into the project either way.
   rm -rf .ai-context           # the seed prompt's own `mxcli init --sync-skills`
                                # wrote this; `mxcli new` writes its own copy from
                                # the same binary, so the one here is a stale
                                # duplicate and `mv` fails with
                                #   mv: cannot overwrite './.ai-context': Directory not empty
   shopt -s dotglob && mv <AppName>/* . && rmdir <AppName>

   mxcli new also runs mxcli init, which writes .claude/settings.json with a SessionStart hook plus the .claude/bootstrap-mxcli.sh it runs — check that the .mpr named in the script is right after the move.

2. Confirm the Claude tooling: ./mxcli init --tool claude. Idempotent — it is what step 1 already ran, and re-running it is the cheapest way to be sure the hook, skills and commands are in place.

3. Bring prerequisites up: ./mxcli run --local --setup --ensure-db -p <AppName>.mpr (caches MxBuild + runtime, starts Postgres, creates the app database).

4. Write the brief to README.md at the repo root: the app name(s), the answers to Q3–Q5 in the user's words, and the theme and Mendix version used. For a solution, say which app owns what and how they talk to each other. Say that the project's MDL scripts are mdl 1: each one starts with mdl 1;. This is what tells the next session — after an idle reap, with none of this conversation — what it is building. Keep it short enough that it stays true.

5. Start a FINDINGS.md at the repo root and keep appending to it as you work. Log anything surprising or broken: an mxcli command that errored, a workaround you applied, a mxcli check that passed but a real mx check later flagged. Note the Mendix + mxcli versions, the MDL language version the scripts use (mdl 1), and how each finding was verified. This is durable context for the next session, and the most useful thing to share back to improve mxcli.

6. Record the plan in the brain — unless the user opted out at Q8:

   ./mxcli brain init -p <AppName>.mpr
   ./mxcli brain capture "<one requirement, in the user's words>" \
     --slice 01-<first-slice> -a @<AppName>Module.<WhatWillImplementIt> \
     -p <AppName>.mpr
   ./mxcli brain staged -p <AppName>.mpr    # then promote each

   Split the requirements into slices you could deliver one at a time, named with a numeric prefix so they sort into a roadmap: 01-accounts, 02-approvals. Anchor each requirement at what will implement it — the entity, microflow or page you are about to create. The anchor points forward, so naming something that does not exist yet is correct here, and it is what makes ./mxcli brain plan a real progress report instead of a checklist.

   Read .ai-context/skills/project-brain/SKILL.md before doing this.

   Two things to keep straight, because they are easy to conflate:

   • README.md is the brief — what the app is, in the user's words, for a human landing on the repo. One page, written once.
   • docs/brain/plan/ is the scope — the individual requirements, anchored and countable, appended to as they emerge.

   Never write a status or a tick-box next to a requirement. Whether it is built is computed by ./mxcli brain plan from the model; a hand-maintained status is wrong the moment anyone builds anything, and nothing will tell you.

7. COMMIT everything now — <AppName>.mpr, .devcontainer/, .claude/ (the SessionStart hook and .claude/bootstrap-mxcli.sh), README.md, FINDINGS.md and docs/brain/. This step is mandatory, not housekeeping: the seed prompt is a one-time seed, and committing its output is what makes every later session bootstrap from files instead of from a re-paste. The mxcli binary itself stays git-ignored (~85 MB); the bootstrap script is what fetches it back into a fresh clone, so committing the script is what makes the hook survive a reap.

8. Boot and verify: ./mxcli run --local --watch --detach -p <AppName>.mpr returns once the app answers (or prints why the boot failed, exit 1) — report its one line. Manage it with ./mxcli run status|wait|stop, never nohup, poll loops or pkill.

9. Take the quality baseline — run the two gates that score the project, on the blank app, before any of your own work is in it:

   ./mxcli lint -p <AppName>.mpr
   ./mxcli report -p <AppName>.mpr --format markdown

   Report the warning count and the six category scores, and put them in FINDINGS.md with the date. This is the only moment the numbers mean "what the template ships with" — afterwards every figure is yours plus the template's, and there is nothing to subtract. A blank app is not expected to score zero warnings; knowing which ones it starts with is what stops you chasing them later. Read .ai-context/skills/assess-quality/SKILL.md before interpreting the report — it covers what each category means and which findings are worth acting on.

10. (Optional) browser preview from a cloud session: ./mxcli run --hub https://hub.mxcli.org -p <AppName>.mpr, and report the preview URL it prints. Needs MXCLI_HUB_KEY on the environment; without it, continue as a normal local run. --hub ships in the Linux build only (a cloud session is a Linux container, so it works there); on a native Windows/macOS mxcli it fails with an explanatory message — continue as a normal local run.