flow — Gated Build Harness
Mô Tả Dự Án
/flow — harness build có cổng kiểm duyệt cho coding agent: biến ý tưởng thành bằng chứng hoàn thành thực sự qua các gate trung thực. Skill độc lập chạy với Claude Code, Codex, Cursor, Antigravity; viết bằng bash và Python, mã nguồn MIT, kèm website tài liệu riêng.
Tổng quan
flow là một harness build có cổng kiểm duyệt (gated build harness) bọc quanh coding agent mà lập trình viên đang dùng — Claude Code, Codex, Cursor hoặc Antigravity. Bài toán nó giải quyết là tình trạng agent tuyên bố "xong" khi công việc chưa hoàn thành thật: nghiên cứu chưa làm, phạm vi bị hạ lặng lẽ cho đến khi qua cổng, hoặc "tests pass" được đưa ra thay cho một URL sống hay một CLI đang chạy. flow biến việc giết một ý tưởng yếu tại cổng thành kết quả hợp lệ và được tôn trọng, thay vì một thất bại phải giấu.
Kiến trúc & quyết định kỹ thuật
Quyết định nền tảng nằm ở ADR 0001 ("discipline-layer identity"): flow sở hữu cổng và biên nhận (receipts), không bao giờ sở hữu runtime. Điều đó cho phép flow chạy host-agnostic — từ Claude Code đến các host tầm trung như Gemini Flash hay DeepSeek — mà không cần tự làm runner. Cổng hoạt động theo nguyên tắc "cả hai phải đồng ý": cổng cơ khí là flow.sh exit 0/1, đếm ô chưa tick, phát hiện [FILL] còn sót trong file hoặc evidence block rỗng; cổng ngữ nghĩa là SKILL.md, phán xét xem công việc có rỗng ruột không. Chat là cửa vào mặc định, các verb gõ tường minh vẫn giữ nguyên.
Nội dung cổng được tổ chức thành dữ liệu có kiểm soát: gate-rules.md tách thành index + file theo phần + gate-shared.md; gate-examples.md cung cấp few-shots PASS/FLAG cho các stage 01/02/03/05 và card. Lớp pháp lý law/CODING.md đóng gói sáu luật di động (explicit resolve, fail-loud, test theo hành vi, không empty catch, trích dẫn seam, dùng thư viện thay vì tự viết). Điểm đáng chú ý nhất là hệ thống tự đánh giá: flow.sh eval --record/--replay ghi biên nhận chỉ chứa hash (prompt_sha), không lưu prompt thô; replay không bao giờ tính vào eval floor; mọi rule cổng mới phải kèm một cặp fixture PASS/FAIL; NEXT_VERB= là enum đóng mang tính khuyến nghị, cấm host tự động chạy auto/skip. Phiên bản 0.33.0 thêm status --json / resume --json trả một object đóng flow_context/v1 chỉ để hiển thị, cùng heading-map cho Stage 05. Vận hành: CI GitHub Actions trên 3 hệ điều hành với một job tổng all-checks-passed, mỗi PR đều chạy pack-rehearsal không credential — đóng gói npm wrapper, so byte thư mục skills/flow/, cài vào DEST tạm rồi điều khiển e2e.
Tính năng nổi bật
- Cổng kép cơ khí + ngữ nghĩa: hoàn thành phải là bằng chứng về trạng thái thế giới, không phải lời khai của agent
/flow autobuild tự trị, tự dừng khi gặp vấn đề lớp bảo mật;NEXT_VERBchặn auto-exec ngoài enum/flow assessđánh giá codebase hiện hữu; build card kiểm chứng được qua/flow check C-001status --json/resume --jsoncho host mất trạng thái cổng sau compact- Hệ eval có receipt, fixture-pair bắt buộc và replay không tính điểm
- Website tài liệu song ngữ Anh–Việt tại flowskill.io.vn; CI 3 hệ điều hành
Trạng thái
Đang phát triển chủ động: skill ở v0.33.0 (17/09/2026), npm installer @manhquy/flow-skill 0.7.3 (xác nhận trên registry), CHANGELOG chi tiết đến từng PR, website tài liệu sống. Cài bằng npx @manhquy/flow-skill@latest (Node ≥ 22.14).