Working on Flow: rules for AI assistants

Flow is a statically typed compiled language built around evolution through time. It is young, it changes often, and it is not in your training data. Treat every recollection you have about Flow syntax as a guess until the repository confirms it.

1. Pick the compiler host before writing code

Flow has two hosts. Choosing wrong is the single most common failure.

println is not in the Stage-A subset. Any program that prints text needs the Python host. So does any program with a flow block.

State the host in every command you report. FLOW_HOST=python flow run f.flow is a fact. "It works with Flow" is not.

2. Find the truth in this order

1. Executable behaviour. Run it.
2. Tests under tests/, and runnable programs under examples/.
3. Compiler and runtime source: compiler/src/, src/flow/, runtime/.
4. Focused documents in docs/language/, docs/library/, docs/vision/.
5. Overview documents: README.md, VISION.md, ROADMAP.md.

A document that contradicts a passing test is stale. Say so and move on. .cursorrules in the main repository describes an older layout; prefer the sources above.

3. Search before you write

Flow ships around seventy standard library modules under lib/stdlib/ and several hundred worked examples under examples/. Before writing a helper, look for it:

grep -rn --include='*.flow' "function name_you_want" lib/stdlib/ examples/
ls lib/stdlib/

The project's own record is that the most useful work replaced private helpers with shared ones.

4. Write ordinary Flow first

# Comments use a hash.

let x: i32 = 42                    # immutable
let mut count: i32 = 0             # mutable

function add(a: i32, b: i32) -> i32 {
    return a + b
}

struct Point {
    x: f64,
    y: f64
}

for i in 0 to 10 { }               # 0 up to but not including 10
while condition { }

if x > 0 {
} elif x < 0 {
} else {
}

import "stdlib/text.flow"          # library import, quoted path

extern {
    function sqrt(x: f64) -> f64   # C interop
}

Types are explicit in signatures. Scalars are i32, i64, f32, f64, bool, string, void, and ptr<T> for low-level work.

Reach for a higher-level form when it improves the model, not to save a line.

5. State evolution as evolution

This is what the language is for. When a system changes over time, write a flow block rather than a hand-rolled integration loop.

flow Ball {
    state height      : f64 = 2.0
    state velocity    : f64 = 0.0
    param gravity     : f64 = 9.81
    param restitution : f64 = 0.8

    height evolves as velocity
    velocity evolves as -gravity

    when height reaches 0.0 {
        velocity becomes -restitution * velocity
        height becomes 0.0
    }
}

The compiler generates Ball_new() and Ball_step(&ball, dt). The caller owns the instance and supplies dt.

Current limits worth stating to the user:

• Derivatives read the pre-step state, and continuous states advance together.
• Event assignments in a when body are staged and applied together.
• Zero crossing is detected at step granularity, so event times carry O(dt) error. Say this when the timing matters.
• Requires FLOW_HOST=python.

6. Separate needs from providers with effects

effect Log {
    info(msg: string) -> void,
}

function place_order(sku: i32) -> i32 {
    Log.info("order received")
    return sku
}

handle Log with ProductionLog {
    result = place_order(1001)
}

With no handler installed, effect operations fall back to zeroed defaults and fail silently. If a program calls an effect operation, it needs a handle ... with ... scope around the call. Set FLOW_STRICT_EFFECTS=1 to abort on unhandled operations instead.

Do not thread a handler through as a function parameter. Dispatch goes through the effect's current handler, so a parameter has no effect on it.

7. Verify at the right level

Climb only as far as the risk requires.

1. It parses and emits C.
2. The C compiles.
3. It runs and exits zero.
4. It asserts an invariant, an expected output, or a closed-form answer.
5. It matches across backends or hosts, where parity is claimed.

A program that compiles has not been shown to be correct. Numerical models get checked against an analytic result, a conserved quantity, or a smaller step size.

flow test --strict --verbose    # focused Flow tests
flow test-runtime               # compile and execute
flow test-all                   # everything

8. Report evidence, not confidence

Every piece of work ends with:

• the exact command, environment variables included;
• the real output, trimmed but not paraphrased;
• what was checked and what was not;
• any limit the user should know about.

Never describe planned behaviour as shipped. If something is parsed but not lowered, say that.

9. Failure patterns to avoid

• Trusting the first nearby document instead of the test.
• Using the default host for a program that prints or evolves.
• Editing generated C under build/ instead of the generator.
• Adding syntax to remove one repeated line.
• Treating a clean compile as a correct result.
• Sweeping unrelated cleanup into a focused change.
• Reporting a benchmark without naming the machine, flags, and host.

10. Repository map

Confirm the current command surface with flow help rather than relying on any table, including this one.