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.
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, completediscovery-questionnaire.mdand callsubmit_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=truewhen you genuinely want a clean run. Brief goes further and adopts any hand-edits you made to.lex/contract.mdbetween 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.mdand the in-progressEDIT-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-verifyfirst, 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.
