@longph2102/v-flow 1.5.0

package/templates/knowledge/api-contract-template.md

@@ -0,0 +1,140 @@
+# API Contract: [Service/Module Name]
+
+> **Version**: 1.0.0
+> **Last Updated**: YYYY-MM-DD
+> **Owner**: [Tên người/team chịu trách nhiệm]
+> **REQ Reference**: REQ-xxx
+
+---
+
+## Overview
+
+*(Mô tả ngắn gọn API này phục vụ nghiệp vụ gì)*
+
+---
+
+## Base URL
+
+```
+Production: https://api.example.com/v1
+Staging:    https://api-staging.example.com/v1
+```
+
+---
+
+## Authentication
+
+| Method | Header | Notes |
+|--------|--------|-------|
+| Bearer Token | `Authorization: Bearer <token>` | JWT, TTL = 1h |
+
+---
+
+## Endpoints
+
+### POST /resource
+
+> **Mô tả**: Tạo mới resource
+> **Auth**: Required
+> **Rate Limit**: 100 req/min
+
+#### Request
+
+```json
+{
+  "name": "string (required, max 255)",
+  "description": "string (optional, max 1000)",
+  "category_id": "integer (required)"
+}
+```
+
+#### Response — 201 Created
+
+```json
+{
+  "id": 1,
+  "name": "Example",
+  "description": "...",
+  "category_id": 1,
+  "created_at": "2026-04-27T00:00:00Z",
+  "updated_at": null
+}
+```
+
+#### Error Responses
+
+| Status | Code | Message | When |
+|--------|------|---------|------|
+| 400 | `VALIDATION_ERROR` | Field-level error details | Invalid input |
+| 401 | `UNAUTHORIZED` | "Authentication required" | Missing/invalid token |
+| 409 | `CONFLICT` | "Resource already exists" | Duplicate name |
+| 422 | `UNPROCESSABLE` | "Category not found" | Invalid category_id |
+| 500 | `INTERNAL_ERROR` | "Internal server error" | Unexpected failure |
+
+---
+
+### GET /resource/:id
+
+> **Mô tả**: Lấy thông tin resource theo ID
+> **Auth**: Required
+
+#### Response — 200 OK
+
+```json
+{
+  "id": 1,
+  "name": "Example",
+  "description": "...",
+  "category_id": 1,
+  "created_at": "2026-04-27T00:00:00Z",
+  "updated_at": null
+}
+```
+
+#### Error Responses
+
+| Status | Code | When |
+|--------|------|------|
+| 404 | `NOT_FOUND` | Resource does not exist |
+
+---
+
+## Data Models
+
+### Resource
+
+| Field | Type | Constraints | Notes |
+|-------|------|------------|-------|
+| `id` | integer | PK, auto-increment | |
+| `name` | string | max 255, unique | |
+| `description` | string | max 1000, nullable | |
+| `category_id` | integer | FK → categories.id | |
+| `created_at` | datetime | auto-set | ISO 8601 |
+| `updated_at` | datetime | nullable | ISO 8601 |
+
+---
+
+## SLA & Performance
+
+| Metric | Target |
+|--------|--------|
+| P95 Latency | < 200ms |
+| Availability | 99.9% |
+| Rate Limit | 100 req/min per user |
+| Max Payload | 1MB |
+
+---
+
+## Versioning Policy
+
+- **Breaking changes** → Increment major version (v1 → v2)
+- **Additive changes** → No version bump (new optional fields OK)
+- **Deprecation** → 6-month sunset notice in `Sunset` header
+
+---
+
+## Change Log
+
+| Date | Version | Changes |
+|------|---------|---------|
+| YYYY-MM-DD | 1.0.0 | Initial contract |

package/templates/knowledge/domain-glossary.md

@@ -0,0 +1,29 @@
+# Domain Glossary
+
+> Từ điển thuật ngữ của dự án. Cập nhật khi gặp thuật ngữ mới.
+> Agent PHẢI dùng đúng thuật ngữ từ glossary — không dùng synonym.
+
+---
+
+## Thuật ngữ V-Flow
+
+| Thuật ngữ | Định nghĩa | Context |
+|-----------|------------|--------|
+| **Spec** | Specification — đặc tả yêu cầu kỹ thuật, Single Source of Truth | S.1 phase |
+| **Constitution** | Bộ nguyên tắc và luật lệ của dự án — mọi Agent phải tuân thủ | S.0a phase |
+| **EARS** | Easy Approach to Requirements Syntax — 4 loại: Ubiquitous, Event, State, Optional | S.1 phase |
+| **No-Go Zone** | Vùng code mà Agent KHÔNG được sửa | context.md |
+| **Master Check** | Quality gate — cross-validate Spec↔Plan↔Tests | R.0 phase |
+| **Concern** | Warning (W-xxx) từ Master Check — phải resolve | R.0 → B.1 |
+| **Routing** | Quyết định next phase sau Master Check | R.0 output |
+| **Golden Test** | Test case mẫu chất lượng cao, dùng làm reference | Knowledge base |
+| **Flow State** | Trạng thái pipeline dạng machine-readable (YAML) | .flow-state.yaml |
+| **Session** | Working memory — ghi lại decisions, trace | _session.md |
+
+## Thuật ngữ dự án
+
+*Điền thuật ngữ domain-specific của dự án ở đây*
+
+| Thuật ngữ | Định nghĩa | Context |
+|-----------|------------|--------|
+| | | |

package/templates/knowledge/golden-tests-readme.md

@@ -0,0 +1,115 @@
+# Golden Tests — Hướng Dẫn
+
+> Golden tests là **bộ test tham chiếu** — input + expected output cố định — dùng để đảm bảo behavior không thay đổi sau khi refactor hoặc thêm tính năng.
+
+---
+
+## Khi Nào Cần Golden Test?
+
+| Tình huống | Lý do |
+|-----------|-------|
+| API response format | Đảm bảo backward compatibility |
+| Template generation output | Verify output không bị sai sau refactor |
+| State machine transitions | Lock valid state transitions |
+| Complex business rules | Document exact expected behavior |
+| Data migration | Verify data transform đúng |
+
+---
+
+## Cấu Trúc Golden Test
+
+```
+knowledge/golden-tests/
+├── README.md              ← File này
+├── api-responses/
+│   ├── get-user.input.json
+│   ├── get-user.expected.json
+│   ├── create-order.input.json
+│   └── create-order.expected.json
+├── state-transitions/
+│   ├── order-lifecycle.input.yaml
+│   └── order-lifecycle.expected.yaml
+└── templates/
+    ├── context-md.input.json
+    └── context-md.expected.md
+```
+
+---
+
+## Quy Tắc
+
+1. **Tên file có ý nghĩa** — `{action}.input.{ext}` + `{action}.expected.{ext}`
+2. **Không dùng mock** — Golden test dùng dữ liệu thật hoặc realistic fixtures
+3. **Khi test fail → xác nhận** — Nếu expected output thay đổi là intentional → update golden file
+4. **Ghi ngày tạo** — Trong comment hoặc metadata, ghi ngày golden test được tạo
+5. **Liên kết REQ** — Mỗi golden test nên tham chiếu REQ-xxx nếu có
+
+---
+
+## Template Cho Golden Test
+
+### Input file (`*.input.json`)
+
+```json
+{
+  "_meta": {
+    "created": "YYYY-MM-DD",
+    "req": "REQ-xxx",
+    "description": "Mô tả scenario"
+  },
+  "data": {
+    // Input data cho function/API
+  }
+}
+```
+
+### Expected file (`*.expected.json`)
+
+```json
+{
+  "_meta": {
+    "approved_by": "Tên người approve",
+    "approved_date": "YYYY-MM-DD"
+  },
+  "result": {
+    // Expected output
+  }
+}
+```
+
+---
+
+## Ví Dụ: Scan Codebase → context.md
+
+**Input** (`context-md.input.json`):
+```json
+{
+  "_meta": { "created": "2026-04-27", "req": "U.0", "description": "Scanner generates context.md" },
+  "data": {
+    "projectName": "my-app",
+    "languages": ["TypeScript", "JavaScript"],
+    "frameworks": ["Next.js", "React"],
+    "testingTools": ["Jest"],
+    "packageManager": "pnpm"
+  }
+}
+```
+
+**Expected** (`context-md.expected.md`):
+```markdown
+# context.md — Codebase Understanding Report
+> **Dự án**: my-app
+...
+| **Ngôn ngữ chính** | TypeScript, JavaScript |
+| **Framework** | Next.js, React |
+```
+
+---
+
+## Tích Hợp Với CI
+
+```yaml
+# .github/workflows/golden-tests.yml
+- name: Run Golden Tests
+  run: npx jest tests/golden/ --ci
+```

package/templates/knowledge/lessons-learned.md

@@ -0,0 +1,41 @@
+# V-Flow Lessons Learned
+
+> Bài học rút ra từ các feature cycles. Cập nhật sau mỗi `/v.retrospective`.
+
+---
+
+## Template Entry
+
+```markdown
+### LL-{N}: {Tiêu đề}
+- **Feature**: {feature name}
+- **Phase**: {phase khi phát hiện}
+- **Mô tả**: {bối cảnh + vấn đề}
+- **Bài học**: {rút ra điều gì}
+- **Action**: {thay đổi process/skill/constitution}
+```
+
+---
+
+## Entries
+
+### LL-001: Master Check bắt issues BA/Plan bỏ sót
+- **Feature**: 001-user-login
+- **Phase**: R.0 (Master Check)
+- **Mô tả**: BA Agent và Plan Agent không đề cập rate limiting cho login API. Master Check phát hiện qua concern W-001.
+- **Bài học**: Cross-validation giữa 3 artifacts (Spec↔Plan↔Tests) hiệu quả hơn review từng artifact riêng.
+- **Action**: Thêm "Security considerations" checklist vào BA Agent spec.
+
+### LL-002: API response format change là breaking change
+- **Feature**: 002-legacy-crud
+- **Phase**: R.0 (Master Check)
+- **Mô tả**: GET /api/products đổi từ array sang `{ data, pagination }` object. Master Check phát hiện W-002.
+- **Bài học**: Mọi API response format change cần explicit approval từ Tech Lead, kèm migration plan cho consumers.
+- **Action**: Thêm "Backward Compatibility Check" vào Plan Agent checklist cho legacy projects.
+
+### LL-003: EARS notation giúp tránh requirement ambiguity
+- **Feature**: 001-user-login
+- **Phase**: S.1 (Specification)
+- **Mô tả**: Trước EARS: "User đăng nhập được" → không measurable. Sau EARS: "Khi user nhấn Đăng nhập, hệ thống phải validate email format" → clear, testable.
+- **Bài học**: EARS notation bắt buộc Agent viết requirements có structure, mỗi loại (U/E/S/O) map rõ vào component type.
+- **Action**: EARS notation là standard bắt buộc cho tất cả projects, không phải optional.

package/templates/knowledge/patterns.md

@@ -0,0 +1,103 @@
+# V-Flow Patterns Library
+
+> Reusable patterns cho development pipeline. Mỗi entry mô tả KHI NÀO dùng, CÁCH dùng, và GOTCHAS.
+
+---
+
+## 1. Adapter Pattern (No-Go Zone Workaround)
+
+**Khi dùng**: Cần interact với No-Go Zone module mà không sửa nó.
+
+```
+// Thay vì sửa no-go-module trực tiếp
+// Tạo adapter wrap interface cần thiết
+
+// adapters/payment-adapter.js
+const payment = require('../no-go/payment');
+module.exports = {
+  getStatus: (id) => payment.checkStatus(id),  // wrap method hiện có
+  // Thêm method mới MÀ KHÔNG SỬA payment module
+  getStatusFormatted: (id) => {
+    const raw = payment.checkStatus(id);
+    return { ...raw, formattedDate: formatDate(raw.date) };
+  }
+};
+```
+
+**Gotcha**: Adapter KHÔNG được modify behavior của original — chỉ wrap hoặc extend.
+
+---
+
+## 2. Concern Carry-Forward Pattern
+
+**Khi dùng**: Master Check (R.0) phát hiện concern (W-xxx) → track qua B.1 → verify ở R.1.
+
+```
+R.0: validation-report.md
+  → W-001: "Thiếu rate limiting"
+  → Route: B.1, assigned_to: T-004
+
+B.1: _session.md
+  → Agent đọc concerns từ validation-report.md
+  → Implement fix trong T-004
+  → Ghi: "W-001: Resolved — added loginAttempts counter"
+
+R.1: code-review-report.md
+  → Review Agent verify W-001 resolved
+  → Check implementation quality
+```
+
+**Gotcha**: KHÔNG skip concerns. Review Agent PHẢI verify mỗi W-xxx.
+
+---
+
+## 3. Regression Test Pattern
+
+**Khi dùng**: Refactor legacy code — verify existing behavior giữ nguyên.
+
+```
+1. TRƯỚC refactor: capture current behavior
+   - Record API responses cho tất cả endpoints
+   - Document expected behavior
+
+2. SAU refactor: run regression suite
+   - Same inputs → same outputs
+   - Performance không degrade
+   - Error codes/messages giữ nguyên
+
+3. ĐẶC BIỆT chú ý:
+   - Response format changes (breaking!)
+   - Side effects (events, notifications)
+   - Error handling differences
+```
+
+**Gotcha**: "Same behavior" bao gồm cả error paths, không chỉ happy paths.
+
+---
+
+## 4. TDD Red-Green-Refactor Pattern
+
+**Khi dùng**: Implement mọi task trong tasks.md.
+
+```
+🔴 RED:    test-cases.md → viết test → chạy → FAIL
+🟢 GREEN:  viết code tối thiểu → chạy → PASS
+🔵 REFACTOR: clean code → chạy → vẫn PASS
+```
+
+**Gotcha**: Nếu test PASS ngay ở RED → test sai, xem lại.
+
+---
+
+## 5. Dual BA Loop Pattern
+
+**Khi dùng**: Feature phức tạp cần spec review kỹ — `/v.specify --dual`.
+
+```
+Round 1: BA Agent → draft spec.md
+Round 2: BA Critic → phản biện (≥3 issues)
+Round 3: BA Agent → revise spec
+(Optional) Round 4: BA Critic → final check
+```
+
+**Gotcha**: BA Critic PHẢI fresh context mỗi round — không bị ảnh hưởng round trước.

package/templates/module-card/SKILL.md

@@ -0,0 +1,85 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# Domain: {Tên Module}
+## Quick Summary
+## Key Business Rules
+## Key Entities
+## ⚠️ No-Go Zones (trong module này)
+## 📂 Supporting Files
+-->
+---
+name: domain-{tên-module}
+version: "1.0"                  # MAJOR.MINOR — bump khi có thay đổi. MAJOR = business rule thay đổi lớn; MINOR = bổ sung/clarification
+last_updated: "YYYY-MM-DD"      # auto-set khi bump version
+last_updated_by: "v.understand" # "human" | "v.understand" | "v.sync" | tên agent khác
+description: "{Mô tả chức năng cốt lõi — module làm gì, tích hợp với gì, dùng pattern gì}"
+user-invocable: false
+when_to_use: "Khi làm feature liên quan đến {keywords cụ thể}"
+---
+
+> ⚠️ **Versioning Convention**: Nếu bạn chỉnh sửa bất kỳ file nào trong thư mục module card này, hãy bump `version` trong file này trước khi commit. **MAJOR** nếu thay đổi business rule/flow. **MINOR** nếu bổ sung chi tiết hoặc fix sai sót nhỏ.
+
+# Domain: {Tên Module}
+
+**Service(s)**: {danh sách service chủ}
+**Complexity**: {⭐ đến ⭐⭐⭐⭐⭐} — {giải thích ngắn}
+**Last verified**: {YYYY-MM-DD}
+**Files count**: {N files} | **LOC ước tính**: {~X dòng}
+
+## Quick Summary
+
+<!-- HƯỚNG DẪN: Viết 3-4 câu PHÂN TÍCH CHUYÊN SÂU kiến trúc module — KHÔNG phải mô tả chung chung.
+Phải nêu rõ: pattern sử dụng, cách tổ chức layer, state management, tích hợp gì, thiếu gì.
+VD: "Module X sử dụng Clean Architecture (entity → usecases → repository). Frontend dùng Riverpod StateNotifier.
+Backend xử lý qua Isolate riêng. Dữ liệu lưu SQLite local. Không có unit test cho business logic."
+-->
+
+{Viết phân tích chuyên sâu ở đây — KHÔNG copy đoạn VD trên}
+
+## Key Business Rules
+
+> ⚠️ Trích xuất TỪ CODE CỤ THỂ. Mỗi rule phải kèm file + hàm tham chiếu.
+
+<!-- HƯỚNG DẪN: Mỗi BR phải có dạng:
+- Source: `tên_file_thực.dart:dòng`, hàm `tên_hàm_thực`
+- Code: `đoạn code ngắn thực tế từ codebase`
+KHI CHƯA SCAN: Để trống hoặc ghi [❓ CẦN SCAN CODE]
+-->
+
+- **BR-01**: {Rule quan trọng nhất — mô tả chi tiết điều kiện, hành động, ngoại lệ}
+  - Source: `{file_thực}:{line}`, hàm `{function_thực}`
+  - [⚠️ AI-inferred]
+- **BR-02**: {Rule quan trọng thứ 2}
+  - Source: `{file_thực}:{line}`
+  - [⚠️ AI-inferred]
+
+## Key Entities
+
+> Liệt kê models/entities chính kèm fields quan trọng và bảng DB.
+
+<!-- HƯỚNG DẪN: Lấy TỪ CODE THỰC TẾ — entity/model files, ORM definitions.
+Phải ghi đúng tên class, tên bảng, tên fields từ codebase.
+-->
+
+- `{EntityName}` — {mô tả ngắn}
+  - **Bảng DB**: `{table_name_thực}`
+  - **Fields chính**: `{field1}` ({type}), `{field2}` ({type}, {constraint})
+  - **Relationships**: → `{RelatedEntity}` (1-n)
+
+## ⚠️ No-Go Zones (trong module này)
+
+> Files/methods nguy hiểm — Agent KHÔNG đụng nếu không có chỉ định rõ ràng.
+
+| File / Method | LOC | Có Test? | Lý do không đụng |
+|---|---|---|---|
+| `{file_thực}` | {N} | ❌ | {lý do cụ thể} |
+
+## 📂 Supporting Files
+
+- [use-cases.md](use-cases.md) — Luồng E2E, state machines, business rules chi tiết
+- [api-specs.md](api-specs.md) — API endpoints, data contracts, enums
+- [ui-flows.md](ui-flows.md) — Màn hình, UI components, field mapping
+- [tech-context.md](tech-context.md) — Patterns, key files, tech debt
+- [cross-service.md](cross-service.md) — Tích hợp với modules/services khác
+- [db.md](db.md) — Database schema, quan hệ bảng, DDL links
+- [state-diagram.md](state-diagram.md) — Chi tiết state machine, triggers
+- [permissions.md](permissions.md) — Ma trận phân quyền, roles, data policies

package/templates/module-card/api-specs.md

@@ -0,0 +1,96 @@
+<!-- HEADING MAP — Agent PHẢI dùng CHÍNH XÁC các heading dưới đây:
+# API Specs: {Tên Module}
+## 1. Endpoints
+### {Nhóm chức năng}
+#### `{METHOD}` {/path/thực}
+## 2. Data Contracts (DTOs)
+### {TênDTO_thực}
+## 3. Enums & Constants
+## 4. Error Codes (Module-specific)
+-->
+# API Specs: {Tên Module}
+
+> **Audience chính**: Dev
+> **AI generate**: Scan controllers, DTOs, entities → auto-generate. Human review accuracy.
+
+**Service**: {tên service thực}
+**Base path**: {base path thực từ code}
+**Auth scheme**: {scheme thực — VD: Bearer JWT, API Key, Session, hoặc "N/A — local app"}
+
+---
+
+## 1. Endpoints
+
+> ⚠️ Liệt kê TẤT CẢ endpoints trong module. Mỗi endpoint phải có đủ: Method, Path, Auth, Request, Response, Error cases.
+> Nếu module KHÔNG có REST API (VD: mobile-only, library module) → ghi rõ và liệt kê internal method calls thay thế.
+
+### {Nhóm 1: tên nhóm chức năng}
+
+<!-- HƯỚNG DẪN: Với mỗi endpoint, mô tả ĐẦY ĐỦ:
+- Chức năng cụ thể (không chung chung)
+- Auth: role cụ thể từ code
+- Controller file + line number
+- Request Body/Params: TỪNG field với type, required, validation
+- Response: format JSON thực tế
+- Errors: error codes + điều kiện trigger cụ thể
+-->
+
+#### `{METHOD}` {/path/thực/từ/code}
+
+- **Chức năng**: {mô tả cụ thể}
+- **Auth**: {role cụ thể từ code}
+- **Controller**: `{file_thực}:{line}` → hàm `{function_thực}`
+- **Request Body**:
+  ```json
+  {
+    "{field_thực_1}": "{type} ({required/optional}, {validation})",
+    "{field_thực_2}": "{type} ({required/optional}, {validation})"
+  }
+  ```
+- **Response {status_code}**:
+  ```json
+  {
+    "{field_thực}": "{type — mô tả}"
+  }
+  ```
+- **Errors**:
+  | Code | Điều kiện | Message |
+  |---|---|---|
+  | {code} | {điều kiện từ code} | "{message từ code}" |
+
+#### `{METHOD}` {/path/thực/từ/code/2}
+
+- **Chức năng**: {mô tả}
+- **Auth**: {roles}
+- **Query Params** (nếu GET):
+  | Param | Type | Required | Mô tả | Default |
+  |---|---|---|---|---|
+  | `{param}` | {type} | {✅/❌} | {mô tả} | {default} |
+
+---
+
+## 2. Data Contracts (DTOs)
+
+> ⚠️ Liệt kê CHI TIẾT từng field. Không bỏ sót validation rules.
+
+### {TênDTO_thực}
+
+| Field | Type | Required | Validation | Ghi chú |
+|---|---|---|---|---|
+| `{field_thực}` | `{type}` | {✅/❌} | `{validation annotation thực}` | {mô tả} |
+
+---
+
+## 3. Enums & Constants
+
+| Enum | Values | Ý nghĩa | File reference |
+|---|---|---|---|
+| `{EnumName_thực}` | `{VALUE_1}`, `{VALUE_2}`, ... | {ý nghĩa} | `{file_thực}:{line}` |
+
+---
+
+## 4. Error Codes (Module-specific)
+
+| HTTP Code | Error Code | Message | Điều kiện trigger | File reference |
+|---|---|---|---|---|
+| {code} | `{ERROR_CODE_thực}` | "{message thực}" | {điều kiện từ code} | `{file_thực}:{line}` |