PROOF OVER VIBES.

flow

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.

NODE ≥22

npx @manhquy/flow-skill@latest

Install 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.

01Idea
02Research
03Scope
04PRD
05ADR
06Contract

Idea

flow/00-idea.md

Kill bad ideas before code exists.

1# Problem statement

2[FILL: describe user problem]

3# Proposed solution

4<empty>

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 next
refusing: flow/00-idea.md is empty (line 1)
kill is a valid outcome.

Research

flow/01-research.md

Cite real sources or stop here.

1## Primary sources

2• [RFC-9110] §4.2 Idempotent methods

3• github.com/owner/repo#412 (repro)

4## Competitive diff & failure modes

02EVIDENCE · PRIMARY SOURCES

Ground truth before architecture

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

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

Scope

flow/02-scope.md

Draw the boundary. Drop the rest.

1IN-SCOPE S-01 CLI harness gate loop

2IN-SCOPE S-02 Receipt schema validator

3NON-GOAL Telemetry / analytics tracking

4NON-GOAL Custom cloud daemon runtime

03PERIMETER · NON-GOALS

Explicit non-goals frozen

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

$ /flow check 02-scope
✓ 3 deliverable slices locked
✓ non-goals explicitly frozen (scope creep blocked)

PRD

flow/03-prd.md

Define the test before writing code.

1INV-01: exit 1 on empty spec file

2INV-02: refusal line emitted to stderr

3INV-03: receipt JSON conforms to schema

4INV-04: degraded mode creates debt entry

04CONTRACT · ACCEPTANCE

Observable criteria only

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

$ /flow check 03-prd
✓ observable acceptance criteria specified
✓ error states & degraded paths defined

ADR

flow/04-adr.md

Log the trade-off before you commit.

1Status: Accepted (2026-10-11)

2Context: File state vs SQLite daemon

3Decision: Git-tracked Markdown files

4Consequence: Portable; zero background server

05DECISION · TRADE-OFFS

Architecture Decision Records

Context, decision, and consequences recorded before implementation starts.

$ /flow check 04-adr
✓ context, decision, consequences documented
✓ reversibility & negative test cases mapped

Contract

flow/05-contract.md

Both sides agree or nothing advances.

[✓] human-signoff: approved by @dev

[✓] harness-attest: sha256:7f3a..9e1b

[✓] doctor-check: READY (skills verified)

[✓] dual-agreement: UNLOCKED -> advance

PASS · READY

After install

The skill is on disk. /flow or$flow exists.doctor can print 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 doctor
doctor: 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.

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 run Read the docs