Ý tưởng chỉ thành code sau khi thành contract.

Bản ngắn gọn#

/hapo:specs                  # requirements, research, design, tasks
  -> approve task packet     # contract về scope và evidence
  -> /hapo:develop           # từng unblocked task một
  -> /hapo:test              # command thật và runtime proof
  -> /hapo:code-review       # spec, quality, security, regression
  -> /hapo:sync              # task_registry và task markdown luôn khớp

Điểm quan trọng không phải là danh sách command. Điểm quan trọng là chat không phải source of truth. Contract bền vững nằm trong specs/<feature>/spec.json, requirements.md, research.md, design.md, và tasks/task-R*.md.

Optional pre-spec clarification#

Dùng /hapo:brainstorm khi request còn thô: hướng sản phẩm còn mở, architecture chưa chắc, risk chưa rõ, hoặc câu hỏi đầu tiên cần dựa vào codebase thật.

Brainstorm là scout-first và nằm trước delivery path. Phase này không viết implementation code. Output nên là bộ quyết định đủ sẵn sàng để viết spec: đang giải quyết vấn đề gì, ngoài scope là gì, architecture nào đơn giản nhất, và risk nào phải đưa vào spec.

Chỉ skip phase này khi request đã đủ cụ thể để chuyển thành requirements.

1. Biến request thành spec#

Dùng /hapo:specs để chuyển intent thành artifacts lưu được. Một spec khỏe có:

Spec không phải paperwork. Nó là lớp chống drift. Nó ngăn assistant thay technology đã chốt, tự thêm scope ẩn, hoặc gọi placeholder là xong.

2. Approve task packet#

CafeKit không nên bắt đầu implementation từ toàn bộ feature nằm trong đầu assistant. Nó bắt đầu từ một task packet active.

Một task packet phải trả lời được:

• Behavior nào chính xác nằm trong scope?
• File hoặc surface nào liên quan?
• Task này satisfy requirement nào?
• Design contract nào phải giữ?
• Evidence nào chứng minh task đã done?
• Điều gì nên block task thay vì đoán?

Nếu thiếu các câu trả lời này, quay lại /hapo:specs hoặc /hapo:sync audit <feature>. Không tự lấp gap bằng phỏng đoán implementation.

3. Implement từng boundary#

Dùng /hapo:develop <feature> để chạy full-spec, hoặc /hapo:develop <feature> <task-file> để làm đúng một task.

Rule implementation của CafeKit rất rõ: một unblocked task, một scout, một implementation loop, một bộ proof.

Trước khi code, task nên chuyển sang in_progress. Assistant cần inspect entrypoint thật, caller thật, pattern xung quanh, output từ task trước, và blast radius. Work có ảnh hưởng runtime chưa xong nếu chưa reachable từ route, command, UI mount, worker, service, hoặc API boundary thật.

Không âm thầm đổi contract đã nêu tên. Nếu spec nói Next.js route, Better Auth, Redis, Drizzle, S3, OpenCode command, hoặc runtime cụ thể khác, lựa chọn đó là contract. Placeholder local không thỏa mãn trừ khi spec nói rõ như vậy.

4. Verify bằng evidence, không bằng cảm giác#

Dùng /hapo:test <feature> hoặc /hapo:test --full sau implementation. Test phase nên detect runner, chạy command thật, thu result, rồi so behavior với requirements, design contracts, task evidence, và reachability obligations.

NO_TESTS không phải pass. Command exit 0 nhưng chạy zero tests cũng không phải pass. Build success đơn lẻ không đủ proof cho task có runtime behavior. Task cần evidence khớp completion criteria.

5. Review như thể change đang cố phá production#

Dùng /hapo:code-review --pending, feature scope, PR, hoặc commit target.

Review kiểm tra ba lớp:

Critical finding sẽ block completion. Review không phải bước polish; nó là một phần Definition of Done.

6. Sync state và documentation#

Chỉ dùng /hapo:sync <feature> <task> done sau khi đã có proof. Dùng /hapo:sync audit <feature> khi nghi state drift. CafeKit kỳ vọng machine state và human state đi cùng nhau:

Khi task thành done, spec.json.task_registry và task markdown tương ứng phải khớp. Task phải có verification receipt đọc được: command đã chạy, outcome, artifact proof, runtime proof, hoặc blocker được ghi rõ.

Sau verified task, cân nhắc docs checkpoint. Nếu source behavior đã đổi đến mức docs hoặc onboarding sẽ sai, update docs trước release.

Khi workflow chính rẽ nhánh#

Core flow dùng cho planned feature delivery. Nếu loại việc khác, dùng route khác:

OpenCode equivalent#

OpenCode dùng command không có prefix, nhưng vẫn đọc cùng CafeKit skill bundle:

/specs -> /develop -> /test -> /code-review

Contract không đổi: spec có source backing, từng task một, evidence thật, adversarial review, state đã sync.

Definition of Done#

Một task CafeKit chỉ done khi tất cả điều này đúng:

• Approved task packet đã được implement không có hidden scope change.
• Work có runtime behavior đã wired vào entrypoint thật.
• Completion criteria đã satisfy.
• Verification evidence có exact commands và outcomes.
• Code review không có blocking correctness, security, hoặc regression issue.
• spec.json và task markdown khớp.
• Docs impact đã xử lý hoặc ghi rõ.