flow

实证胜于感觉。

报完工 过不了 gate。

给你的 coding agent 加一层带 gate 的 harness。flow 掌管 gate 与证据，从不碰 runtime。在 gate 毙掉一个弱想法，是合理产出。

只有双方都点头，gate 才会开。

安装与首次运行读文档
npx @manhquy/flow-skill@latest安装与首次运行

与你的 CODING AGENT 协同工作

Claude CodeCodex CLIGemini CLICursorAiderClineContinueZed

开工前的六道 gate

每个 stage 都会在你的仓库里留下一个真实文件。只有 runner 和 skill 都点头，/flow next 才会放行下一个 stage。这些文件只在你走完 gate 之后出现——刚装完时什么都没有。

  1. FAIL · 毙于 GATE

    Idea

    flow/00-idea.md

    在写代码之前毙掉烂想法。

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

    过不了 gate 的东西

    空文件、残留的 [FILL]、拿“tests pass”来报完工——一律拦下。 弱想法在 gate 就被毙掉。

    • 空文件。
    • 文件里还留着 [FILL]。
    • 拿一句“tests pass”来报完工。

    $/flow nextrefusing: flow/00-idea.md is empty (line 1)毙掉也是有效产出。

  2. 证据 · 一手来源

    Research

    flow/01-research.md

    拿出真实来源，否则止步于此。

    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
    02证据 · 一手来源

    先有 ground truth，再谈架构

    竞品对比、核实过的文档引用、真实的失败模式，全部记进仓库文件。

    $/flow check 01-research3 个一手来源已引用（URL 已核实）竞品对比与失败模式已锁定

  3. 边界 · 非目标

    Scope

    flow/02-scope.md

    画清边界，砍掉其余。

    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
    03边界 · 非目标

    non-goals 明确冻结

    交付范围切成小块。范围蔓延在写代码之前就被抓住。

    $/flow check 02-scope3 个交付切片已锁定non-goals 已明确冻结（范围蔓延被拦下）

  4. 契约 · 验收

    PRD

    flow/03-prd.md

    先定好测试，再写代码。

    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
    04契约 · 验收

    只认可观察的验收标准

    每个 user story 都带着可测试的不变量。agent 不能中途改写成功的定义。

    $/flow check 03-prd可观察的验收标准已确认错误状态与降级路径已定义

  5. 决策 · 权衡

    ADR

    flow/04-adr.md

    先记录权衡，再提交。

    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
    05决策 · 权衡

    架构决策记录

    开工之前，先记下背景、决策和后果。

    $/flow check 04-adr背景、决策、后果已记录可逆性与反例测试已梳理

  6. PASS · 就绪

    Contract

    flow/05-contract.md

    双方都认可，否则寸步不让。

    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 · 就绪

    装完之后

    skill 已经在磁盘上。输入 /flow（Codex：$flow）。flow doctor 会打出 READY。对空 idea 文件跑 /flow next，会带着行号拒绝你。

    • skill 文件落进 agent 的家目录。
    • 输入 /flow（Codex：$flow）。
    • doctor 能打出 READY。
    • 对空 idea 文件跑 /flow next，会带着行号拒绝你。

    $flow doctordoctor: READY (skills/flow/SKILL.md verified)只有双方都点头，gate 才会开。

然后是 /flow card。完成意味着拿出世间的证据：一个已部署的 URL、一个装得上跑得起来的 CLI、一个公开 API，或一次真实的 skill 运行。

证据与来源

以下数字均在构建时从仓库实时读取，或按注明的来源计数。每个数字都标注来源。

  • 0.34.4skill 版本skills/flow/SKILL.md · 构建时读取
  • 0.7.11npm installernpm-wrapper/package.json · 构建时读取
  • 72registry 中的测试套件tests/manifest.txt
  • 6开工前的 gateskills/flow/references/stage-state-machine.md

85 秒看一遍运行

85 秒

弱想法在 gate 01 被毙掉；有来源的想法走完六道 gate，拿到通过回执。

安装与首次运行读文档

不是 AI coding agent，是套在它外面的 harness。

flow 不替你写代码。写代码的还是 agent；harness 只决定这份工作配不配往前走。

安装与首次运行读文档