Handoff

Why a LEX AI run survives leaving the chat session: the durable artifacts each mode writes, the read-only status tools, and how to resume in every mode.

A
Written By Atakan KayaLast updated 3 months ago

Handoff

LEX AI is built so no run is trapped inside a single chat session. State lives in files, not in the assistant's memory, so you can stop, hand the project to a teammate, or resume in a brand-new IDE session and continue where you left off.

What makes handoff work

Every run writes durable artifacts:

  • A session manifest per mode — .lex-brief/, .lex-workflow/ (Forward and MVP Completion), .lex-reverse/, .lex-edit/, .lex-review/, .lex-test/, .lex-input/, .lex-deploy/, .lex-mvp/. Each records what has been completed, and in forward-style runs which files each step changed.
  • The project contract — .lex/contract.md, written by Brief, stays tracked in git and is hand-editable. Its fields carry provenance, so a reader can tell what you decided ([USER-REQUIRED]), what the assistant drafted and you confirmed ([LLM-FILLED]), and what is still an unvalidated default ([AUTO-FILLED]).
  • Plans and reports — plans/, technical-map/, edits/, reviews/, test-runs/, input-changes/, deployment/, mvp/<run_id>/: the plan of record, the audit trail, and the technical knowledge layer.
  • Git history — Forward and MVP Completion commit every step onto the run branch with structured messages like [step-04/planning] ..., so the history itself reads as a log.

Check where a run stands

Every mode ships a read-only status tool that takes no arguments and is safe at any point: get_workflow_status, get_reverse_status, get_brief_status, get_edit_status, get_review_status, get_test_status, get_input_change_status, get_deployment_status, get_mvp_status. Ask for the one belonging to the active mode before doing anything else in a fresh session.

Resuming a forward-style run

In a fresh IDE session, /lex-resume drives:

resume_workflow(...)

It reconfigures the workflow remote, fetches, checks out the highest <repo>/run-NN branch, and loads .lex-workflow/manifest.json — or reconstructs the completed steps from git log subjects if the manifest is missing. It does not mutate history; it restores context and names the next action. For a brand-new run on an existing repo, use kickstart_run(...) instead.

Resuming other modes

  • Backward — /lex-reverse-resume. If the run paused at the questionnaire, complete discovery-questionnaire.md and call submit_questionnaire(...).
  • Brief, Review, Test, Input, Deploy — call the mode's kickstart again on the same project. Finding a manifest on disk, it resumes that session instead of starting a new one; pass force_new=true when you genuinely want a clean run. Brief goes further and adopts any hand-edits you made to .lex/contract.md between sessions as your own words, then validates them.
  • MVP Generator — kickstart_mvp(resume=true) restores the run from its manifest.
  • Edit — no resume path. Read edits/_index.md and the in-progress EDIT-REPORT.md, then start a fresh edit session scoped to what is left.

Handoff to a person

Because the contract, the plans, and the technical map are written down and versioned, a teammate can open the repo, read .lex/contract.md, plans/technical_docs/, and technical-map/, and see what was decided and built without replaying the chat. Answers given during a run are recorded with their origin, so it stays visible whether a decision came from the user directly or was relayed through the assistant.

Practical tips

  • Commit and push before handing off. Forward and MVP Completion do this per step; MVP Generator makes a best-effort local commit per checkpoint but never pushes; every other mode leaves the commit to you.
  • Don't switch branches mid-run.
  • Have the next session run lex ai-verify first, so it starts from assets that match the installed build.

See During a run and Outputs and artifacts.

Was this helpful?

Your feedback shapes what we write next.