Edit

How edit mode makes one focused change to an existing Lex app: the 22-task catalog, the sustainability checks the server injects, and when another mode fits better.

A
Written By Atakan KayaLast updated 3 months ago

Edit

Edit mode makes one focused change to an existing Lex app — a bug fix, a small feature, a targeted refactor — with safety checks the server adds for you so the change stays Lex-compliant and does not silently break its dependents. It is a flat workflow: no step loop and no mandatory ordering. Since 1.2.1 it version-controls its own work: a branch per run, one commit per task, and a pull request at the end. Slash command: /lex-edit.

The flow

/lex-edit
  ↓
kickstart_edit(project_path, change_description, context="")
list_edit_tasks()                        # inspect the catalog (optional)
propose_edit_plan(change_description)    # heuristics, not a decision
  ↓
set_edit_plan(task_ids=[...], rationale="why these and not more")
  ↓ server auto-injects the sustainability tasks
loop for each task:
    get_task_brief(task_id) → run the named agent → notify_task_complete(task_id, ...)
    # or: waive_task(task_id, rationale) for a waivable check
  ↓
finalize_edit()                          # writes edits/EDIT-REPORT.md

project_path accepts a local path or a git URL, which the server clones into a working copy first.

Pick the minimum set of changes

The catalog holds 22 tasks — 16 code-change tasks you choose from, and 6 sustainability tasks you never choose. propose_edit_plan hands back the catalog and the picking rules but deliberately infers nothing: you hold the change description and the codebase, the server does not. Prefer one to three code-change tasks; a list growing past five is a signal that separate changes are being conflated and should run separately. set_edit_plan needs a written rationale and rejects sustainability ids passed as picks.

Auto-injected sustainability tasks

Task

Injected when

Waivable

lex-compliance-check

Any code-change task

No

dependent-code-scan

Any code-change task

Yes

tests-update

Any code-change task

Yes

docs-sync

Any code-change task

Yes

technical-map-sync

Public surface changes — models, calculations, serializers, permissions, auth, CLI settings, process admin

Yes

migration-check

A model-shaped change is planned

No

Four are injected on every plan, so quality work cannot be quietly left out of a plan. A waiver needs a rationale of at least 20 characters and is recorded in the report, which makes a skipped check a disclosed decision rather than an absence.

What the server enforces

  • Declared artifacts must exist — notify_task_complete refuses a completion whose declared files are not on disk, because an agent reporting success without writing anything is the common failure.
  • Nothing is left pending — finalize_edit refuses while any planned task is neither completed nor waived.
  • The coordinator routes, the agent works — each task brief names its own agent. On the Copilot surfaces and Claude Code those are native subagents; on Cursor, Codex and Windsurf they ship to .lex/agents/ and the workspace rules carry the delegation protocol. See Agents and prompts.

When another mode fits better

  • The input-data format changed — renamed columns, a new delimiter or encoding, a different row grain: see Input, which knows where a rename fails silently instead of raising.
  • The work is writing or proving tests — see Test.
  • The app needs to run somewhere — see Deploy.
  • You want findings, not a change — see Review.
  • It is really a new product or a full MVP expansion — see Forward and MVP workflows.

The targeted_edit scenario in Brief hands off here, so .lex/contract.md may already record what the user agreed to change.

Where output lands

edits/<run-id>/ holds one artifact per task, an auto-maintained _index.md, and EDIT-REPORT.md from finalize_edit. The run has its own branch: whatever you had uncommitted is checkpointed on your branch first, then each task is committed on its own as [edit/<task_id>] <summary>, and finalize_edit pushes and opens a pull request. It never merges — with several runs open on one base, merging would land one run's work underneath another still building on it. See Outputs and artifacts.

Was this helpful?

Your feedback shapes what we write next.