During a run
What a LEX AI run looks like while it is happening: the four workflow shapes, when to answer or intervene, what not to touch, and how finalize behaves.
During a run
Once a workflow starts, the assistant follows a predictable rhythm. Knowing what to expect makes it easy to follow along, intervene when useful, and stay out of the way when not.
The rhythm, by shape
The mode's shape tells you what the run will look like.
- Coordinator step loop — Forward, Backward and MVP Completion walk numbered steps in order: get the next step, delegate it to a step agent, record it, move on. Forward and MVP Completion also commit and push after every step.
- Flat catalogue — Edit, Review, Test and Input run their tasks in any order and then finalize. Nothing is gated on sequence; what is gated is evidence.
- Checkpoint-gated — MVP Generator passes six checkpoints (plan, scope, scaffold, implementation, boot-check, finalize).
- Question-ordered — Brief asks one question at a time until the contract is complete or you end the interview.
Deploy is sequential, but its step bodies come from the remote Lex deployment handbook rather than a local catalogue, so there is no fixed count to tick down.
What you should do
- Watch the summaries. Each completion record says what was done. If one looks wrong, say so — it is easier to correct early than to unwind later.
- Answer questions when they come. Questions arrive one at a time, and in Brief mode exactly one is ever outstanding. Depending on your environment a question reaches you as a host dialog, a local form on
127.0.0.1, or plain text relayed by the assistant. A dialog stays open for 120 seconds by default; if it lapses the ask falls through to the next rung — the local form, then plain text — and the run continues. - Say "I don't know yet" if that is the truth. Declining is recorded as a disclosed gap together with the assumption made in its place, which is safer than a confident guess nobody can find later.
- Fill the questionnaire (Backward). The single pause at step 07 needs your business knowledge; the documentation phase cannot finish without it.
- Hand over files rather than describing them.
read_input_fileconverts a.csv,.tsv,.txt,.xlsx,.xlsm,.xlsor.pdfto markdown server-side;render_pdf_pagesrasterises pages so a scan or chart with no text layer can still be read. - Edit docs or drop data if needed. In forward-style runs, editing a planning doc or adding a recognised data file between steps triggers re-execution from the earliest affected step. That redirect returns
ok: true— it is a redirect, not a failure. Docs drive code, and code drives docs.
What you should not do
- Don't switch git branches during an active forward-style run. Steps commit onto the current workflow branch; a manual branch change misplaces commits.
- Don't run git yourself in the modes the MCP owns (Forward, MVP Completion). The backend handles commits, pushes, and the final PR.
- Don't hand over a credential value. In Deploy, a secret value is never written into a step record, note, index row, report or log line — only the key name and where it belongs. You place the value;
.env.exampleis the artifact the run produces. - Don't work around an
ok: falseerror. Stop, read the troubleshooting block, resolve the underlying issue, and let the assistant retry the same tool.
If a tool "disappears"
A stale_tool_call: true response means the IDE cached an old tool list after a mode switch. Refresh the tool list, switch mode if a suggested_mode is named, then retry. Don't improvise. See Troubleshooting.
Finishing
Forward-style runs end with a two-stage finalize_workflow: the first call returns audit instructions and per-step summaries so the coordinator writes plans/technical_docs/audit-report.md itself, and the second refuses until that file exists before opening the PR and squash-merging it. Flat modes end by writing a consolidated report you commit yourself. A finalize that refuses is doing its job — Test will not issue a clean report while a mandatory responsibility is incomplete, and Deploy will not finalize when no step was recorded. See Outputs and artifacts and Handoff.
Was this helpful?
Your feedback shapes what we write next.
