Outputs and artifacts
Where each of the ten modes writes its files, which artifacts get committed and pushed, and why the contract, plans and technical map outlive a single chat session.
Outputs and artifacts
Every LEX AI run leaves durable files in your project. These artifacts are the point: they are the plan of record, the audit trail, and the handoff memory that lets humans and future AI sessions continue the work.
This article is the full contract for them — every directory, every filename, which mode owns it, and what stays in git. It describes your Lex project, not the LEX AI package.
A path that is not in this article does not exist. Every artifact a mode writes has one decided home, and every mode that reads it reads the same one. That is what stops one mode quietly looking for a file another mode never wrote, which is the kind of failure that does not announce itself.
The naming rules
These generalise. Once you know them you can predict where a new artifact lands without looking it up.
Rule | Example |
|---|---|
One directory per mode, at the project root, plural, kebab-case |
|
A run's artifacts nest under the run id |
|
Ordered artifacts carry a two-digit prefix |
|
Workflow-step artifacts name the step |
|
Backward-workflow steps prefix the number with |
|
An auto-maintained chronological index |
|
The one consolidated report a run ends with, upper-case |
|
Session state is hidden, singular, prefixed |
|
Durable project records |
|
What each mode writes
<project root>/
│
├── Inputs/ normalised data models
├── Uploads/ models that accept input files
├── Reports/ report-generating models
├── <module>/CONTEXT.md per-module context, BESIDE the source
│
├── plans/
│ ├── technical_docs/ forward + completion
│ │ ├── step-00-overview.md
│ │ ├── step-01-io-schemas.md
│ │ ├── step-02-requirements.md
│ │ ├── step-03-user-stories.md
│ │ ├── step-04-architecture.md
│ │ ├── step-05-functional-breakdown.md
│ │ ├── step-06-uml-er.md
│ │ ├── step-08-rule-validation.md
│ │ ├── step-09-implementation-planning.md
│ │ ├── step-10-blueprint.md
│ │ ├── step-11-implementation.md
│ │ ├── step-11-refactoring.md (only when step 11 routes to refactor)
│ │ ├── step-12-initial-data.md
│ │ ├── step-13-streamlit-capabilities.md
│ │ ├── step-14-code-rule-validation.md
│ │ ├── step-19-cross-sync.md
│ │ ├── run.md run log — server-written
│ │ ├── audit-report.md written by the coordinator itself
│ │ └── questions-to-user.md
│ └── business_docs/ backward
│ ├── step-R00-structure-scan.md scanner-written
│ ├── step-R01-model-extraction.md scanner-written
│ ├── step-R02-data-flow.md scanner-written
│ ├── step-R17-gap-report.md
│ ├── discovery-questionnaire.md
│ ├── questions-to-user.md
│ └── business/
│ ├── 00-executive-summary.md
│ ├── 01-information-sources.md
│ ├── 02-business-outcomes.md
│ ├── 03-user-journeys.md
│ ├── 04-system-context.md
│ ├── 05-capability-breakdown.md
│ ├── 06-process-and-journey-maps.md
│ ├── 07-decision-logic.md
│ ├── 08-trust-governance-and-standards.md
│ └── 09-writing-review.md
│
├── technical-map/ the code wiki
│ ├── index.md
│ ├── overview.md
│ ├── glossary.md
│ ├── architecture/
│ │ ├── modules.md
│ │ ├── interaction-map.md
│ │ ├── external-dependencies.md
│ │ └── data-sources.md
│ ├── models/
│ │ ├── _index.md
│ │ └── <ModelName>.md
│ ├── conventions/
│ │ ├── patterns.md
│ │ ├── do-this-not-that.md
│ │ └── deviations.md
│ ├── errors/
│ │ ├── error-patterns.md
│ │ └── gotchas.md
│ └── step-07-pseudocode/ forward only
│ ├── _index.md
│ └── <module>.md
│
├── Tests/ test mode + the framework's own convention
│ ├── test_data.json root switchboard
│ ├── 00_reset.json deletes, reverse-dependency order
│ ├── <NN>_<what>.json ordered shared action files
│ ├── UploadFiles/<Area>/ real workbooks for FileField parameters
│ ├── GroundTruth/gt_*.xlsx expected numbers from outside the app
│ ├── scenarios/<scenario-id>_<slug>/test_data.json
│ └── test_<scenario-id>_<slug>.py
├── lex_test_config.yaml marker groups + tests entrypoint
│
├── test-runs/ test mode reports
│ ├── _index.md
│ ├── TEST-REPORT.md
│ └── <run-id>/
│ ├── scenario-matrix.json
│ ├── 00-story-assurance.md
│ ├── 01-scenario-matrix.md
│ ├── 02-chains.md
│ ├── 03-assertions.md
│ ├── 04-calculation-coverage.md
│ ├── 05-runner-config.md
│ ├── 06-execution.md
│ ├── 07-effectiveness-audit.md
│ ├── 08-chain-fidelity-audit.md
│ └── 09-gap-report.md
│
├── edits/ edit mode
│ ├── _index.md
│ └── <run_id>/
│ ├── task-<task-id>.md one per planned code-change task
│ ├── sustainability-<name>.md compliance | tests | docs |
│ │ technical-map | migration |
│ │ dependents
│ └── EDIT-REPORT.md
│
├── reviews/ review mode
│ ├── _index.md
│ ├── <type>-<run-id>.md type is business or convention
│ └── REVIEW-REPORT.md
│
├── input-changes/ input mode
│ ├── _index.md
│ ├── format-spec-<run_id>.md
│ ├── upload-parser-<run_id>.md
│ ├── data-model-<run_id>.md
│ ├── calc-fanout-<run_id>.md
│ ├── migrations-<run_id>.md
│ ├── reports-<run_id>.md
│ ├── serializers-<run_id>.md
│ ├── test-data-<run_id>.md
│ └── INPUT-FORMAT-CHANGE-REPORT.md
│
├── deployment/ deploy mode
│ ├── _index.md
│ ├── step-NN-<run-id>.md
│ └── DEPLOYMENT-REPORT.md
│
├── mvp/ mvp mode
│ └── <run_id>/
│ ├── 00-plan.md
│ ├── 00-scope.md
│ ├── 01-scaffold-manifest.md
│ ├── 02-implementation.md
│ ├── 03-boot-check.md
│ └── MVP-REPORT.md
│
├── docs/ THE SHIPPED HANDBOOK — read-only during a run
│ (delivered with the package, never a run output)
│
├── .lex/ durable records
│ ├── contract.md your requirements record (tracked)
│ ├── briefs/<run_id>.md one run's intake (tracked)
│ ├── prompt.md standalone contract prompt (brief mode)
│ ├── ai-assets.json onboarding manifest (ignored)
│ └── agents/ payload fallback for hosts with no agent dir
│
└── .lex-<mode>/ session state — never committed
├── .lex-brief/manifest.json
├── .lex-workflow/manifest.json forward + completion
├── .lex-reverse/manifest.json
├── .lex-edit/runs/<run_id>.json one manifest PER RUN
├── .lex-review/manifest.json
├── .lex-test/manifest.json
├── .lex-input/manifest.json
├── .lex-deploy/manifest.json
└── .lex-mvp/manifest.jsonHighlights
.lex/contract.md— what Brief produced: the agreed requirements, each field tagged[USER-REQUIRED],[LLM-FILLED]or[AUTO-FILLED]so nobody has to guess who decided what. It is hand-editable and stays tracked in git; Forward parses it at kickstart and points every step agent at it..lex/briefs/<run_id>.md— one run's own intake, as opposed to the project's standing record. A scoped run inherits the app's standing clauses fromcontract.mdwithout re-asking them, merging the brief over the record field by field..lex-<mode>/manifest.json— the session's memory: completed units and the files each changed.resume_workflowreads the forward manifest, or reconstructs it from the git log, to pick up where a previous session stopped.technical-map/— an AST-derived wiki with aCONTEXT.mdper source module. Forward writes the scaffold once and never overwrites an existing file; Backward'sgenerate_wikirebuilds it from the current scan, so re-running that replaces what is there.test-runs/— reports live here and never in a lowercasetests/, because on macOS and Windows that would collide with the Lex conventionTests/.deployment/— no secret value is ever written into a step summary, index row, report or log line: only the key name and where it belongs, with an explicit Secrets section saying so. The.env.exampleis the artifact, never a populated.env.
What goes in each directory
plans/technical_docs/ — forward and completion
The planning record. One file per workflow step, named for the step, written by that step's agent and read by every later step.
step-07 is the exception: it writes a directory of per-module pseudocode under technical-map/step-07-pseudocode/ instead of a single file, because the output is one file per service boundary. Steps 15 to 18 write only into technical-map/.
run.md is the run log, and it is machine-read. The literal ## Step Status Board heading and the - [ ] checkbox format must survive any hand-edit, because a run counts as complete only when every box in that section is ticked. Never paste a template over it.
audit-report.md is the one artifact the coordinator writes itself rather than delegating to an agent.
plans/business_docs/ — backward
step-R00 through step-R02 are written by the scanner rather than by an agent. The business/ sub-tree is the business-facing documentation set.
Tests/ — your test tree
Test mode writes here, but the layout is the LEX framework's own, not LEX AI's. Shared action files are flat under Tests/; a per-scenario chain root may sit at Tests/scenarios/<scenario-id>_<slug>/test_data.json. A large multi-module app instead puts chains beside the module they exercise, at <Module>/Tests/<period>/<region>/.
Follow whichever layout your project already uses — the chain report says which one it found.
The per-mode folders
Every one has the same three-part shape: an _index.md the server appends to, one artifact per unit of work, and a single <MODE>-REPORT.md written at finalize. Read one and you can predict the rest.
Edit is the one that differs, deliberately. Several edit runs can be open on one repository at once, so its session state is one manifest per run at .lex-edit/runs/<run_id>.json. A single shared manifest was overwritten by whichever run called a tool last.
MVP generator has no _index.md — its report sits inside mvp/<run_id>/.
Three things that surprise people
- The per-module
CONTEXT.mdfiles are not intechnical-map/. Each one is written beside the source it describes, at<module_path>/CONTEXT.md. Anything looking for them under the wiki tree finds nothing. - Backward's
business/numbering is independent of its step numbers. Backward step R-09 writesbusiness/01-information-sources.md. Check the tree above rather than inferring the pairing. - The delivered tree is restored, never pruned. A rename leaves the old file on disk in every project that already has it, which is why these names change very rarely.
Who commits what
- Forward and MVP completion commit and push their artifacts onto the run branch, then merge via pull request.
- MVP generator makes local commits only — one per checkpoint, never a remote and never a push.
- Edit commits its own work: a branch per run, one commit per task, then a pull request it deliberately does not merge.
- Brief, Backward, Review, Test, Input and Deploy leave artifacts in the working tree for you to review and commit. Deploy is deliberately git-free, because a deployment run writes configuration and an automatic commit is how a populated
.envreaches a remote.
Tracked or ignored
Anything a run is meant to produce stays in git. Session state never does.
Tracked | Why | |
|---|---|---|
Mode output directories | yes | Negated back into |
| yes | Your requirements record and each run's intake |
| yes | Your own prose around a managed block |
Generated payload, | no | Rebuilt on every tool call |
| no | See below |
Session state is not a tidiness rule. A manifest embeds a markdown window of every sample file you registered — your own data — alongside the full question-and-answer ledger, and Forward and Edit both push.
The generated MCP configs are gitignored for the same class of reason: they carry your GitHub token and remote access key. Setup cannot untrack what git already has, so it reports anything already committed and tells you to rotate any credential in a listed config.
Outside your working tree
Path | Holds |
|---|---|
| The roster of concurrent runs. In |
| A prepared checkout for a second chat |
| Operational telemetry. Not a project artifact |
Two names that break the pattern on purpose
plans/ holds technical_docs/ and business_docs/ in snake_case where everything else is kebab-case. Tests/ is capitalised because that is the LEX framework's own convention for a test tree rather than LEX AI's.
Both predate the conventions, and because the delivered tree is restored but never pruned, renaming either would strand the old directory in every existing project. Neither is renamable.
Why this matters
Because the contract, the plan and the technical map are written down and versioned, a run is never trapped inside one chat session. A teammate, or a new AI session in a different tool, can open these files and see what was decided, what was built and what remains.
And because the layout is a published contract rather than a convention, you can find an artifact without searching for it, review a change by opening one report instead of reading a diff, and notice when something is missing — because there is a written answer to what should have been there.
See Handoff and Git and GitHub next.
Was this helpful?
Your feedback shapes what we write next.
