BẰNG CHỨNG HƠN CẢM HỨNG.

flow

Báo xong không qua được gate.

flow là harness gắn gate vào coding agent bạn đang dùng. Nó giữ gate và bằng chứng — không can thiệp vào runtime. Loại một ý tưởng yếu ngay tại gate cũng là kết quả hợp lệ.

Gate chỉ mở khi cả hai cùng duyệt.

NODE ≥22

npx @manhquy/flow-skill@latest

Cài đặt và lần chạy đầu

HOẠT ĐỘNG CÙNG CÁC CODING AGENT BẠN DÙNG

Claude CodeCodex CLIGemini CLICursorAiderClineContinueZed

6 gate phải vượt trước khi build

Mỗi stage để lại một file trong repo. /flow next chỉ mở stage kế tiếp khi cả runner lẫn skill cùng duyệt. Các file này chỉ xuất hiện khi bạn vượt qua từng gate — cài đặt xong chưa có gì.

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

Idea

flow/00-idea.md

Loại ý tưởng yếu trước khi đụng vào code.

1# Vấn đề cần giải quyết

2[FILL: mô tả vấn đề người dùng]

3# Đề xuất giải pháp

4<trống>

FAIL · DỪNG TẠI GATE

Những gì không qua được gate

File để trống, sót token [FILL], hay chỉ tuyên bố “tests pass” — đều bị chặn ngay.Ý tưởng yếu dừng tại gate.

File còn để trống.
Còn sót token [FILL] chưa điền.
Báo “tests pass” nhưng không đưa bằng chứng hoàn thành.

$ /flow next
refusing: flow/00-idea.md is empty (line 1)
dừng ở gate là kết quả hợp lệ.

Research

flow/01-research.md

Dẫn nguồn thật hoặc dừng tại đây.

1## Nguồn tài liệu gốc

2• [RFC-9110] §4.2 Phương thức idempotent

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

4## So sánh đối thủ & các kịch bản lỗi

02BẰNG CHỨNG · NGUỒN TÀI LIỆU GỐC

Dữ liệu kiểm chứng trước khi lên kiến trúc

So sánh đối thủ, trích dẫn tài liệu thật, ghi lại failure mode vào repo.

$ /flow check 01-research
✓ 3 nguồn tài liệu gốc được kiểm chứng (URL thật)
✓ phân tích đối thủ & failure mode đã khóa

Scope

flow/02-scope.md

Vạch rõ ranh giới. Cắt bỏ phần thừa.

1TRONG-PHẠM-VI S-01 Vòng lặp gate CLI

2TRONG-PHẠM-VI S-02 Kiểm tra schema biên nhận

3NGOÀI-PHẠM-VI Thu thập telemetry / tracking

4NGOÀI-PHẠM-VI Daemon đám mây riêng

03RANH GIỚI · NON-GOALS

Khóa danh sách non-goals

Chốt từng hạng mục bàn giao. Chặn scope creep trước khi agent viết một dòng code.

$ /flow check 02-scope
✓ 3 phần việc bàn giao đã khóa
✓ non-goals đã khóa (chặn scope creep)

PRD

flow/03-prd.md

Chốt tiêu chí test trước khi viết code.

1INV-01: exit 1 khi spec file còn trống

2INV-02: in dòng từ chối ra stderr

3INV-03: bằng chứng JSON đúng schema

4INV-04: chế độ degrade tự ghi nhận technical debt

04CAM KẾT · TIÊU CHÍ NGHIỆM THU

Chỉ chấp nhận tiêu chí kiểm chứng được

Mỗi user story đi kèm điều kiện bất biến có thể kiểm chứng. Agent không được tự đổi chuẩn “done” giữa chừng.

$ /flow check 03-prd
✓ đã xác nhận tiêu chí nghiệm thu kiểm chứng được
✓ đã xác định trạng thái lỗi và luồng xử lý degrade

ADR

flow/04-adr.md

Ghi nhận đánh đổi trước khi commit.

1Trạng thái: Chấp nhận (2026-10-11)

2Bối cảnh: Lưu file trong repo vs chạy daemon SQLite

3Quyết định: Dùng file Markdown trong git

4Hệ quả: Portable; không cần background server

05QUYẾT ĐỊNH · ĐÁNH ĐỔI

Bản ghi quyết định kiến trúc

Ghi lại bối cảnh, quyết định và hệ quả trước khi viết code.

$ /flow check 04-adr
✓ đã ghi nhận bối cảnh, quyết định và hệ quả
✓ đã đối chiếu khả năng rollback và kịch bản kiểm thử lỗi

Contract

flow/05-contract.md

Cả hai cùng duyệt mới được đi tiếp.

[✓] dev-xác-nhận: @dev đã duyệt

[✓] harness-chứng-thực: sha256:7f3a..9e1b

[✓] flow-doctor: READY (đã kiểm tra skill)

[✓] xác-nhận-kép: UNLOCKED -> tiến hành build

PASS · SẴN SÀNG

Sau khi cài đặt

Skill đã sẵn sàng trên máy. Gõ /flow (Codex: $flow) là chạy.flow doctor in ra READY./flow next trên file idea trống sẽ báo lỗi kèm số dòng.

File skill nằm gọn trong thư mục của agent.
Gõ /flow trong chat (Codex: $flow).
Lệnh doctor in ra READY.
/flow next trên file idea trống sẽ từ chối và chỉ rõ số dòng.

$ flow doctor
doctor: READY (skills/flow/SKILL.md verified)
Gate chỉ mở khi cả hai cùng duyệt.

Tiếp theo là /flow card. Muốn đánh dấu hoàn thành phải có bằng chứng thật: một URL đang chạy, một CLI đã cài và chạy được, một public API đang hoạt động, hoặc một lần chạy skill thành công.

Không phải một coding agent. Đây là harness bắt agent giữ kỷ luật.

flow không tự viết code. Agent vẫn viết — còn harness quyết định phần việc đó có đủ chuẩn để đi tiếp hay không.

Cài đặt và lần chạy đầu Đọc tài liệu