@ngocsangairvds/vsaf 3.0.11 → 3.0.12

package/.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -22,7 +22,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
 
-**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. Re-run `npx gitnexus analyze` manually after commits/merges when needed.
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
 
 ### status — Check index freshness
 

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

@@ -10,11 +10,28 @@ Implement code đúng theo SRS và testcase, từng task một, với TDD — đ
 
 ## Đ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-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 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.
+
+  → 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 — 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
@@ -24,24 +41,47 @@ Implement code đúng theo SRS và testcase, từng task một, với TDD — đ
 - Đọc file testcase trong `docs/project/testcases/`
 - Xác nhận mapping FR/NFR -> testcase trước khi bắt đầu
 
-### 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 3 — 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 4 — Implement từng task (TDD)
+- **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 4.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
-- Fail 1-2 lần: thử approach khác
+### Bước 5 — 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
+### Bước 6 — Output sau mỗi task
 ```
 ✓ Task [N]: [tên task]
   - 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,104 @@
+---
+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 — Search MemPalace
+- Gọi `mcp__mempalace__mempalace_search` với keyword từ `$ARGUMENTS`
+- Kiểm tra: đã có research cũ nào liên quan chưa?
+- Nếu có: tóm tắt findings cũ, tránh lặp lại
+
+### Bước 2 — 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 3 — 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 4 — 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 5 — 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 6 — 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 7 — 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 8 — 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 9 — Lưu insights vào MemPalace
+- Gọi `mcp__mempalace__mempalace_add_drawer` để lưu:
+  - Market insights
+  - Domain knowledge
+  - Product decisions + rationale
+  - Open questions chưa trả lời
+
+### Bước 10 — 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

@@ -13,41 +13,67 @@ 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ó SRS/PRD trong `docs/project/srs/` 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: "SRS đã tồn tại. Bạn muốn tạo mới hoàn toàn hay chỉnh sửa?"
+
 ### 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
+### Bước 2 — Sinh hoặc Chỉnh sửa SRS
+
+#### Mode CREATE:
 - 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
+- Nếu user muốn format PRD chuẩn: dùng skill `bmad-create-prd` để sinh PRD đầy đủ
+- SRS/PRD 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
+#### Mode EDIT:
+- Dùng skill `bmad-edit-prd` để chỉnh sửa SRS/PRD đã có
+- bmad-edit-prd sẽ: đọc SRS hiện tại, nhận changes từ user/plan, update in-place
+- Giữ nguyên traceability IDs đã có — chỉ thêm/sửa/xoá sections cần thiết
+- Đảm bảo: changes không break consistency với testcases đã sinh (nếu có)
+- Nếu thay đổi lớn: cảnh báo user rằng testcases cần re-run `/vsaf-test`
+
+### Bước 3 — 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
+- Nếu mode EDIT và validate FAIL: dùng `bmad-edit-prd` lần nữa để fix
+- Ghi nhận validation result (PASS/FAIL + findings)
+
+### Bước 4 — 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)
+### Bước 5 — 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:
-
+### Bước 6 — Output cho user
 ```
-## Tài liệu đã tạo
+## Tài liệu đã tạo/cập nhật
 
 ### SRS
 - docs/project/srs/[feature].md
+- Mode: [CREATE / EDIT]
+- Validation: [PASS / FAIL — chi tiết nếu fail]
+- Testcases impact: [None / Need re-run /vsaf-test]
 
 ### Architecture Decision
 - Đã lưu vào MemPalace
 
 ## Next step
 Chạy /vsaf-test docs/project/srs/[feature].md để sinh testcase
+[Nếu EDIT và testcases cũ bị ảnh hưởng]: Re-run /vsaf-test bắt buộc
 ```
 
 ## 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>"`
+- Khi edit PRD: luôn check impact lên testcases đã sinh

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

@@ -0,0 +1,99 @@
+---
+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, AI agents có đủ context, và knowledge không bị mất giữa các session/sprint.
+
+## Input
+`$ARGUMENTS` — scope cần document:
+- *(không có argument)* — full documentation refresh
+- `<module>` — document module cụ thể
+- `context` — chỉ sinh project-context.md
+- `wiki` — chỉ build wiki
+
+## 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
+- Dùng `mcp__mempalace__mempalace_search` với "decision", "architecture", "pattern"
+- 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 — Build knowledge graph wiki
+- Chạy `/graphify . --wiki` để build agent-crawlable wiki từ codebase
+- Output: `graphify-out/` — index.md + article per community
+- Wiki này giúp AI agents navigate codebase nhanh hơn
+
+### Bước 9 — Sync to MemPalace
+- Gọi `mcp__mempalace__mempalace_diary_write` ghi nhận:
+  - Docs nào đã cập nhật
+  - Stale docs nào đã xoá/replace
+  - New patterns/conventions đã document
+
+### Bước 10 — 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]
+- Knowledge wiki:    graphify-out/ [rebuilt]
+
+### Quality checks
+- Prose review:      PASS
+- Structure review:  PASS
+- Stale docs found:  [N — list]
+
+### Knowledge saved
+- MemPalace diary:   ✓
+
+### 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-plan/SKILL.md

@@ -36,6 +36,8 @@ Hiểu đầy đủ yêu cầu, phân tích impact, và xác định chiến lư
 ### Bước 5 — 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)
 - Dùng skill `bmad-brainstorming` để explore alternatives và uncover hidden risks
@@ -44,7 +46,13 @@ Hiểu đầy đủ yêu cầu, phân tích impact, và xác định chiến lư
 - 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 7 — 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 5 để điều chỉnh approach
+
+### Bước 8 — Output cho user
 Trình bày kết quả theo format:
 
 ```
@@ -62,9 +70,15 @@ 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
 ```

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

@@ -14,47 +14,78 @@ description: Review 2 lớp, ship code, và ghi lại knowledge vào bộ nhớ.
 
 ## Các bước thực hiện
 
-### Bước 1 — Review Layer 1: Methodology (Superpowers)
-- Dùng skill `superpowers:code-review`
+### Bước 1 — Review Layer 1: Code Review
+- **Nếu có Superpowers**:
+  - Dùng `superpowers:code-review` — review code against plan, standards, architecture
+  - Dùng `superpowers:verification-before-completion` — đảm bảo không bỏ sót verification step
+- **Nếu không có Superpowers**: dùng skill `bmad-code-review` (đã có sẵn trong bộ cài)
 - Kiểm tra: code structure, naming, patterns, SOLID principles
 - Fix issues nếu có, commit lại
 
-### Bước 2 — Review Layer 2: Knowledge graph sync
+### Bước 2 — Review Layer 1.5: Adversarial Review
+- Dùng skill `bmad-review-adversarial-general` — cynical attack trên code mới
+  - Tìm: logic flaws, security holes, performance traps, silent failures
+- Dùng skill `bmad-review-edge-case-hunter` — exhaustive boundary analysis
+  - Tìm: unhandled null/empty, off-by-one, concurrent access, resource leaks
+- Triage findings:
+  - **MUST FIX**: fix ngay trước khi ship
+  - **SHOULD FIX**: tạo follow-up task
+  - **NOTED**: ghi nhận, không cần action
+
+### Bước 3 — Review Layer 2: Knowledge graph sync
 - Chạy `gitnexus analyze` để cập nhật call graph
 - Hoặc: `vsaf index`
 - Đây là layer cuối cùng — đảm bảo index reflect đúng code mới
 
-### Bước 3 — Ghi nhớ vào MemPalace
+### Bước 4 — Pre-PR checklist
+- **Nếu có Superpowers**: dùng `superpowers:finishing-a-development-branch` — chạy pre-PR checklist tự động
+- **Nếu không**: kiểm tra thủ công: tests pass, no uncommitted changes, branch up-to-date
+
+### Bước 5 — Ghi nhớ vào MemPalace
 - Gọi `mcp__mempalace__mempalace_add_drawer` để lưu decisions quan trọng từ feature này
 - Gọi `mcp__mempalace__mempalace_diary_write` để ghi lại session summary
+- Bao gồm: adversarial findings, lessons learned, follow-up tasks
 
-### Bước 4 — Push PR
+### Bước 6 — Push PR
 ```bash
 git push origin feature/<name>
 ```
 PR description phải bao gồm:
 - Impact summary (từ GitNexus)
 - Test results summary
+- Adversarial review summary (MUST FIX: 0, SHOULD FIX: N)
+
+### Bước 7 — Retrospective (sau mỗi epic hoặc khi user yêu cầu)
+- **Nếu đây là feature cuối cùng của epic**: dùng skill `bmad-retrospective`
+  - Review: gì đã tốt? gì cần cải thiện? surprise nào?
+  - Output: lessons learned → lưu vào MemPalace
+  - Cập nhật workflow nếu cần
+- **Nếu không phải cuối epic**: skip, nhắc user chạy retro sau khi epic hoàn thành
 
-### Bước 5 — Output cho user
+### Bước 8 — Output cho user
 ```
 ## Ship Complete: [feature]
 
 ### Reviews
-- Layer 1 (Methodology): PASS
-- Layer 2 (Graph sync):   PASS
+- Layer 1 (Code Review):       PASS [superpowers / bmad-code-review]
+- Layer 1.5 (Adversarial):     PASS [MUST FIX: 0, SHOULD FIX: N, NOTED: N]
+- Layer 2 (Graph sync):        PASS
+- Pre-PR checklist:             PASS
 
 ### Knowledge saved
 - Diary entry: ✓
 - Decisions: [X entries]
+- Follow-up tasks: [N items]
 
 ### PR
 - Branch: feature/[name]
 - PR: [link]
 
 Workflow hoàn tất. Chạy /vsaf-plan <next-feature> cho task tiếp theo.
+[Nếu cuối epic]: Retrospective đã chạy — lessons saved to MemPalace.
 ```
 
 ## Lưu ý
-- Không ship nếu bất kỳ layer review nào fail
+- Không ship nếu bất kỳ layer review nào fail hoặc còn MUST FIX
 - `vsaf mine` — chạy weekly, không phải mỗi feature
+- Retrospective: chạy sau mỗi epic (3-5 features), không phải mỗi feature

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

@@ -0,0 +1,120 @@
+---
+name: vsaf-sprint
+description: Sprint management — break PRD thành epics/stories, lập sprint plan, tracking progress. Dùng khi cần quản lý nhiều features cùng lúc.
+---
+
+# VSAF Sprint
+
+## Mục tiêu
+Quản lý backlog và sprint cho dự án — từ PRD/SRS chia thành stories, lập plan, track progress, surface risks.
+
+## Input
+`$ARGUMENTS` — hành động cần làm:
+- `plan` — lập sprint plan mới từ PRD/epics
+- `status` — xem trạng thái sprint hiện tại
+- `story <id>` — tạo story file chi tiết cho 1 story
+
+## Khi nào dùng
+- Sau `/vsaf-discover` khi đã có PRD
+- Khi dự án có nhiều features cần ưu tiên
+- Khi cần visibility vào progress tổng thể
+
+## Các bước thực hiện
+
+### Mode: `plan` — Lập sprint plan mới
+
+#### Bước 1 — Search MemPalace
+- Gọi `mcp__mempalace__mempalace_search` với "sprint", "velocity", "capacity"
+- Kiểm tra: sprint cũ có lessons learned gì? Velocity ước lượng bao nhiêu?
+
+#### Bước 2 — Break thành Epics + Stories
+- Dùng skill `bmad-create-epics-and-stories` với PRD/SRS làm input
+- Output: danh sách epics, mỗi epic chứa user stories
+- Mỗi story có: description, acceptance criteria, estimated complexity (S/M/L/XL)
+
+#### Bước 3 — Sprint Planning
+- Dùng skill `bmad-sprint-planning` để:
+  - Ưu tiên stories (MoSCoW hoặc WSJF)
+  - Assign stories vào sprint dựa trên capacity
+  - Identify dependencies giữa stories
+- Lưu sprint plan vào `docs/project/planning-artifacts/sprint-plan.md`
+
+#### Bước 4 — Lưu vào MemPalace
+- Gọi `mcp__mempalace__mempalace_add_drawer` để lưu sprint decisions
+- Nội dung: priorities, trade-offs, deferred items
+
+#### Bước 5 — Output
+```
+## Sprint Plan: [sprint name/number]
+
+### Capacity: [X story points / N stories]
+
+### Stories in sprint
+| # | Story | Epic | Size | Priority | Depends on |
+|---|-------|------|------|----------|------------|
+| 1 | ...   | ...  | M    | MUST     | -          |
+| 2 | ...   | ...  | L    | MUST     | #1         |
+
+### Deferred to next sprint
+| Story | Reason |
+|-------|--------|
+
+### Next step
+Chạy /vsaf-sprint story <id> để tạo story file chi tiết
+Hoặc: /vsaf-plan <story description> để bắt đầu feature đầu tiên
+```
+
+---
+
+### Mode: `status` — Xem trạng thái sprint
+
+#### Bước 1 — Collect status
+- Dùng skill `bmad-sprint-status` để:
+  - Scan sprint plan file
+  - Check git log cho completed stories
+  - Surface: blocked items, risks, velocity trend
+
+#### Bước 2 — Output
+```
+## Sprint Status: [sprint name]
+
+### Progress: [X/Y stories done] ([Z%])
+### Burndown: [on track / behind / ahead]
+
+### Completed
+- [x] Story #1: ...
+- [x] Story #2: ...
+
+### In Progress
+- [ ] Story #3: ... (blocked by: ...)
+
+### Risks
+- [risk description + mitigation]
+
+### Recommendation
+[Continue / adjust scope / escalate]
+```
+
+---
+
+### Mode: `story <id>` — Tạo story file chi tiết
+
+#### Bước 1 — Tạo story file
+- Dùng skill `bmad-create-story` với story ID từ sprint plan
+- Story file bao gồm: full context, acceptance criteria, technical notes, dependencies
+- Lưu vào `docs/project/planning-artifacts/stories/story-[id].md`
+
+#### Bước 2 — Output
+```
+## Story Created: [story title]
+- File: docs/project/planning-artifacts/stories/story-[id].md
+
+### Next step
+Chạy /vsaf-plan <story description> để plan implementation
+```
+
+## Lưu ý
+- Sprint plan là living document — cập nhật khi có thay đổi
+- Re-run `/vsaf-sprint status` hàng ngày hoặc sau mỗi `/vsaf-ship`
+- Nếu sprint bị delay >20%: dùng `bmad-correct-course` để điều chỉnh scope
+

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

@@ -19,16 +19,22 @@ Tạo tài liệu testcase coverage đầy đủ từ SRS để làm contract ch
 - Test cases phải cover: happy path, edge cases, error cases, NFRs
 - Nguồn gốc: từ FRs/NFRs trong SRS — KHÔNG dựa trên implementation
 
-### Bước 2 — Đối chiếu coverage
+### Bước 2 — Hunt edge cases (BMAD edge case hunter)
+- Dùng skill `bmad-review-edge-case-hunter` với SRS + testcases đã sinh
+- Tìm: boundary conditions, race conditions, empty/null inputs, overflow, concurrent access
+- Bổ sung test cases cho mọi edge case chưa cover
+- Mục tiêu: không có unhandled edge case nào lọt qua
+
+### Bước 3 — Đối chiếu coverage
 - So sánh test cases với FR/NFR trong SRS
 - Mỗi FR/NFR phải có ít nhất 1 test case tương ứng
 - Ghi nhận gaps nếu có
 
-### Bước 3 — Xuất traceability matrix
+### Bước 4 — Xuất traceability matrix
 - Tạo bảng mapping `FR/NFR -> Testcase ID`
 - Mỗi testcase có: input, expected output, pass/fail criteria
 
-### Bước 4 — Lưu tài liệu testcase
+### Bước 5 — Lưu tài liệu testcase
 - Lưu testcase vào `docs/project/testcases/[feature].md`
 - Format:
 
@@ -47,12 +53,28 @@ Tạo tài liệu testcase coverage đầy đủ từ SRS để làm contract ch
 | ...       | ...   | ...      | [ ]    |
 ```
 
-### Bước 5 — Output cho user
-- Trả về đường dẫn file testcase + coverage summary theo FR/NFR
-- Nêu rõ gaps cần bổ sung trước khi build
+### Bước 6 — Implementation readiness gate (BMAD)
+- Dùng skill `bmad-check-implementation-readiness` để validate toàn bộ artifacts
+- Kiểm tra: SRS đầy đủ? Testcases cover hết FRs/NFRs? Architecture align?
+- Nếu **PASS**: hiển thị `✓ Implementation ready — proceed to /vsaf-build`
+- Nếu **FAIL**: liệt kê gaps cần fix trước khi build, KHÔNG cho tiếp
+
+### Bước 7 — Output cho user
+```
+## Testcase Summary: [feature]
+
+- Total test cases: [N]
+- FR/NFR coverage: [X/Y] ([%])
+- Edge cases found by hunter: [N]
+- Implementation readiness: [PASS / FAIL]
+
+Files:
+- docs/project/testcases/[feature].md
 
 ## Next step
-Chạy `/vsaf-build <path/to/srs> <path/to/testcases>` để implement theo testcase đã chuẩn hoá.
+[Nếu PASS]: Chạy /vsaf-build <path/to/srs> <path/to/testcases>
+[Nếu FAIL]: Fix gaps listed above, then re-run /vsaf-test
+```
 
 ## Lưu ý
 - Không đánh dấu implementation done ở bước này

package/README.md

@@ -10,6 +10,9 @@ every decision. $20/month total.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────┐
+│  DISCOVERY         BMAD (agents)                                     │
+│                    PM · Analyst · domain/market/tech research        │
+├──────────────────────────────────────────────────────────────────────┤
 │  PLANNING          BMAD (agents)                                     │
 │                    Analyst · Architect · Brainstorming · QA          │
 ├──────────────────────────────────────────────────────────────────────┤
@@ -21,6 +24,9 @@ every decision. $20/month total.
 ├──────────────────────────────────────────────────────────────────────┤
 │  IMPLEMENTATION    Claude Code + Superpowers                         │
 │                    TDD execution, code review                        │
+├──────────────────────────────────────────────────────────────────────┤
+│  KNOWLEDGE         Graphify + BMAD (tech writer, editors)            │
+│                    wiki, docs sync, distillation                     │
 └──────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -95,26 +101,56 @@ Run `npx @ngocsangairvds/vsaf@latest --help` for the full list. Highlights:
 
 Main skill commands inside Claude Code:
 
+- `/vsaf-discover <product/domain>` — product discovery *(new)*
+- `/vsaf-sprint plan|status|story` — sprint management *(new)*
 - `/vsaf-onboard`
 - `/vsaf-plan <feature>`
 - `/vsaf-doc`
 - `/vsaf-test <path/to/srs>`
 - `/vsaf-build <path/to/srs> <path/to/testcases>`
 - `/vsaf-ship`
+- `/vsaf-docs` — documentation sync *(new)*
 
 ## Workflow
 
-Every feature follows an **SRS-first cycle**:
+Full product lifecycle:
 
 ```
-/vsaf-onboard → /vsaf-plan → /vsaf-doc → /vsaf-test → /vsaf-build → /vsaf-ship
+/vsaf-discover → /vsaf-sprint plan → [per feature in sprint]:
+  /vsaf-onboard → /vsaf-plan → /vsaf-doc → /vsaf-test → /vsaf-build → /vsaf-ship
+→ /vsaf-docs → /vsaf-sprint status → next sprint
 ```
 
-Bug fixes (Quick Flow) may use mini-SRS + mini-testcases, but still require
-`gitnexus_impact` before editing symbols and `gitnexus_detect_changes` before commit.
+Every feature follows an **SRS-first cycle**. Bug fixes (Quick Flow) may use
+mini-SRS + mini-testcases, but still require `gitnexus_impact` before editing
+symbols and `gitnexus_detect_changes` before commit.
 
 ### Flow breakdown
 
+#### `/vsaf-discover <product/domain>` — Product discovery *(new)*
+| Step | Tool | Does |
+|------|------|------|
+| 1 | **MemPalace** `mempalace_search` | Checks for prior research |
+| 2 | **BMAD** `bmad-domain-research` | Deep dive into domain/industry terminology, rules, patterns |
+| 3 | **BMAD** `bmad-market-research` | Competition landscape, customer needs, market trends |
+| 4 | **BMAD** `bmad-technical-research` | Tech stack options, feasibility, build-vs-buy |
+| 5 | **BMAD** `bmad-product-brief` | Synthesises findings into product brief |
+| 6 | **BMAD** `bmad-prfaq` | Working Backwards — stress-tests product concept |
+| 7 | **BMAD** `bmad-agent-pm` + `bmad-create-prd` | PM creates PRD from brief; `bmad-validate-prd` checks quality; `bmad-edit-prd` fixes issues |
+| 8 | **BMAD** `bmad-party-mode` | Multi-agent roundtable: PM + Analyst + Architect review |
+| 9 | **MemPalace** `mempalace_add_drawer` | Saves market insights + product decisions |
+| → | Output | Research artifacts, product brief, validated PRD, open questions |
+
+#### `/vsaf-sprint plan|status|story` — Sprint management *(new)*
+| Mode | Tool | Does |
+|------|------|------|
+| **plan** | **BMAD** `bmad-create-epics-and-stories` | Breaks PRD into epics + prioritised user stories |
+| **plan** | **BMAD** `bmad-sprint-planning` | Assigns stories to sprint, identifies dependencies |
+| **plan** | **MemPalace** `mempalace_add_drawer` | Saves sprint decisions, priorities, trade-offs |
+| **status** | **BMAD** `bmad-sprint-status` | Progress %, burndown, blocked items, risks |
+| **story** | **BMAD** `bmad-create-story` | Creates detailed story file with full context for implementation |
+| → | Output | Sprint plan, status dashboard, or story file |
+
 #### `/vsaf-onboard` — Understand the codebase
 | Step | Tool | Does |
 |------|------|------|
@@ -130,44 +166,72 @@ Bug fixes (Quick Flow) may use mini-SRS + mini-testcases, but still require
 | 3 | **GitNexus** `mcp__gitnexus__impact` + `query` | Blast radius — how many modules touched, risk level |
 | 4 | **Graphify** `/graphify path A B` *(if needed)* | Traces dependency path between two services |
 | 5 | **BMAD** `bmad-agent-architect` (Winston) | Proposes architecture approach, compares alternatives |
+| 5b | **BMAD** `bmad-create-architecture` *(if HIGH risk / >3 modules)* | Formal ADR → `docs/project/planning-artifacts/adr-[feature].md` |
 | 6 | **BMAD** `bmad-brainstorming` | Creative exploration — min. 20 alternatives / risk angles |
-| → | Output | Scope, impact report, chosen approach, rejected alternatives |
+| 7 | **BMAD** `bmad-advanced-elicitation` | Pre-mortem + red team — challenges chosen approach, finds failure modes |
+| → | Output | Scope, impact, approach, pre-mortem findings, rejected alternatives |
 
 #### `/vsaf-doc` — Write the SRS
 | Step | Tool | Does |
 |------|------|------|
+| 0 | *(Claude)* | Detects mode: **CREATE** (new SRS) or **EDIT** (modify existing) |
 | 1 | **MemPalace** `mempalace_search` | Checks for old decisions to reference in SRS |
-| 2 | *(Claude)* | Writes SRS with FRs/NFRs/acceptance criteria + traceability IDs → `docs/project/srs/` |
-| 3 | *(Claude)* | Writes implement notes: affected modules, technical constraints |
-| 4 | **MemPalace** `mempalace_add_drawer` | Persists chosen approach + rejected alternatives |
-| → | Output | `docs/project/srs/[feature].md` ready for testcase generation |
+| 2a | **BMAD** `bmad-create-prd` *or* *(Claude)* | **CREATE mode**: writes SRS/PRD with FRs/NFRs + traceability IDs |
+| 2b | **BMAD** `bmad-edit-prd` | **EDIT mode**: modifies existing SRS in-place, preserves traceability IDs, flags testcase impact |
+| 3 | **BMAD** `bmad-validate-prd` | Validates SRS quality; if FAIL in EDIT mode → `bmad-edit-prd` fixes again |
+| 4 | *(Claude)* | Writes implement notes: affected modules, technical constraints |
+| 5 | **MemPalace** `mempalace_add_drawer` | Persists chosen approach + rejected alternatives |
+| → | Output | Validated `docs/project/srs/[feature].md` + testcase impact report |
 
 #### `/vsaf-test <path/to/srs>` — Generate testcases
 | Step | Tool | Does |
 |------|------|------|
 | 1 | **BMAD** `bmad-qa-generate-e2e-tests` | Derives unit / integration / edge-case tests from SRS FRs/NFRs |
-| 2 | *(Claude)* | Validates every FR/NFR has ≥ 1 test, records gaps |
-| 3 | *(Claude)* | Builds FR/NFR → Testcase ID traceability matrix |
+| 2 | **BMAD** `bmad-review-edge-case-hunter` | Finds unhandled boundaries, race conditions, null/empty cases — adds tests |
+| 3 | *(Claude)* | Validates every FR/NFR has ≥ 1 test, builds traceability matrix |
 | 4 | *(Claude)* | Saves to `docs/project/testcases/[feature].md` |
-| → | Output | Testcase contract — used as implementation guardrails |
+| 5 | **BMAD** `bmad-check-implementation-readiness` | **Quality gate** — blocks build if SRS/testcase/architecture gaps found |
+| → | Output | Testcase contract + implementation readiness verdict (PASS/FAIL) |
 
 #### `/vsaf-build <path/to/srs> <path/to/testcases>` — Implement with TDD
 | Step | Tool | Does |
 |------|------|------|
+| 0 | **Superpowers** check | Detects plugin. If yes → uses write-plan, execute-plan, TDD, debugging. If no → warns + fallback |
 | 1 | **MemPalace** `mempalace_search` | Last check — no old decisions conflict with implementation |
 | 2 | *(Claude)* | Reads SRS + testcases, confirms FR/NFR → testcase mapping |
-| 3 | **Claude Code** (TDD loop) | RED → GREEN → REFACTOR per testcase group |
-| 3b | **GitNexus** `mcp__gitnexus__detect_changes` | Verifies only intended files changed before each commit |
+| 3 | **Superpowers** `write-plan` *or* *(Claude)* | Generates atomic task list from SRS + testcases |
+| 4 | **Superpowers** `execute-plan` + `test-driven-development` *or* **Claude Code** | TDD loop per task. Large plans (20+): `subagent-driven-development` |
+| 4b | **GitNexus** `mcp__gitnexus__detect_changes` | Verifies only intended files changed before each commit |
+| 4.5 | **BMAD** `bmad-checkpoint-preview` *(every 3-5 tasks)* | Human-in-the-loop review — summarise progress, flag issues, ask user to continue |
+| 5 | **Superpowers** `systematic-debugging` *or* manual | On failure: structured hypothesis → experiment → conclusion |
+| 5b | **BMAD** `bmad-correct-course` *(if scope drift detected)* | Assesses impact of scope change, proposes adjusted plan vs re-plan |
 | → | Output | Working code, all tests passing, 1 commit per task |
 
 #### `/vsaf-ship` — Review, sync, and record
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **Superpowers** `superpowers:code-review` | Layer 1 — structure, naming, SOLID, patterns |
-| 2 | **GitNexus** `gitnexus analyze` / `vsaf index` | Layer 2 — updates call graph to reflect new code |
-| 3 | **MemPalace** `mempalace_add_drawer` + `diary_write` | Saves decisions + session summary for future sessions |
-| 4 | *(git)* | Push branch, open PR with impact summary + test results |
-| → | Output | Shipped feature, updated graph, persistent knowledge |
+| 1 | **Superpowers** `code-review` + `verification-before-completion` *or* **BMAD** `bmad-code-review` | Layer 1 — code quality, patterns, SOLID |
+| 2 | **BMAD** `bmad-review-adversarial-general` + `bmad-review-edge-case-hunter` | Layer 1.5 — cynical attack + boundary analysis. Triage: MUST FIX / SHOULD FIX / NOTED |
+| 3 | **GitNexus** `gitnexus analyze` / `vsaf index` | Layer 2 — updates call graph to reflect new code |
+| 4 | **Superpowers** `finishing-a-development-branch` *or* manual | Pre-PR checklist |
+| 5 | **MemPalace** `mempalace_add_drawer` + `diary_write` | Saves decisions, adversarial findings, session summary |
+| 6 | *(git)* | Push branch, open PR with impact + test + adversarial summary |
+| 7 | **BMAD** `bmad-retrospective` *(end of epic only)* | Lessons learned → MemPalace. What went well / what to improve |
+| → | Output | Shipped feature, updated graph, persistent knowledge, follow-up tasks |
+
+#### `/vsaf-docs` — Documentation & knowledge sync *(new)*
+| Step | Tool | Does |
+|------|------|------|
+| 1 | **GitNexus** `query` + **MemPalace** `search` | Scans codebase + decisions, finds stale docs |
+| 2 | **BMAD** `bmad-document-project` | Generates/updates project documentation from code |
+| 3 | **BMAD** `bmad-generate-project-context` | Creates `project-context.md` — AI agent instructions |
+| 4 | **BMAD** `bmad-agent-tech-writer` (Paige) | Reviews docs for clarity, completeness, consistency |
+| 5 | **BMAD** `bmad-editorial-review-prose` + `bmad-editorial-review-structure` | Polish prose + restructure for readability |
+| 6 | **BMAD** `bmad-distillator` | Compresses long docs into LLM-optimised format |
+| 7 | **BMAD** `bmad-index-docs` | Generates `index.md` for each docs folder |
+| 8 | **Graphify** `/graphify . --wiki` | Builds agent-crawlable wiki from codebase |
+| 9 | **MemPalace** `diary_write` | Records what was updated/replaced |
+| → | Output | Updated docs, project context, wiki, doc indexes |
 
 ### Generated docs path convention
 
@@ -187,22 +251,23 @@ Bug fixes (Quick Flow) may use mini-SRS + mini-testcases, but still require
 
 See [1-setup-guide.md § Your First Project](docs/onboarding/1-setup-guide.md#5-your-first-project--a-walkthrough)
 for a walkthrough, or [2-workflow-guide.md § JWT Demo](docs/onboarding/2-workflow-guide.md#4-full-sdlc-demo)
-for a full command-by-command example.
+for a full code-by-code example.
 
 ## Tools
 
 | Tool | What It Does | Cost |
 |---|---|---|
 | **Claude Code** | AI coding agent — everything else plugs into it | $20/mo |
-| **BMAD Method** | AI agents for planning: Analyst, Architect, Brainstorming, QA | Free |
-| **Superpowers** | Methodology engine: code review | Free |
+| **BMAD Method** | AI agents for full lifecycle: PM, Analyst, Architect, QA, Tech Writer, Code Review + 40 skills | Free |
+| **Superpowers** | Claude Code plugin: plan execution, TDD, debugging, code review, pre-PR checklist *(optional — BMAD/manual fallback)* | Free |
 | **GitNexus** | Code knowledge graph via MCP — impact analysis, dependency queries | Free |
 | **MemPalace** | Knowledge base — verbatim storage of decisions, temporal knowledge graph | Free |
-| **Graphify** | Any input → knowledge graph → clustered communities, dependency tracing between services | Free |
+| **Graphify** | Any input → knowledge graph → clustered communities, dependency tracing, wiki | Free |
 
 ---
 
-**Core principles:** Onboard first. SRS before implementation. Testcases derived from SRS.
-Impact analysis before touching any symbol. Run `gitnexus_detect_changes` before commit.
-2-layer review before every PR. Re-index after every merge. Mine decisions weekly and after major decisions.
+**Core principles:** Discover before planning. Onboard first. SRS before implementation.
+Testcases derived from SRS. Impact analysis before touching any symbol.
+Run `gitnexus_detect_changes` before commit. 2-layer review before every PR.
+Re-index after every merge. Mine decisions weekly. Sync docs every sprint.
 MemPalace = decisions. Not CLAUDE.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.0.11",
+  "version": "3.0.12",
   "description": "VSAF — Agentic AI SDLC Framework. 4 integrated tools: BMAD, GitNexus, Superpowers, MemPalace. 2-layer review.",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "mempalace"],
   "bin": {

package/src/workflow.js

@@ -19,7 +19,13 @@ function runIndex() {
 
 function runReview() {
   step('Review (2-layer)');
-  info('Layer 1: Methodology review — run in Claude Code: /superpowers:code-review');
+
+  info('Layer 1: Code review');
+  info('  If Superpowers installed → run in Claude Code: /superpowers:code-review');
+  info('  Otherwise             → run in Claude Code: /bmad-code-review');
+  warn('  Superpowers is a Claude Code plugin. To install:');
+  warn('    /plugin install superpowers@claude-plugins-official');
+
   info('Layer 2: Knowledge graph sync');
   const indexOk = runIndex();