flow

PROOF OVER VIBES.

Hollow work does not advance.

A gated harness around the coding agent you already use. Flow owns the gates and the receipts, never the runtime. Killing a weak idea at a gate is a valid outcome.

The gate opens only when both agree.

Install and first runRead the docs
npx @manhquy/flow-skill@latestInstall and first run

WORKS WITH YOUR CODING AGENTS

Claude CodeCodex CLIGemini CLICursorAiderClineContinueZed

Six gates before you build

Each stage writes a real file in your repo. /flow next will not unlock the next one until the runner and the skill both agree. Those files exist after you walk the gates, not after install.

  1. FAIL · KILLED AT GATE

    Idea

    flow/00-idea.md

    Kill bad ideas before code exists.

    flow/00-idea.mdHALT
    # Problem statement
    [FILL: describe user problem]
    # Proposed solution
    <empty>
    exit: 1 · unresolved [FILL] token
    FAIL · KILLED AT GATE

    What will not pass

    Empty, leftover [FILL], or “tests pass” offered as done. A weak idea is killed at the gate.

    • An empty file.
    • A leftover [FILL] still in the file.
    • “Tests pass” offered as done.

    $/flow nextrefusing: flow/00-idea.md is empty (line 1)kill is a valid outcome.

  2. EVIDENCE · PRIMARY SOURCES

    Research

    flow/01-research.md

    Cite real sources or stop here.

    flow/01-research.md3/3 CITED
    ## Primary sources
    • [RFC-9110] §4.2 Idempotent methods
    • github.com/owner/repo#412 (repro)
    ## Competitive diff & failure modes
    urls verified · ground truth locked
    02EVIDENCE · PRIMARY SOURCES

    Ground truth before architecture

    Competitor diffs, verified documentation quotes, and real failure modes recorded to repo files.

    $/flow check 01-research3 primary sources cited (verified URLs)competitive diff & failure modes locked

  3. PERIMETER · NON-GOALS

    Scope

    flow/02-scope.md

    Draw the boundary. Drop the rest.

    flow/02-scope.mdFROZEN
    IN-SCOPE S-01 CLI harness gate loop
    IN-SCOPE S-02 Receipt schema validator
    NON-GOAL Telemetry / analytics tracking
    NON-GOAL Custom cloud daemon runtime
    2 deliverable slices · perimeter frozen
    03PERIMETER · NON-GOALS

    Explicit non-goals frozen

    Bounded delivery slices. Scope creep is caught before any code generation begins.

    $/flow check 02-scope3 deliverable slices lockednon-goals explicitly frozen (scope creep blocked)

  4. CONTRACT · ACCEPTANCE

    PRD

    flow/03-prd.md

    Define the test before writing code.

    flow/03-prd.mdCRITERIA
    INV-01: exit 1 on empty spec file
    INV-02: refusal line emitted to stderr
    INV-03: receipt JSON conforms to schema
    INV-04: degraded mode creates debt entry
    4 observable invariants · 0 prose fluff
    04CONTRACT · ACCEPTANCE

    Observable criteria only

    User stories with testable invariants. The agent cannot redefine success mid-flight.

    $/flow check 03-prdobservable acceptance criteria specifiederror states & degraded paths defined

  5. DECISION · TRADE-OFFS

    ADR

    flow/04-adr.md

    Log the trade-off before you commit.

    flow/04-adr.mdACCEPTED
    Status: Accepted (2026-10-11)
    Context: File state vs SQLite daemon
    Decision: Git-tracked Markdown files
    Consequence: Portable; zero background server
    reversibility mapped · trade-off locked
    05DECISION · TRADE-OFFS

    Architecture Decision Records

    Context, decision, and consequences recorded before implementation starts.

    $/flow check 04-adrcontext, decision, consequences documentedreversibility & negative test cases mapped

  6. PASS · READY

    Contract

    flow/05-contract.md

    Both sides agree or nothing advances.

    flow/05-contract.mdUNLOCKED
    [✓] human-signoff: approved by @dev
    [✓] harness-attest: sha256:7f3a..9e1b
    [✓] doctor-check: READY (skills verified)
    [✓] dual-agreement: UNLOCKED -> advance
    signed contract · gate cleared for build
    PASS · READY

    After install

    The skill is on disk. Type /flow (Codex: $flow). flow doctor prints READY. /flow next on an empty idea file refuses with line numbers.

    • Skill files land in the agent home.
    • Type /flow (Codex: $flow).
    • doctor can print READY.
    • /flow next on an empty idea file refuses with line numbers.

    $flow doctordoctor: READY (skills/flow/SKILL.md verified)The gate opens only when both agree.

Then /flow card. Done means proof in the world: a deployed URL, a CLI that installs and runs, a public API, or a real skill run.

Proof, with sources

Every number below is read live from the repo at build time or counted from the named source. Each number lists its source.

  • 0.34.4skill versionskills/flow/SKILL.md · read at build time
  • 0.7.11npm installernpm-wrapper/package.json · read at build time
  • 72test suites in the registrytests/manifest.txt
  • 6gates before buildskills/flow/references/stage-state-machine.md

Watch a run in 85 seconds

85 seconds

An idea dies at gate 01; a sourced one walks through all six gates to a passing receipt.

Install and first runRead the docs

Not an AI coding agent. A harness around one.

flow does not write your code. The agent still writes; the harness decides whether that work may advance.

Install and first runRead the docs