@longph2102/v-flow 1.5.0

package/skills/specify/ears-writer/examples/good/login-requirements.md

@@ -0,0 +1,41 @@
+REQ-E01 [Event-driven]
+Khi người dùng nhấn nút "Đăng nhập", hệ thống phải:
+  a) Validate email format theo RFC 5322
+  b) Kiểm tra credentials với auth service trong vòng 3 giây
+  c) Redirect về /dashboard nếu thành công
+  d) Hiển thị "Email hoặc mật khẩu không đúng" nếu thất bại (không nói cái nào sai)
+
+Acceptance Criteria:
+  - [ ] Login thành công trong <3s
+  - [ ] Error message không reveal thông tin credential cụ thể
+  - [ ] Email không hợp lệ → hiển thị inline error ngay
+
+---
+
+REQ-U01 [Ubiquitous]
+Hệ thống phải mã hóa mật khẩu bằng thuật toán hash an toàn trước khi lưu vào database.
+
+Acceptance Criteria:
+  - [ ] Không có plaintext password trong database
+  - [ ] Hash output khác nhau cho cùng password (có salt)
+
+---
+
+REQ-S01 [State-driven]
+Trong khi hệ thống đang gọi API đăng nhập, hệ thống phải:
+  a) Hiển thị loading indicator
+  b) Disable nút Đăng nhập để tránh submit trùng
+
+Acceptance Criteria:
+  - [ ] Loading indicator visible khi isLoading = true
+  - [ ] Nút Đăng nhập disabled khi đang loading
+
+---
+
+REQ-O01 [Optional]
+Nếu người dùng đã có access token hợp lệ trong storage, hệ thống phải
+tự động redirect về /dashboard mà không hiển thị màn hình đăng nhập.
+
+Acceptance Criteria:
+  - [ ] Có valid token → skip login screen
+  - [ ] Token expired → hiển thị login screen bình thường

package/skills/specify/ears-writer/gotchas.md

@@ -0,0 +1,43 @@
+# Gotchas — EARS Writer
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns Phổ Biến
+
+1. ❌ **Trộn nhiều actions**: "Hệ thống phải validate, hash, và lưu" → Tách 3 REQs.
+   - **Hậu quả**: Test Agent không biết test cái nào, Plan Agent không biết split task.
+
+2. ❌ **Thiếu error case**: Chỉ viết happy path "Khi login thành công" → Quên REQ cho login fail.
+   - **Hậu quả**: Implement Agent skip error handling → bug production.
+
+3. ❌ **Copy-paste prefix**: Dùng REQ-E cho tất cả → Mất ý nghĩa phân loại.
+   - **Dấu hiệu**: Toàn bộ spec chỉ có REQ-E → chắc chắn sai.
+
+4. ❌ **AC không measurable**: "- [ ] Login nhanh" → Không test được.
+   - **Fix**: "- [ ] Login response < 3s" hoặc "- [ ] Test pass với mock delay 2s".
+
+5. ❌ **Viết technical trong spec**: "Dùng SHA-256 với salt 16 bytes, bcrypt cost 12"
+   - **Fix**: Spec: "mã hóa mật khẩu". Plan quyết algorithm. Spec nói WHAT, không nói HOW.
+
+6. ❌ **Quên actors**: Mọi REQ đều "Hệ thống phải..." — không rõ ai trigger.
+   - **Fix**: Event-driven REQ phải nói rõ: "Khi **Admin** nhấn Delete..."
+
+7. ❌ **REQ quá vague nhưng có AC quá cụ thể**: REQ mơ hồ + AC chi tiết = inconsistency.
+   - **Fix**: REQ phải đủ cụ thể để AC derive tự nhiên.
+
+8. ❌ **Quên cross-reference No-Go Zones**: Viết REQ cần sửa file No-Go → sẽ bị block ở B.1.
+   - **Fix**: Khi viết REQ → đọc context.md No-Go Zones → verify REQ khả thi.
+
+---
+
+## Edge Cases Hay Quên
+
+- Empty state: App mới không có data → UI hiện gì?
+- Timeout: API call > timeout → hiện gì?
+- Concurrent access: 2 users edit cùng 1 record → gì xảy ra?
+- Network error: Offline → retry? Cache?
+- Boundary values: limit = 0? price = 0? string = 255 chars?
+- Unicode/emoji: Tên chứa emoji? Address chứa ký tự đặc biệt?

package/skills/specify/ears-writer/scripts/check-ears-compliance.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# check-ears-compliance.sh — Validate spec.md follows EARS notation
+# Usage: ./check-ears-compliance.sh <spec.md_path>
+#
+# Checks: ID format, banned words, EARS keyword presence, AC presence
+
+SPEC="${1:-spec.md}"
+
+if [ ! -f "$SPEC" ]; then
+  echo "❌ File not found: $SPEC"
+  exit 1
+fi
+
+echo "📋 EARS Compliance Check: $SPEC"
+echo "════════════════════════════════════════"
+ERRORS=0
+WARNINGS=0
+
+# 1. Check EARS IDs
+echo ""
+echo "### 1. REQ ID Format"
+# Đếm theo SỐ TOKEN bằng `grep -o | wc -l` (mỗi match 1 dòng) — KHÔNG dùng
+# `$(grep -c ... || echo 0)`: grep -c in "0" rồi exit 1 → `|| echo 0` tạo "0\n0"
+# → lỗi "integer expression expected".
+ALL_REQ=$(grep -oE "REQ-[A-Za-z][0-9]+" "$SPEC" | wc -l | tr -d ' ')   # mọi REQ-X##
+VALID=$(grep -oE "REQ-[UESO][0-9]+" "$SPEC" | wc -l | tr -d ' ')        # đúng EARS U/E/S/O
+INVALID=$((ALL_REQ - VALID))
+echo "   ✅ Valid EARS IDs: $VALID"
+[ "$INVALID" -gt 0 ] && echo "   ❌ Invalid IDs (not REQ-U/E/S/O): $INVALID" && ERRORS=$((ERRORS+INVALID))
+
+# 2. Banned words
+echo ""
+echo "### 2. Banned Words"
+for word in "nên" "should" "có thể" "hợp lý" "v.v." "etc." "dễ dùng" "user-friendly"; do
+  count=$(grep -ci "$word" "$SPEC" 2>/dev/null)   # grep -c luôn in số nguyên (0 nếu không có)
+  [ "$count" -gt 0 ] && echo "   ⚠️  '$word' found $count time(s)" && WARNINGS=$((WARNINGS+count))
+done
+[ "$WARNINGS" -eq 0 ] && echo "   ✅ No banned words found"
+
+# 3. Acceptance Criteria
+echo ""
+echo "### 3. Acceptance Criteria"
+AC_COUNT=$(grep -c "\- \[ \]" "$SPEC" 2>/dev/null)
+REQ_COUNT=$(grep -cE "REQ-[UESO]" "$SPEC" 2>/dev/null)
+echo "   REQs: $REQ_COUNT, ACs: $AC_COUNT"
+[ "$REQ_COUNT" -gt 0 ] && [ "$AC_COUNT" -lt "$REQ_COUNT" ] && echo "   ⚠️  Some REQs may be missing ACs" && WARNINGS=$((WARNINGS+1))
+
+echo ""
+echo "════════════════════════════════════════"
+echo "📊 Errors: $ERRORS, Warnings: $WARNINGS"
+[ "$ERRORS" -eq 0 ] && [ "$WARNINGS" -eq 0 ] && echo "✅ PASS" || echo "⚠️  NEEDS REVIEW"

package/skills/test/test-case-generator/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: test-case-generator
+description: "Hướng dẫn Test Agent tạo test cases từ spec.md. Agent PHẢI đọc skill này khi /v.test được gọi. Đảm bảo 100% REQ coverage + edge cases + traceability."
+trigger: "Khi /v.test được gọi, tạo test cases từ spec"
+phase: "B.0b"
+used_by:
+  - /v.test
+hooks:
+  pre_generate: "Load spec.md → extract TẤT CẢ REQ-xxx + AC, tạo coverage matrix"
+  post_generate: "Verify: mỗi REQ có ≥1 TC, mỗi AC có TC, edge cases covered"
+---
+
+# Test Case Generator — Tạo Test Cases Toàn Diện
+
+> ⚠️ Đây là **Skill bắt buộc** cho Test Agent.
+> Mỗi REQ PHẢI có ≥1 Test Case. REQ không có TC = gap nguy hiểm.
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi viết test cases.
+> → Xem `examples/good/` cho mẫu test-cases.md chuẩn.
+> → Xem `config.json` để customize (coverage_target, tc_format).
+
+---
+
+## Khi nào KHÔNG tạo test cases
+
+- Documentation-only change — không có code logic
+- Config/constant change — test ở integration level, nhưng vẫn cần TC cho behavior
+
+---
+
+## REQ Type → Test Strategy Mapping
+
+> 💡 Mỗi loại REQ gợi ý strategy test khác nhau (từ EARS notation).
+
+| REQ Type | Test Strategy | Ví dụ |
+|----------|--------------|-------|
+| **REQ-U** (Ubiquitous) | Test ở MỌI entry point — always true | "Password always hashed" → test ở create, update, import |
+| **REQ-E** (Event-driven) | Given trigger → expect action | "Khi login → redirect" → test trigger + verify action |
+| **REQ-S** (State-driven) | While in state → verify behavior | "Trong khi offline → queue requests" → set state + verify |
+| **REQ-O** (Optional) | Branch test: condition true + false | "Nếu admin → show panel" → test admin = true + false |
+
+---
+
+## Đặc Thù Và Quy Ước
+
+### 1. Test Case ID Convention
+
+```
+TC-NN (đánh số tuần tự toàn file): TC-01, TC-02, TC-03 ...
+```
+
+Traceability KHÔNG nhúng vào ID mà qua field **Gắn với: REQ-xxx** + **AC: AC-NN** trong mỗi TC — khớp `test-cases-template.md` và Master Check matrix (REQ + AC-NN).
+
+### 2. Test Layers
+
+Mỗi REQ nên có test ở ≥1 layer:
+
+| Layer | Khi nào dùng | Ví dụ |
+|-------|-------------|-------|
+| **Unit** | Business logic, pure functions | UseCase, Repository, Validation |
+| **Integration** | Cross-component interaction | API → DB → Response |
+| **E2E** | User-facing flows | Login → Dashboard redirect |
+
+**Rule**: Unit tests cho MỌI REQ. Integration cho cross-component REQ. E2E cho critical path.
+
+### 3. Edge Case Generation — 7 Categories
+
+Mỗi REQ, quét qua 7 categories để tìm edge cases:
+
+| Category | Câu hỏi | Test cases cần có |
+|----------|---------|-------------------|
+| **Empty** | Input rỗng? List 0 items? | TC cho null, "", [], {} |
+| **Boundary** | Min/max values? Off-by-one? | TC cho 0, 1, MAX, MAX+1 |
+| **Error** | Network fail? Invalid input? | TC cho timeout, 400, 500 |
+| **Concurrent** | 2 requests cùng lúc? | TC cho race condition |
+| **Auth** | Không có token? Wrong role? | TC cho 401, 403 |
+| **State** | First time? After reset? | TC cho initial state, reset |
+| **Performance** | Large dataset? Slow network? | TC cho 10K items, 3s timeout |
+
+### 4. Test Case Completeness Check
+
+Trước khi submit test-cases.md:
+
+```
+[ ] Mỗi REQ-xxx có ≥1 TC (happy path)
+[ ] Mỗi REQ Error path có TC riêng
+[ ] Mỗi AC trong spec có TC verify
+[ ] ≥1 edge case per REQ (từ 7 categories)
+[ ] Test priority assigned (P1/P2/P3)
+[ ] Test type assigned (Unit/Integration/E2E)
+```
+
+### 5. Priority Assignment
+
+| Priority | Criteria | PHẢI test |
+|----------|---------|-----------|
+| **P1** | Core business logic, security, data integrity | ✅ Bắt buộc |
+| **P2** | Important flows, edge cases | ✅ Nên có |
+| **P3** | Nice-to-have, optimization verify | ⚠️ Tùy scope |
+
+---
+
+## Test Case Template
+
+```markdown
+### TC-NN: {Tên test case mô tả behavior}
+
+**Gắn với:** REQ-{xxx}
+**AC:** AC-NN (tiêu chí chấp nhận spec §4 mà TC này verify — bắt buộc để cross-check AC↔TC)
+**Loại:** Unit / Integration / E2E
+**Priority:** P1 / P2 / P3
+
+#### Preconditions
+- {Trạng thái ban đầu cần thiết}
+
+#### Test Steps
+1. {Action 1}
+2. {Action 2}
+
+#### Expected Result
+- {Kết quả mong đợi — measurable}
+
+#### Edge Cases
+- {Biến thể của test case này}
+```
+
+---
+
+## Coverage Matrix Template
+
+> Đặt ở đầu test-cases.md để overview.
+
+```markdown
+## Coverage Matrix
+
+| REQ | AC | Description | TC Count | Types | Priority |
+|-----|----|------------|----------|-------|----------|
+| REQ-E01 | AC-01 | Login success | 3 | Unit, E2E | P1 |
+| REQ-E02 | AC-02 | Login error | 2 | Unit | P1 |
+| REQ-U01 | AC-03 | Password hash | 1 | Unit | P1 |
+| REQ-O01 | AC-04 | Rate limit | 2 | Unit, Integration | P2 |
+
+**Coverage**: 4/4 REQs (100%) ✅
+**Total TCs**: 8
+```
+
+---
+
+## V-Flow Integration Points
+
+- **spec.md** (S.1) → Input: REQs + ACs
+- **ears-notation skill** → REQ type → test strategy mapping
+- **plan.md** (B.0a) → Component info cho integration test scope
+- **tasks.md** (B.0a) → Test Agent map TC → TASK cho Implement Agent
+- **cross-validator skill** → Master Check verify TC coverage
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho lỗi phổ biến khi viết test cases — cập nhật liên tục.

package/skills/test/test-case-generator/config.json

@@ -0,0 +1,33 @@
+{
+  "setup_questions": [
+    {
+      "id": "coverage_target",
+      "question": "REQ coverage target (%)?",
+      "type": "number",
+      "default": 100,
+      "description": "Phần trăm REQs phải có test case. 100% recommended."
+    },
+    {
+      "id": "tc_format",
+      "question": "Test case format?",
+      "options": ["structured", "gherkin", "tabular"],
+      "default": "structured",
+      "description": "structured = markdown template. gherkin = Given-When-Then. tabular = table format."
+    },
+    {
+      "id": "edge_case_min",
+      "question": "Số edge case tối thiểu per REQ?",
+      "type": "number",
+      "default": 1
+    }
+  ],
+  "hooks": {
+    "pre_generate": "Load spec.md → extract REQ list + AC list → tạo coverage matrix skeleton",
+    "post_generate": "Verify coverage matrix 100%, mỗi AC có TC, edge cases ≥ min per REQ"
+  },
+  "memory": {
+    "file": "test-gen-history.log",
+    "format": "[date] | [feature] | [total_reqs] | [total_tcs] | [coverage_pct] | [edge_cases]",
+    "purpose": "Track test coverage patterns — dùng cho /v.metrics"
+  }
+}

package/skills/test/test-case-generator/examples/good/test-cases-login.md

@@ -0,0 +1,104 @@
+# Ví dụ — Test Cases (User Login Feature)
+
+> Đây là mẫu output chuẩn cho Test Agent.
+
+---
+
+## Coverage Matrix
+
+| REQ | Description | TC Count | Types | Priority |
+|-----|------------|----------|-------|----------|
+| REQ-E01 | Login success | 3 | Unit, E2E | P1 |
+| REQ-E02 | Invalid credentials | 2 | Unit | P1 |
+| REQ-U01 | Password security | 2 | Unit | P1 |
+| REQ-O01 | Rate limiting | 3 | Unit, Integration | P2 |
+
+**Coverage**: 4/4 REQs (100%) ✅
+**Total TCs**: 10
+
+---
+
+## Test Cases
+
+### TC-E01-01: Login thành công với credentials hợp lệ
+
+**Gắn với:** REQ-E01
+**Loại:** Unit
+**Priority:** P1
+
+#### Preconditions
+- User "test@example.com" tồn tại trong DB
+- Password hash hợp lệ
+
+#### Test Steps
+1. Gọi LoginUseCase.execute(email: "test@example.com", password: "Valid1@pass")
+2. Verify response
+
+#### Expected Result
+- Result = Success
+- AuthToken not null, length ≥ 32
+- User object contains email, id
+
+---
+
+### TC-E01-02: Login redirect về dashboard sau success
+
+**Gắn với:** REQ-E01
+**Loại:** E2E
+**Priority:** P1
+
+#### Preconditions
+- User tồn tại, credentials hợp lệ
+
+#### Test Steps
+1. Navigate to /login
+2. Nhập email + password hợp lệ
+3. Click "Đăng nhập"
+
+#### Expected Result
+- Redirect to /dashboard
+- Token stored in secure storage
+- Loading indicator hiện trong lúc chờ
+
+---
+
+### TC-E02-01: Login fail với wrong password
+
+**Gắn với:** REQ-E02
+**Loại:** Unit
+**Priority:** P1
+
+#### Preconditions
+- User "test@example.com" tồn tại
+- Password sai
+
+#### Test Steps
+1. Gọi LoginUseCase.execute(email: "test@example.com", password: "wrong")
+
+#### Expected Result
+- Result = Failure(InvalidCredentials)
+- Error message = "Email hoặc mật khẩu không đúng" (không reveal cái nào sai)
+
+#### Edge Cases
+- Email không tồn tại → same error message (không leak info)
+- Empty password → validation error trước khi gọi API
+
+---
+
+### TC-O01-01: Rate limit sau 5 attempts thất bại
+
+**Gắn với:** REQ-O01
+**Loại:** Integration
+**Priority:** P2
+
+#### Preconditions
+- User tồn tại, attempt counter = 0
+
+#### Test Steps
+1. Gọi login 5 lần với wrong password
+2. Gọi login lần 6 với ĐÚNG password
+
+#### Expected Result
+- Lần 1-5: Result = Failure(InvalidCredentials)
+- Lần 6: Result = Failure(RateLimited), message = "Quá nhiều lần thử, đợi 15 phút"
+- Lần 6 KHÔNG check credentials (block trước khi authenticate)

package/skills/test/test-case-generator/gotchas.md

@@ -0,0 +1,43 @@
+# Gotchas — Test Case Generator
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns
+
+1. ❌ **Chỉ test happy path** — Viết TC cho success, quên error cases.
+   - **Hậu quả**: Error handling untested → crash production.
+   - **Fix**: Mỗi REQ event-driven → ≥1 TC happy + ≥1 TC error.
+
+2. ❌ **TC không trace về REQ** — Test case "kiểm tra login" không reference REQ-xxx.
+   - **Hậu quả**: Master Check sẽ flag "REQ coverage gap".
+   - **Fix**: TC ID = TC-NN tuần tự; trace bằng field "Gắn với: REQ-xxx" + "AC: AC-NN" trong mỗi TC.
+
+3. ❌ **TC mơ hồ** — "Expected: hệ thống hoạt động đúng."
+   - **Hậu quả**: Implement Agent không biết test gì → test useless.
+   - **Fix**: Expected Result = cụ thể + measurable: "Response 201, body.id not null".
+
+4. ❌ **TC duplicate** — 3 TCs test cùng behavior nhưng khác wording.
+   - **Fix**: 1 behavior = 1 TC. Biến thể = edge cases trong cùng TC.
+
+5. ❌ **Quên edge categories** — Viết 5 TCs nhưng toàn happy path biến thể.
+   - **Fix**: Quét 7 categories (Empty, Boundary, Error, Concurrent, Auth, State, Performance).
+
+6. ❌ **Priority tất cả P1** — Mọi TC đều P1 → không biết test nào quan trọng nhất.
+   - **Fix**: P1 = core logic + security. P2 = edge cases. P3 = optimization.
+
+7. ❌ **Thiếu preconditions** — TC nói "login" nhưng không nói user phải tồn tại trước.
+   - **Fix**: Mỗi TC PHẢI có preconditions rõ ràng: data state, auth state, system state.
+
+8. ❌ **TC quá tightly coupled với implementation** — "Mock UserRepository.findByEmail()".
+   - **Fix**: TC mô tả BEHAVIOR, không mô tả implementation detail. Implement Agent quyết mock strategy.
+
+---
+
+## Edge Cases
+
+- ✅ Spec chỉ có 1-2 REQ → Vẫn cần edge cases. REQ ít ≠ test ít.
+- ✅ REQ-U (ubiquitous) → Test ở NHIỀU entry points, không chỉ 1.
+- ✅ Feature liên quan external API → TC cho API down, slow, wrong format.