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.

A
Written By Atakan KayaLast updated 3 months ago

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

  1. 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.
  2. Agents — focused sub-assistants with a single responsibility (for example lex-step-04 for architecture, lex-edit-lex-implementer for a code change, lex-review-convention for 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  →  repeat

Mode

Brief tool

Completion tool

Forward / MVP Completion

get_plan_step(step=N)

notify_step_complete(step=N)

Backward

get_reverse_step

notify_reverse_complete

Edit

get_task_brief

notify_task_complete

Review

get_review_brief

notify_review_complete

Test

get_responsibility_brief

notify_responsibility_complete

Input

get_change_brief

notify_change_complete

Deploy

get_deployment_step(N)

notify_deployment_step_complete(N)

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.