Pipeline các stage

Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro
|------------------ planning (files in flow/) ------------------|  |------- shipping (inside cards/) -------|

Pipeline không phải là danh sách tài liệu cần phải tạo ra. Mỗi stage tồn tại vì ở đúng điểm đó trong build thường xảy ra một kiểu tự lừa nhất định, và gate nhắm vào đúng kiểu tự lừa đó.

Planning: sáu file có gate

Artifact planning nằm dưới flow/ và được đánh số để thứ tự không thể thương lượng.

00 — Idea. Pitch ba câu: ai có vấn đề, họ đang làm gì, bạn sẽ làm gì khác. Gate đang tìm vấn đề chứ không phải giải pháp đội lốt vấn đề. Đây là chỗ rẻ nhất trong cả dự án để loại thứ gì đó.

01 — Research. Thứ đã tồn tại: đối thủ, hệ thống live, giá thật. Luật là inspect first, bằng chứng không phải vibe. Đây là stage mà việc bịa đặt vừa hấp dẫn nhất vừa đắt nhất, vì plan dựng trên đối thủ bịa sẽ sai một cách tự tin suốt nhiều tuần. Script không phát hiện quote bịa; gate ngữ nghĩa là phòng thủ duy nhất.

02 — Scope. Chấm hạng feature và cắt. Fail đặc trưng ở đây là bơm hạng — feature hạng C được viết thành B vì bạn muốn build. Scope là nơi hầu hết dự án được cứu hoặc bị bỏ đi, nên mode work dừng lại để operator duyệt một cách tường minh đúng tại điểm này, không nơi nào khác.

03 — PRD. Phần scope sống sót trở thành các functional requirement có số. Mỗi FRn viết ở đây sau này phải được một card claim và một interface contract phục vụ. Truy vết đó có thể kiểm bằng máy, nên requirement không thể bốc hơi lặng lẽ giữa planning và building.

04 — ADR. Quyết định kiến trúc, kể cả cái bạn loại và vì sao. Option bị loại mới là phần đáng giá: sáu tháng sau chúng là lý do không ai mở lại câu hỏi đã chốt.

05 — Contract. Interface, viết trước khi có code. Method, path, auth, shape request và response cho web; lệnh, flag, shape output và exit code cho CLI; bề mặt API export cho library; bề mặt lệnh cho skill.

Vì sao contract không bao giờ skip được

Mọi stage planning khác skip được với debt được ghi lại một cách trung thực. Stage 05 thì không, không bao giờ.

Contract là seam. Bên sản xuất build dựa vào nó, bên tiêu thụ build từ nó, và hai bên làm việc độc lập được chính vì shape giữa chúng đã cố định. Skip không tiết kiệm thời gian; nó chỉ dời chi phí sang lúc tích hợp, khi hai phía đang build dở phát hiện ra bất đồng và ai đó phải viết lại một bên.

Kỷ luật đi kèm rất nghiêm: đừng tự ý ứng biến shape. Shape sai thì sửa contract trước rồi mới đổi code. Hãy tôn trọng shape ngay từ bây giờ bằng null hoặc stub, dù giá trị thật chỉ ship ở card sau.

Nếu contract không khớp loại dự án, hãy thích nghi — đọc “endpoint” thành “interface” hoặc “command” — chứ đừng skip.

Shipping: cards

Sau khi stage 05 pass, /flow card cắt build card. Mỗi card là một phiên build có phạm vi với danh sách allowed-files, requirement nó implements, khối verify, independent test, và section evidence bắt đầu trống.

Build, review đối kháng, deploy, rồi verify live như người dùng. Card được coi là xong khi bằng chứng thế giới thật được dán vào và gate check pass — không phải khi test xanh.

Brownfield: stage 00-inspect

Codebase có sẵn không bắt đầu ở Idea. /flow assess scaffold và đặt gate cho flow/00-inspect.md, bản đồ hiện trạng gồm stack, những gì sản phẩm đang làm so với những gì nó nên làm, rủi ro, và baseline test. Do operator duyệt, và nó tồn tại để việc planning cho hệ thống có sẵn bám vào cái thực sự đang có, chứ không phải cái mà README của kho tuyên bố.

Retro

Một dòng trung thực mỗi lần chạy, do operator viết, không bao giờ do agent. Nó cung cấp dữ liệu cho lớp bền vững, nên recall của dự án sau sẽ hiện lên nỗi đau của dự án này.

Kill là lối ra hợp lệ

Mỗi gate có ba kết quả, không phải hai: pass, chặn, và loại. Harness mà chỉ biết nói “tiến” thì chẳng khác gì băng chuyền có gắn thêm nghi thức tuân thủ. Loại ý tưởng yếu ở Scope là quyết định tốt và rẻ nhất trong một lần build.

Vượt gate bằng `/flow next`

/flow next kiểm tra gate của stage bạn đang đứng, và chỉ khi pass mới mở stage kế tiếp. Runner lấy file stage số cao nhất liên tục đã có trong flow/ làm stage hiện tại — một file stage chỉ được tính khi mọi stage trước nó đều tồn tại (một file 05 đơn độc mà thiếu 00–04 sẽ không được coi là stage hiện tại). Planning chỉ xong khi cả sáu gate stage đều sạch; lúc đó /flow card mới mở.

Khi lớp cơ học fail, nó in ra đúng cái sai kèm số dòng: ô gate chưa tick, [FILL] còn sót, rồi dừng. FAIL thì không bao giờ tiến. Bản listing đó chính là toàn bộ chẩn đoán: mở file được nêu, sửa đúng những dòng đó, chạy /flow next lại. Đừng đoán ô nào trống.

Khi script pass, thử thách ngữ nghĩa của stage vừa xong được áp dụng trước khi bạn được phép đi tiếp, nên artifact tuy sạch về mặt cơ học nhưng rỗng vẫn bị gọi tên là yếu. Ở mode teach agent không bao giờ tick ô hoặc viết artifact hộ bạn; nó chỉ cho bạn biết cái gì đang fail.

Loại là trạng thái kết thúc hợp lệ. Dừng ở bất kỳ gate nào, nhất là Scope, là kết quả đáng được tôn trọng, chứ không phải là flow thất bại. Pass, chặn và loại là ba câu trả lời; còn harness mà chỉ biết nói “tiến” thì chỉ là băng chuyền.

Loại dự án

flow vốn được thiết kế cho web. Cách trung thực để hỗ trợ các loại phần mềm khác không phải là làm gate trở nên mơ hồ bằng cách khái quát hóa, mà là nêu rõ đúng ba thứ thay đổi. Đặt loại bằng /flow project-type web|cli|library|skill trước stage 05. Giá trị lưu trong file PROJECT_TYPE, mặc định web. Chạy không đối số in giá trị hiện tại và luật bằng chứng hoàn thành mà nó kéo theo.

Loại dự án sẽ điều chỉnh seam contract ở stage 05, trình tự card chuẩn, và ý nghĩa của bằng chứng hoàn thành. Mọi thứ khác (tinh thần mỗi gate, “contract trước code”, “hoàn thành là bằng chứng thế giới thật”) không đổi. Đổi loại sau này nghĩa là phải xem lại contract — nên đổi bây giờ thì rẻ, để sau thì đắt.

web. Contract: HTTP endpoint (method, path, auth, request, response); OpenAPI được phục vụ. Xong: URL đã deploy live cộng output curl thật.
cli. Contract: lệnh, flag, cấu trúc output, exit code. Xong: tool cài được và một lần gọi thật trả output và exit code đúng. Việc đầu trên lần build CLI: /flow project-type cli.
library. Contract: bề mặt public API, hàm và type export kèm shape. Xong: public API import được, ví dụ dùng chạy được, đạt ngưỡng coverage.
skill. Contract: lệnh và file mà agent đọc. Xong: đã cài vào skill home và một lần chạy thật đạt done-definition của chính nó. Việc đầu trên lần build skill: /flow project-type skill.

Lần build CLI không phải lần build web pha loãng: bằng chứng nó phải sinh ra cụ thể như nhau, chỉ mang hình thức của một tool đã cài và exit code thật chứ không phải URL đã deploy. Bản thân các gate không đổi; chỉ hình thức của bằng chứng là thay đổi.

Một số câu chữ của gate stage-05 vẫn nói “endpoint” và hỏi cột auth, mang hương vị web. Với loại khác bạn đọc “endpoint” thành “interface” hoặc “command”, và thay auth bằng writes cùng side-effect. Phần mở đầu của stage cho phép sự thích nghi đó một cách tường minh, và bài kiểm tra no-drift tương đương chính là bằng chứng hoàn thành theo loại đó thực sự pass.

Ma trận loại dự án

Đặt bằng /flow project-type <web|cli|library|skill>, lưu trong PROJECT_TYPE, mặc định web.

Loại	Seam contract (stage 05)	Bằng chứng hoàn thành	Trình tự card
`web`	HTTP endpoint: method, path, auth, request, response; OpenAPI được phục vụ	URL đã deploy live cộng output `curl` thật	scaffold và `/healthz`, lát cắt dọc, backend, contract test, UI mock, frontend, e2e
`cli`	Lệnh, flag, shape output, exit code	Tool cài được và một lần gọi thật trả output và exit code đúng	scaffold cộng một lệnh thật, nhóm subcommand, test, smoke cài trên thư mục sạch
`library`	Bề mặt public API: hàm và type export kèm shape	Public API import được, ví dụ dùng chạy được, đạt ngưỡng coverage	scaffold cộng core API, các vòng API, test, ví dụ dùng chạy được, dry-run publish
`skill`	Lệnh và file mà agent đọc	Cài vào skill home và một lần chạy thật đạt done-definition của chính nó	scaffold cộng một lệnh chạy được, references và law, cài, một lần chạy dogfood

Điều không đổi trên cả bốn loại: mọi requirement map tới một interface, mọi interface đều có cấu trúc viết trước code, contract là seam, và “tests pass” hoặc “merged” không bao giờ được tính là hoàn thành.

Chế độ và chiến lược chạy

flow có bốn trục mode thực sự độc lập với nhau, nên bạn đặt từng trục theo dự án rồi kết hợp theo nhu cầu công việc.

Mode soạn quyết định ai là người viết artifact ở gate: teach, mặc định, nghĩa là bạn viết và agent chỉ đứng gác ở gate; work nghĩa là agent phỏng vấn bạn một lần, soạn các stage từ 00 tới 05, và chỉ dừng lại để bạn duyệt scope.

Loại dự án quyết định thế nào là hoàn thành: URL live cho web, lần gọi thật và exit code cho CLI, API import được cho library, lần chạy đã cài cho skill.

Chế độ chạy quyết định card được build ra sao: thủ công, bạn tự lái card — build rồi check; hoặc auto, lần chạy tự động xử lý theo tier và HALT khi gặp work thuộc nhóm bảo mật.

Greenfield versus brownfield quyết định bạn bắt đầu từ đâu: stage 00-idea cho thứ mới, hoặc bản đánh giá hiện trạng có gate cho codebase có sẵn.

Không trục nào đổi được chuẩn gate. Gate và luật hoàn thành giống nhau trên mọi tổ hợp; mode chỉ đổi người soạn, hình thức bằng chứng và cách lái — không bao giờ đổi chuẩn của gate.

Làm rõ quyết định còn mở

Các quyết định sản phẩm chưa xong tồn tại dưới dạng bullet - [ ] dưới heading ## Open decisions trên artifact Scope, PRD, và Contract. Chúng được cùng scanner ô mà các gate đã dùng đếm, nghĩa là một quyết định chưa chốt sẽ thật sự chặn stage chứ không ngồi trong comment không ai đọc.

/flow clarify in các bullet sót đó, giới hạn đúng section, và luôn exit 0. Nó chỉ in ra để tham khảo, không phải gate thứ hai. Việc chốt chúng là các bước write-back có giới hạn và opt-in: đi qua từng bullet, ghi quyết định vào artifact, rồi tick ô. Không có gì về clarify là điều kiện tiên quyết của /flow next; chính scanner của gate mới là thứ ép các ô — và các ô vốn đã là điều kiện đó.

Artifact từng stage

Runner copy các template vào dự án khi mỗi stage mở. Các artifact planning nằm dưới flow/, đơn vị shipping nằm dưới cards/, và sổ cái ở root dự án. Path dưới đây là file, không phải heading.

Path	Stage	Nội dung
`flow/00-idea.md`	00	Pitch ba câu: ai có vấn đề, họ đang làm gì, bạn sẽ làm gì khác
`flow/00-inspect.md`	brownfield	Đánh giá hiện trạng: stack, chức năng so với mục tiêu sản phẩm, rủi ro, baseline test
`flow/01-research.md`	01	Thứ đã tồn tại: đối thủ, hệ thống live, bằng chứng thật
`flow/02-scope.md`	02	Feature đã chấm hạng, phần cắt, và duyệt scope
`flow/03-prd.md`	03	Functional requirement có số (`FRn`)
`flow/04-adr.md`	04	Quyết định kiến trúc, kể cả option đã loại
`flow/05-contract.md`	05	Interface, viết trước code. Seam. Không bao giờ skip được
`flow/constitution.md`	tùy chọn	Bất biến do operator tự viết cho từng dự án, mang tính cố vấn
`cards/C-NNN.md`	build	Một phiên build có phạm vi: allowed files, implements, verify, independent test, evidence, risk
`MODE`, `PROJECT_TYPE`	-	Mode soạn và loại dự án
`DEBT.md`, `RETRO.md`, `AUTO-LOG.md`	-	Skip có chủ đích, dòng retro, log lần chạy tự chủ
`.flow/harness.db`	-	Bản ghi bền vững

Mọi artifact planning đi kèm placeholder [FILL] và ô gate; cả hai được scan cơ học, và thứ nào chưa xong đều khiến stage fail. Các quyết định chưa xong nằm dưới heading ## Open decisions, nơi cùng scanner đếm chúng.

Xem thêm

Dành cho maintainer (không phải trang công khai): skills/flow/references/stage-state-machine.md, skills/flow/references/project-types.md, skills/flow/references/mode-work.md, skills/flow/references/clarify.md.