@longph2102/v-flow 1.5.0

package/skills/prototype/LOGIC.md

@@ -0,0 +1,240 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## When this is the right shape
+
+- "State machine xử lý edge case X rồi Y thế nào?"
+- "Data model có thực sự biểu diễn được case này không?"
+- "API nên có shape như thế nào trước khi viết thật?"
+- Bất cứ khi nào user muốn **nhấn nút và xem state thay đổi**.
+
+## Process
+
+### 1. State the question (từ spec.md)
+
+Đọc `spec.md` — tìm REQ-xxx có ambiguity markers. Viết rõ câu hỏi ở đầu prototype (README hoặc comment đầu file):
+
+```
+# PROTOTYPE — [Feature NNN]
+# Question: [câu hỏi cụ thể lấy từ spec REQ-xxx]
+# Branch: LOGIC
+# Delete after: verdict captured in prototype-notes.md
+```
+
+### 2. Pick the runtime (auto-detect)
+
+Scan project files theo thứ tự:
+
+| Signal file | Runtime |
+|------------|---------|
+| `package.json` có `"@angular/core"` | Angular + TypeScript |
+| `package.json` không có Angular | Node.js / TypeScript |
+| `bun.lockb` hoặc `bunfig.toml` | Bun |
+| `pom.xml` hoặc `build.gradle` | Java |
+| `requirements.txt` hoặc `pyproject.toml` | Python |
+| Không detect được | → Hỏi user chọn runtime |
+
+Match project's existing tooling conventions — don't add a new package manager or runtime just for the prototype.
+
+### 3. Isolate the logic in a portable module
+
+Put actual logic behind a small, pure interface. The right shape:
+
+- **Pure reducer** — `(state, action) => state`. Khi actions là discrete events.
+- **State machine** — explicit states và transitions. Khi "actions nào legal hiện tại" là một phần câu hỏi.
+- **Pure functions** over plain data type. Khi không có implicit state.
+- **Class/module** với clear method surface. Khi logic cần ongoing internal state.
+
+```
+.v-flow/features/NNN/prototype/logic/
+├── logic.ts        ← pure module (the thing worth keeping)
+├── tui.ts          ← thin shell, throwaway
+├── README.md       ← câu hỏi + run command
+└── package.json    ← chỉ nếu cần isolate deps
+```
+
+Keep it pure: **no I/O, no terminal code, no `console.log` for control flow** in the logic module. TUI imports it; nothing flows the other direction. This makes the logic liftable into real code after prototype is done.
+
+### 4. Build the smallest TUI that exposes the state
+
+Lightweight TUI — on every tick: **clear screen + re-render whole frame**:
+
+```
+console.clear()  // Node/Bun/TypeScript
+print("\033[2J\033[H")  // Python
+// Java: ProcessBuilder("clear").inheritIO().start().waitFor()
+```
+
+Each frame has two parts (in this order):
+
+1. **Current state** — pretty-printed, one field per line or formatted JSON. Use bold for field names (`\x1b[1m`), dim for less important context (`\x1b[2m`), reset (`\x1b[0m`).
+2. **Keyboard shortcuts** — `[a] add item  [d] delete  [t] tick  [q] quit`. Bold key, dim description.
+
+Behavior loop:
+```
+init state → render frame → read keystroke → dispatch handler → mutate state → re-render → loop until [q]
+```
+
+### 4.5. Handling Text & Number Inputs (Prompts)
+
+Nếu TUI cần nhận dữ liệu đầu vào dài từ bàn phím (ví dụ: nhập số tiền, tên, câu trả lời), **BẮT BUỘC phải tạm thời tắt Raw Mode** để tránh xung đột phím tắt và lỗi crash.
+
+#### Node.js (TypeScript) Blueprint:
+```typescript
+import readline from 'readline';
+
+async function promptInput(questionText: string): Promise<string> {
+  // 1. Tắt Raw Mode & Pause stdin để nhập văn bản bình thường
+  process.stdin.setRawMode(false);
+  process.stdin.pause();
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(questionText, (answer) => {
+      rl.close();
+      // 2. Bật lại Raw Mode & Resume stdin để tiếp tục nhận phím tắt menu
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      resolve(answer);
+    });
+  });
+}
+```
+
+Khi muốn gọi nhập liệu trong TUI:
+```typescript
+// Trong event loop handler của tui.ts
+if (key === 'i') { // Ví dụ nhấn 'i' để nhập số tiền
+  const amountStr = await promptInput('Nhập số tiền: ');
+  const amount = parseFloat(amountStr);
+  if (!isNaN(amount)) {
+    state = reducer(state, { type: 'INPUT_AMOUNT', amount });
+  }
+  renderFrame(state);
+}
+```
+
+### 5. Make it runnable in one command
+
+Add script to project's existing task runner:
+
+```json
+// package.json
+"scripts": {
+  "prototype:NNN": "tsx .v-flow/features/NNN/prototype/logic/tui.ts"
+}
+```
+
+```toml
+# pyproject.toml
+[tool.taskipy.tasks]
+prototype-NNN = "python .v-flow/features/NNN/prototype/logic/tui.py"
+```
+
+Document the exact command in `prototype-notes.md` → "Run command" field.
+
+### 5.5. Runtime Verification (Verify before handover)
+
+Trước khi gửi lệnh chạy cho người dùng, Agent **BẮT BUỘC** phải tự chạy thử lệnh chạy đó trên Workspace bằng tool `run_command` để verify:
+- Không bị lỗi biên dịch (TypeScript compile error).
+- Không bị lỗi import path (ví dụ: `@/` path resolution lỗi).
+- Chương trình TUI hiển thị được giao diện ban đầu thành công mà không bị crash ngay lập tức.
+- Bạn có thể chạy thử lệnh với tham số chờ/timeout ngắn (ví dụ: `WaitMsBeforeAsync: 1000` hoặc chạy bất đồng bộ rồi kill task sau 1 giây) để đảm bảo process khởi động thành công và exit code bằng 0 hoặc process vẫn đang run bình thường.
+
+### 6. Hand it over
+
+Give the user the run command. They'll drive it themselves. Interesting moments: "wait, that shouldn't be possible" or "huh, I assumed X" — những lỗi trong _idea_, đó mới là mục tiêu.
+
+### 7. Capture the answer → prototype-notes.md
+
+Khi prototype đã trả lời câu hỏi:
+
+1. Điền verdict vào `prototype-notes.md` (VALIDATED / REJECTED / INCONCLUSIVE)
+2. Map verdict về REQ-xxx trong spec — prototype finding này ảnh hưởng requirement nào?
+3. Append execution trace vào `_session.md`
+4. Update `artifacts.prototype.*` trong `.flow-state.yaml`
+5. Xóa prototype code — chỉ giữ `prototype-notes.md`
+
+## Anti-patterns
+
+- **Don't add tests** — prototype that needs tests is no longer a prototype
+- **Don't wire to real DB** — in-memory unless question is specifically about persistence
+- **Don't generalise** — "what if we want X later" is out of scope. Answer one question.
+- **Don't blur logic and TUI** — if reducer references `console.log` or escape codes, it's no longer portable
+- **Don't ship TUI to production** — shell is optimised for hand-driven terminal, not users
+
+---
+
+## Async / Event-driven State Machines
+
+Khi câu hỏi liên quan đến **timers, polling, hoặc external events** (webhooks, queue messages, websocket), TUI cần mô phỏng async mà không cần infrastructure thật.
+
+### Pattern: Manual tick command
+
+Thêm `[t] tick` vào keyboard shortcuts — mỗi lần nhấn `t` giả lập 1 đơn vị thời gian trôi qua:
+
+```typescript
+// logic.ts — async events được model thành discrete actions
+type Action =
+  | { type: 'SUBMIT' }
+  | { type: 'TICK' }          // ← giả lập thời gian trôi qua (polling cycle, timer, etc.)
+  | { type: 'WEBHOOK_OK' }    // ← giả lập external event thành công
+  | { type: 'WEBHOOK_FAIL' }  // ← giả lập external event thất bại
+
+function reducer(state: State, action: Action): State {
+  switch (state.status) {
+    case 'PENDING':
+      if (action.type === 'SUBMIT') return { ...state, status: 'PROCESSING', ticks: 0 };
+      break;
+    case 'PROCESSING':
+      if (action.type === 'TICK') {
+        const ticks = state.ticks + 1;
+        // Giả lập timeout sau 5 ticks
+        return ticks >= 5 ? { ...state, status: 'TIMED_OUT' } : { ...state, ticks };
+      }
+      if (action.type === 'WEBHOOK_OK')   return { ...state, status: 'DONE' };
+      if (action.type === 'WEBHOOK_FAIL') return { ...state, status: 'FAILED', retries: state.retries + 1 };
+      break;
+  }
+  return state;
+}
+```
+
+```typescript
+// tui.ts — keyboard shortcuts map sang actions + external events
+const keyMap: Record<string, Action> = {
+  's': { type: 'SUBMIT' },
+  't': { type: 'TICK' },           // "[t] tick (simulate time passing)"
+  'o': { type: 'WEBHOOK_OK' },     // "[o] webhook ok"
+  'f': { type: 'WEBHOOK_FAIL' },   // "[f] webhook fail"
+};
+```
+
+Frame render hiển thị `ticks` để user biết đang ở đâu trong timeline:
+
+```
+Status: PROCESSING
+Ticks elapsed: 3 / 5 (timeout at 5)
+Retries: 0
+
+[s] submit  [t] tick  [o] webhook ok  [f] webhook fail  [q] quit
+```
+
+### Khi nào dùng pattern này
+
+- Câu hỏi về **timeout/retry logic** — bao nhiêu ticks thì timeout? retry có reset counter không?
+- Câu hỏi về **race condition** — submit 2 lần trước khi webhook về thì sao?
+- Câu hỏi về **external event ordering** — nếu webhook về trước khi processing xong thì state là gì?
+
+### Anti-patterns (async-specific)
+
+- **Đừng dùng `setTimeout` thật trong TUI** — async loop phức tạp, khó debug, khó drive by hand. Manual tick đủ để trả lời câu hỏi.
+- **Đừng mock real HTTP** — dùng keyboard shortcut `[o]`/`[f]` thay vì `fetch()` stub. Mục tiêu là drive state, không phải simulate network.
+

package/skills/prototype/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: prototype
+description: >
+  Tạo throwaway prototype để resolve ambiguity trong spec trước khi lên plan.
+  Hai nhánh: LOGIC (validate state machine/data model qua terminal TUI)
+  hoặc UI (gen multi-variant UI dùng design tokens của dự án).
+  Chỉ dùng khi spec có câu hỏi chưa trả lời được bằng văn bản.
+phase: "S.1.5"
+trigger: "Khi /v.prototype hoặc BA Agent gợi ý prototype do phát hiện ambiguity trong spec"
+used_by:
+  - /v.prototype
+  - /v.specify (ba-agent-ambiguity-suggest)
+hooks:
+  pre_prototype: "Đọc spec.md → xác định câu hỏi + REQ refs → chọn branch"
+  post_prototype: "Chạy thử (test-run) để verify → Ghi prototype-notes.md → append _session.md → update .flow-state.yaml → gợi ý cleanup"
+output:
+  - "prototype-notes.md"
+  - "_session.md append"
+  - ".flow-state.yaml update"
+---
+
+# Prototype Skill
+
+> ⚠️ Đây là **Skill bắt buộc** cho Prototype Agent khi được kích hoạt.
+> Đọc skill này TRƯỚC khi tạo bất kỳ prototype code nào.
+>
+> → Xem `gotchas.md` cho các lỗi phổ biến — đặc biệt G-001, G-002, G-005.
+> → Xem `examples/good/` và `examples/bad/` cho mẫu `prototype-notes.md` chuẩn.
+> → Xem `config.json` để customize (default_variants, default_framework, ambiguity_markers).
+> → Chạy scripts validate trước khi routing:
+>   - **Linux/macOS**: `.v-flow/skills/prototype/scripts/check-prototype-notes.sh`
+>   - **Windows (PowerShell)**: `.v-flow/skills/prototype/scripts/check-prototype-notes.ps1`
+
+---
+
+## Khi nào KHÔNG cần Prototype
+
+- Spec đã rõ ràng — mọi REQ có AC cụ thể, không có ambiguity markers
+- Câu hỏi có thể trả lời bằng văn bản trong spec (≤ 2 câu giải thích)
+- Quick Fix hoặc Hotfix flow — không đủ time budget cho prototype
+- Prototype của feature tương tự đã được chạy trong cùng epic (có thể tái dùng verdict)
+
+---
+
+## Pick a branch
+
+Identify which question is being answered — từ spec.md, từ `--question`, từ `--req`, hoặc hỏi thẳng user:
+
+- **"Logic/behavior/state model có đúng không?"** → [LOGIC.md](LOGIC.md). Terminal TUI cho phép drive state machine qua real cases.
+- **"UI nên trông như thế nào?"** → [UI.md](UI.md). Multi-variant web UI switchable qua URL param.
+
+Nếu câu hỏi genuinely ambiguous và user không available, áp dụng theo thứ tự:
+
+```
+1. --req hoặc --question được chỉ định?  → Dùng câu đó, bỏ qua bước 2-4
+2. Chỉ có 1 REQ với ambiguity marker?    → Dùng REQ đó
+3. Nhiều REQ có ambiguity markers?       → Ưu tiên theo REQ type: S > E > U > O
+                                            Cùng type → chọn REQ đầu tiên trong spec
+4. Không detect được REQ nào?            → Báo user: "Spec khá sạch, prototype có thể không cần"
+```
+
+**Chọn branch khi ambiguous** (xem `config.json` §auto_rules cho đầy đủ):
+
+| Context signal | Branch |
+|---|---|
+| REQ type E hoặc S | LOGIC |
+| Ambiguity nằm trong UI/Layout section của spec | UI |
+| AC có từ khóa state/flow ("trạng thái", "transition", "khi nào") | LOGIC |
+| Module là backend service / API | LOGIC |
+| Module là frontend page / component | UI |
+| Không detect được | LOGIC _(safer default — TUI ít side-effects hơn UI variant)_ |
+
+**Bắt buộc khi AFK**: Ghi rõ assumption ở đầu prototype README:
+```
+# ASSUMPTION (User AFK): Defaulted to LOGIC branch
+# Signal detected: REQ-S02 is State type
+# Override: Re-run with --ui nếu assumption sai
+```
+
+
+---
+
+## V Flow Integration Layer
+
+### Input
+
+Khi được kích hoạt, agent phải đọc theo thứ tự:
+
+1. **`spec.md`** — extract câu hỏi cần prototype trả lời (tìm REQ-xxx có ambiguity markers)
+   - Nếu user dùng `--req REQ-E01` → focus vào REQ đó, không cần scan toàn bộ spec
+   - Nếu user dùng `--question "..."` → dùng câu đó, liên kết ngược về REQ gần nhất
+2. **`DESIGN.md`** (chỉ UI branch) — lookup order:
+   - `[project-root]/DESIGN.md` — project override (nếu tồn tại, ưu tiên)
+   - `[project-root]/.v-flow/DESIGN.md` — fallback (auto-copy lúc `v-flow init`)
+2b. **`ui/mockups/` + UI Intent (spec §2)** (chỉ UI mode `from-mockup`) — ảnh mockup + Bố cục/Kế thừa trang/Mức ràng buộc. **Cấu trúc** render lấy từ đây; **style** lấy từ `DESIGN.md` (không copy pixel từ ảnh).
+3. **`config.json`** (optional) — override default behavior (variants, framework, subshape)
+
+### Ambiguity markers cần detect trong spec
+
+```
+Keywords VI: "chưa rõ", "cần thảo luận", "phụ thuộc", "có thể là A hoặc B",
+             "TBD", "tùy thiết kế", "xem mockup", "cần xác nhận", "đang xem xét"
+Keywords EN: "unclear", "to be decided", "pending", "tbc", "needs clarification"
+Patterns:    Acceptance Criteria trống hoặc quá vague
+             State transitions có nhiều nhánh chưa được validate
+             UI section không có wireframe hoặc reference
+```
+
+### Output bắt buộc
+
+- **`prototype-notes.md`** → lưu tại `.v-flow/features/NNN/prototype-notes.md`
+- **Append verdict block** vào `_session.md` (xem template bên dưới)
+- **Update `.flow-state.yaml`** — điền `artifacts.prototype.*`
+
+### Verdict levels
+
+| Verdict | Ý nghĩa | Routing |
+|---------|---------|---------|
+| `VALIDATED` | Prototype xác nhận hướng đúng | Tiếp tục → `/v.plan + /v.test` |
+| `REJECTED` | Prototype phát hiện hướng sai | Sửa spec → `/v.specify` |
+| `INCONCLUSIVE` | Chưa đủ thông tin | Tạm dừng, chờ stakeholder |
+
+### Session append block
+
+Sau khi có verdict, append vào `_session.md`:
+
+```markdown
+### [S.1.5] Prototype — [YYYY-MM-DD]
+- **Agent**: Prototype Agent
+- **Branch**: [LOGIC | UI]
+- **Mode**: [N/A (LOGIC) | from-mockup | explore]
+- **Sub-shape**: [N/A | A — embedded in existing page | B — new throwaway route]
+- **Question**: [câu hỏi prototype trả lời]
+- **REQ refs**: [REQ-xxx, REQ-xxx]
+- **Verdict**: [VALIDATED | REJECTED | INCONCLUSIVE]
+- **Prototype location**: `.v-flow/features/NNN/prototype/[logic|ui]/`
+- **Approved render**: [`ui/approved/UC-NN.*` (mode=from-mockup) | N/A]
+- **Key findings**: [tóm tắt 1-2 câu]
+- **Spec impact**: [no change | update needed | new REQ added]
+- **Routing**: [→ /v.plan + /v.test | → /v.specify | → awaiting stakeholder]
+```
+
+---
+
+## Nguyên tắc cốt lõi (applies to both branches)
+
+1. **Throwaway từ đầu** — đặt tên rõ là prototype, không nhầm với production code
+2. **One command to run** — user chạy được ngay, không cần giải thích path phức tạp
+3. **No persistence by default** — state ở memory, không phụ thuộc DB
+4. **Skip the polish** — không cần test, error handling, abstraction
+5. **Surface the state** — sau mỗi action (LOGIC) hoặc variant switch (UI), hiển thị state đầy đủ
+6. **Delete or absorb when done** — *(Explore)* verdict là thứ duy nhất đáng giữ. *(Reproduce / `--from-mockup`)* render `ui/approved/UC-NN.*` được **GIỮ** làm contract — không xóa.
+
+Locate prototype code at **`.v-flow/features/NNN/prototype/logic/`** or **`.v-flow/features/NNN/prototype/ui/`** — trong feature folder, gần spec/plan/test-cases.
+
+---
+
+## V-Flow Integration Points
+
+| File | Role |
+|------|------|
+| `spec.md` | Input chính — source of ambiguity questions + REQ refs + UI Intent |
+| `DESIGN.md` | Design tokens cho UI branch (style authority) |
+| `ui/mockups/` | [from-mockup] Ảnh mockup — nguồn cấu trúc/layout |
+| `ui/approved/` | [from-mockup] Render đã chốt — visual contract (GIỮ) |
+| `config.json` | Customize prototype behavior per-project |
+| `prototype-notes.md` | **Output chính** — verdict + findings (file duy nhất đáng giữ) |
+| `_session.md` | Execution trace — carry-forward cho Plan Agent |
+| `.flow-state.yaml` | Machine-readable state — `artifacts.prototype.*` |
+| `.v-flow/templates/prototype-notes-template.md` | Format chuẩn cho prototype-notes.md |
+| `.v-flow/skills/prototype/scripts/check-prototype-notes.sh` / `.ps1` | Validate prototype-notes.md đủ fields trước khi routing |
+| `.v-flow/skills/prototype/scripts/check-flow-state.sh` / `.ps1` | Verify .flow-state.yaml đã được update |
+| `.v-flow/skills/prototype/scripts/check-prototype-cleanup.sh` / `.ps1` | Kiểm tra prototype/ code đã được cleanup |
+
+---
+
+## When done
+
+The _answer_ is the only thing worth keeping *(Explore)* — capture it in `prototype-notes.md` trước khi xóa prototype code. *(Reproduce)* ngoài verdict, render `ui/approved/UC-NN.*` cũng được giữ làm contract. Verdict + (nếu có) render chốt là input cho Plan Agent — carry-forward qua `_session.md`.
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho các lỗi phổ biến khi tạo prototype — cập nhật liên tục.