Sync

Sync is the fifth step of the Flow workflow. In this guide, you will learn:

• What the sync skill does and what canonical state is
• How the promotion works
• When sync stops instead of guessing

Overview

The sync skill promotes a finished change into Flow's canonical state, the long-lived, always-current record of how each capability behaves.

You invoke it with the change name:

/flow-sync project-archiving

A change is temporary. Once it ships, its folder is archived and forgotten. The state files are permanent. Sync is the step that carries what a change did out of the temporary world and into the permanent one.

Canonical state

Flow keeps one state file per capability under .flow/states/. A state file such as .flow/states/projects.md is the current behavior contract for that capability, a flat list of everything it guarantees today, with no history and no diff markers.

The planning step already produced the raw material. For every capability a change affects, a delta was written, recording which behaviors the change adds, modifies, or removes. A brief writes these for a feature, and a task writes them when it changes a capability. Sync applies those deltas to the state files.

How the promotion works

Sync is mechanical. It does not re-interpret the change or re-derive behavior; it applies fixed rules, matched by behavior heading:

• An added behavior is appended to the capability's state file.
• A modified behavior replaces the matching entry already in the state file.
• A removed behavior is deleted from the state file.

Before it writes anything, sync validates every delta against every state file. If all of them apply cleanly, it computes the new state files and writes them in one pass. If any single delta does not apply, the run stops before the filesystem is touched, so a problem in one capability never leaves the state half-updated.

Gates and escalation

Sync will only promote a change that was actually built, whether you built it with the build skill or by implementing a task. It refuses to run on work that has not been built, because unbuilt work must never reach the canonical record.

When a delta does not apply, for example a modified behavior whose heading matches nothing in the state file, sync stops and reports SYNC PAUSED. It names the capability, the behavior, and what it found, and waits for you. It never guesses a match or writes a partial state file.

Once the state files are written, sync marks the change as synced. That is what the archive step looks for.

What sync produces

Sync creates or updates the affected files under .flow/states/, and marks the change as synced. It writes no application code and makes no commits.

Next step

• Hand off to the Archive skill to file the completed change away.