Execution model
How the coordinator-agent loop drives all ten LEX AI modes, where step briefs come from, and why the server owns the ordering, the gates and the error handling.
Execution model
LEX AI runs on a coordinator-agent model. Understanding it explains why runs are reliable, why context stays lean, and why the assistant delegates instead of doing everything inline.
Two layers
- Coordinator — your IDE assistant. It is a lightweight flow controller. It calls an MCP tool, receives the next brief plus the name of a specialized agent, invokes that agent, and reports the result back to the server. It does not do the step/task work itself when an agent is named.
- Agents — focused sub-assistants with a single responsibility (for example
lex-step-04for architecture,lex-edit-lex-implementerfor a code change,lex-review-conventionfor an audit). They read the relevant docs and produce the actual output.
This division keeps the coordinator's context window small and makes each unit of work self-contained and repeatable.
The tool loop
All ten modes are driven by the same rhythm:
get the next brief → delegate to the named agent → report completion → repeatMode | Brief tool | Completion tool |
|---|---|---|
Forward / MVP Completion |
|
|
Backward |
|
|
Edit |
|
|
Review |
|
|
Test |
|
|
Input |
|
|
Deploy |
|
|
Two modes vary the shape. Brief is question-ordered rather than agent-ordered — get_next_question → submit_answer, one question outstanding at a time. MVP Generator runs six checkpoints, each closed by its own tool; the last of them, finalize_mvp, is refused while any critical item from run_boot_checklist() is still failing. Every mode opens with a mandatory kickstart call and closes with its own finalize.
Where a brief comes from
The flat modes hold their task catalogue locally. Forward and MVP Completion are split: the 20-step spine is local, but each step body below 15 is served by the remote Lex handbook, and only the technical-map wiki phase from step 15 on is built locally. Deploy holds nothing locally — its step bodies all come from the remote Lex deployment handbook, which is why it has no fixed local step count. Synthesizing one locally is forbidden — if the remote cannot be reached the tool halts and names the settings to check, rather than inventing a plausible instruction for a production system.
Delegating without native subagents
The three GitHub Copilot surfaces and Claude Code spawn agents natively. Cursor, Codex and Windsurf do not, so the same agent files ship to a neutral .lex/agents/ tree and the workspace rules state the protocol: read the agent file in full, execute it as one focused sub-task, drop the working detail, report the summary. The no-skip, halt-on-ok: false and hands-off-git rules are restated verbatim. Only the spawning mechanism differs — see Agents and prompts.
The server enforces order and gates
The model does not decide the process; the server does. It:
- returns the correct next step and the agent to use;
- detects user edits between forward steps and rewinds to the earliest affected step;
- advances the deploy cursor only on a completed status, so a blocked step is returned to rather than passed;
- gates finalization behind checklists (MVP), an audit report (Forward) and mandatory responsibilities (Test);
- owns git in Forward and MVP Completion, and makes local commits in MVP Generator; the other modes leave git alone.
Structured errors, not stack traces
When a tool fails it returns ok: false with a troubleshooting block. Every payload carries an ok key, so the rule always has a field to evaluate, and the rule is strict: stop, show the troubleshooting to the user, wait, then retry the same tool once resolved. It must not improvise a workaround, run git to "fix" infrastructure, or silently continue. A special stale_tool_call: true variant means the IDE cached an old tool list — refresh the tool list, switch mode if a suggested_mode is given, then retry.
This is why LEX AI runs are deterministic: the process, the gates, and the error handling all live in the server, not in a prompt. See Tool surfaces for what each mode exposes.
Was this helpful?
Your feedback shapes what we write next.
