@longph2102/v-flow 1.5.0

package/templates/context-template.md

@@ -0,0 +1,94 @@
+# context.md — Project Overview (Tầng 1)
+
+> **Phase**: U.0a (Understand — Project Overview)
+> **Dự án**: [Tên dự án]
+> **Ngày tạo**: YYYY-MM-DD | **Cập nhật lần cuối**: YYYY-MM-DD
+> **Người review**: [Tech Lead / Architect]
+
+> ⚠️ File này là **Tầng 1** trong Multi-Layer Understanding System.
+> Chỉ chứa thông tin tổng quan (~50-100 dòng). Chi tiết từng module xem tại `.v-flow/modules/`.
+> Nội dung file này sẽ được auto-inject vào AGENTS.md để AI agent luôn có sẵn.
+
+---
+
+## 1. Tech Stack
+
+| Hạng mục | Công nghệ | Phiên bản |
+|----------|-----------|-----------|
+| **Ngôn ngữ** | | |
+| **Framework** | | |
+| **Database** | | |
+| **Message Queue** | | |
+| **CI/CD** | | |
+
+---
+
+## 2. Kiến Trúc Tổng Quan
+
+> Mô tả kiến trúc AS-IS (1-3 câu). Không lý tưởng hóa.
+
+```
+project/
+├── [thư mục chính 1]/  ← [vai trò]
+├── [thư mục chính 2]/  ← [vai trò]
+└── ...
+```
+
+**Pattern chính**: [Monolith / Microservices / Modular Monolith / ...]
+
+---
+
+## 3. Entry Points
+
+| Entry Point | File | Ghi chú |
+|-------------|------|---------|
+| API chính | | |
+| Background jobs | | |
+| CLI / Scripts | | |
+
+---
+
+## 4. 🚫 No-Go Zones
+
+> **Đây là luật**: Agent KHÔNG được tự ý sửa các vùng này.
+> **Mức độ** (cột bắt buộc — `check-nogo-zones.sh` đọc để phân loại): 🔴 Strict = BLOCK · 🟡 Warning = cần Tech Lead duyệt · 🟢 Thấp = LOG (được phép, ghi nhận). **Ô trống = mặc định 🔴 Strict** (fail-safe — không để vùng lọt qua).
+
+| Vùng code | Mức độ | Lý do | Rủi ro |
+|-----------|:------:|-------|--------|
+| `[file/module]` | 🔴 | | |
+
+---
+
+## 5. Technical Debt (Top 3-5)
+
+| # | Mô tả | Mức độ |
+|---|-------|--------|
+| 1 | | 🔴/🟠/🟡 |
+| 2 | | |
+
+---
+
+## 6. Module Index
+
+> Danh sách module cards có sẵn. Agent đọc module liên quan trước khi làm feature.
+
+| Module | Mô tả 1 dòng | Đường dẫn |
+|--------|--------------|-----------|
+| | | `.v-flow/modules/domain-xxx/SKILL.md` |
+| | | `.v-flow/modules/domain-yyy/SKILL.md` |
+
+---
+
+## 7. Quy ước quan trọng
+
+- **Naming**: [camelCase / snake_case / PascalCase]
+- **Error handling**: [pattern đang dùng]
+- **Test coverage ước tính**: ~X%
+
+---
+
+## Lịch Sử Cập Nhật
+
+| Ngày | Người | Lý do |
+|------|-------|-------|
+| YYYY-MM-DD | | Tạo mới (U.0a) |

package/templates/data-model-template.md

@@ -0,0 +1,95 @@
+# Template: Data Model
+
+> Được tạo bởi **Plan Agent** — Phase B.0a (khi feature có data model rõ ràng)
+> Lưu tại `data-model.md`
+> Feature: [TÊN FEATURE]
+> Spec Version: [vX.Y]
+
+> 📌 Khi có **cả FE và BE** (contract-first): đóng băng data model TRƯỚC, cùng với `contracts/api-contract.md`. FE và BE đều `[DEPENDS]` vào task chốt model này rồi mới `[PARALLEL]`.
+
+---
+
+## 1. Entities
+
+> Mỗi entity: field (tên / kiểu / bắt buộc / ý nghĩa nghiệp vụ). KHÔNG bịa field ngoài spec.
+
+```
+[EntityName]
+├── id: uuid (required) — khóa chính
+├── field1: type (required) — [ý nghĩa nghiệp vụ]
+├── field2: type (optional) — [ý nghĩa]
+└── field3: type — [ý nghĩa]
+```
+
+| Entity | Nguồn (REQ/UC) | Persistence | Ghi chú |
+|--------|----------------|-------------|---------|
+| `[Entity]` | REQ-xxx (UC-xx) | DB table / DTO / state | |
+
+---
+
+## 2. Relationships
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : "has many"
+    ENTITY_B }|--|| ENTITY_C : "belongs to"
+```
+
+| Quan hệ | Loại | Ràng buộc (FK / cascade) |
+|---------|------|--------------------------|
+| A → B | 1-n | FK `b.a_id`, on delete cascade |
+
+---
+
+## 3. State Machine (nếu entity có vòng đời)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Active : approve
+    Active --> Completed : complete
+    Active --> Cancelled : cancel
+```
+
+| Trạng thái | Vào từ | Ra tới | Điều kiện chuyển |
+|-----------|--------|--------|------------------|
+| Draft | [*] | Active | approve |
+
+---
+
+## 4. Validation Rules
+
+> Ràng buộc dữ liệu ở tầng domain (đồng bộ với validation FE/BE). Mỗi rule trace về REQ.
+
+| Field | Rule | Lỗi khi vi phạm | REQ |
+|-------|------|-----------------|-----|
+| `email` | định dạng email hợp lệ | `VALIDATION_ERROR` | REQ-xxx |
+| `price` | number > 0 | `VALIDATION_ERROR` | REQ-xxx |
+
+---
+
+## 5. Persistence & Migrations (nếu lưu DB)
+
+> Đồng bộ với plan §3.4. Phân biệt bảng **MỚI** vs **ALTER**.
+
+| Bảng | New/ALTER | Cột | Kiểu | Null? | Index / Constraint | REQ |
+|------|:---------:|-----|------|:-----:|--------------------|-----|
+| `[table]` | NEW/ALTER | | | | | REQ-xxx |
+
+- **DDL thật (up + down)** — copy-paste-được (hoặc lệnh ORM tương đương):
+
+```sql
+-- up
+ALTER TABLE [table] ADD COLUMN [col] [type] NULL;
+-- down (rollback)
+ALTER TABLE [table] DROP COLUMN [col];
+```
+
+- **Truy vấn quan trọng**: xem plan §3.5 (bảng / predicate / index cho query không hiển nhiên).
+- **Breaking change → Expand-Contract**: xem plan §3.4.
+- **Rollback**: [cách hoàn tác]
+
+---
+
+> **Trạng thái**: Draft / Frozen (đóng băng cho contract-first) / Approved
+> **Đồng bộ**: `contracts/api-contract.md` (nếu có API), `plan.md` §3

package/templates/decision-log-template.md

@@ -0,0 +1,92 @@
+# Template: Agent Decision Log
+
+> Mỗi Agent tạo 1 decision log kèm theo output chính.
+> Giúp human reviewer hiểu reasoning, audit, và cải tiến prompts.
+> Lưu tại: `.v-flow/features/NNN-ten-feature/decision-logs/[agent-name]-decision-log.md`
+
+## Thông tin
+
+| Mục | Giá trị |
+|-----|--------|
+| **Agent** | [BA / Plan / Test / Master Check / Implement] Agent |
+| **Feature** | #[NNN] — [Tên feature] |
+| **Thời gian** | [YYYY-MM-DD HH:MM] |
+| **Model** | [Model name + version] |
+| **Temperature** | [X.X] |
+
+---
+
+## 1. Input Summary — Tóm tắt đầu vào
+
+### Đã đọc
+<!-- Liệt kê files/documents Agent đã đọc -->
+- [ ] `constitution.md` — [tóm tắt ngắn điểm liên quan]
+- [ ] [Input khác] — [tóm tắt]
+
+### Hiểu được
+<!-- Agent hiểu yêu cầu chính là gì? -->
+
+### Câu hỏi / Unclear points
+<!-- Điều gì không rõ? Giả định gì đã đặt ra? -->
+
+---
+
+## 2. Reasoning — Quá trình suy luận
+
+### Các phương án đã xem xét
+<!-- Agent đã cân nhắc những lựa chọn nào? -->
+
+| Phương án | Ưu điểm | Nhược điểm | Quyết định |
+|-----------|---------|------------|-----------|
+| [A] | | | ✅ Chọn / ❌ Bỏ |
+| [B] | | | ✅ Chọn / ❌ Bỏ |
+
+### Lý do quyết định
+<!-- Tại sao chọn phương án này? -->
+
+### Trade-offs chấp nhận
+<!-- Có trade-off nào không? -->
+
+---
+
+## 3. Key Decisions — Quyết định quan trọng
+
+| # | Quyết định | Lý do | Constitution reference |
+|---|-----------|--------|----------------------|
+| 1 | [Decision] | [Rationale] | [Section N.N nếu có] |
+| 2 | | | |
+
+---
+
+## 4. Assumptions — Giả định
+
+| # | Giả định | Rủi ro nếu sai |
+|---|---------|----------------|
+| 1 | [Assumption] | [Risk] |
+| 2 | | |
+
+---
+
+## 5. Confidence — Độ tự tin
+
+| Phần output | Confidence (1-5) | Ghi chú |
+|-------------|:-----------------:|---------|
+| [Section 1] | /5 | |
+| [Section 2] | /5 | |
+| **Tổng thể** | **/5** | |
+
+> Confidence thấp (< 3) = cần human review kỹ hơn.
+
+---
+
+## 6. Output Summary — Tóm tắt đầu ra
+
+### Files tạo ra
+- [ ] [output-file.md] — [mô tả ngắn]
+
+### Metrics
+| Metric | Giá trị |
+|--------|--------|
+| Processing time | [X phút] |
+| Output length | [X dòng / words] |
+| Revision number | [1st / 2nd / ...] |

package/templates/flow-state-template.yaml

@@ -0,0 +1,208 @@
+# V Flow State Schema
+# File: .v-flow/features/NNN-feature-name/.flow-state.yaml
+# Tạo tự động bởi /v.specify — cập nhật tại mỗi phase transition
+# ⚠️ KHÔNG sửa tay — dùng /v.status để xem; phase tự chuyển khi chạy command tương ứng (vd /v.plan, /v.check, /v.implement)
+
+# ────────────────────────────────────────────────────────────────────────────
+# IDENTITY
+# ────────────────────────────────────────────────────────────────────────────
+feature_id: "NNN"                        # e.g. "001"
+feature_name: "ten-feature"              # e.g. "user-login"
+created_at: "YYYY-MM-DD"
+last_updated: "YYYY-MM-DD"
+project_type: "greenfield"               # greenfield | legacy
+schema_version: "2.0"                    # artifact-schema generation — validator dùng để gate; bump khi template đổi schema
+
+# ────────────────────────────────────────────────────────────────────────────
+# GOVERNANCE — Risk tier + approval metadata (validator gate; --strict chặn CI)
+# ────────────────────────────────────────────────────────────────────────────
+risk_tier: "medium"                      # low | medium | high | critical — quyết định gate bắt buộc
+                                         #   low: 0 approval · medium: spec · high: spec+security · critical: spec+security+tech_lead
+approvals:                               # mỗi approval cần actor + timestamp để audit được
+  # - role: spec                         # gate được approve: spec | security | tech_lead | ...
+  #   actor: "Nguyen Van A"
+  #   decision: approved                 # approved | rejected
+  #   timestamp: "2026-06-06T10:00:00Z"
+
+# ────────────────────────────────────────────────────────────────────────────
+# PIPELINE STATE — Phase hiện tại
+# ────────────────────────────────────────────────────────────────────────────
+current_phase: "S.1"                     # U.0 | S.0a | S.0b | S.1 | S.1.5 | B.0a | B.0b | R.0 | B.1 | R.1 | M.0 | O.0
+phase_status: "in_progress"             # pending | in_progress | awaiting_human | done | blocked
+
+# Phase history (tự động append)
+phase_history:
+  - phase: "S.1"
+    entered_at: "YYYY-MM-DD"
+    exited_at: null
+    reason: "initial specification"
+
+# ────────────────────────────────────────────────────────────────────────────
+# ARTIFACTS — Trạng thái từng artifact
+# ────────────────────────────────────────────────────────────────────────────
+artifacts:
+  spec:
+    exists: true
+    version: "v1.0"
+    status: "draft"                      # draft | reviewed | approved
+    human_approved: false
+    approved_by: null
+    approved_at: null
+
+  plan:
+    exists: false
+    synced_to_spec: null                 # spec version plan này được sync với
+    human_approved: false
+
+  tasks:
+    exists: false
+    synced_to_spec: null
+    total: 0
+    completed: 0
+    in_progress: 0
+
+  test_cases:
+    exists: false
+    synced_to_spec: null
+    total: 0
+    human_approved: false
+
+  validation_report:
+    exists: false
+    verdict: null                        # PASS | PASS_WITH_CONCERNS | FAIL | PENDING_RECHECK
+    spec_version_checked: null
+    concerns_count: 0
+    issues_critical: 0
+    issues_major: 0
+
+  code_review:
+    exists: false
+    verdict: null                        # APPROVED | APPROVED_WITH_NOTES | CHANGES_REQUIRED
+
+  ui_mockups:                            # ảnh mockup — prototype/human đặt (KHÔNG do BA ingest ở S.1)
+    exists: false
+    count: 0                             # số ảnh mockup
+    sources: []                          # [pdf, docx, md, figma] — nguồn ảnh nếu có
+    screens: []                          # [UC-01, UC-02, ...] — UC có mockup
+    dir: null                            # path: .v-flow/features/NNN/ui/mockups/
+
+  prototype:
+    exists: false
+    branch: null                         # LOGIC | UI
+    mode: null                           # from-mockup (tái hiện) | explore (variant) — chỉ UI branch
+    verdict: null                        # VALIDATED | REJECTED | INCONCLUSIVE
+    approved_by: null                    # tên + vai trò người duyệt — BẮT BUỘC khi verdict=VALIDATED
+    approved_at: null                    # YYYY-MM-DD — thời điểm duyệt
+    question: null                       # câu hỏi prototype trả lời
+    req_refs: []                         # [REQ-xxx, ...] từ spec
+    notes_file: null                     # path: .v-flow/features/NNN/prototype-notes.md
+    approved_ref: null                   # path ui/approved/UC-NN.* — render đã chốt (mode=from-mockup, KHÔNG xóa)
+    skipped: false
+    skip_reason: null                    # lý do skip nếu skipped = true
+
+# ────────────────────────────────────────────────────────────────────────────
+# ROUTING — Quyết định routing tại mỗi gate
+# ────────────────────────────────────────────────────────────────────────────
+routing:
+  # Sau Master Check (R.0)
+  after_master_check:
+    last_verdict: null
+    last_fail_reason: null               # spec_gap | plan_gap | test_gap | constitution_violation | nogo_violation
+    route_decision: null                 # implement | re_specify | re_plan | re_test
+
+  # Sau Code Review (R.1)
+  after_review:
+    last_verdict: null
+    route_decision: null                 # deploy | fix_and_re_review | re_specify
+
+  # Sau Operations (O.0)
+  after_operations:
+    priority: null                       # P1 | P2 | P3 | P4
+    route_decision: null                 # hotfix_b1 | bugfix_full | lessons_learned
+
+# ────────────────────────────────────────────────────────────────────────────
+# HUMAN CHECKPOINTS — Các điểm cần người approve
+# ────────────────────────────────────────────────────────────────────────────
+human_checkpoints:
+  spec_approved: false
+  prototype_verdict_confirmed: false    # human xác nhận prototype verdict (S.1.5, optional)
+  plan_approved: false
+  master_check_approved: false          # human xác nhận PASS/PASS_WITH_CONCERNS
+  implementation_approved: false        # human kick off implement sau check
+  review_approved: false               # human approve để deploy
+  deploy_approved: false
+
+# Checkpoint hiện tại đang chờ (nếu có)
+awaiting_checkpoint: null               # e.g. "spec_approved" | null
+
+# ────────────────────────────────────────────────────────────────────────────
+# BUSINESS VERIFICATION — Cognitive gate trước khi /v.specify viết spec
+# ────────────────────────────────────────────────────────────────────────────
+business_verification:
+  status: null                          # null | pending | passed | passed_with_warnings | failed | skipped
+  verified_at: null
+  verified_by: null                     # tên human BA/PO đã đánh giá
+  skip_reason: null                     # lý do skip nếu status = "skipped"
+
+  # Danh sách modules đã được verify (append mỗi lần chạy gate)
+  modules_verified:
+    # - module: "domain-orders"
+    #   module_card_version: "1.2"      # version lúc verify — dùng để detect staleness
+    #   quiz_status: "ready"            # "draft" | "ready" — quiz đã được human review chưa?
+    #   must_score: "3/3"               # N/Total câu MUST đúng
+    #   should_score: "2/3"             # N/Total câu SHOULD đúng
+    #   verdict: "passed"               # "passed" | "passed_with_warnings" | "failed"
+    #   verified_at: "YYYY-MM-DD"
+    #   warnings: []                    # List SHOULD questions AI trả lời sai/thiếu
+
+# ────────────────────────────────────────────────────────────────────────────
+# CONCERNS — Từ Master Check, carry forward đến Implement
+# ────────────────────────────────────────────────────────────────────────────
+active_concerns:
+  # - id: "W-001"
+  #   description: "Rate limiting chưa được spec rõ"
+  #   source: "R.0 Master Check"
+  #   resolved: false
+  #   resolved_at: null
+  #   resolved_how: null
+
+# ────────────────────────────────────────────────────────────────────────────
+# BLOCKED — Lý do bị block (nếu có)
+# ────────────────────────────────────────────────────────────────────────────
+blocked: false
+blocked_reason: null                    # e.g. "Đang chờ API backend từ team khác"
+blocked_since: null
+blocked_dependencies:                   # Cross-feature dependency tracking (Thread Isolation)
+  # - feature: "001-login"
+  #   reason: "Cần auth API endpoint"
+  #   unblocked_when: "001-login phase >= R.1"
+
+# ────────────────────────────────────────────────────────────────────────────
+# B.0 OUTPUTS — Map-Reduce: optional agents và outputs song song
+# ────────────────────────────────────────────────────────────────────────────
+b0_outputs:
+  plan: { exists: false }
+  tests: { exists: false }
+  security: { exists: false, skipped: true, reason: null }
+  ux: { exists: false, skipped: true, reason: null }
+  api_contracts: { exists: false, skipped: true, reason: null }
+
+# ────────────────────────────────────────────────────────────────────────────
+# TIME TRAVEL — Fork & Rewind tracking
+# ────────────────────────────────────────────────────────────────────────────
+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 bản forks đang active
+
+rewind_count: 0                         # số lần rewind (> 2 = cảnh báo)
+
+# ────────────────────────────────────────────────────────────────────────────
+# METADATA
+# ────────────────────────────────────────────────────────────────────────────
+spec_version_latest: "v1.0"
+session_file: ".v-flow/features/NNN-feature-name/_session.md"
+notes: ""

package/templates/github/workflows/v-flow-validate.yml

@@ -0,0 +1,30 @@
+# V-Flow — validate spec/plan/tasks/test-cases on every PR.
+# Scaffolded by `v-flow init`. Gates the spec-driven pipeline so plan/task
+# artifacts can't drift. Legacy features (older schema_version) won't fail —
+# their new-schema warnings stay advisory until migrated.
+name: V-Flow Validate
+
+on:
+  pull_request:
+    paths:
+      - '.v-flow/features/**'
+      - '.v-flow/constitution.md'
+  push:
+    branches: [main, master]
+    paths:
+      - '.v-flow/features/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install v-flow CLI
+        run: npm install -g v-flow-cli
+      - name: Validate artifacts (strict — warnings block too)
+        run: v-flow validate --strict
+      # Optional — also lint source vs constitution [LINT:xxx] rules:
+      # - run: v-flow validate --constitution

package/templates/knowledge/adr-template.md

@@ -0,0 +1,70 @@
+# ADR-XXX: [Tiêu đề quyết định]
+
+> **Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-YYY]
+> **Date**: YYYY-MM-DD
+> **Deciders**: [Tên người quyết định]
+> **Technical Story**: [REQ-xxx hoặc ticket reference]
+
+---
+
+## Context
+
+> Mô tả bối cảnh kỹ thuật dẫn tới quyết định này.
+> Gồm: vấn đề đang gặp, ràng buộc, yêu cầu phi chức năng liên quan.
+
+*(Viết 3-5 câu mô tả tình huống thực tế)*
+
+---
+
+## Decision
+
+> Mô tả quyết định đã chọn — ghi rõ "chọn cái gì" và "vì sao".
+
+**Chúng tôi quyết định**: *(ghi rõ quyết định)*
+
+---
+
+## Options Considered
+
+### Option A: [Tên phương án]
+
+| Tiêu chí | Đánh giá |
+|----------|----------|
+| Performance | *(tốt/trung bình/kém)* |
+| Maintainability | |
+| Team familiarity | |
+| Risk level | |
+
+**Pros**: *(liệt kê ưu điểm)*
+**Cons**: *(liệt kê nhược điểm)*
+
+### Option B: [Tên phương án]
+
+*(tương tự Option A)*
+
+---
+
+## Consequences
+
+### Positive
+- *(tác động tích cực)*
+
+### Negative
+- *(tác động tiêu cực — chấp nhận được vì...)*
+
+### Neutral
+- *(tác động trung lập cần theo dõi)*
+
+---
+
+## Compliance
+
+- [ ] Không vi phạm No-Go Zones (ref: `context.md` §4)
+- [ ] Consistent với Constitution (ref: `constitution.md`)
+- [ ] Đã review với Architect/Tech Lead
+
+---
+
+## Notes
+
+*(Ghi chú bổ sung, link tham khảo, benchmark data, proof-of-concept results)*