Build

Build is the fourth step of the Flow workflow. In this guide, you will learn:

• What the build skill does and how it stays on plan
• The difference between TDD mode and no-tdd mode
• How build escalates when reality diverges from the plan

Overview

The build skill implements a planned change. It is the only skill in the workflow that writes application code. Everything before it produced plans; build turns those plans into a working change.

You invoke it with the change name:

/flow-build project-archiving

Build does not improvise. It executes a contract you already approved, and when the codebase does not match that contract, it stops and asks rather than guessing.

Two modes

Build runs in one of two modes, and the skill picks the mode for you.

In TDD mode, the default, build works from the test plan. It walks the ordered test list and, for each test, runs a strict cycle: write the test, run it and prove it fails for the right reason, implement just enough code to satisfy it, run it again and prove it passes, then run the rest of the file to guard against regressions. Code is written one test at a time, and nothing is implemented ahead of the test that needs it.

In no-tdd mode, build works from the blueprint alone. It walks the blueprint's sections in order and implements each artifact they declare. No tests are written or run. You opt into this mode by passing the --no-tdd flag:

/flow-build project-archiving --no-tdd

Staying on plan

Build is deliberately constrained. It treats the blueprint and the test plan as a contract, and it implements every framework detail against the knowledge base, never from memory.

Before it writes or overwrites any file, build classifies that file against the plan. A file that matches the plan is left alone. A file that is absent is implemented. A file that is present but diverges from the plan is drift, and build does not silently resolve it.

When build hits drift, or finds a harness doc that contradicts the plan, or needs an artifact the plan never declared, it stops and reports a BUILD DRIFT notice. The notice states what the plan declared, what the file actually has, and a short list of options: overwrite with the plan's version, keep the existing file, amend the plan, or abort. You decide. When build gets genuinely stuck, it reports BUILD PAUSED instead, with the failing output and its best guess at the cause.

This is the point of a separate build step. The plan was reviewed; build holds the code to it, and surfaces every place reality refuses to cooperate instead of papering over it.

The quality gate

Build runs a quality gate as it goes. After each phase of the work it runs the project's format, lint, and typecheck commands. Lint and typecheck are hard gates: they must pass before build moves on, and a failure escalates to you. A final gate runs the full test suite (in TDD mode) once all the work is done.

When the final gate passes, build stamps the plan files as built. That stamp is what the next step checks.

Next step

• Hand off to the Sync skill to promote the change into Flow's canonical state.