@longph2102/v-flow 1.5.0

package/commands/v.import-ba-docs.md

@@ -0,0 +1,222 @@
+---
+description: "Import BA Docs Agent — Trích xuất tài liệu BA từ Google NotebookLM vào Module Cards (Optional — U.0d)"
+phase: "U.0d"
+agent: "import-ba-docs-agent"
+optional: true
+dependency: "notebooklm-py (unofficial — pip install notebooklm-py)"
+---
+
+# /v.import-ba-docs
+
+> Orchestration wrapper cho **Import BA Docs Agent**. Đọc `agents/import-ba-docs-agent.md` để thực hiện core logic.
+
+> ⚠️ **OPTIONAL PHASE** — Phase U.0d không bắt buộc.
+> Phụ thuộc vào `notebooklm-py` — thư viện unofficial, có thể break bất cứ lúc nào.
+> Nếu không dùng được, BA export thủ công (PDF/copy-paste) → đặt vào `.v-flow/modules/{module}/raw/`
+
+---
+
+## Prerequisites
+
+Trước khi chạy, cần đảm bảo:
+
+```
+1. pip install "notebooklm-py[browser]"
+2. playwright install chromium
+3. notebooklm login          ← Mở browser, login Google account
+4. notebooklm list           ← Verify thấy notebooks của BA
+```
+
+Nếu bất kỳ bước nào fail → thông báo user và **hướng dẫn fallback thủ công**.
+
+---
+
+## Modes
+
+### Mode B: `--interactive` — User chọn cách nhóm sources (MẶC ĐỊNH)
+
+```
+/v.import-ba-docs --notebook <id> --interactive
+/v.import-ba-docs --notebook <id>                ← mặc định = interactive
+```
+
+Dành cho: **1 notebook lớn chứa nhiều sources thuộc nhiều domain khác nhau.**
+User sẽ được hỏi cách nhóm sources → tạo nhiều Module Cards.
+
+### Mode A: `--module <name>` — 1 Notebook → 1 Module Card
+
+```
+/v.import-ba-docs --notebook <id> --module <name>
+```
+
+Dành cho: **BA đã tổ chức 1 notebook/domain.** Tất cả sources trong notebook → 1 module card.
+
+### Mode A+: `--module <name> --sources <ids>` — Chọn sources cụ thể
+
+```
+/v.import-ba-docs --notebook <id> --module <name> --sources src1,src2,src3
+```
+
+Dành cho: **Chọn thủ công** một số sources từ notebook lớn → 1 module card.
+
+### Mode C: `--auto-split` — AI đề xuất cách nhóm
+
+```
+/v.import-ba-docs --notebook <id> --auto-split
+```
+
+Dành cho: **Notebook rất lớn, nhiều sources.** AI phân tích titles + summaries → đề xuất nhóm → user confirm.
+
+### Utility: `--raw-only` — Chỉ lấy raw data
+
+```
+/v.import-ba-docs --notebook <id> --module <name> --raw-only
+```
+
+Chỉ download raw materials, không generate AI drafts.
+
+### Utility: `--refresh` — Cập nhật module card
+
+```
+/v.import-ba-docs --notebook <id> --module <name> --refresh
+```
+
+Re-download raw materials mới, so sánh diff với bản cũ → output diff report (sources UNCHANGED/MODIFIED/NEW/DELETED + affected drafts). Hỏi user: `"Cập nhật drafts tự động? (Y/n/manual review)"`.
+Sections đã được Human verify (không còn tag `[⚠️ AI-inferred]`) → KHÔNG ghi đè, chỉ ghi warning.
+
+---
+
+## Execution
+
+1. Đọc agent definition: `agents/import-ba-docs-agent.md`
+2. Đọc Skill scan strategy: `skills/understand/ba-docs-scanner/SKILL.md`
+3. Thực hiện quy trình trong agent definition theo mode được chọn
+
+### Bước 1: Kiểm tra điều kiện
+
+1. Kiểm tra `notebooklm` CLI: `notebooklm --version`
+2. Kiểm tra auth: `notebooklm auth check`
+3. Kiểm tra `.v-flow/` đã tồn tại
+
+### Bước 2: Kết nối notebook & liệt kê sources
+
+```bash
+notebooklm use <notebook_id>
+notebooklm status
+notebooklm source list --json
+```
+
+### Bước 3: Xác định mapping Sources → Module Cards
+
+- **Interactive (mặc định)**: Hiển thị sources → user nhóm thủ công
+- **1:1 (--module)**: Tất cả sources → 1 module
+- **Auto-split (--auto-split)**: AI đề xuất nhóm từ titles + summaries → user confirm
+
+### Bước 4: Trích xuất raw materials (cho mỗi module)
+
+```bash
+mkdir -p .v-flow/modules/{module-name}/raw/sources/
+
+# Fulltext từng source
+notebooklm source fulltext $source_id -o raw/sources/{title}.txt
+
+# Mind-map, briefing doc, study guide
+notebooklm generate mind-map -s src1 -s src2
+notebooklm download mind-map raw/domain-map.json
+notebooklm generate report --format briefing-doc --wait
+notebooklm download report raw/overview.md
+```
+
+> ⚠️ Nếu `generate report` fail (rate limit) → skip, ghi warning. Raw fulltext đủ để tiếp tục.
+> ⚠️ Với `--raw-only` → DỪNG ở đây.
+
+### Bước 5: AI generate Module Card drafts
+
+> **TRƯỚC KHI GENERATE**: Agent PHẢI đọc 2 files:
+> 1. 📖 `skills/understand/ba-docs-scanner/SKILL.md` — scan strategy chi tiết cho từng loại draft
+> 2. 📖 `skills/understand/ba-docs-scanner/gotchas.md` — anti-patterns và quality gate
+
+Thực hiện generate theo hướng dẫn trong Agent + Skill. Kết quả:
+
+| File | Khi nào tạo |
+|------|------------|
+| `SKILL.md` | Luôn tạo (entry point + glossary + constraints) |
+| `use-cases.md` | Luôn tạo (E2E flows + business rules trích dẫn) |
+| `cross-service.md` | Nếu BA docs đề cập tích hợp |
+| `state-diagram.md` | Nếu BA docs mô tả trạng thái |
+| `permissions.md` | Nếu BA docs mô tả phân quyền |
+| `db.md` | Nếu BA docs mô tả data model |
+| `ui-flows.md` | Nếu BA docs mô tả giao diện |
+| `api-specs.md` | ⏳ Placeholder (chờ code scan) |
+| `tech-context.md` | ⏳ Placeholder (chờ code scan) |
+
+### Bước 6: Output summary
+
+Hiển thị: files đã tạo, thống kê (BR count, flows, glossary terms), files cần BA review, bước tiếp theo.
+
+---
+
+## Merge với U.0b (Code Scan)
+
+> 📖 Xem chi tiết: `skills/understand/ba-docs-scanner/merge-rules.md`
+
+Khi chạy `/v.understand --module {tên}` trên module đã có U.0d data → merge BA content với code scan results.
+
+---
+
+## Fallback khi không có notebooklm-py
+
+```
+⚠️ notebooklm-py không khả dụng. Hãy export thủ công:
+
+1. Mở NotebookLM web (https://notebooklm.google.com)
+2. Với mỗi domain/module:
+   a. Copy nội dung sources → lưu vào .v-flow/modules/{module}/raw/sources/
+   b. Generate Study Guide trên web → download → lưu vào raw/
+   c. Screenshot Mind Map → lưu vào raw/
+3. Chạy /v.import-ba-docs --module {tên} --raw-only
+   (skip NotebookLM, chỉ đọc files trong raw/ để generate drafts)
+```
+
+---
+
+## Ví dụ sử dụng
+
+```bash
+/v.import-ba-docs --notebook abc123
+/v.import-ba-docs --notebook abc123 --module domain-wo
+/v.import-ba-docs --notebook abc123 --auto-split
+/v.import-ba-docs --notebook abc123 --module domain-wo --raw-only
+/v.import-ba-docs --notebook abc123 --module domain-wo --refresh
+```
+
+---
+
+## Bước tiếp theo sau khi chạy
+
+```
+1. BA review: use-cases.md, SKILL.md — xác nhận business rules     [BẮT BUỘC]
+2. BA xóa tag [⚠️ AI-inferred] sau khi verify                      [BẮT BUỘC]
+3. (Song song) Chạy /v.understand --module {tên}           [BẮT BUỘC]
+   → AI scan codebase → điền api-specs, tech-context, ui-flows, db, state-diagram, permissions
+   → Merge với U.0d data nếu có
+4. Tech Lead review: SKILL.md — set Last verified date              [BẮT BUỘC]
+5. Tiến sang S.0a hoặc S.1                                         [Khi sẵn sàng]
+```
+
+---
+
+## Cập nhật State & Session
+
+**Không cập nhật `.flow-state.yaml`** — U.0d là optional, project-level.
+
+**Append vào `_session.md`** (nếu đang trong feature context):
+```markdown
+### [U.0d] Import BA Docs — [YYYY-MM-DD]
+- **Agent**: Import BA Docs Agent
+- **Source**: NotebookLM notebook [ID]
+- **Mode**: [interactive | 1:1 | auto-split | raw-only]
+- **Modules created**: [N]
+- **Files generated**: [list]
+- **Routing**: → /v.understand --module (deep scan)
+```

package/commands/v.metrics.md

@@ -0,0 +1,74 @@
+---
+description: "Thu thập và phân tích Agent Metrics sau mỗi feature cycle"
+phase: "M.0"
+agent: "metrics-agent"
+---
+
+# /v.metrics
+
+> Orchestration wrapper cho **Metrics Agent**. Đọc `agents/metrics-agent.md` để thực hiện core logic.
+
+## Điều kiện tiên quyết
+- Feature phải đã qua **R.1** (Code Review hoàn thành)
+- `spec.md`, `tasks.md`, `validation-report.md` phải tồn tại
+- `_session.md` nên có execution trace
+
+## Execution
+1. Đọc agent definition: `agents/metrics-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Tạo `metrics-report.md`
+
+## Options
+
+### (không có argument) — Feature hiện tại
+Đo metrics cho feature đang active trong context.
+
+### --aggregate — Tổng hợp nhiều features
+```
+/v.metrics --aggregate 5
+```
+Tổng hợp metrics từ 5 features gần nhất, phát hiện trends và rút ra improvement areas.
+
+---
+
+## 🔀 Routing Rules — Sau Metrics
+
+```
+Metrics report tạo xong
+  → Route: /v.retrospective (nếu chưa chạy)
+  → Hoặc: Feature complete — archive
+
+Phát hiện Agent cần cải tiến urgently
+  → Đề xuất sửa agent-config.md TRƯỚC feature tiếp theo
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "M.0"
+phase_status: "done"
+artifacts:
+  metrics_report:
+    exists: true
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [M.0] Metrics — [YYYY-MM-DD]
+- **Agent**: Metrics Agent
+- **Output**: `metrics-report.md`
+- **Key findings**: [top 3 findings]
+- **Recommendations**: [top 3 recommendations]
+- **Routing**: → /v.retrospective
+```
+
+---
+
+## Ví dụ
+
+```
+/v.metrics
+/v.metrics feature 001-user-login
+/v.metrics --aggregate 5
+```

package/commands/v.operations.md

@@ -0,0 +1,70 @@
+---
+description: "Operations Agent — rà soát vận hành định kỳ / phân loại incident production rồi route flow khắc phục (O.0)"
+phase: "O.0"
+agent: "operations-agent"
+---
+
+# /v.operations
+
+> Orchestration wrapper cho **Operations Agent**. Đọc `agents/operations-agent.md` để thực hiện core logic.
+> Khác `/v.hotfix` (vào thẳng flow khẩn P1/P2): `/v.operations` là **điểm vào O.0 thường xuyên** — rà soát vận hành sau deploy (M.0 → O.0) hoặc phân loại tín hiệu production trước khi quyết định flow.
+
+## Điều kiện sử dụng
+
+- Có alert/log/user report từ production cần đánh giá, **hoặc**
+- Rà soát vận hành định kỳ sau khi feature đã deploy (chu trình M.0 → O.0)
+
+## Execution
+1. Đọc agent definition: `agents/operations-agent.md`
+2. Thực hiện toàn bộ quy trình: assess severity (P1–P4) → root cause sơ bộ + scope → route
+3. Ghi `operations-report.md` (+ `incidents/INC-XXX.md` nếu là incident) theo `.v-flow/templates/operations-report-template.md`
+
+---
+
+## 🔀 Routing Rules — Sau Operations
+
+```
+Severity = P1 / P2 (production down / nghiêm trọng)
+  → Route: /v.hotfix (O.0 → B.1 → R.1 → O.0)
+
+Severity = P3 và cần root cause + regression prevention
+  → Route: /v.bugfix (S.1 → B.0 → B.1 → R.1)
+
+Severity = P4 / thay đổi nhỏ (<5 files)
+  → Route: /v.quickfix (S.1 nhanh → B.1 → R.1)
+
+Không phải lỗi / chỉ theo dõi
+  → Route: monitor — ghi nhận vào knowledge base, không trigger fix
+```
+
+> Closed-loop: feedback từ production quay lại pipeline (spec/test/knowledge) để incident không lặp lại.
+
+## Input
+- Tín hiệu production: alert / log / user report (mô tả qua argument hoặc đính kèm)
+- `.v-flow/features/NNN-feature/` *(nếu incident gắn với feature cụ thể)*
+- `.v-flow/constitution.md`
+
+## Output
+- `.v-flow/features/NNN-feature/operations-report.md` *(hoặc thư mục feature liên quan)*
+- `.v-flow/incidents/INC-XXX.md` *(nếu là incident — đánh số tăng dần)*
+
+## Ví dụ
+
+```
+/v.operations
+/v.operations "API /checkout trả 500 tăng đột biến từ 14:00"
+```
+
+---
+
+## Cập nhật State & Session
+
+**Append vào `_session.md`**:
+```markdown
+### [O.0] Operations — [YYYY-MM-DD]
+- **Agent**: Operations Agent
+- **Severity**: [P1 | P2 | P3 | P4]
+- **Root cause (sơ bộ)**: [...]
+- **Route decision**: [hotfix | bugfix | quickfix | monitor]
+- **Routing**: → [next step]
+```

package/commands/v.plan.md

@@ -0,0 +1,78 @@
+---
+description: "Plan Agent — Thiết kế kiến trúc và tạo Implementation Plan + Task Breakdown"
+phase: "B.0a"
+agent: "plan-agent"
+optional_agents: ["security", "ux", "api-contract"]
+---
+
+# /v.plan
+
+> Orchestration wrapper cho **Plan Agent**. Đọc `agents/plan-agent.md` để thực hiện core logic.
+
+## Điều kiện tiên quyết
+- `spec.md` phải tồn tại và đã **Approved**
+- `constitution.md` phải tồn tại
+- Chạy **SONG SONG** với `/v.test`
+
+## Execution
+1. Đọc agent definition: `agents/plan-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Áp dụng command options bên dưới (nếu có)
+
+## Options
+
+### --with-security
+Kích hoạt **Security Agent** — tạo `security-review.md`.
+Dùng khi: Feature có auth, payment, user data, external API.
+
+### --with-ux
+Kích hoạt **UX Agent** — tạo `ux-checklist.md` theo `.v-flow/templates/ux-checklist-template.md`.
+Dùng khi: Feature có UI/UX components.
+
+### --with-api
+Kích hoạt **API Contract Agent** — tạo `contracts/api-contract.md` theo `.v-flow/templates/api-contract-template.md`.
+Dùng khi: Feature expose API cho client/3rd party (hoặc contract-first khi có cả FE+BE).
+
+> Các optional agents chạy **SONG SONG** với Plan Agent (Map-Reduce B.0).
+
+---
+
+## 🔀 Routing Rules — Sau Plan
+
+```
+Plan + Tasks tạo xong
+  → Nếu /v.test chưa xong → Chờ Test Agent
+  → Nếu /v.test đã xong   → /v.check (Master Check)
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "B.0a"
+phase_status: "done"
+artifacts:
+  plan: { exists: true, synced_to_spec: "v1.0" }
+  tasks: { exists: true, total: [N] }
+b0_outputs:
+  plan: { exists: true, agent: "Plan Agent" }
+  tests: { exists: true, agent: "Test Agent" }
+  security: { exists: true/false, skipped: true/false }
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [B.0a] Plan — [YYYY-MM-DD]
+- **Output**: plan.md, tasks.md ([N] tasks)
+- **Annotations**: [N] parallel, [N] critical, [N] risky, [N] gates
+- **Optional agents**: security=[yes/no], ux=[yes/no], api=[yes/no]
+```
+
+---
+
+## Ví dụ
+
+```
+/v.plan Feature 001-user-login
+/v.plan --with-security --with-api
+```

package/commands/v.prototype.md

@@ -0,0 +1,121 @@
+---
+description: "Prototype Agent — Reproduce (dựng render chốt từ mockup qua DESIGN.md) hoặc Explore (variant throwaway) để chốt giao diện/validate ambiguity trước khi lên plan"
+phase: "S.1.5"
+agent: "prototype-agent"
+optional: true
+---
+
+# /v.prototype
+
+> **Optional** step tại S.1.5 — sau Specify (S.1), trước Plan (B.0).
+> Hai chế độ: **Reproduce (`--from-mockup`)** — dựng render chốt (`ui/approved/`) từ mockup đã ingest qua DESIGN.md; **Explore (`--ui`/`--logic`)** — prototype throwaway khi spec còn câu hỏi chưa trả lời được bằng văn bản.
+> **Không block pipeline** — user có thể skip và tiếp tục `/v.plan` bình thường.
+
+## Điều kiện tiên quyết
+
+- `spec.md` phải tồn tại (không cần Approved — Draft cũng chạy được)
+- Câu hỏi cần trả lời được xác định (từ spec hoặc user chỉ định qua `--question`)
+
+## Options
+
+### `--logic`
+Ép buộc LOGIC branch (terminal TUI). Bỏ qua branch selection tự động.
+
+### `--ui`
+Ép buộc UI branch (multi-variant HTML/CSS prototype — mode **Explore**). Bỏ qua branch selection tự động.
+
+### `--from-mockup`
+**UI branch — mode Reproduce.** Dùng khi UC có mockup định hướng. Agent tự lấy ảnh từ **con trỏ `Mockup nguồn`** (spec UI Intent §2) hoặc `ui/mockups/` (do human đặt) — đọc/trích ảnh **tại bước này** (render được human duyệt). Link Figma → đọc qua **Figma MCP** (`get_design_context`/`get_screenshot`); không có MCP → export PNG/SVG vào `ui/mockups/`. Thay vì sinh nhiều variant, agent dựng **1 render trung thực** qua `DESIGN.md` và lưu `ui/approved/UC-NN.*` làm **visual contract** (không throwaway). Cấu trúc bám mockup, style từ design system (không copy pixel).
+Thường kèm `--req REQ-xxx` (hoặc `--question`) để xác định UC/màn hình. Kết hợp `--framework` nếu muốn render bằng framework dự án.
+
+### `--framework <name>`
+**Chỉ áp dụng cho UI branch.** Thường dùng kèm với `--ui`.
+Nếu không có flag này: generate **HTML + CSS thuần** (mặc định, không cần setup, mở ngay trên trình duyệt).
+
+Framework hỗ trợ:
+- `--framework react` → TSX + CSS Module
+- `--framework vue` → Vue SFC (`.vue`)
+- `--framework angular` → Angular Component
+- `--framework next` → Next.js page component
+
+### `--question "..."`
+Chỉ định câu hỏi cụ thể cần prototype trả lời.
+Nếu không có, agent tự detect từ ambiguity markers trong `spec.md`.
+
+### `--req <REQ-ID>`
+Chỉ định trực tiếp requirement cần prototype trả lời (ví dụ: `--req REQ-E03`).
+Agent sẽ đọc REQ đó trong `spec.md`, extract câu hỏi, và tự xác định branch phù hợp.
+
+**Ưu tiên**: `--req` > `--question` > auto-detect từ spec.
+
+> **Lưu ý**: Nếu REQ chỉ định không có ambiguity markers, agent sẽ confirm với user trước khi tiến hành.
+
+### `--subshape <A|B>`
+**Chỉ áp dụng cho UI branch.**
+- `A` — Embed variants vào existing page (preferred, mặc định)
+- `B` — Tạo throwaway route mới (last resort)
+
+Nếu không có flag này: agent tự hỏi user hoặc default theo `config.json`.
+
+## Ví dụ
+
+```
+/v.prototype
+/v.prototype --req REQ-S02
+/v.prototype --req REQ-E03 --logic
+/v.prototype --from-mockup --req REQ-U05
+/v.prototype --from-mockup --req REQ-U05 --framework react
+/v.prototype --ui --question "Dashboard layout nên dùng sidebar hay top nav?"
+/v.prototype --ui --subshape A --framework react --req REQ-U05
+/v.prototype --ui --framework react --question "Dashboard layout nên dùng sidebar hay top nav?"
+/v.prototype --logic --question "State machine xử lý concurrent upload có đúng không?"
+/v.prototype --logic
+```
+
+## Routing Rules — Sau khi có verdict
+
+```
+VALIDATED
+  → Ghi verdict vào .v-flow/features/NNN/prototype-notes.md
+  → [mode=from-mockup] Lưu render chốt vào ui/approved/UC-NN.* + cập nhật spec UI Intent "Render đã chốt"
+  → Append execution trace vào _session.md
+  → Update .flow-state.yaml (artifacts.prototype.verdict = VALIDATED, mode, approved_ref)
+  → ✅ Suggest: /v.plan + /v.test (chạy song song)
+
+REJECTED
+  → Ghi verdict + lý do + spec impact vào prototype-notes.md
+  → ⚠️  Alert: "Spec cần được cập nhật trước khi plan"
+  → Route: /v.specify (update spec với findings từ prototype)
+  → Update .flow-state.yaml (artifacts.prototype.verdict = REJECTED)
+
+INCONCLUSIVE
+  → Ghi open questions vào prototype-notes.md
+  → 🔔 Notify: "Cần thêm input từ stakeholder để kết luận"
+  → Pipeline tạm dừng — user quyết định: iterate prototype hay tiếp tục với assumptions
+  → Update .flow-state.yaml (artifacts.prototype.verdict = INCONCLUSIVE)
+
+Skip prototype (user bỏ qua hoàn toàn)
+  → Pipeline tiếp tục bình thường
+  → Update .flow-state.yaml (artifacts.prototype.skipped = true)
+  → Suggest: /v.plan + /v.test
+```
+
+## Output
+
+```
+.v-flow/features/NNN/
+├── prototype-notes.md    ← verdict + findings
+├── ui/approved/          ← [mode=from-mockup] render đã chốt — GIỮ làm contract
+│   └── UC-NN.[html|tsx|...]
+└── prototype/            ← [explore] throwaway code (xóa sau khi có verdict)
+    ├── [logic.ts | VariantA.tsx | ...]
+    └── README.md
+```
+
+## Read next
+
+- `agents/prototype-agent.md` — chi tiết workflow của agent
+- `skills/prototype/SKILL.md` — branch selection + V Flow integration
+- `skills/prototype/LOGIC.md` — terminal TUI branch
+- `skills/prototype/UI.md` — multi-variant UI branch
+- `.v-flow/templates/prototype-notes-template.md` — output format chuẩn