@longph2102/v-flow 1.5.0

package/commands/v.sync.md

@@ -0,0 +1,81 @@
+---
+description: "Sync Agent — Cập nhật plan/tasks/tests khi spec thay đổi"
+phase: "Any"
+agent: "sync-agent"
+---
+
+# /v.sync
+
+> Orchestration wrapper cho **Sync Agent**. Đọc `agents/sync-agent.md` để thực hiện core logic.
+
+> **Nguyên tắc cốt lõi**: `spec.md` là Single Source of Truth — spec luôn thắng.
+
+## Điều kiện tiên quyết
+- `spec.md` đã được chỉnh sửa (bump version) sau khi đã có plan/tasks/tests
+- Artifact Sync Status trong spec.md Status block có **❌** (cần sync)
+- `plan.md`, `tasks.md`, `test-cases.md` phải tồn tại
+
+## Execution
+1. Đọc agent definition: `agents/sync-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Báo cáo sync summary
+
+## Options
+
+### (không có argument) — Feature hiện tại
+Sync artifacts cho feature đang active trong context.
+
+### --dry-run — Chỉ báo cáo, không sửa
+```
+/v.sync --dry-run
+```
+Hiển thị delta analysis mà không thay đổi files.
+
+---
+
+## 🔀 Routing Rules — Sau Sync
+
+```
+Sync hoàn tất
+  → Route: /v.check (BẮT BUỘC — validation-report cũ không còn giá trị)
+
+Change quá lớn (architecture impact)
+  → Route: /v.plan (re-plan từ đầu)
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+spec_version_latest: "vX.Y"
+artifacts:
+  plan:
+    synced_to_spec: "vX.Y"
+  tasks:
+    synced_to_spec: "vX.Y"
+  test_cases:
+    synced_to_spec: "vX.Y"
+  validation_report:
+    verdict: "PENDING_RECHECK"
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [Sync] Spec Sync — [YYYY-MM-DD]
+- **Agent**: Sync Agent
+- **Trigger**: spec v[old] → v[new]
+- **Changes**: [+N tasks, ~M modified, -K superseded]
+- **Tests updated**: [+N, ~M, -K]
+- **Validation**: Reset to PENDING RECHECK
+- **Routing**: → /v.check (mandatory)
+```
+
+---
+
+## Ví dụ
+
+```
+/v.sync
+/v.sync feature 001-user-login
+/v.sync --dry-run
+```

package/commands/v.test.md

@@ -0,0 +1,67 @@
+---
+description: "Test Agent — Tạo Test Cases toàn diện từ Specification"
+phase: "B.0b"
+agent: "test-agent"
+---
+
+# /v.test
+
+> Orchestration wrapper cho **Test Agent**. Đọc `agents/test-agent.md` để thực hiện core logic.
+
+Chạy **SONG SONG** với `/v.plan`.
+
+## Đ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
+- `.flow-state.yaml` phải tồn tại
+
+## Execution
+1. Đọc agent definition: `agents/test-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Tạo `test-cases.md` với test matrix đầy đủ
+
+---
+
+## 🔀 Routing Rules — Sau Test
+
+```
+Test cases tạo xong
+  → Nếu /v.plan chưa xong → Chờ Plan Agent
+  → Nếu /v.plan đã xong   → /v.check (Master Check)
+
+Không đủ thông tin viết test
+  → Route: Quay về S.1 (BA Agent clarify REQ)
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "B.0b"
+phase_status: "done"
+artifacts:
+  test_cases:
+    exists: true
+    total: [N]
+    synced_to_spec: "v1.0"
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [B.0b] Test — [YYYY-MM-DD]
+- **Agent**: Test Agent
+- **Output**: test-cases.md ([N] test cases)
+- **Test Matrix**: Unit: [N], Integration: [N], E2E: [N]
+- **Coverage**: [N]/[N] REQ covered (100%)
+- **Edge cases**: [N] edge case tests
+- **Routing**: → /v.check (khi /v.plan xong)
+```
+
+---
+
+## Ví dụ
+
+```
+/v.test
+/v.test feature 001-user-login
+```

package/commands/v.understand.md

@@ -0,0 +1,112 @@
+---
+description: "Understand Agent — Scan codebase và generate Multi-Layer Understanding (context.md + Module Cards)"
+phase: "U.0"
+agent: "understand-agent"
+---
+
+# /v.understand
+
+> Orchestration wrapper cho **Understand Agent**. Đọc `agents/understand-agent.md` để thực hiện core logic.
+
+## Điều kiện tiên quyết
+- `.v-flow/` phải tồn tại (đã chạy `v-flow init`)
+- Codebase phải có source files để scan
+- Nếu dùng `--module`: module name phải tương ứng với domain có trong codebase
+
+## Modes
+
+### Mode 1: `--module {tên}` — Scan 1 module (khuyến khích)
+
+```
+/v.understand --module {tên-module}
+```
+
+Generate folder `.v-flow/modules/domain-{tên}/` gồm 10 file bắt buộc: `SKILL.md`, `use-cases.md`, `api-specs.md`, `tech-context.md`, `cross-service.md`, `db.md`, `state-diagram.md`, `permissions.md`, `business-quiz.md`, `dev-quiz.md` — cộng `ui-flows.md` nếu có FE (tối đa 11).
+
+### Mode 2: `--all` — Scan toàn bộ
+
+```
+/v.understand --all
+```
+
+1. Generate/update `context.md` (Tầng 1)
+2. Auto-detect modules → generate tất cả module folders (Tầng 2)
+
+### Mode 3: `--check` — Kiểm tra stale (chỉ báo cáo)
+
+```
+/v.understand --check --module {tên}
+```
+
+### Mode 4: `--refresh` — Re-scan và update
+
+```
+/v.understand --module {tên} --refresh
+```
+
+## Execution
+1. Đọc agent definition: `agents/understand-agent.md`
+2. Đọc Skill hướng dẫn scan: `skills/understand/codebase-scanner/SKILL.md`
+3. Thực hiện quy trình trong agent definition theo mode được chọn
+4. **(Tùy chọn) Verify bằng CLI khi cần** (Bước 6 trong agent): KHÔNG chạy xen kẽ lúc sinh card. Card "xong" theo Quality Gate chiều sâu + đủ file. Khi muốn đối chiếu máy (vd trước Tech Lead review) → `v-flow validate --module-cards <module>` + `v-flow score-card <module>` + `v-flow dev-quiz <module>`. Đây là kiểm tra on-demand, KHÔNG phải điều kiện "xong". Mode `--check` bỏ qua.
+
+---
+
+## ❌ Anti-patterns (Output VÔ GIÁ TRỊ)
+
+| Anti-pattern | Ví dụ BAD | Ví dụ GOOD |
+|---|---|---|
+| Liệt kê tên file không giải thích | "Key files: service.ts, controller.ts" | "service.ts (250 LOC): Xử lý CRUD WO, validate business rules" |
+| Business rule chung chung | "Validate input trước khi lưu" | "`amount` phải > 0, `assignee_id` cùng `branch_id` (file: wo_service.dart:89)" |
+| API không chi tiết | "POST /api/orders — Tạo order" | "POST /api/orders — Auth: ROLE_USER. Body: {itemId: required, qty: min:1}." |
+
+---
+
+## 🔀 Routing — Bước tiếp theo
+
+```
+context.md + Module Cards tạo xong (đủ file + đạt Quality Gate chiều sâu)
+  → (tùy chọn) Verify máy khi cần: v-flow validate --module-cards <module> + score-card + dev-quiz
+  → Tech Lead review: xóa [⚠️ AI-inferred], set Last verified
+  → Tiến sang S.0a (/v.constitute) hoặc S.1 (/v.specify)
+```
+
+## Output
+
+| Mode | Output |
+|------|--------|
+| `--all` | `.v-flow/context.md` (v2) + `.v-flow/modules/domain-xxx/` (N folders, mỗi folder đủ bộ card gồm `business-quiz.md` + `dev-quiz.md`) |
+| `--module {tên}` | `.v-flow/modules/domain-{tên}/` (1 folder, 10 file bắt buộc + `ui-flows.md` nếu có FE = tối đa 11) |
+| `--check` | Báo cáo diff (không sửa file) |
+| `--refresh` | Cập nhật module card + bump MINOR version trong `SKILL.md` |
+
+---
+
+## Cập nhật State & Session
+
+**Không cập nhật `.flow-state.yaml`** — U.0 là project-level, không per-feature.
+
+**Auto-bump MINOR version** (sau mỗi lần ghi module card):
+- `SKILL.md` được cập nhật `version`, `last_updated`, `last_updated_by` tự động
+- Không bump MAJOR — chỉ human mới được bump MAJOR
+
+**Ghi vào context.md** (khi `--all`):
+```markdown
+## Module Index (auto-generated by /v.understand)
+
+| Module | SKILL.md | use-cases | business-quiz | version | Last verified |
+|--------|----------|-----------|---------------|---------|---------------|
+| auth | ✅ | ✅ | ✅ ready | v1.2 | [date] |
+| payment | ✅ | ✅ | ⚠️ draft | v2.0 | [date] |
+```
+
+---
+
+## Ví dụ
+
+```
+/v.understand --all
+/v.understand --module orders
+/v.understand --module payment --refresh
+/v.understand --check --module auth
+```

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@longph2102/v-flow",
+  "version": "1.5.0",
+  "description": "CLI toolkit for V Flow — Agentic AI Software Development Process (Spec-Driven Development)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "cli/index.js",
+  "bin": {
+    "v-flow": "./cli/index.js"
+  },
+  "files": [
+    "cli/",
+    "agents/",
+    "commands/",
+    "skills/",
+    "templates/",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "eslint cli/ tests/",
+    "lint:fix": "eslint cli/ tests/ --fix",
+    "validate": "node cli/index.js validate",
+    "validate:strict": "node cli/index.js validate --strict",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "v-flow",
+    "spec-driven-development",
+    "agentic-ai",
+    "sdlc",
+    "ai-agents",
+    "specification"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quochoang228/v-Flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/quochoang228/v-Flow/issues"
+  },
+  "homepage": "https://github.com/quochoang228/v-Flow#readme",
+  "author": "quochoang228",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "exceljs": "^4.4.0",
+    "jest": "^30.3.0",
+    "markdown-docx": "^1.6.0"
+  }
+}

package/skills/_shared/constitution-reader/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: constitution-reader
+description: "Load và parse constitution.md, extract rules áp dụng cho phase hiện tại. Agent PHẢI gọi skill này ở đầu MỖI session."
+trigger: "Đầu mỗi agent session / mỗi phase mới"
+phase: "All"
+used_by:
+  - /v.specify
+  - /v.plan
+  - /v.test
+  - /v.check
+  - /v.implement
+  - /v.review
+---
+
+# Constitution Reader — Load Project Rules
+
+> ⚠️ Đây là **Skill dùng chung** — chạy ĐẦU TIÊN trong mọi agent session.
+> Nếu constitution.md không tồn tại → WARN, nhưng vẫn tiếp tục.
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi đọc constitution.
+> → Xem `examples/good/` cho mẫu output per phase.
+
+---
+
+## Khi nào KHÔNG đọc
+
+- Chạy `/v.constitute` (đang TẠO constitution)
+- Chạy `/v.understand` lần đầu (chưa có constitution)
+
+---
+
+## Nguồn Constitution
+
+```
+Đường dẫn: .v-flow/constitution.md
+Nếu không tồn tại → WARN: "No constitution found. Consider running /v.constitute"
+```
+
+---
+
+## Mapping Sections → Phases
+
+> 💡 Agent KHÔNG cần đọc toàn bộ constitution. Chỉ đọc sections LIÊN QUAN cho phase hiện tại.
+
+| Constitution Section | Áp dụng cho Phase | Agent đọc |
+|---------------------|:------------------:|-----------|
+| §1 Architecture Principles | B.0a, B.1 | Plan, Implement |
+| §2 Code Standards | B.1, R.1 | Implement, Review |
+| §3 Testing Policy | B.0b, B.1 | Test, Implement |
+| §4 API Conventions | S.1, B.0a | BA, Plan |
+| §5 Security Requirements | ALL | ALL |
+| §6 Naming Conventions | B.1, R.1 | Implement, Review |
+| §7 No-Go Zones | B.0a, B.1 | Plan, Implement |
+| §8 Error Handling | B.0a, B.1 | Plan, Implement |
+| §9 Spec Change Policy | S.1 | BA |
+
+## Per-Agent Extraction Depth
+
+> 💡 Mỗi Agent cần KHÁC NHAU từ constitution. Đây là bảng chi tiết:
+
+| Agent | Sections cần | Extraction depth | Quyết định gì từ constitution |
+|-------|-------------|:-----:|-----|
+| **BA Agent** | §4, §5, §9 | Shallow | API naming style → ảnh hưởng spec endpoint names |
+| **Plan Agent** | §1, §4, §5, §7, §8 | Deep | Architecture pattern → ảnh hưởng task breakdown |
+| **Test Agent** | §3, §5 | Medium | Coverage target, test strategy → ảnh hưởng TC count |
+| **Implement Agent** | §1-§3, §5-§8 | Deep | Everything — most affected by constitution |
+| **Review Agent** | §1-§8 | Deep | Review criteria derived from rules |
+| **Master Check** | §5, §7 | Shallow | Security và No-Go → blocking concerns |
+
+---
+
+## Cross-Reference With context.md
+
+Nếu context.md tồn tại (legacy project):
+- No-Go Zones từ context.md **override** constitution §7
+- Technical Debt từ context.md **bổ sung** vào awareness
+- Architecture thực tế từ context.md **có thể khác** constitution (→ flag mismatch)
+
+### Conflict Resolution
+
+| Conflict | Rule |
+|----------|------|
+| context.md nói "monolith" + constitution nói "clean architecture" | Code MỚI → follow constitution. Code CŨ → don't refactor (No-Go) |
+| context.md nói "raw SQL" + constitution nói "ORM" | New features → ORM. Existing queries → keep raw SQL |
+| constitution §7 lists No-Go + context.md lists MORE No-Go | **Union** — cả hai đều block |
+| constitution `[Cần quyết định]` | DỪNG. Ghi _session.md. Hỏi Tech Lead |
+| Version mismatch (constitution updated mid-pipeline) | WARN → suggest `/v.sync` |
+
+---
+
+## Đặc Thù
+
+### Constitution có thể chưa hoàn chỉnh
+- Sections ghi `[Cần quyết định]` → Agent ghi vào _session.md và hỏi Tech Lead
+- KHÔNG tự quyết định thay — **đây là lỗi phổ biến nhất**
+
+### Constitution version
+- Check version ở header → so sánh với .flow-state.yaml `constitution_version`
+- Nếu mismatch → WARN: "Constitution updated since last pipeline run"
+- **Action**: Suggest `/v.sync` để propagate changes
+
+### Multiple projects in monorepo
+- Mỗi sub-project có thể có constitution riêng
+- Đọc constitution gần nhất theo directory hierarchy
+
+### Edge Case: No constitution + No context
+- Greenfield project chưa chạy `/v.constitute`
+- Agent PHẢI vẫn chạy được — dùng best-practice defaults
+- Ghi WARN vào _session.md: "No project rules found"

package/skills/_shared/constitution-reader/config.json

@@ -0,0 +1,52 @@
+{
+  "name": "constitution-reader",
+  "version": "1.0",
+  "description": "Load và parse constitution.md, extract rules áp dụng cho phase hiện tại",
+  "agent": "_shared",
+  "phase": ["All"],
+  "triggers": ["session_start", "phase_change"],
+  "dependencies": [],
+  "config": {
+    "constitution_path": ".v-flow/constitution.md",
+    "fallback_behavior": "warn_and_continue",
+    "cache_duration": "session",
+    "section_mapping": {
+      "S.1": ["§4", "§5", "§9"],
+      "B.0a": ["§1", "§4", "§5", "§7", "§8"],
+      "B.0b": ["§3", "§5"],
+      "B.1": ["§1", "§2", "§3", "§5", "§6", "§7", "§8"],
+      "R.0": ["§5", "§7"],
+      "R.1": ["§1", "§2", "§3", "§5", "§6", "§7", "§8"]
+    }
+  },
+  "setup_questions": [
+    {
+      "id": "extraction_depth",
+      "question": "Default extraction depth khi không có mapping rõ ràng?",
+      "options": ["shallow", "medium", "deep"],
+      "default": "medium",
+      "description": "shallow = chỉ đọc headings. medium = headings + rules. deep = toàn bộ nội dung."
+    },
+    {
+      "id": "version_check",
+      "question": "Có kiểm tra constitution version vs .flow-state.yaml không?",
+      "type": "boolean",
+      "default": true
+    },
+    {
+      "id": "mismatch_action",
+      "question": "Khi phát hiện constitution version mismatch?",
+      "options": ["warn", "block", "auto-sync"],
+      "default": "warn"
+    }
+  ],
+  "hooks": {
+    "pre_read": "Check constitution.md tồn tại → nếu không → fallback_behavior",
+    "post_read": "Compare constitution version với .flow-state.yaml → warn nếu mismatch"
+  },
+  "memory": {
+    "file": "constitution-reads.log",
+    "format": "[date] | [agent] | [phase] | [sections_read] | [version] | [warnings]",
+    "purpose": "Track agent nào đọc sections nào — dùng cho audit và optimization"
+  }
+}

package/skills/_shared/constitution-reader/examples/good/b1-phase-output.md

@@ -0,0 +1,48 @@
+# Good Example — Constitution Reader Output cho Phase B.1
+
+> Mẫu output khi constitution-reader extract rules cho Implement Agent.
+
+## Input
+- Phase: B.1 (Implementation)
+- Agent: Implement Agent
+- Constitution: v2.1
+
+## Output
+
+```markdown
+## Active Constitution Rules (Phase: B.1 Implementation)
+
+### §1 Architecture (ACTIVE)
+- ✅ Clean Architecture: Presentation → Domain → Data
+- ✅ Dependency Rule: inner layers không depend outer layers
+- ✅ Domain layer: pure Dart, no framework imports
+
+### §2 Code Standards (ACTIVE)
+- ✅ camelCase for variables/functions
+- ✅ PascalCase for classes
+- ✅ Max function length: 50 LOC
+- ✅ Max file length: 300 LOC
+
+### §3 Testing (ACTIVE)
+- ✅ Coverage target: ≥ 80%
+- ✅ TDD mandatory: test before code
+- ✅ Naming: should_X_when_Y
+
+### §5 Security (ALWAYS ACTIVE)
+- ✅ No hardcoded secrets
+- ✅ Validate all external input
+
+### §7 No-Go Zones (ACTIVE)
+- 🔴 lib/core/engine/ — FFI bridge, native code
+- 🟡 lib/core/auth/ — shared by 5 modules
+
+### Not applicable for B.1
+- §4 API Conventions → Plan phase only
+- §9 Spec Change Policy → Spec phase only
+```
+
+## Điểm đáng chú ý
+
+✅ **Chỉ sections liên quan** — skip §4, §9 (không dùng ở B.1)
+✅ **No-Go Zones LUÔN included** — dù phase nào
+✅ **Actionable** — rules cụ thể, không generic

package/skills/_shared/constitution-reader/gotchas.md

@@ -0,0 +1,46 @@
+# Gotchas — Constitution Reader
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Đây là "institutional memory" cho constitutional compliance.
+
+---
+
+## Gotchas Phổ Biến
+
+1. ❌ **Đọc toàn bộ constitution mỗi lần** — Waste context window (500+ LOC).
+   - **Fix**: Chỉ đọc sections liên quan (xem Per-Agent Extraction Depth table).
+   - **Hậu quả**: Agent chậm, context window bị chiếm bởi rules không dùng.
+
+2. ❌ **Constitution nói A, context.md nói B** — Conflict không phát hiện.
+   - **VD**: Constitution: "No ORM, use raw SQL". Context.md: "Sequelize ORM đang dùng".
+   - **Fix**: context.md reflect THỰC TẾ → ưu tiên context.md cho legacy. Ghi conflict.
+   - **Hậu quả**: Agent dùng sai pattern → code inconsistent.
+
+3. ❌ **Bỏ qua `[Cần quyết định]`** — Agent tự fill placeholder.
+   - **VD**: §3 Testing: "[Cần quyết định]". Agent pick "80%" tự ý.
+   - **Rule**: KHÔNG tự quyết. Ghi vào _session.md, chờ Tech Lead.
+   - **Hậu quả**: Tech Lead không biết Agent đã quyết thay.
+
+4. ❌ **Quên No-Go Zones** — Constitution §7 liệt kê nhưng Agent quên extract.
+   - **Fix**: Output ALWAYS include No-Go list ở cuối, DÙ phase nào.
+   - **Hậu quả**: Implement Agent đụng No-Go → bị block muộn.
+
+5. ❌ **Version mismatch** — Constitution updated nhưng pipeline chạy từ version cũ.
+   - **Fix**: Compare header version vs .flow-state.yaml. Flag nếu khác.
+   - **Hậu quả**: Agent follow rules cũ → drift.
+
+6. ❌ **Skip constitution cho greenfield** — "Dự án mới, chưa cần rules".
+   - **Rule**: Greenfield CŨNG cần. Nếu chưa có → suggest `/v.constitute`.
+   - **Hậu quả**: Code không consistent từ đầu.
+
+7. ❌ **§5 Security bị skip** — Agent chỉ đọc §1, §2, quên §5.
+   - **Rule**: §5 Security = ALWAYS ACTIVE cho MỌI phase.
+   - **Hậu quả**: Security holes không được catch sớm.
+
+---
+
+## Edge Cases
+
+- **Monorepo**: Nhiều constitution files → đọc gần nhất theo directory
+- **Empty sections**: Constitution có heading nhưng nội dung trống → treat như [Cần quyết định]
+- **Spec change mid-pipeline**: constitution.md §9 quy định enqueue/interrupt → đọc kỹ