@ngocsangairvds/vsaf 3.1.0 → 3.1.2

package/.claude/skills/vsaf-doc-srs/SKILL.md

@@ -1,169 +1,169 @@
 ---
 name: vsaf-doc-srs
-description: Viết tài liệu SRS (Software Requirements Specification) từ PRD đã có. Dùng sau /vsaf-doc-prd. Theo workflow BA chuẩn với template SRS feature-level.
+description: Write SRS (Software Requirements Specification) from an existing PRD. Use after /vsaf-doc-prd. Follows standard BA workflow with feature-level SRS template.
 ---
 
 # VSAF Doc SRS
 
-## Mục tiêu
-Phân tích PRD và viết tài liệu SRS feature-level theo template chuẩn — đảm bảo truy xuất được từ PRD → Use Cases → Màn hình → Epic/Story.
+## Goal
+Analyze the PRD and write a feature-level SRS following a standard template — ensuring traceability from PRD → Use Cases → Screens → Epic/Story.
 
-**Your Role:** Business Analyst chuyên nghiệp — viết SRS theo quy trình chuẩn.
+**Your Role:** Professional Business Analyst — write SRS following a standard process.
 
-## Điều kiện tiên quyết
-- Phải đã chạy `/vsaf-doc-prd` và có PRD được approve trước khi chạy skill này.
+## Prerequisites
+- Must have run `/vsaf-doc-prd` and have an approved PRD before running this skill.
 
-## Cấu hình
+## Configuration
 ```yaml
 outputDir: docs/project/srs
 featureTemplate: _bmad/bmm/1-analysis/bmad-document-project/templates/srs-feature-template.md
 systemTemplate: _bmad/bmm/1-analysis/bmad-document-project/templates/srs-system-template.md
 ```
 
-## Các bước thực hiện
+## Steps
 
-### Bước 0 — Kiểm tra đầu vào
+### Step 0 — Validate inputs
 
-Trước khi bắt đầu, kiểm tra xem user đã cung cấp đủ thông tin chưa:
+Before starting, check if the user has provided sufficient information:
 
-**Yêu cầu bắt buộc:**
-- [ ] Tài liệu PRD (file path hoặc nội dung) — thường ở `docs/project/planning-artifacts/prd-[feature].md`
-- [ ] Figma link (URL figma.com/design/...) — nếu có
+**Required:**
+- [ ] PRD document (file path or content) — typically at `docs/project/planning-artifacts/prd-[feature].md`
+- [ ] Figma link (URL figma.com/design/...) — if available
 
-Nếu thiếu PRD, **dừng lại ngay** và yêu cầu user cung cấp:
+If PRD is missing, **stop immediately** and request from the user:
 
 ```
-Để viết tài liệu SRS, tôi cần bạn cung cấp:
+To write the SRS document, I need you to provide:
 
-❌ [liệt kê những gì còn thiếu]
+[list what is missing]
 
-Vui lòng cung cấp:
-1. File PRD: đường dẫn file hoặc paste nội dung vào đây
-2. Figma link (nếu có): URL dạng https://www.figma.com/design/...
-3. Flow/Feature cần viết SRS (VD: FR-1, FR-2,...)
+Please provide:
+1. PRD file: file path or paste the content here
+2. Figma link (if available): URL like https://www.figma.com/design/...
+3. Flow/Feature to write SRS for (e.g., FR-1, FR-2,...)
 ```
 
-Chỉ tiếp tục khi đã có đủ PRD.
+Only continue when the PRD is available.
 
 ---
 
-### Bước 1 — Xác định mode: Tạo mới hay Chỉnh sửa
-- Kiểm tra xem đã có SRS trong `docs/project/srs/` cho feature này chưa
-- **Nếu chưa có** → Mode: CREATE
-- **Nếu đã có** → Mode: EDIT
-  - Hỏi user: "SRS đã tồn tại. Bạn muốn tạo mới hoàn toàn hay chỉnh sửa?"
-  - Mode EDIT: dùng skill `bmad-edit-prd` để chỉnh sửa SRS đã có
+### Step 1 — Determine mode: Create or Edit
+- Check if an SRS already exists in `docs/project/srs/` for this feature
+- **If none exists** → Mode: CREATE
+- **If one exists** → Mode: EDIT
+  - Ask user: "An SRS already exists. Do you want to create a new one from scratch or edit the existing one?"
+  - Mode EDIT: use skill `bmad-edit-prd` to edit the existing SRS
 
 ---
 
-### Bước 2 — Đọc & phân tích PRD
+### Step 2 — Read & analyze PRD
 
-Đọc toàn bộ tài liệu PRD. Trích xuất và tổ chức thông tin theo cấu trúc:
+Read the entire PRD document. Extract and organize information into the following structure:
 
-**2.1 Mục tiêu dự án**
+**2.1 Project objectives**
 - Business objective, Problem statement, Success criteria
 
-**2.2 Phạm vi (Scope)**
-- In-scope features / Sub-FRs, Out-of-scope, Các module/màn hình chính
+**2.2 Scope**
+- In-scope features / Sub-FRs, Out-of-scope, Main modules/screens
 
 **2.3 Actors & Use Cases**
-- Danh sách các actor (vai trò người dùng), User stories / use cases đã đề cập
+- List of actors (user roles), User stories / use cases mentioned
 
 **2.4 Business Rules**
-- Quy tắc nghiệp vụ quan trọng, Constraints & assumptions
+- Key business rules, Constraints & assumptions
 
 **2.5 Non-functional Requirements**
-- Performance, security, scalability, v.v. (nếu có)
+- Performance, security, scalability, etc. (if applicable)
 
-Sau bước này, xuất ra **"Tóm tắt PRD"** để user xác nhận trước khi sang bước 3.
+After this step, output a **"PRD Summary"** for user confirmation before proceeding to step 3.
 
 ---
 
-### Bước 3 — So sánh PRD với Figma (nếu có Figma)
+### Step 3 — Compare PRD with Figma (if Figma is available)
 
-Nếu có Figma link, dùng Figma MCP tools để đọc design:
-1. Gọi `get_figma_data` để lấy danh sách pages/frames
-2. Download screenshots cho từng màn hình chính
+If a Figma link is available, use Figma MCP tools to read the design:
+1. Call `get_figma_data` to get the list of pages/frames
+2. Download screenshots for each main screen
 
-So sánh và ghi nhận:
+Compare and record:
 
-| Hạng mục | PRD nói | Figma thiết kế | Trạng thái |
+| Item | PRD states | Figma design | Status |
 |---|---|---|---|
-| [Feature/Screen] | ... | ... | ✅ Khớp / ⚠️ Khác biệt / ❓ Chưa rõ |
+| [Feature/Screen] | ... | ... | Matched / Discrepancy / Unclear |
 
-**Phân tích gap:**
-- **Gap 1 — Thiếu trong Figma:** Features có trong PRD nhưng không thấy trong design
-- **Gap 2 — Thêm trong Figma:** UI elements trong Figma nhưng không đề cập trong PRD
-- **Gap 3 — Mâu thuẫn:** Thông tin không nhất quán giữa hai nguồn
+**Gap analysis:**
+- **Gap 1 — Missing in Figma:** Features in PRD but not found in the design
+- **Gap 2 — Added in Figma:** UI elements in Figma but not mentioned in the PRD
+- **Gap 3 — Conflicts:** Inconsistent information between the two sources
 
-Nếu không có Figma: ghi rõ "Chưa có Figma design — cần UX team cung cấp" tại mục 2 của SRS.
+If no Figma: note "No Figma design available — UX team needs to provide" in section 2 of the SRS.
 
-Sau bước này, xuất ra **"Báo cáo Gap Analysis"** và hỏi user có muốn clarify gap nào trước khi viết SRS không.
+After this step, output a **"Gap Analysis Report"** and ask the user if they want to clarify any gaps before writing the SRS.
 
 ---
 
-### Bước 4 — Viết tài liệu SRS theo Feature Template
+### Step 4 — Write SRS following the Feature Template
 
-Đọc template tại `_bmad/bmm/1-analysis/bmad-document-project/templates/srs-feature-template.md` và viết SRS **đúng theo cấu trúc template**, bao gồm đầy đủ 12 sections (0–11):
+Read the template at `_bmad/bmm/1-analysis/bmad-document-project/templates/srs-feature-template.md` and write the SRS **strictly following the template structure**, including all 12 sections (0-11):
 
-0. **Preamble** — Thông tin tài liệu, bảng ghi nhận thay đổi, bảng phê duyệt
-1. **Introduction** — Mục tiêu, phạm vi, tài liệu tham chiếu
-2. **Business Context** — Business objective, actors, use cases tổng quan
+0. **Preamble** — Document information, change log table, approval table
+1. **Introduction** — Objectives, scope, reference documents
+2. **Business Context** — Business objective, actors, use cases overview
 3. **System Overview** — High-Level Activity Diagram + Architecture
 4. **Data Model** — Entity tables, ER diagram, Kafka Events, API Endpoints
-5. **Functional Requirements** — Đặc tả Use Cases chi tiết. Mỗi UC gồm:
-   - **Màn hình** — Bảng chi tiết controls từng màn hình thuộc UC
-   - **Luồng nghiệp vụ** — Sequence diagram (PlantUML) + Activity diagram (PlantUML, nếu cần)
-   - Màn hình dùng chung: đặt bảng đầy đủ tại UC đầu tiên, UC sau ghi tham chiếu
+5. **Functional Requirements** — Detailed Use Case specifications. Each UC includes:
+   - **Screens** — Detailed controls table for each screen in the UC
+   - **Business flows** — Sequence diagram (PlantUML) + Activity diagram (PlantUML, if needed)
+   - Shared screens: place the full table at the first UC, subsequent UCs reference it
 6. **State & Behavioral Models** — State diagrams (Mermaid stateDiagram-v2), entity lifecycle
 7. **Business Rules & Validation** — BR table + Validation Rules + Error Codes
-8. **NFR** — Non-functional requirements đặc thù cho flow
+8. **NFR** — Non-functional requirements specific to the flow
 9. **Constraints** — Constraints, assumptions, dependencies, transition requirements
-10. **RTM** — Ma trận truy xuất: PRD FR → UC → Màn hình → Epic/Story → BR → AC → Test Case
-11. **Appendix** — Figma Mapping tables, Screen List, Chức năng ảnh hưởng, Gap Analysis
+10. **RTM** — Requirements Traceability Matrix: PRD FR → UC → Screen → Epic/Story → BR → AC → Test Case
+11. **Appendix** — Figma Mapping tables, Screen List, Affected features, Gap Analysis
 
-**Quy tắc viết:**
-- Viết bằng **tiếng Việt** trừ khi user yêu cầu tiếng Anh
-- Giữ nguyên business rules từ PRD, không tự ý thay đổi logic nghiệp vụ
-- Mỗi Use Case phải có: Precondition, Main flow, Alternative flow, Exception flow, Postcondition
-- Activity/Flow diagrams dùng Mermaid `flowchart TD`; State diagrams dùng `stateDiagram-v2`; ER dùng `erDiagram`
-- Nếu thông tin chưa đủ → ghi `{{Cần bổ sung}}` và liệt kê ở phần Gap Analysis
+**Writing rules:**
+- Write in **English** by default unless user requests otherwise
+- Preserve business rules from the PRD, do not arbitrarily change business logic
+- Each Use Case must have: Precondition, Main flow, Alternative flow, Exception flow, Postcondition
+- Activity/Flow diagrams use Mermaid `flowchart TD`; State diagrams use `stateDiagram-v2`; ER uses `erDiagram`
+- If information is insufficient → mark as `{{TBD}}` and list in the Gap Analysis section
 
 ---
 
-### Bước 5 — Validate SRS (BMAD validate)
-- Dùng skill `bmad-validate-prd` để validate SRS vừa sinh/sửa
-- Kiểm tra: FRs đủ rõ ràng? NFRs đo lường được? Acceptance criteria kiểm chứng được?
-- Nếu có issues: fix ngay trong SRS, không chờ đến build
-- Ghi nhận validation result (PASS/FAIL + findings)
+### Step 5 — Validate SRS (BMAD validate)
+- Use skill `bmad-validate-prd` to validate the generated/edited SRS
+- Check: Are FRs clear enough? Are NFRs measurable? Are acceptance criteria verifiable?
+- If issues found: fix immediately in the SRS, do not wait until build
+- Record validation result (PASS/FAIL + findings)
 
 ---
 
-### Bước 6 — Lưu file SRS
-Lưu tài liệu SRS vào: `docs/project/srs/SRS-[tên-dự-án]-[FR-ID]-[tên-feature]-v1.0.md`
+### Step 6 — Save SRS file
+Save the SRS document to: `docs/project/srs/SRS-[project-name]-[FR-ID]-[feature-name]-v1.0.md`
 
-### Bước 7 — Output cho user
+### Step 7 — Output to user
 ```
-## SRS đã tạo/cập nhật
+## SRS Created/Updated
 
 ### File
-- docs/project/srs/SRS-[tên-dự-án]-[FR-ID]-[tên-feature]-v1.0.md
+- docs/project/srs/SRS-[project-name]-[FR-ID]-[feature-name]-v1.0.md
 - Mode: [CREATE / EDIT]
-- Use Cases viết: [N]
-- Validation: [PASS / FAIL — chi tiết nếu fail]
+- Use Cases written: [N]
+- Validation: [PASS / FAIL — details if fail]
 
-### Gaps cần confirm
-- [Danh sách gaps quan trọng cần team confirm]
+### Gaps to confirm
+- [List of important gaps that need team confirmation]
 
-### Phần chưa hoàn thiện
-- [Các phần SRS còn {{...}} cần bổ sung thêm]
+### Incomplete sections
+- [SRS sections still containing {{...}} that need additional input]
 
 ## Next step
-Chạy /vsaf-test docs/project/srs/SRS-[...].md để sinh testcase
+Run /vsaf-test docs/project/srs/SRS-[...].md to generate testcases
 ```
 
-## Lưu ý
-- Không bắt đầu code trong bước này
-- Nếu scope quá lớn (>3 modules): đề nghị split thành nhiều PRs
+## Notes
+- Do not start coding in this step
+- If scope is too large (>3 modules): suggest splitting into multiple PRs
 - Commit docs: `git commit -m "docs: srs for <feature>"`
-- Nếu mode EDIT và testcases cũ bị ảnh hưởng: cảnh báo user re-run `/vsaf-test`
+- If mode is EDIT and existing testcases are affected: warn user to re-run `/vsaf-test`

package/.claude/skills/vsaf-docs/SKILL.md

@@ -1,61 +1,61 @@
 ---
 name: vsaf-docs
-description: Documentation & knowledge sync — cập nhật docs, sinh project context, build wiki. Dùng sau /vsaf-ship hoặc cuối sprint để đảm bảo knowledge không bị mất.
+description: Documentation & knowledge sync — update docs, generate project context, build wiki. Use after /vsaf-ship or at end of sprint to ensure knowledge is not lost.
 ---
 
 # VSAF Docs
 
-## Mục tiêu
-Đảm bảo documentation luôn cập nhật và AI agents có đủ context.
+## Goal
+Ensure documentation is always up to date and AI agents have sufficient context.
 
 ## Input
-`$ARGUMENTS` — scope cần document:
-- *(không có argument)* — full documentation refresh
-- `<module>` — document module cụ thể
-- `context` — chỉ sinh project-context.md
-
-## Khi nào dùng
-- Sau mỗi sprint (batch update)
-- Sau ship feature lớn (>3 modules thay đổi)
-- Khi onboard team member mới
-- Khi AI agent gặp khó hiểu codebase
-
-## Các bước thực hiện
-
-### Bước 1 — Scan current state
-- Dùng `mcp__gitnexus__query` để scan codebase hiện tại
-- So sánh: docs hiện tại vs code hiện tại — tìm docs lạc hậu
-
-### Bước 2 — Generate project documentation
-- Dùng skill `bmad-document-project` để sinh/cập nhật project docs
-- Output: mô tả architecture, module breakdown, API endpoints, data flows
-- Lưu vào `docs/project/`
-
-### Bước 3 — Generate project context for AI
-- Dùng skill `bmad-generate-project-context` để tạo `project-context.md`
-- File này = instructions cho AI agents: conventions, patterns, do/don't
-- Lưu tại root project
-
-### Bước 4 — Tech writing review
-- Dùng skill `bmad-agent-tech-writer` (Paige) để review docs vừa sinh
-- Paige sẽ: fix unclear sections, add missing context, ensure consistency
-
-### Bước 5 — Editorial polish
-- Dùng skill `bmad-editorial-review-prose` — clean up writing quality
+`$ARGUMENTS` — scope to document:
+- *(no argument)* — full documentation refresh
+- `<module>` — document a specific module
+- `context` — only generate project-context.md
+
+## When to use
+- After each sprint (batch update)
+- After shipping a large feature (>3 modules changed)
+- When onboarding a new team member
+- When an AI agent struggles to understand the codebase
+
+## Steps
+
+### Step 1 — Scan current state
+- Use `mcp__gitnexus__query` to scan the current codebase
+- Compare: current docs vs current code — find outdated docs
+
+### Step 2 — Generate project documentation
+- Use skill `bmad-document-project` to generate/update project docs
+- Output: architecture description, module breakdown, API endpoints, data flows
+- Save to `docs/project/`
+
+### Step 3 — Generate project context for AI
+- Use skill `bmad-generate-project-context` to create `project-context.md`
+- This file = instructions for AI agents: conventions, patterns, do/don't
+- Save at project root
+
+### Step 4 — Tech writing review
+- Use skill `bmad-agent-tech-writer` (Paige) to review the generated docs
+- Paige will: fix unclear sections, add missing context, ensure consistency
+
+### Step 5 — Editorial polish
+- Use skill `bmad-editorial-review-prose` — clean up writing quality
   - Fix: passive voice, jargon, ambiguity, grammar
-- Dùng skill `bmad-editorial-review-structure` — improve doc organization
+- Use skill `bmad-editorial-review-structure` — improve doc organization
   - Fix: duplicated content, poor ordering, missing sections
 
-### Bước 6 — Distill for LLM consumption
-- Dùng skill `bmad-distillator` với docs dài (>500 lines)
-- Tạo phiên bản compressed — giữ nguyên thông tin, giảm token count
-- Lưu distilled version cạnh original: `[name].distilled.md`
+### Step 6 — Distill for LLM consumption
+- Use skill `bmad-distillator` for long docs (>500 lines)
+- Create a compressed version — preserve all information, reduce token count
+- Save distilled version alongside original: `[name].distilled.md`
 
-### Bước 7 — Index all docs
-- Dùng skill `bmad-index-docs` cho mỗi folder trong `docs/`
-- Sinh/cập nhật `index.md` — mục lục tất cả files + mô tả ngắn
+### Step 7 — Index all docs
+- Use skill `bmad-index-docs` for each folder in `docs/`
+- Generate/update `index.md` — table of contents of all files + short descriptions
 
-### Bước 8 — Output cho user
+### Step 8 — Output to user
 ```
 ## Documentation Sync Complete
 
@@ -74,8 +74,8 @@ description: Documentation & knowledge sync — cập nhật docs, sinh project
 Documentation is current. Continue with /vsaf-plan or /vsaf-sprint.
 ```
 
-## Lưu ý
-- Flow này **không sửa code** — chỉ documentation
-- Chạy ít nhất 1 lần mỗi sprint hoặc sau mỗi major ship
-- Commit tất cả docs: `git commit -m "docs: sync documentation [sprint N]"`
-- Nếu docs >1000 lines: luôn tạo distilled version
+## Notes
+- This flow **does not modify code** — documentation only
+- Run at least once per sprint or after each major ship
+- Commit all docs: `git commit -m "docs: sync documentation [sprint N]"`
+- If docs >1000 lines: always create a distilled version

package/.claude/skills/vsaf-onboard/SKILL.md

@@ -1,46 +1,81 @@
 ---
 name: vsaf-onboard
-description: Hiểu toàn bộ context dự án mới. Dùng khi lần đầu tiếp nhận project, cần nắm kiến trúc, decisions cũ, và codebase trước khi làm bất cứ điều gì.
+description: Understand the full context of a new project. Use when first onboarding to a project, needing to grasp the architecture, past decisions, and codebase before doing anything.
 ---
 
 # VSAF Onboard
 
-## Mục tiêu
-Xây dựng full mental model về dự án trước khi chạm vào bất kỳ code nào.
+## Objective
+Build a full mental model of the project before touching any code.
 
-## Các bước thực hiện
+## Steps
 
-### Bước 1 — Code intelligence (GitNexus)
-- Dùng `mcp__gitnexus__query` với query rộng (ví dụ: "main entry point", "core module") để lấy codebase overview
-- Dùng `mcp__gitnexus__group_list` để xem các functional clusters
-- Nếu cần drill-down symbol cụ thể: dùng `mcp__gitnexus__context` với param `name` là tên symbol đó
-- Tóm tắt: execution flows quan trọng, symbols có nhiều dependencies nhất
+### Step 1 — Codebase overview (GitNexus resource)
+- Read `gitnexus://repo/{name}/context` — get codebase overview:
+  - Size, index freshness, health metrics
+  - Overview of symbols, relationships
 
-### Bước 2 — Đọc tài liệu dự án
-- Đọc `docs/project/planning-artifacts/` để tìm PRD, ADR, architecture docs
-- Đọc `docs/project/srs/` để tìm SRS đã có
-- Tóm tắt: các quyết định kiến trúc quan trọng đã document
+### Step 2 — Functional areas (GitNexus resource)
+- Read `gitnexus://repo/{name}/clusters` — functional areas + cohesion scores
+- Understand what functional groups the codebase is divided into
 
-### Bước 3 — Output cho user
-Trình bày tóm tắt theo format:
+### Step 3 — Execution flows (GitNexus resource)
+- Read `gitnexus://repo/{name}/processes` — all execution flows in the codebase
+- Understand how data flows through the system
+
+### Step 4 — Module groupings (GitNexus tools)
+- Use `gitnexus_group_list` to view module groups
+- Use `gitnexus_group_query` to view inter-module relationships
+- Understand which modules depend on which
+
+### Step 5 — API surface (GitNexus, for API projects)
+- Use `gitnexus_route_map` to map all API routes → handlers
+- Skip if the project is not an API/web service
+
+### Step 6 — Deep-dive key symbols (GitNexus)
+- Use `gitnexus_context` on 3-5 key symbols (main entry points, core services)
+- Get a 360° view: callers, callees, process participation
+- Identify: hot symbols (many callers), risk areas (high fan-out)
+
+### Step 7 — Read project documentation + synthesize
+- Read `docs/project/planning-artifacts/` to find PRDs, ADRs, architecture docs
+- Read `docs/project/srs/` to find existing SRS documents
+- Synthesize all findings into a project overview
+
+### Step 8 — Output to user
+Present the summary in this format:
 
 ```
 ## Project Overview
-[Mô tả ngắn về dự án]
+[Brief description of the project]
+
+## Codebase Health
+- Symbols: [N] | Relationships: [N] | Execution flows: [N]
+- Index freshness: [fresh / stale — last indexed: date]
+
+## Architecture
+[Main layers/modules and their relationships — from clusters + groups]
+
+## Key Execution Flows
+[Top 5-10 most important flows — from processes]
+
+## API Surface
+[Routes overview — from route_map, or "N/A" if not an API project]
 
-## Kiến trúc
-[Các layer/module chính và quan hệ]
+## Hot Symbols
+[3-5 symbols with the most callers/dependencies — from context deep-dive]
 
-## Patterns đang dùng
+## Patterns in Use
 [Tech stack, design patterns, conventions]
 
-## Decisions quan trọng
-[Những gì team đã quyết định và lý do]
+## Key Decisions
+[What the team has decided and why — from docs]
 
-## Cần chú ý
+## Areas of Concern
 [Risk areas, legacy code, known issues]
 ```
 
-## Lưu ý
-- KHÔNG sửa bất kỳ file nào trong bước này
-- Sau khi hoàn thành: gợi ý user dùng `/vsaf-plan <feature>` để bắt đầu task
+## Notes
+- Do NOT modify any files during this step
+- If GitNexus index is stale: run `vsaf index` before onboarding
+- After completion: suggest the user run `/vsaf-plan <feature>` to begin a task