Forward

Forward mode builds a Lex app end to end across 20 steps on its own GitHub run branch, starting either from a project contract or from a prose description.

A
Written By Atakan KayaLast updated about 1 month ago

Forward

Forward mode builds a Lex app end to end through a deterministic 20-step workflow (steps 0–19). Of the ten modes it is the most complete, and one of only two — the other is MVP completion — that touch GitHub remotely: it creates the repository, drives every step onto its own run branch, and finishes by opening and merging a pull request.

Slash commands: /lex-app "<project description>" to start, /lex-resume to pick up an interrupted run.

The mandatory shape

/lex-app "..."                          # you describe the product
kickstart_workflow(...)                 # first call; repo, run-NN branch, issue
loop step N = 0..19:
    get_plan_step(step=N)               # brief + agent + docs to read
    runSubagent("lex-step-NN", ...)     # the step agent does the work
    notify_step_complete(step=N, ...)   # commits + pushes the run branch
finalize_workflow()                     # stage 1 — audit instructions
finalize_workflow(audit_complete=True)  # stage 2 — PR, squash-merge, close issue

Stage two refuses to run until plans/technical_docs/audit-report.md exists on disk — the one piece of work the coordinator does not delegate.

The 20 steps by phase

Phase

Steps

Purpose

Planning

0–8

Overview → I/O schemas → requirements → user story → architecture → functional breakdown → diagrams → pseudocode → rule compliance

Implementation

9–11

Implementation plan → blueprint → full code delivery

Hardening

12–14

Initial data upload → Streamlit or Reflex dashboards → code-level Lex compliance

Wiki

15–18

technical-map/ AST scaffold, written once and never over an existing file, then enriched

Sync

19

Forward ↔ backward doc and code reconciliation

From a project contract

kickstart_workflow and kickstart_run both take contract_path, defaulting to .lex/contract.md — the artefact Brief produces. The server parses it, records its sha256, and puts it in front of every step agent as statements you agreed to, so they are requirements rather than assumptions. Without one the run proceeds from your prose description.

Git and GitHub behaviour

  • Kickstart — creates the GitHub repo, runs git init, commits and pushes the default branch, then cuts <repo-or-requested-name>/run-NN and opens a tracking issue.
  • Per step — notify_step_complete commits the worktree as [step-04/planning] <summary> and pushes the run branch.
  • Finalize — stage two opens the PR, squash-merges it, pulls the default branch and closes the issue. The merge is attempted on every finalize and no supported setting disables it.
  • The backend owns git — the coordinator never runs git itself, because a hand-run commit breaks the step-to-commit attribution that resume and rewind depend on.

Resuming and recovering

  • New run on an existing repo — kickstart_run(...) cuts a fresh run-NN branch without git init, and routes step 11 to the refactoring agent rather than full implementation.
  • New session on an in-progress run — resume_workflow(...) rehydrates from .lex-workflow/manifest.json, or reconstructs it from the git log, without mutating history.

Input files and questions

Step 1 documents your production schemas, so read_input_file reads the file server-side and returns markdown — .csv, .tsv, .txt, .xlsx, .xlsm, .xls, .pdf — with column names verbatim, because a prettified name is one the app will never match. render_pdf_pages rasterises the pages you name as images, for scans and charts that carry no text layer, and ask_user_question puts a question to you directly wherever the host can render a dialog.

Keeping docs and code in sync

Edit a planning document or drop a new data file between steps and get_plan_step notices, commits it as [user-feedback] ... and re-runs from the earliest affected step; new data forces re-execution from step 2. The redirect returns ok: true — it is a redirect, not a failure.

The numbered agents are spawned natively on the Copilot surfaces and Claude Code; on Cursor, Codex and Windsurf they ship to .lex/agents/ instead. See Supported coding tools.

Was this helpful?

Your feedback shapes what we write next.