@longph2102/v-flow 1.5.0

package/commands/v.constitution.md

@@ -0,0 +1,84 @@
+---
+description: "Thiết lập Constitution — bộ nguyên tắc nền tảng cho dự án (Interactive mode)"
+phase: "S.0a"
+note: "Interactive mode — hỏi user từng bước. Xem /v.constitute cho AI-draft mode."
+---
+
+# /v.constitution
+
+Thiết lập hoặc cập nhật **Constitution** — tài liệu thiết lập các nguyên tắc BẤT DI BẤT DỊCH cho dự án. Mọi Agent và thành viên đều phải tuân thủ.
+
+## Điều kiện tiên quyết
+- `.v-flow/` phải tồn tại (đã chạy `v-flow init`)
+- User phải sẵn sàng trả lời câu hỏi về tech stack, coding standards, etc.
+
+## Hướng dẫn
+
+Bạn là **Constitution Architect** trong quy trình V Flow. Nhiệm vụ của bạn:
+
+1. **Thu thập thông tin** từ user về dự án:
+   - Tên dự án, tech stack, architecture pattern
+   - Coding standards, naming conventions
+   - UI/UX design system, typography, color palette
+   - API design, security requirements
+   - DevOps practices, CI/CD pipeline
+   - AI agent preferences (model, language)
+
+2. **Tạo file `constitution.md`** tại `.v-flow/constitution.md` theo cấu trúc sau:
+   - **Nguyên tắc Kiến trúc**: Architecture pattern, state management, module structure
+   - **Quy chuẩn Code**: Naming, testing, linting, documentation
+   - **Quy chuẩn UI/UX**: Design system, spacing, typography, colors
+   - **Quy chuẩn API & Backend**: API design, error handling, security
+   - **Quy chuẩn DevOps**: Version control, CI/CD, environments
+   - **AI Agent Configuration**: Preferred models, output language, privacy
+   - **AI Compliance & Model Risk**: Approved models, data handling, audit trail
+
+3. **Quy tắc**:
+   - Hỏi user nếu thiếu thông tin quan trọng
+   - Điền giá trị mặc định hợp lý cho các mục user chưa trả lời
+   - Đánh dấu `[x]` cho mục đã điền, `[ ]` cho mục cần bổ sung
+   - Constitution phải cụ thể, không chung chung
+
+## Input cần thiết
+- Yêu cầu tổ chức, quy chuẩn công ty
+- Tech stack dự định sử dụng
+- Thông tin dự án (tên, phạm vi, team size)
+
+## Output
+- `.v-flow/constitution.md`
+
+---
+
+## 🔀 Routing — Sau Constitution
+
+```
+Constitution tạo xong
+  → Tech Lead review và hoàn thiện
+  → Sau đó: /v.constitute (AI nâng cấp lên v2) hoặc /v.specify
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "S.0a"
+phase_status: "done"
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [S.0a] Constitution (Interactive) — [YYYY-MM-DD]
+- **Mode**: Interactive
+- **Output**: `constitution.md` v1
+- **Sections filled**: [N]/7
+- **Routing**: → Tech Lead review → /v.specify
+```
+
+---
+
+## Ví dụ
+
+```
+/v.constitution Dự án mobile app Flutter, Clean Architecture, 
+sử dụng Riverpod cho state management, REST API, Material Design 3
+```

package/commands/v.fork.md

@@ -0,0 +1,127 @@
+---
+description: "Fork — Branch feature để thử hướng khác (Time Travel)"
+phase: "Any"
+---
+
+# /v.fork
+
+Tạo một **bản sao (branch)** của feature để thử hướng spec/plan/architecture khác mà không ảnh hưởng bản gốc.
+
+> Lấy cảm hứng từ LangGraph Time Travel: **Fork** — branch từ checkpoint cũ để explore alternative paths.
+
+## Điều kiện tiên quyết
+- Feature gốc phải tồn tại với `.flow-state.yaml`
+- Tối đa 2 forks per feature
+- Phải có lý do rõ ràng (không "thử cho vui")
+
+## Khi nào dùng
+
+- Muốn so sánh 2 architecture approaches trước khi quyết định
+- Spec có 2 hướng giải quyết — cần prototype cả hai để chọn
+- Muốn thử risky approach mà không ảnh hưởng feature chính
+- Team debate về solution → fork ra để mỗi approach có proof-of-concept
+
+## Quy trình
+
+### Bước 1: Tạo Fork
+
+```
+/v.fork [feature-id] --as [new-name]
+/v.fork 001-login --as 001-login-graphql  ← thử GraphQL thay vì REST
+```
+
+### Bước 2: Sao chép & Diverge
+
+```
+1. Copy toàn bộ feature folder:
+   .v-flow/features/001-login/
+   → .v-flow/features/001-login-graphql/
+
+2. Cập nhật .flow-state.yaml trong bản fork:
+   feature_name: "001-login-graphql"
+   forked_from: "001-login"
+   forked_at_phase: "B.0"
+   forked_at_spec: "v1.2"
+   fork_reason: "Thử GraphQL thay vì REST — so với original REST approach"
+
+3. Cập nhật _session.md trong bản fork:
+   ### [FORK] — [YYYY-MM-DD]
+   - **Forked from**: 001-login (phase B.0, spec v1.2)
+   - **Reason**: Thử GraphQL approach
+   - **Compare with**: 001-login (REST approach)
+
+4. Cập nhật _session.md trong bản GỐC:
+   ### [FORK CREATED] — [YYYY-MM-DD]
+   - **Fork**: 001-login-graphql
+   - **Purpose**: So sánh GraphQL vs REST
+```
+
+### Bước 3: Develop Independently
+
+Mỗi fork được develop độc lập:
+- Chạy `/v.plan` riêng
+- Chạy `/v.implement` riêng
+- Mỗi fork có `.flow-state.yaml` riêng
+
+### Bước 4: Compare & Decide
+
+```
+/v.status 001-login 001-login-graphql --compare
+
+## 📊 Fork Comparison
+
+| Metric | 001-login (REST) | 001-login-graphql |
+|--------|-----------------|-------------------|
+| Phase | B.1 (70% tasks) | B.1 (40% tasks) |
+| Tasks | 10 | 14 |
+| Complexity | Medium | High |
+| Test coverage | 85% | 60% |
+| Performance | ✅ Good | ⚠️ N+1 risk |
+| Spec coverage | 10/10 REQ | 10/10 REQ |
+
+→ Recommendation: Tiếp tục với REST approach (simpler, better test coverage)
+```
+
+### Bước 5: Merge hoặc Discard
+
+```
+/v.fork --keep 001-login           ← giữ bản gốc, discard fork
+/v.fork --keep 001-login-graphql    ← giữ fork, archive bản gốc
+/v.fork --merge 001-login 001-login-graphql  ← merge ideas từ cả hai
+```
+
+## Quy tắc
+
+- **Tối đa 2 forks per feature** — quá nhiều = spec chưa rõ ràng
+- **Mỗi fork phải có reason rõ ràng** — không fork vì "thử cho vui"
+- **Compare trước khi decide** — sử dụng metrics, không sử dụng gut feeling
+- **Archive fork không dùng** — lưu vào `_archive/` thay vì xóa, để tham khảo sau
+
+---
+
+## State Schema mới
+
+```yaml
+# Thêm vào .flow-state.yaml
+fork_info:
+  is_fork: false                    # true nếu đây là bản fork
+  forked_from: null                 # feature gốc (nếu is_fork = true)
+  forked_at_phase: null
+  forked_at_spec: null
+  fork_reason: null
+  active_forks:                     # danh sách forks đang active (nếu đây là bản gốc)
+    # - name: "001-login-graphql"
+    #   reason: "Thử GraphQL approach"
+    #   current_phase: "B.1"
+```
+
+---
+
+## Ví dụ
+
+```
+/v.fork 001-login --as 001-login-graphql --reason "So sánh GraphQL vs REST"
+/v.fork 002-dashboard --as 002-dashboard-ssr --reason "Thử server-side rendering"
+/v.status 001-login 001-login-graphql --compare
+/v.fork --keep 001-login
+```

package/commands/v.help.md

@@ -0,0 +1,73 @@
+---
+description: "Help Agent — Hướng dẫn bước tiếp theo dựa trên trạng thái dự án hiện tại"
+phase: "Any"
+agent: "help-agent"
+---
+
+# /v.help
+
+> Orchestration wrapper cho **Help Agent**. Đọc `agents/help-agent.md` để thực hiện core logic.
+
+## Điều kiện tiên quyết
+- Không có điều kiện đặc biệt — lệnh này luôn chạy được
+
+## Execution
+1. Đọc agent definition: `agents/help-agent.md`
+2. Thực hiện quy trình: quét trạng thái → đề xuất bước tiếp theo
+
+## Options
+
+### (không có argument) — Trạng thái tổng quan
+Quét toàn bộ dự án, hiển thị foundation status + tất cả features.
+
+### feature [name] — Trạng thái 1 feature
+```
+/v.help feature 002-dashboard
+```
+Chỉ quét và đề xuất cho feature cụ thể.
+
+### [câu hỏi tự do] — Hỏi kèm context
+```
+/v.help Tôi vừa sửa spec, bước tiếp theo là gì?
+```
+Help Agent phân tích câu hỏi kèm trạng thái hiện tại.
+
+---
+
+## 🔀 Routing Rules (cho Help Agent tham khảo)
+
+| Tình huống | Gợi ý |
+|-----------|-------|
+| Chưa init V Flow | `v-flow init` |
+| Chưa có `context.md` (dự án cũ) | `/v.understand --all` |
+| Có `context.md` chưa có module cards | `/v.understand --module {tên}` |
+| BA có tài liệu trên NotebookLM | `/v.import-ba-docs --notebook <id>` |
+| Chưa có `constitution.md` | `v-flow init` → `/v.constitute` |
+| Có `constitution.md` v1 (template trống) | `/v.constitute` |
+| Chưa có feature nào | `v-flow feature create <name>` |
+| Spec chưa viết | `/v.specify` |
+| Spec = Draft | ⏳ Human review & approve |
+| Spec approved, có ambiguity trong spec | `/v.prototype` (optional S.1.5) |
+| Spec approved (sau prototype hoặc không có ambiguity) | `/v.plan` + `/v.test` (song song) |
+| Spec approved, cần bàn giao tài liệu PTYC (Phân tích Yêu cầu) | `/v.ba-to-ptyc` (optional, Doc Export S.1.6) |
+| S.1.5 — prototype VALIDATED | `/v.plan` + `/v.test` |
+| S.1.5 — prototype REJECTED | `/v.specify` (sửa spec) |
+| S.1.5 — prototype INCONCLUSIVE | Chờ stakeholder input |
+| Artifact out-of-sync (❌ trong Status block) | `/v.sync` TRƯỚC |
+| Validation = FAIL | Đọc `fail_reason` → route tương ứng |
+| Validation = PASS/CONCERNS | `/v.implement` |
+| Multi-feature, cần sprint | `/v.sprint` |
+| Tất cả tasks `[x]` | `/v.review` |
+| Review = CHANGES_REQUIRED | Fix → `/v.review` lại |
+| Review = APPROVED | 🚀 Deploy → `/v.retrospective` → `/v.metrics` |
+
+---
+
+## Ví dụ
+
+```
+/v.help
+/v.help feature 002-dashboard
+/v.help Tôi vừa sửa spec, bước tiếp theo là gì?
+/v.help Dự án mới, chưa biết bắt đầu từ đâu
+```

package/commands/v.hotfix.md

@@ -0,0 +1,200 @@
+---
+description: "Hotfix Flow — O.0 → B.1 → R.1. Dành cho Production Incident P1/P2, skip spec hoàn toàn"
+phase: "O.0 → B.1 → R.1"
+agents: ["operations-agent", "implement-agent", "review-agent"]
+---
+
+# /v.hotfix
+
+Chạy **Hotfix Flow** — pipeline khẩn cấp cho **Production Incident P1/P2**, ưu tiên tốc độ khôi phục, thực hiện phân tích spec sau.
+
+> 🔴 **Chỉ dùng khi**:
+> - Production đang down hoặc có vấn đề nghiêm trọng đang xảy ra
+> - Incident severity = P1 (Critical, immediate) hoặc P2 (High)
+> - Cần deploy fix trong vòng 1-2 giờ
+
+> ❌ **Không dùng cho**:
+> - Bug không ảnh hưởng production → `/v.quickfix`
+> - Feature mới hoặc improvement → full pipeline
+> - P3/P4 incidents → `/v.quickfix`
+
+---
+
+## Phase 0: Incident Assessment (< 5 phút)
+
+Bạn là **Operations Agent** (xem `agents/operations-agent.md`) — xác định nhanh root cause và scope.
+
+### Output: Incident Summary
+
+```markdown
+## Incident — [INC-ID]
+
+**Severity**: P1 | P2
+**Phát hiện**: [YYYY-MM-DD HH:MM]
+**Symptom**: [Mô tả biểu hiện — logs, errors, user reports]
+**Bị ảnh hưởng**: [Service/feature nào bị ảnh hưởng]
+**Root Cause (hypothesis)**: [Nguyên nhân sơ bộ]
+
+## Fix Plan (sơ bộ)
+- Files cần thay đổi: [list]
+- Expected fix: [mô tả]
+- Rollback plan: [nếu fix không work]
+
+## No-Go Check
+- [ ] Fix không đụng vào No-Go Zones ✅
+
+## Routing
+→ Proceed to Hotfix Implement
+```
+
+---
+
+## Phase 1: Hotfix Implement
+
+Bạn là **Implement Agent** — implement nhanh, focused, có safety net.
+
+### Quy trình (ưu tiên speed + safety)
+
+1. **Đọc Incident Summary** — hiểu root cause
+2. **Kiểm tra context.md** — No-Go Zones (bắt buộc, dù khẩn)
+3. **Implement minimal fix** — chỉ fix đúng vấn đề, không refactor
+4. **Viết smoke test** — test nhanh verify fix hoạt động
+5. **Chuẩn bị rollback** — ghi rõ cách rollback nếu cần
+
+### Nguyên tắc Hotfix
+
+```
+✅ Minimal change — nhỏ nhất có thể để fix vấn đề
+✅ Có rollback plan — phải biết cách undo nếu fail
+✅ Smoke test — ít nhất 1 test verify fix
+❌ Không refactor — không "tranh thủ" clean code
+❌ Không thêm feature — chỉ fix
+❌ Không đụng No-Go Zones — dù khẩn cũng không
+```
+
+### Routing sau implement
+
+```
+Fix sẵn sàng → Phase 2 (Emergency Review)
+Fix không đủ → Escalate, cần thêm người hỗ trợ
+```
+
+---
+
+## Phase 2: Emergency Review (< 15 phút)
+
+Bạn là **Review Agent** — review nhanh nhưng đảm bảo safety.
+
+### Checklist (phải check đủ, dù nhanh)
+
+```
+[ ] Fix address đúng root cause (theo incident summary)?
+[ ] Change scope minimal — không có thay đổi "bonus"?
+[ ] No-Go Zones không bị đụng vào?
+[ ] Có smoke test?
+[ ] Rollback plan rõ ràng?
+[ ] Không introduce regression rõ ràng?
+```
+
+### Verdict
+
+```
+APPROVED → Deploy ngay 🚀
+APPROVED_WITH_MONITORING → Deploy + monitor chặt 30 phút
+HOLD → Vấn đề với fix, cần thêm review
+```
+
+---
+
+## Phase 3: Deploy & Verify
+
+```
+1. Deploy fix
+2. Monitor 15-30 phút — xác nhận incident resolved
+3. Thông báo stakeholders: incident resolved
+4. Tạo Incident Report: .v-flow/incidents/INC-XXX.md
+5. Schedule Post-mortem: /v.retrospective (trong 24-48h)
+```
+
+---
+
+## Phase 4: Post-Hotfix (sau khi ổn định)
+
+Sau khi incident under control:
+
+```
+[ ] Tạo proper spec cho fix (nếu cần)
+[ ] Chạy /v.retrospective — lessons learned
+[ ] Cập nhật knowledge/lessons-learned/ nếu có pattern mới
+[ ] Xem xét thêm test case vào regression suite
+[ ] Update context.md nếu phát hiện No-Go Zone mới
+```
+
+---
+
+## Sơ đồ tổng thể
+
+```
+Production Incident P1/P2
+         ↓
+[O.0 Assessment] < 5 min
+  → Incident Summary + Root Cause
+         ↓
+[B.1 Hotfix Implement]
+  → Minimal fix + rollback plan + smoke test
+         ↓
+[R.1 Emergency Review] < 15 min
+  → APPROVED / HOLD
+         ↓
+Deploy 🚀 → Monitor
+         ↓
+[Post-mortem] trong 24-48h
+  → Retrospective + Lessons Learned
+```
+
+---
+
+## Incident Severity Guide
+
+| Priority | Mô tả | SLA Fix | Flow |
+|----------|-------|---------|------|
+| **P1** Critical | Production down, toàn bộ user bị ảnh hưởng | < 1h | Hotfix |
+| **P2** High | Feature quan trọng broken, nhiều user bị ảnh hưởng | < 4h | Hotfix |
+| **P3** Medium | Bug ảnh hưởng một số user, có workaround | < 24h | Quickfix |
+| **P4** Low | Cosmetic, minor issue | Next sprint | Full pipeline |
+
+---
+
+## Cập nhật State & Session
+
+**Tạo `incidents/INC-XXX.md`** (sau khi deploy):
+```markdown
+# Incident INC-XXX — [Mô tả ngắn]
+
+**Severity**: P[N]
+**Detected**: [YYYY-MM-DD HH:MM]
+**Resolved**: [YYYY-MM-DD HH:MM]
+**Root Cause**: [mô tả]
+**Fix**: [mô tả fix]
+**Post-mortem**: [pending | done]
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [O.0] Hotfix — [YYYY-MM-DD]
+- **Incident**: INC-XXX (P[N])
+- **Root Cause**: [mô tả]
+- **Fix**: [mô tả]
+- **Review**: [APPROVED | HOLD]
+- **Post-mortem**: scheduled [date]
+- **Routing**: → Deploy → Monitor → /v.retrospective
+```
+
+---
+
+## Ví dụ
+
+```
+/v.hotfix INC-042 Login API trả về 500 sau deploy lúc 14:30
+/v.hotfix INC-043 Payment service không xử lý được transaction mới
+```

package/commands/v.implement.md

@@ -0,0 +1,92 @@
+---
+description: "Implement Agent — Coding theo Plan & Test Cases (TDD)"
+phase: "B.1"
+agent: "implement-agent"
+---
+
+# /v.implement
+
+> Orchestration wrapper cho **Implement Agent**. Đọc `agents/implement-agent.md` để thực hiện core logic.
+
+## Điều kiện tiên quyết BẮT BUỘC
+- `validation-report.md` phải tồn tại với kết quả = **PASS** hoặc **PASS WITH CONCERNS**
+- Nếu = **FAIL** → **DỪNG LẠI**, báo cho user chạy `/v.check` trước
+
+## Execution
+1. Đọc agent definition: `agents/implement-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
+
+### --yolo (YOLO Mode)
+
+> Kích hoạt khi bạn muốn AI tự động implement toàn bộ, không hỏi xác nhận.
+
+**YOLO Mode sẽ**:
+- Bỏ qua các bước hỏi xác nhận giữa các tasks
+- Tự động implement toàn bộ tasks theo thứ tự dependency
+- Tự động đánh dấu `[x]` mỗi task khi hoàn thành
+- Chạy test sau mỗi task — dừng lại nếu test fail
+- Báo cáo kết quả tổng hợp khi hoàn thành
+
+**YOLO Mode KHÔNG bỏ qua** (đây là *correctness gate*, không phải bước confirm):
+- Kiểm tra spec Status block (vẫn phải ✅)
+- Kiểm tra `validation-report.md` = **PASS** hoặc **PASS WITH CONCERNS**
+- Version drift: `plan/tasks.synced_to_spec` lệch `spec_version_latest` → vẫn dừng, đề xuất `/v.sync`
+- No-Go Zones trong `context.md` (script exit 1/2 → vẫn BLOCK)
+- Task `[GATE]` → vẫn **DỪNG**, chờ human review
+- Task `[CLARIFY]` → vẫn **DỪNG, hỏi human** "Câu hỏi mở"; TUYỆT ĐỐI không tự đoán business rule
+- Task `[RISKY]` → vẫn test kỹ + chạy fallback plan nếu fail
+- `gitnexus_impact` HIGH/CRITICAL trên symbol → vẫn cảnh báo human trước khi sửa
+- Test failures (sẽ dừng và báo cáo)
+
+> ⚠️ Sau YOLO Mode, luôn chạy `/v.review` trước khi merge.
+
+---
+
+## 🔀 Routing Rules — Sau Implement
+
+```
+Tất cả tasks [x]
+  → Route: /v.review
+
+Có task fail / blocked
+  → Báo cáo cho human review
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "B.1"
+phase_status: "done"
+artifacts:
+  tasks:
+    completed: [N]
+    in_progress: 0
+active_concerns:
+  - id: "W-001"
+    resolved: true
+    resolved_how: "[mô tả cách xử lý]"
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [B.1] Implement — [YYYY-MM-DD]
+- **Tasks hoàn thành**: [N/total]
+- **Tests passing**: [N/N]
+- **Concerns addressed**:
+  - [W-001] → [cách giải quyết]
+- **Deviations from plan**: [none | mô tả nếu có lý do]
+- **Routing**: → /v.review
+```
+
+---
+
+## Ví dụ
+
+```
+/v.implement Feature 001-user-login
+/v.implement --yolo
+```