Stage 4: the build

Tests first, one small phase at a time, with proof saved

TLM Forge builds your change in small, numbered phases. In each one, tests are written first and must fail, then the code makes them pass. What counts as passing is committed before the tests run, and the real results after. Your full existing test suite runs at the end.

How it startsRuns automatically
Runs onMedium and Deep tasks (Light tasks use tests-first without the documents)

How to use it

/tlmforge:build

You do not run this step yourself. It happens inside /tlmforge:build on Medium and Deep tasks, after the plan is written and the plan reviewers have started. Light tasks follow the same tests-first rule, just without the phase documents.

Words you will see on this page

Phase: One small chunk of the build with its own tests, documents and commit.
RED / GREEN: RED means the new tests fail, as they should before the code exists. GREEN means they pass once it is written.
Test suite: All the tests your project already has.
Unit, integration, end-to-end: Tests of one piece alone, of pieces working together, and of a whole user flow.
Evidence file: phase-N-evidence.md, the file holding a phase's real test output.
Final review (Stage 5): The step after the build, where several AI reviewers read the whole finished change at once.

Which tests a phase needs

Test type	What it checks	Required when
Unit	One piece of code on its own	Always, for new logic
Integration	Pieces working together	The change crosses a module boundary or touches files, a database, the network or a queue
End-to-end	A whole user flow	The change affects a user-facing flow or a public API

The documents each phase leaves behind

Document	Written	What it holds
Phase spec	Before coding	Goal, files to change, tests to add, how to undo it
Verification plan	Before tests run	Each check, its command, what passing looks like
Evidence	After the run	Real test output, counts by test type, steps to reproduce
Summary	End of the phase	Differences from the plan and honest weak spots

What it does

Each phase leaves a short set of documents in specs/<feature>/, committed with your code. Before coding: a phase spec (goal, files to change, tests to add, how to undo it) and a verification plan (each check, its exact command and what passing looks like). After the run: an evidence file with the real test output, and a summary of anything that differed from the plan, plus the weak spots a tough reviewer would attack.

Inside a phase the loop is strict. Tests come first and are run to confirm they fail, because a test that passes before the code exists proves nothing. Then Claude writes the minimum code to make them pass. Unit tests are always required for new logic. Integration tests are added when the change crosses a module boundary or touches files, databases or the network. End-to-end tests are added when it affects a user-facing flow or public API.

While iterating, only the tests affected by the change run, to keep each loop fast. Your full existing suite runs once at the end of the build, and again on the final version for the final review. Independent parts of a phase can be built in parallel by helper agents, but phases stay in order and each is its own commit. Nobody reviews each phase; everything is reviewed once, together, in the final review (Stage 5).

How it works, step by step

Write the phase spec
Before any code, a short document lists the goal, the files to change, the tests to add and how to undo the phase.
Commit what passing means
A verification plan lists each check, its command and what passing looks like. It is committed before any test runs, separately from the results.
Write tests and watch them fail
Tests are written first for every type that applies, then run. They must fail, because the code does not exist yet.
Write the code and watch them pass
Claude writes the minimum code needed. The new tests and the tests that use the changed code must pass, and the build must compile cleanly.
Save the proof and move on
The real test output and an honest summary are saved, the phase is committed and pushed, and the next phase starts.
Run everything at the end
After the last phase, your full existing suite runs once to confirm nothing else broke. Slow checks, such as an emulator run, run once per version of the code and their output is saved.

What it looks like

The end of an evidence file, the proof saved after a phase: test counts by type, a check that the old tests still pass, and the exact steps anyone can follow to get the same result. Real format, made-up numbers and names.

## Summary
- Unit: 14 passed, 0 failed, 1.8s
- Integration: 3 passed, 0 failed, 6.2s
- E2E: not applicable
- Regression check (impacted tests; full suite on the last phase): 412 passed, 0 failed (unchanged from pre-phase)

## Reproducibility
A reviewer can reproduce all of the above by:
1. Checkout commit 3f9c2a1
2. Run pytest tests/test_payments.py -q
3. Observe 14 passed

Why it is better

Passing is defined before the run

Without a record, nothing shows the pass criteria were set before the results came in. With TLM Forge, the criteria and the results are separate commits, so the history shows which came first.

Every test has failed once

Without a fail-first check, a test that passes no matter what can slip through. With TLM Forge, every new test must fail before the code is written. TLM Forge's instructions call skipping this the top reason features ship broken.

Fast while building, thorough at the end

Running every test on every change is slow. With TLM Forge, only affected tests run while building, and the full suite still runs at the end, so speed does not replace the regression check.

An honest record

Without a record, what changed from the plan gets lost. With TLM Forge, each phase writes down its deviations and weak spots, and a gap found later gets a new document instead of an edit to the old one.

Good to know

There are no reviewers at the end of each phase. TLM Forge measured 0.5 to 1.2 CRITICAL or HIGH findings per reviewer run there, against 3 to 8 when reviewing the plan, so everything is reviewed once, together, in the final review.
Tests-first is something TLM Forge tells Claude to do. No built-in check confirms a test failed before the code was written. On Pro, a check built into the plugin does stop code edits until the design has been shown to you and you have replied.
On Deep tasks, the first phase's tests wait for the tester's list of edge cases from plan review. That is the only time the build waits on a plan reviewer.
Plan-review findings that arrive mid-build are sorted between phases. Say "pause for review" at any time to wait for the background reviewers and see open counts, then "resume" to continue.
The phase documents are committed with your code, so the proof travels with the branch.

Related features

Get TLM Forge