Skip to content

Latest commit

 

History

History
98 lines (76 loc) · 7.19 KB

CONVERSION-RUNBOOK.md

File metadata and controls

98 lines (76 loc) · 7.19 KB

Conversion Runbook — Start Here

This is the thin front door. The executable detail lives in skills/conversion-runbook.md — the stage matrix, the interview protocol every gate runs, and the done-checklist. This file only tells you how to start and what to expect.

Prefer a visual walkthrough? Open toolkit-guide.html in a browser (open toolkit-guide.html) — the same journey as a guided page, including the "something went wrong" section. Agents: open it for the user only under the first-touch rule in CLAUDE.md (sentinel <project-root>/.claude/.guide-shown absent), never once per session.


How to start

git clone https://github.com/MendixMau/mxcli-project-toolkit.git ~/Mendix/mxcli-project-toolkit
~/Mendix/mxcli-project-toolkit/bin/init-project.sh <project-root>

<project-root> is your project's own folder (usually its git repo) — scaffolding, analysis output, architecture, and the .mpr all live inside it. Never create a sibling analysis/<project>/ next to the project.

Then open your agent (Claude Code or equivalent) in <project-root> and say what you're starting from. The agent picks the entry mode (skills/conversion-runbook.md → "Entry Modes"):

Starting from Mode Stages
Legacy source code Migration P, 0–7
Requirements/specs only, no code Requirements-driven P, 1–6
Just an idea — a real app Requirements-driven, the conversation as the source P, 0–6
Just an idea — a demo Build type: poc (skills/poc-build.md) its own steps 1–9
A live Mendix app you are changing Change an existing app P, 0–6 per change

Running unattended — the kick-off brief

The single source of the text an unattended run (Interview mode: auto) is started with. A project brief quotes it, verbatim, instead of writing its own; add the project's own goal and sources under it, never a different definition of done.

Follow the toolkit's process: skills/conversion-runbook.md, from Stage P, stage by stage.
1. Run bin/init-project.sh <project-root> first, before writing PROJECT.md or touching the model.
2. Declare the entry mode and build type at kickoff (intake Q1 and Q16); never switch them later
   without a recorded decision (conversion-runbook.md → Entry Modes, "Mode changes are decisions").
3. Stage 5 only after stages 1-4 pass their gates and bin/gate-check.sh <p> build-ready passes.
4. Close every stage on a clean gate (bin/gate-check.sh <p> <stage>) and commit its output.
5. Stop at a gate that does not pass; report it, do not route around it.
"Done" is the declared mode's steps done and their gates clean — not only journeys passing.

Failure it prevents (two field runs, 2026-11): the project instructions said "follow the runbook", but the brief the agent read first defined done as journeys passing under a time budget and never mentioned stages. The agent built about 78 pages with no plan. Five earlier field builds, whose briefs said in effect what the lines above say, followed the stages.

Where you run this — detected, not asked

You do not pick an environment; bin/doctor.sh detects it from where the session started, and the agent records it once in PROJECT.md (Environment: cloud | devcontainer | local | local-linux). Every stage runs headless — the build gate is mxbuild, mxcli new creates the app, mxcli run --local serves it, Playwright and OQL test it — so Studio Pro is never on the critical path and the lane only changes how you see the app and which write modes exist:

Where the chat started Detected lane What that means for you
Claude Code on the web / mobile cloud — the default when you have nothing installed Nothing to install. The container is ephemeral, so the agent commits and pushes at every gate. You see the app through a preview URL (mxcli run --hub). Setup order: skills/cloud-dev-environment.md. Network policy must allow cdn.mendix.com; GitHub Releases too, or build mxcli from source when Releases 403s (the skill has the recipe) — hub.mxcli.org for the preview.
Terminal Claude Code in a VS Code devcontainer / Codespaces devcontainer Same headless lane as cloud, on your own disk — nothing ephemeral, no network policy to negotiate.
Terminal Claude Code on your Mac or Windows machine local Everything above, plus the two write modes that need Studio Pro open (--mcp, hand-rolled MCP) and the Studio-Pro-only operations (ALTER SETTINGS, security level). Windows: Git Bash — README.md → Platform support.

The default is simply where you are. Start there; the lanes are not exclusive. A model built in the cloud opens in any Studio Pro later (skills/handoff-to-studio-pro.md), and a local project can be pushed and continued from the web. The agent may mention the other lanes when one would help (a preview link for a stakeholder, a Studio Pro session for UI polish) — it does not ask you to choose up front.

Agents: never conclude "this cannot be built here" from the absence of Studio Pro — run bin/doctor.sh and let the detected lane decide (real misfire, 2026-09-03: a cloud session read the then local-first front door and announced Stages 5–7 impossible in the container, before mxcli run --local was even probed).

What to expect

  • The pipeline interviews you at every gate: the agent proposes 2–4 options with evidence from your actual source, states its assumptions, and asks you to correct it — it never asks what it can derive itself.
  • If you don't know an answer, the run doesn't stall: the recommendation is applied and recorded as ASSUMED in PROJECT.md with the risk if wrong. Hard gates (✋) are the exception — those need an explicit CONFIRMED answer (under Interview mode: auto: skills/interview-protocol.md §"What auto obliges you to do").
  • Every stage ends with bin/gate-check.sh <project-dir> <stage> — a mechanical check that required artifacts exist, which also regenerates your project dashboard (index.html).
  • Verdicts: PASS, PENDING (not there yet — not started is not failed), FAIL (something is there and it is wrong), WAIVED, MANUAL.
  • Already underway when you wired this in? Say so once — bin/gate-check.sh <project-dir> --adopt <stage> --reason "..." — and every earlier stage reports WAIVED instead of red. --waive <stage> does one stage. See the runbook's "What a gate verdict means" in §2.
  • Every decision ends up in exactly one place: PROJECT.md, your project's decision register.

The stages at a glance

P  Kickoff        → intake + workspace scaffold
0  Triage ✋       → extractor reuse-vs-build decision, scope ordering
1  Analysis       → code extractors + document extraction + SME interview
2  Requirements   → validated BRDs
3  Architecture ✋ → module boundaries, buy-vs-build, security, NFRs, branding
4  Build Plan ✋   → numbered, dependency-ordered script plan
5  Build          → working modules, gated (CE-error-free ≠ done)
6  Test           → Playwright + DB assertions
7  Cutover ✋      → legacy data decision, rollback plan (migrations only)

Full detail, gates, owners and artifacts: skills/conversion-runbook.md.