@ngocsangairvds/vsaf 3.0.11 → 3.1.0

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

@@ -1,6 +1,6 @@
 ---
 name: vsaf-build
-description: Implement code theo SRS + testcase đã có. Dùng sau /vsaf-doc và /vsaf-test. Tự động search MemPalace trước khi code.
+description: Implement code theo SRS + testcase đã có. Dùng sau /vsaf-doc-srs và /vsaf-test.
 ---
 
 # VSAF Build
@@ -9,32 +9,66 @@ description: Implement code theo SRS + testcase đã có. Dùng sau /vsaf-doc v
 Implement code đúng theo SRS và testcase, từng task một, với TDD — đảm bảo mỗi commit có tests pass.
 
 ## Điều kiện tiên quyết
-- Đã chạy `/vsaf-doc` và có SRS được approve
-- Đã chạy `/vsaf-test` và có testcase docs
+- Đã chạy `/vsaf-doc-srs` và có SRS được approve
+- Đã chạy `/vsaf-test` và có testcase docs (implementation readiness = PASS)
 - User đã xác nhận phạm vi implement
 
 ## Các bước thực hiện
 
-### Bước 1 — Search MemPalace trước khi code (bắt buộc)
-- Gọi `mcp__mempalace__mempalace_search` với keyword là tên module/feature sắp implement
-- Đảm bảo không có architectural decisions cũ xung đột với approach hiện tại
+### Bước 0 — Kiểm tra Superpowers (bắt buộc kiểm tra)
+- Kiểm tra xem Superpowers plugin đã được cài trong Claude Code chưa
+- Nếu **chưa cài** → hiển thị:
+  ```
+  ⚠️  Superpowers chưa được cài đặt.
+  Superpowers giúp tăng chất lượng implement (TDD execution, plan execution, debugging, code review).
+  Để cài, chạy trong Claude Code:
+    /plugin install superpowers@claude-plugins-official
+  Sau đó restart Claude Code.
 
-### Bước 2 — Đọc SRS + testcase
+  → Tiếp tục build không có Superpowers (fallback mode).
+  ```
+- Nếu **đã cài** → ghi nhận `HAS_SUPERPOWERS = true`, hiển thị:
+  ```
+  ✓ Superpowers available — sẽ sử dụng: execute-plan, test-driven-development, code-review
+  ```
+
+### Bước 1 — Đọc SRS + testcase
 - Đọc file SRS trong `docs/project/srs/`
 - Đọc file testcase trong `docs/project/testcases/`
 - Xác nhận mapping FR/NFR -> testcase trước khi bắt đầu
 
+### Bước 2 — Sinh plan từ SRS (có/không Superpowers)
+- **Nếu HAS_SUPERPOWERS**: dùng `superpowers:write-plan` để sinh atomic task list từ SRS + testcase
+- **Nếu không**: tự tạo task list thủ công từ FR/NFR → testcase mapping
+- Mỗi task phải có verification step rõ ràng
+
 ### Bước 3 — Implement từng task (TDD)
-Với mỗi nhóm testcase:
-1. **RED**: Viết test trước, chạy test → phải fail
-2. **GREEN**: Viết code tối thiểu để test pass
-3. **REFACTOR**: Clean up code, giữ test vẫn pass
-4. Chạy `mcp__gitnexus__detect_changes` để verify chỉ đúng files thay đổi
-5. Commit: `git commit -m "<type>: <task description>"`
-
-### Bước 4 — Xử lý khi fail
-- Fail 1-2 lần: thử approach khác
+- **Nếu HAS_SUPERPOWERS**: dùng `superpowers:execute-plan` — tự động chạy TDD cycles (RED → GREEN → REFACTOR) theo plan
+  - Superpowers sẽ gọi `superpowers:test-driven-development` cho mỗi task
+  - Nếu plan lớn (20+ tasks): dùng `superpowers:subagent-driven-development` để dispatch song song
+- **Nếu không**: implement thủ công theo TDD:
+  1. **RED**: Viết test trước, chạy test → phải fail
+  2. **GREEN**: Viết code tối thiểu để test pass
+  3. **REFACTOR**: Clean up code, giữ test vẫn pass
+- Sau mỗi task: chạy `mcp__gitnexus__detect_changes` để verify chỉ đúng files thay đổi
+- Commit: `git commit -m "<type>: <task description>"`
+
+### Bước 3.5 — Checkpoint review (mỗi 3-5 tasks)
+- Sau mỗi 3-5 tasks hoàn thành: dùng skill `bmad-checkpoint-preview`
+- Mục đích: human-in-the-loop review — "walk me through changes so far"
+- Checkpoint sẽ:
+  - Tóm tắt: đã làm gì, files nào thay đổi, tests status
+  - Highlight: điểm cần chú ý, potential issues
+  - Hỏi user: tiếp tục / điều chỉnh / dừng?
+- **Bỏ qua checkpoint nếu**: plan < 5 tasks tổng (chỉ checkpoint cuối)
+
+### Bước 4 — Xử lý khi fail hoặc scope drift
+- **Nếu HAS_SUPERPOWERS**: dùng `superpowers:systematic-debugging` — bắt buộc hypothesis → experiment → conclusion
+- **Nếu không**: thử approach khác thủ công
 - Fail 3 lần cùng 1 task: DỪNG, báo user, quay lại `/vsaf-plan`
+- **Nếu phát hiện scope drift** (feature cần thay đổi lớn so với SRS):
+  - Dùng skill `bmad-correct-course` để đánh giá impact + đề xuất điều chỉnh
+  - DỪNG và trình bày cho user: tiếp tục với điều chỉnh / quay lại `/vsaf-plan` re-plan
 
 ### Bước 5 — Output sau mỗi task
 ```
@@ -42,6 +76,8 @@ Với mỗi nhóm testcase:
   - Files changed: [danh sách]
   - Tests: [X passed]
   - Commit: [hash]
+  - Superpowers: [used/not available]
+  - Checkpoint: [due at task N+X / completed]
 ```
 
 ## Lưu ý

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

@@ -0,0 +1,92 @@
+---
+name: vsaf-discover
+description: Product discovery — nghiên cứu domain, market, feasibility trước khi plan feature. Dùng khi bắt đầu dự án mới hoặc explore hướng phát triển sản phẩm.
+---
+
+# VSAF Discover
+
+## Mục tiêu
+Hiểu rõ domain, market, user needs, và technical feasibility trước khi commit vào bất kỳ feature nào. Đảm bảo build đúng thứ.
+
+## Input
+`$ARGUMENTS` — mô tả product/domain cần khám phá (ví dụ: "nền tảng quản lý đơn hàng cho SME")
+
+## Khi nào dùng
+- Bắt đầu dự án mới (chưa có PRD/SRS)
+- Explore hướng phát triển sản phẩm mới
+- Trước khi chạy `/vsaf-plan` cho feature lớn mà chưa hiểu rõ domain
+
+## Các bước thực hiện
+
+### Bước 1 — Domain Research
+- Dùng skill `bmad-domain-research` để deep dive domain/industry
+- Output: terminology, business rules, regulatory constraints, domain patterns
+- Lưu vào `docs/project/planning-artifacts/domain-research-[topic].md`
+
+### Bước 2 — Market Research
+- Dùng skill `bmad-market-research` để phân tích:
+  - Competition landscape: ai đang làm gì, strengths/weaknesses
+  - Customer needs: pain points, underserved segments
+  - Market trends: hướng đi nào đang tăng trưởng
+- Lưu vào `docs/project/planning-artifacts/market-research-[topic].md`
+
+### Bước 3 — Technical Feasibility
+- Dùng skill `bmad-technical-research` để đánh giá:
+  - Tech stack options + trade-offs
+  - Integration constraints
+  - Performance/scale requirements
+  - Build vs buy decisions
+- Lưu vào `docs/project/planning-artifacts/tech-research-[topic].md`
+
+### Bước 4 — Product Brief
+- Dùng skill `bmad-product-brief` để tổng hợp findings thành product brief
+- Product brief = bản tóm tắt: vấn đề gì, cho ai, giải pháp gì, tại sao bây giờ
+- Lưu vào `docs/project/planning-artifacts/product-brief-[name].md`
+
+### Bước 5 — PRFAQ Challenge (Working Backwards)
+- Dùng skill `bmad-prfaq` để stress-test product concept
+- Viết press release giả lập: nếu product thành công, bài báo sẽ nói gì?
+- Viết FAQ: internal FAQ (team hỏi gì) + external FAQ (customer hỏi gì)
+- Mục đích: phát hiện concept yếu **trước khi** đầu tư thời gian code
+
+### Bước 6 — Tạo PRD (Product Requirements Document)
+- Dùng skill `bmad-agent-pm` (John) để dẫn dắt quá trình tạo PRD
+- John sẽ gọi skill `bmad-create-prd` để sinh PRD chuẩn từ product brief
+- PRD bao gồm: vision, goals, FRs, NFRs, epics, user stories, success metrics
+- Sau khi tạo xong: dùng skill `bmad-validate-prd` để validate PRD đạt chuẩn
+- Nếu validate FAIL: John sẽ dùng `bmad-edit-prd` để fix issues ngay
+- Lưu vào `docs/project/planning-artifacts/prd-[name].md`
+
+### Bước 7 — Multi-agent Review (Party Mode)
+- Dùng skill `bmad-party-mode` để tổ chức roundtable:
+  - PM (John) trình bày PRD
+  - Analyst (Mary) challenge requirements
+  - Architect (Winston) challenge feasibility
+- Ghi nhận consensus và open questions
+
+### Bước 8 — Output cho user
+```
+## Discovery Complete: [product/domain]
+
+### Research artifacts
+- Domain research:  docs/project/planning-artifacts/domain-research-[topic].md
+- Market research:  docs/project/planning-artifacts/market-research-[topic].md
+- Tech research:    docs/project/planning-artifacts/tech-research-[topic].md
+- Product brief:    docs/project/planning-artifacts/product-brief-[name].md
+- PRD:              docs/project/planning-artifacts/prd-[name].md
+
+### Key findings
+- [3-5 bullet points tóm tắt]
+
+### Open questions
+- [Những gì cần validate thêm]
+
+### Recommended next steps
+- Chạy /vsaf-sprint để break PRD thành epics + stories
+- Hoặc: chạy /vsaf-plan <first-feature> để bắt đầu feature đầu tiên
+```
+
+## Lưu ý
+- Flow này **không sinh code** — chỉ research + document
+- Nếu domain quá rộng: đề nghị focus vào 1 vertical/segment trước
+- Commit docs sau mỗi bước: `git commit -m "docs: discovery [topic]"`

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

@@ -1,53 +1,22 @@
 ---
 name: vsaf-doc
-description: Viết tài liệu plan cho feature đã được phân tích. Dùng sau /vsaf-plan, khi đã có scope và approach rõ ràng, cần chuyển thành tài liệu có cấu trúc với task list atomic.
+description: DEPRECATED — Đã được tách thành 2 lệnh riêng. Dùng /vsaf-doc-prd để viết PRD, sau đó /vsaf-doc-srs để viết SRS.
 ---
 
-# VSAF Doc
+# VSAF Doc — DEPRECATED
 
-## Mục tiêu
-Chuyển kết quả plan thành tài liệu chính thức: SRS có traceability rõ ràng để làm testcase và implementation.
+Skill này đã được tách thành 2 lệnh riêng biệt:
 
-## Điều kiện tiên quyết
-Phải đã chạy `/vsaf-plan` và có output trước khi chạy skill này.
+1. `/vsaf-doc-prd` — Viết PRD (Product Requirements Document) từ kết quả `/vsaf-plan`
+2. `/vsaf-doc-srs` — Viết SRS (Software Requirements Specification) từ PRD đã có
 
-## Các bước thực hiện
-
-### Bước 1 — Search MemPalace
-- Gọi `mcp__mempalace__mempalace_search` với keyword từ feature hiện tại
-- Kiểm tra có decision cũ nào cần reference không?
-
-### Bước 2 — Sinh SRS
-- Viết tài liệu SRS từ output `/vsaf-plan`
-- SRS phải bao gồm: scope, FRs, NFRs, assumptions, out-of-scope, acceptance criteria
-- Thêm traceability ID cho FR/NFR để map sang testcase
-- Lưu vào `docs/project/srs/[feature].md`
-
-### Bước 3 — Chuẩn hoá implement notes
-- Tạo implement notes bám SRS: module ảnh hưởng, ràng buộc kỹ thuật, rollout notes
-- Không viết code trong bước này
-
-### Bước 4 — Lưu architecture decision (MemPalace)
-- Gọi `mcp__mempalace__mempalace_add_drawer` để lưu decision quan trọng
-- Nội dung: approach được chọn, lý do, alternatives đã bỏ qua
-
-### Bước 5 — Output cho user
-Thông báo các file đã tạo:
+## Quy trình mới
 
 ```
-## Tài liệu đã tạo
-
-### SRS
-- docs/project/srs/[feature].md
-
-### Architecture Decision
-- Đã lưu vào MemPalace
-
-## Next step
-Chạy /vsaf-test docs/project/srs/[feature].md để sinh testcase
+/vsaf-plan <requirement>    # scope + impact + approach
+/vsaf-doc-prd              # viết PRD từ approved scope
+/vsaf-doc-srs              # viết SRS từ PRD
+/vsaf-test <path/to/srs>   # sinh testcase từ SRS
 ```
 
-## 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
-- Commit docs trước khi chuyển sang build: `git commit -m "docs: plan for <feature>"`
+Vui lòng dùng `/vsaf-doc-prd` hoặc `/vsaf-doc-srs` thay cho skill này.

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

@@ -0,0 +1,57 @@
+---
+name: vsaf-doc-prd
+description: Viết tài liệu PRD (Product Requirements Document) từ kết quả /vsaf-plan. Dùng sau /vsaf-plan khi đã có scope và approach rõ ràng.
+---
+
+# VSAF Doc PRD
+
+## Mục tiêu
+Chuyển kết quả plan thành PRD chính thức: vision, goals, FRs, NFRs, epics, user stories, success metrics.
+
+## Điều kiện tiên quyết
+Phải đã chạy `/vsaf-plan` và có output trước khi chạy skill này.
+
+## Các bước thực hiện
+
+### Bước 0 — Xác định mode: Tạo mới hay Chỉnh sửa
+- Kiểm tra xem đã có PRD trong `docs/project/planning-artifacts/` cho feature này chưa
+- **Nếu chưa có** → Mode: CREATE (tạo mới từ đầu)
+- **Nếu đã có** → Mode: EDIT (chỉnh sửa dựa trên feedback/changes)
+  - Hỏi user: "PRD đã tồn tại. Bạn muốn tạo mới hoàn toàn hay chỉnh sửa?"
+
+### Bước 1 — Sinh hoặc Chỉnh sửa PRD
+
+#### Mode CREATE:
+- Dùng skill `bmad-agent-pm` (John) để dẫn dắt quá trình tạo PRD từ output `/vsaf-plan`
+- John sẽ gọi skill `bmad-create-prd` để sinh PRD chuẩn
+- PRD phải bao gồm: vision, goals, FRs, NFRs, epics, user stories, success metrics, scope, out-of-scope, assumptions
+- Lưu vào `docs/project/planning-artifacts/prd-[feature].md`
+
+#### Mode EDIT:
+- Dùng skill `bmad-edit-prd` để chỉnh sửa PRD đã có
+- Giữ nguyên structure và IDs đã có — chỉ thêm/sửa/xoá sections cần thiết
+- Nếu thay đổi lớn: cảnh báo user rằng SRS và testcases cần re-run
+
+### Bước 2 — Validate PRD (BMAD validate)
+- Dùng skill `bmad-validate-prd` để validate PRD 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 PRD, không chờ đến build
+- Ghi nhận validation result (PASS/FAIL + findings)
+
+### Bước 3 — Output cho user
+```
+## PRD đã tạo/cập nhật
+
+### File
+- docs/project/planning-artifacts/prd-[feature].md
+- Mode: [CREATE / EDIT]
+- Validation: [PASS / FAIL — chi tiết nếu fail]
+
+## Next step
+Chạy /vsaf-doc-srs để viết tài liệu SRS từ PRD này
+```
+
+## 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
+- Commit docs trước khi chuyển sang SRS: `git commit -m "docs: prd for <feature>"`

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

@@ -0,0 +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.
+---
+
+# 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.
+
+**Your Role:** Business Analyst chuyên nghiệp — viết SRS theo quy trình chuẩn.
+
+## Đ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.
+
+## Cấu hình
+```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
+
+### Bước 0 — Kiểm tra đầu vào
+
+Trước khi bắt đầu, kiểm tra xem user đã cung cấp đủ thông tin chưa:
+
+**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ó
+
+Nếu thiếu PRD, **dừng lại ngay** và yêu cầu user cung cấp:
+
+```
+Để viết tài liệu SRS, tôi cần bạn cung cấp:
+
+❌ [liệt kê những gì còn thiếu]
+
+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,...)
+```
+
+Chỉ tiếp tục khi đã có đủ PRD.
+
+---
+
+### 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ó
+
+---
+
+### Bước 2 — Đọc & phân tích 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:
+
+**2.1 Mục tiêu dự án**
+- 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.3 Actors & Use Cases**
+- Danh sách các actor (vai trò người dùng), User stories / use cases đã đề cập
+
+**2.4 Business Rules**
+- Quy tắc nghiệp vụ quan trọng, Constraints & assumptions
+
+**2.5 Non-functional Requirements**
+- Performance, security, scalability, v.v. (nếu có)
+
+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.
+
+---
+
+### Bước 3 — So sánh PRD với Figma (nếu có Figma)
+
+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
+
+So sánh và ghi nhận:
+
+| Hạng mục | PRD nói | Figma thiết kế | Trạng thái |
+|---|---|---|---|
+| [Feature/Screen] | ... | ... | ✅ Khớp / ⚠️ Khác biệt / ❓ Chưa rõ |
+
+**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
+
+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.
+
+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.
+
+---
+
+### Bước 4 — Viết tài liệu SRS theo 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):
+
+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
+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
+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
+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
+
+**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
+
+---
+
+### 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)
+
+---
+
+### 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`
+
+### Bước 7 — Output cho user
+```
+## SRS đã tạo/cập nhật
+
+### File
+- docs/project/srs/SRS-[tên-dự-án]-[FR-ID]-[tên-feature]-v1.0.md
+- Mode: [CREATE / EDIT]
+- Use Cases viết: [N]
+- Validation: [PASS / FAIL — chi tiết nếu fail]
+
+### Gaps cần confirm
+- [Danh sách gaps quan trọng cần team confirm]
+
+### Phần chưa hoàn thiện
+- [Các phần SRS còn {{...}} cần bổ sung thêm]
+
+## Next step
+Chạy /vsaf-test docs/project/srs/SRS-[...].md để sinh testcase
+```
+
+## 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
+- 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`

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

@@ -0,0 +1,81 @@
+---
+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.
+---
+
+# VSAF Docs
+
+## Mục tiêu
+Đảm bảo documentation luôn cập nhật và AI agents có đủ 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
+  - Fix: passive voice, jargon, ambiguity, grammar
+- Dùng 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`
+
+### 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
+
+### Bước 8 — Output cho user
+```
+## Documentation Sync Complete
+
+### Updated
+- Project docs:      [N files updated]
+- Project context:   project-context.md [created/updated]
+- Distilled docs:    [N files compressed]
+- Doc indexes:       [N index.md files]
+
+### Quality checks
+- Prose review:      PASS
+- Structure review:  PASS
+- Stale docs found:  [N — list]
+
+### Next step
+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

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

@@ -16,11 +16,10 @@ Xây dựng full mental model về dự án trước khi chạm vào bất kỳ
 - 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
 
-### Bước 2 — Decisions cũ (MemPalace)
-- Gọi `mcp__mempalace__mempalace_search` với query "architecture"
-- Gọi `mcp__mempalace__mempalace_search` với query "decision"
-- Gọi `mcp__mempalace__mempalace_search` với query "pattern"
-- Tóm tắt: các quyết định kiến trúc quan trọng team đã đưa ra
+### 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
 
 ### Bước 3 — Output cho user
 Trình bày tóm tắt theo format:
@@ -44,5 +43,4 @@ Trình bày tóm tắt theo format:
 
 ## Lưu ý
 - KHÔNG sửa bất kỳ file nào trong bước này
-- Nếu bộ nhớ MemPalace trống: thông báo user chạy `vsaf mine` để populate
 - Sau khi hoàn thành: gợi ý user dùng `/vsaf-plan <feature>` để bắt đầu task

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

@@ -13,38 +13,37 @@ Hiểu đầy đủ yêu cầu, phân tích impact, và xác định chiến lư
 
 ## Các bước thực hiện
 
-### Bước 1 — Search MemPalace (bắt buộc)
-- Gọi `mcp__mempalace__mempalace_search` với keyword từ `$ARGUMENTS`
-- Tìm kiếm: past decisions, architectural patterns, previous attempts
-- Tóm tắt: có decision nào liên quan không?
-
-### Bước 2 — Clarify scope (BMAD analyst)
+### Bước 1 — Clarify scope (BMAD analyst)
 - Dùng skill `bmad-agent-analyst` để phân tích yêu cầu
 - Xác định: FRs, NFRs, edge cases, assumptions, out-of-scope
 - DỪNG và hỏi user nếu còn điểm chưa rõ
 
-### Bước 3 — Impact analysis (GitNexus)
+### Bước 2 — Impact analysis (GitNexus)
 - Dùng `mcp__gitnexus__impact` với target là module/symbol liên quan
 - Dùng `mcp__gitnexus__query` để tìm code liên quan
 - Báo cáo blast radius: bao nhiêu module bị ảnh hưởng, risk level
 - Nếu risk HIGH/CRITICAL: DỪNG, báo user trước khi tiếp tục
 
-### Bước 4 — Trace dependencies (Graphify)
-- Nếu cần trace path giữa 2 services: dùng `/graphify path ServiceA ServiceB`
-- Xác định: integration points, shared dependencies
-
-### Bước 5 — Architecture decision (BMAD architect)
+### Bước 3 — Architecture decision (BMAD architect)
 - Dùng skill `bmad-agent-architect` để đề xuất architecture approach
 - So sánh alternatives, chọn approach phù hợp nhất
+- **Nếu risk HIGH hoặc > 3 modules**: dùng skill `bmad-create-architecture` để tạo ADR (Architecture Decision Record) chính thức
+  - Lưu vào `docs/project/planning-artifacts/adr-[feature].md`
 
-### Bước 6 — Brainstorm (BMAD Brainstorming)
+### Bước 4 — Brainstorm (BMAD Brainstorming)
 - Dùng skill `bmad-brainstorming` để explore alternatives và uncover hidden risks
 - Facilitator sẽ dẫn dắt session với các kỹ thuật sáng tạo đa dạng
 - Đặt câu hỏi: "What if...", "What could go wrong...", "What are we missing?"
 - Mục tiêu: tối thiểu 20 ý tưởng/alternatives trước khi tổ chức lại
 - bmad-brainstorming sẽ load config từ `_bmad/bmm/config.yaml`
 
-### Bước 7 — Output cho user
+### Bước 5 — Challenge approach (BMAD Advanced Elicitation)
+- Dùng skill `bmad-advanced-elicitation` để challenge approach đã chọn
+- Chạy **pre-mortem**: "Giả sử approach này fail sau 3 tháng — vì sao?"
+- Chạy **red team**: tìm điểm yếu, attack vectors, failure modes
+- Nếu phát hiện risk nghiêm trọng: quay lại Bước 3 để điều chỉnh approach
+
+### Bước 6 — Output cho user
 Trình bày kết quả theo format:
 
 ```
@@ -62,11 +61,17 @@ Trình bày kết quả theo format:
 ## Approach được chọn
 [Mô tả architecture approach]
 
+## Pre-mortem findings
+[Những risk đã identify và mitigation plan]
+
 ## Alternatives đã xem xét
 [Tại sao không chọn]
 
+## ADR
+[Đã tạo / Không cần (risk LOW)]
+
 ## Next step
-Chạy /vsaf-doc để viết tài liệu plan
+Chạy /vsaf-doc-prd để viết tài liệu PRD
 ```
 
 ## Lưu ý