flow — Gated Build Harness for Coding Agents
Project Description
/flow — a gated build harness for coding agents that turns ideas into real done-evidence through honest gates. A standalone skill for Claude Code, Codex, Cursor and Antigravity, written in bash and Python, MIT-licensed, with its own documentation site.
Overview
flow is a gated build harness wrapped around the coding agent a developer already uses — Claude Code, Codex, Cursor or Antigravity. It addresses the problem of agents declaring work "done" when it is not: research never done, scope quietly lowered until the gate passes, or "tests pass" offered instead of a live URL or a running CLI. flow makes killing a weak idea at a gate a valid, honored outcome rather than a failure to hide.
Architecture & Technical Decisions
The foundational decision is ADR 0001 ("discipline-layer identity"): flow owns the gates and the receipts, never the runtime. That keeps flow host-agnostic — from Claude Code to mid-tier hosts such as Gemini Flash or DeepSeek — without becoming a runner itself. Gates operate on a "both must agree" principle: the mechanical gate is flow.sh exiting 0/1, counting unchecked boxes, leftover [FILL] markers and empty evidence blocks; the semantic gate is SKILL.md, judging whether the work is hollow. Chat is the default front door; typed verbs remain available.
Gate content is organized as controlled data: gate-rules.md is split into an index plus per-section files plus gate-shared.md; gate-examples.md provides PASS/FLAG few-shots for stages 01/02/03/05 and cards. The law/CODING.md layer packages six portable laws (explicit resolve, fail-loud, behavior-named tests, no empty catch, cite the seam, library over hand-roll). The most distinctive element is the self-evaluation system: flow.sh eval --record/--replay writes receipts containing only hashes (prompt_sha), never raw prompts; replay never counts toward the eval floor; every new gate rule requires a PASS/FAIL fixture pair; NEXT_VERB= is an advisory closed enum that forbids hosts from auto-executing auto/skip. Version 0.33.0 adds status --json / resume --json returning one closed display-only flow_context/v1 object, plus a heading map for Stage 05. Operationally, GitHub Actions CI covers three operating systems behind a single all-checks-passed aggregation job, and every PR runs a credentialless pack-rehearsal — packaging the npm wrapper, byte-comparing the skills/flow/ directory, installing into a temp DEST and driving an e2e script.
Key Features
- Dual mechanical + semantic gates: completion requires world-state proof, not agent testimony
/flow autoautonomous builds that halt on security-class issues;NEXT_VERBblocks out-of-enum auto-exec/flow assessfor brownfield assessment; verifiable build cards via/flow check C-001status --json/resume --jsonfor hosts that lose gate state after compact- Evaluation system with receipts, mandatory fixture pairs, and non-counting replay
- Bilingual English–Vietnamese docs site at flowskill.io.vn; three-OS CI
Status
Actively developed: the skill is at v0.33.0 (2026-09-17), the npm installer @manhquy/flow-skill at 0.7.3 (confirmed on the registry), with a per-PR CHANGELOG and a live docs site. Install via npx @manhquy/flow-skill@latest (Node ≥ 22.14).