@ngocsangairvds/vsaf 3.1.0 → 3.1.1

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

@@ -1,79 +1,101 @@
 ---
 name: vsaf-plan
-description: Lên plan cho 1 feature/task mới. Dùng khi nhận được yêu cầu cần phân tích scope, impact, và chiến lược tiếp cận. Ví dụ: /vsaf-plan tạo module quản lý user
+description: Plan a new feature/task. Use when receiving a requirement that needs scope analysis, impact assessment, and approach strategy. Dual brainstorm (Superpowers + BMAD). Example: /vsaf-plan create user management module
 ---
 
 # VSAF Plan
 
-## Mục tiêu
-Hiểu đầy đủ yêu cầu, phân tích impact, và xác định chiến lược implement trước khi viết bất kỳ dòng code nào.
+## Objective
+Fully understand the requirement, analyze impact, and determine the implementation strategy before writing any line of code.
 
 ## Input
-`$ARGUMENTS` — mô tả feature/task cần làm (ví dụ: "tạo module quản lý dashboard")
-
-## Các bước thực hiện
-
-### 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 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 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 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 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:
+`$ARGUMENTS` — description of the feature/task to be done (e.g.: "create dashboard management module")
+
+## Execution Steps
+
+### Step 1 — Clarify scope (BMAD analyst)
+- Use skill `bmad-agent-analyst` to analyze the requirement
+- Identify: FRs, NFRs, edge cases, assumptions, out-of-scope
+- STOP and ask the user if there are any unclear points
+
+### Step 2 — Impact analysis (GitNexus)
+- Use `gitnexus_impact` with the target being the related module/symbol
+- Use `gitnexus_query` to find related code
+- Report blast radius: how many modules are affected, risk level
+- If risk is HIGH/CRITICAL: STOP, notify the user before continuing
+
+### Step 2b — Module boundary analysis (GitNexus)
+- Use `gitnexus_group_query` to view module boundaries
+- Identify: which groups are affected, interface contracts between groups
+- Understand module boundaries clearly before proposing architecture
+
+### Step 3 — Architecture decision (BMAD architect)
+- Use skill `bmad-agent-architect` to propose an architecture approach
+- Compare alternatives, choose the most suitable approach
+- **If risk is HIGH or > 3 modules**: use skill `bmad-create-architecture` to create a formal ADR (Architecture Decision Record)
+  - Save to `docs/project/planning-artifacts/adr-[feature].md`
+
+### Step 4 — Dual Brainstorm
+
+#### 4a — Structured brainstorm (Superpowers)
+- Use `superpowers:brainstorming` — structured exploration:
+  - Trade-offs, constraints, 2-3 viable options
+  - Evaluate risks for each option
+
+#### 4b — Creative brainstorm (BMAD)
+- Use skill `bmad-brainstorming` to explore alternatives and uncover hidden risks
+- Facilitator leads the session with diverse creative techniques
+- Goal: at least 20 ideas/alternatives before reorganizing
+
+#### 4c — Parallel deep-dive (Superpowers, if >2 approaches)
+- Use `superpowers:dispatching-parallel-agents` to research candidate approaches in parallel
+- Each agent deep-dives into 1 approach: feasibility, risks, effort
+- Synthesize results to choose the best approach
+
+### Step 5 — Challenge approach (BMAD Advanced Elicitation)
+- Use skill `bmad-advanced-elicitation` to challenge the chosen approach
+- Run **pre-mortem**: "Assume this approach fails after 3 months — why?"
+- Run **red team**: find weaknesses, attack vectors, failure modes
+- If serious risks are discovered: go back to Step 3 to adjust the approach
+
+### Step 6 — Output to user
+Present results in the following format:
 
 ```
-## Feature: [tên feature]
+## Feature: [feature name]
 
 ## Scope
-- In: [những gì sẽ làm]
-- Out: [những gì không làm]
+- In: [what will be done]
+- Out: [what will not be done]
 
 ## Impact Analysis
-- Modules bị ảnh hưởng: [danh sách]
+- Affected modules: [list]
+- Module boundaries: [from group_query]
 - Risk level: [LOW/MEDIUM/HIGH]
-- Breaking changes: [có/không, chi tiết]
+- Breaking changes: [yes/no, details]
 
-## Approach được chọn
-[Mô tả architecture approach]
+## Chosen Approach
+[Architecture approach description]
+
+## Brainstorm Summary
+- Superpowers: [N approaches explored, chosen: X]
+- BMAD: [N ideas generated, top insights]
+- Parallel agents: [used / not needed]
 
 ## Pre-mortem findings
-[Những risk đã identify và mitigation plan]
+[Identified risks and mitigation plan]
 
-## Alternatives đã xem xét
-[Tại sao không chọn]
+## Alternatives considered
+[Why they were not chosen]
 
 ## ADR
-[Đã tạo / Không cần (risk LOW)]
+[Created / Not needed (risk LOW)]
 
 ## Next step
-Chạy /vsaf-doc-prd để viết tài liệu PRD
+Run /vsaf-doc-prd to write the PRD document
 ```
 
-## Lưu ý
-- Nếu Impact > 3 modules: cảnh báo user, đề nghị split thành nhiều PRs
-- Nếu risk level HIGH/CRITICAL: DỪNG, báo user trước khi tiếp tục
+## Notes
+- If Impact > 3 modules: warn the user, suggest splitting into multiple PRs
+- If risk level is HIGH/CRITICAL: STOP, notify the user before continuing
+- Dual brainstorm is mandatory: both Superpowers (structured) and BMAD (creative)

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

@@ -0,0 +1,94 @@
+---
+name: vsaf-retro
+description: Sprint/epic retrospective — data-backed, not opinion-based. Uses GitNexus metrics + BMAD retrospective. Run at end of sprint or end of epic.
+---
+
+# VSAF Retro
+
+## Objective
+Run a retrospective based on real data from GitNexus (changes, health, module status) combined with the BMAD retrospective framework. Output: action items for the next sprint.
+
+## When to run
+- End of each sprint
+- End of each epic
+- **Separate from `/vsaf-ship`** — retro reviews the entire sprint/epic, not a single feature
+
+## Prerequisites
+- Sprint/epic has been completed (all features shipped or deferred)
+- GitNexus index is up to date (`vsaf index`)
+
+## Steps
+
+### Step 1 — Collect sprint changes (GitNexus)
+- Run `gitnexus_detect_changes({scope: "compare", base_ref: "<sprint-start-tag>"})`
+  - If no sprint tag exists: use `base_ref: "main"` or the commit hash from the start of the sprint
+- Collect: total files changed, symbols changed, processes affected
+- Record actual scope vs planned scope
+
+### Step 2 — Codebase health metrics (GitNexus)
+- Read `gitnexus://repo/{name}/context` — get health metrics after the sprint:
+  - Codebase size, complexity trends
+  - Index freshness
+  - Symbol/relationship counts
+- Compare with the start of the sprint if a baseline exists
+
+### Step 3 — Module health check (GitNexus)
+- Run `gitnexus_group_status` — check health of each module
+- Identify: which modules degraded during the sprint? Which modules improved?
+- Flag: modules with increased technical debt, modules needing attention
+
+### Step 4 — Retrospective analysis (BMAD)
+- Use skill `bmad-retrospective` with data from Steps 1-3 as input
+- Framework: What went well / What to improve / Action items
+- Data-backed: each observation must have evidence from GitNexus metrics
+- Do not accept vague statements — must have data support
+
+### Step 5 — Sprint metrics summary (BMAD)
+- Use skill `bmad-sprint-status` to compile final sprint metrics
+- Metrics: velocity, completion rate, scope change ratio
+- Compare with previous sprint if historical data is available
+
+### Step 6 — Output for user
+```
+## Sprint Retrospective: [sprint name/number]
+Date: [YYYY-MM-DD]
+
+### Sprint Scope
+- Planned: [N features/stories]
+- Completed: [N]
+- Deferred: [N]
+- Scope change: [+N/-N]
+
+### Codebase Impact (from GitNexus)
+- Files changed: [N]
+- Symbols changed: [N]
+- Processes affected: [N]
+- Modules touched: [list]
+
+### Module Health
+| Module | Status | Trend | Notes |
+|--------|--------|-------|-------|
+| ...    | ...    | ↑/↓/→ | ...   |
+
+### What Went Well (data-backed)
+- [observation] — evidence: [metric/data]
+
+### What To Improve (data-backed)
+- [observation] — evidence: [metric/data]
+
+### Action Items for Next Sprint
+| # | Action | Owner | Priority |
+|---|--------|-------|----------|
+| 1 | ...    | ...   | ...      |
+
+### Sprint Metrics
+- Velocity: [points/tasks]
+- Completion rate: [%]
+- Avg cycle time: [days]
+```
+
+## Notes
+- Retro must be data-backed — do not accept "I feel like..." without evidence
+- If GitNexus index is stale: run `vsaf index` before the retro
+- Action items must be actionable and have an owner — do not write vague "improve testing"
+- Save retro output to `docs/project/implementation-artifacts/retro-[sprint].md` to track historical data

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

@@ -1,78 +1,111 @@
 ---
 name: vsaf-ship
-description: Review 2 lớp, ship code. Dùng sau /vsaf-build khi code + tests đã pass. Bước cuối cùng của mọi feature.
+description: Multi-layer review + ship code. Used after /vsaf-build and /vsaf-test run when code + tests have passed. The final step of every feature.
 ---
 
 # VSAF Ship
 
-## Mục tiêu
-Đảm bảo code chất lượng, đóng gói feature, và push PR.
+## Objective
+Multi-layer review, verify scope, validate architecture, push PR. Ensure code has passed all gates before shipping.
 
-## Điều kiện tiên quyết
-- Đã chạy `/vsaf-build` với SRS + testcase
-- Không có failing tests
+## Prerequisites
+- Have run `/vsaf-build` with PRD + SRS + testcase
+- Have run `/vsaf-test run` — results file exists at `docs/project/testcases/[feature]-results.md`
+- Ship gate from `/vsaf-test run` = PASS
+- No failing tests
 
-## Các bước thực hiện
+## Steps
 
-### 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
+### Step 0 — Scope check (GitNexus, mandatory)
+- Run `gitnexus_detect_changes({scope: "compare", base_ref: "main"})`
+- Confirm only the expected files/symbols have changed
+- If unexpected changes are detected: **STOP** — review before proceeding
 
-### 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
+### Step 1 — Structured review handoff (Superpowers)
+- Use `superpowers:requesting-code-review` to create a structured handoff:
+  - What changed and why
+  - What to watch for (risk areas)
+  - Context for the reviewer
+- This handoff is the input for the subsequent review layers
+
+### Step 2 — Review Layer 1: Code Review
+- **If Superpowers is available**: use `superpowers:code-review`
+- **If not**: use skill `bmad-code-review`
+- Check: code structure, naming, patterns, SOLID principles
+- Fix issues if any, re-commit
+
+#### Step 2b — Handle reviewer feedback (if any)
+- If the review has feedback that needs to be addressed:
+  - Use `superpowers:receiving-code-review` — systematic response, no ad-hoc fixes
+  - Fix → re-commit → re-review if needed
+
+### Step 3 — Review Layer 1.5: Adversarial Review
+- Use skill `bmad-review-adversarial-general` — cynical attack on new code
+  - Look for: logic flaws, security holes, performance traps, silent failures
+- Use skill `bmad-review-edge-case-hunter` — exhaustive boundary analysis
+  - Look for: 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
+  - **MUST FIX**: fix immediately before shipping
+  - **SHOULD FIX**: create a follow-up task
+  - **NOTED**: acknowledged, no action needed
 
-### 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
+### Step 4 — Architectural constraint check (GitNexus)
+- Run `gitnexus_shape_check` — validate no architectural constraints are violated
+- If there are violations: **STOP** — fix before proceeding
 
-### 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
+### Step 5 — Review Layer 2: Knowledge graph sync
+- Run `vsaf index` (= `gitnexus analyze`)
+- Update the call graph to reflect the new code
+- This is the final layer — ensure the index accurately reflects the current code state
 
-### Bước 5 — Push PR
+### Step 6 — Final verification gate (Superpowers)
+- Use `superpowers:verification-before-completion`
+- Confirm all deliverables match the spec — not just "tests pass"
+- This is the final gate before PR
+
+### Step 7 — Pre-PR checklist (Superpowers)
+- **If Superpowers is available**: use `superpowers:finishing-a-development-branch` — automated pre-PR checklist
+- **If not**: check manually:
+  - [ ] Tests pass
+  - [ ] No uncommitted changes
+  - [ ] Branch up-to-date with main
+  - [ ] Test results file exists
+  - [ ] All MUST FIX resolved
+
+### Step 8 — 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 6 — 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?
-  - 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 7 — Output cho user
+PR description must include:
+- Impact summary (from GitNexus detect_changes)
+- Test results file path: `docs/project/testcases/[feature]-results.md`
+- Adversarial triage: MUST FIX: 0, SHOULD FIX: N, NOTED: N
+- Shape check result
+
+### Step 9 — Output to user
 ```
 ## Ship Complete: [feature]
 
 ### Reviews
-- 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
+- Scope check (detect_changes):  PASS — [N files, N symbols changed]
+- Layer 1 (Code Review):         PASS [superpowers / bmad-code-review]
+- Layer 1.5 (Adversarial):       PASS [MUST FIX: 0, SHOULD FIX: N, NOTED: N]
+- Shape check:                   PASS
+- Layer 2 (Graph sync):          PASS
+- Final verification:            PASS
+- Pre-PR checklist:              PASS
 
 ### PR
 - Branch: feature/[name]
 - PR: [link]
+- Test results: docs/project/testcases/[feature]-results.md
 
-Workflow hoàn tất. Chạy /vsaf-plan <next-feature> cho task tiếp theo.
+## Next step
+- Run /vsaf-retro if this is the end of a sprint/epic
+- Or /vsaf-plan <next-feature> for the next task
 ```
 
-## Lưu ý
-- Không ship nếu bất kỳ layer review nào fail hoặc còn MUST FIX
-- Retrospective: chạy sau mỗi epic (3-5 features), không phải mỗi feature
+## Notes
+- Do not ship if any gate fails or there are remaining MUST FIX items
+- Test results file is a mandatory input — no results = no ship
+- Retrospective is a separate skill (`/vsaf-retro`) — run at the end of a sprint, not at the end of every feature

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

@@ -1,41 +1,41 @@
 ---
 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.
+description: Sprint management — break PRD into epics/stories, create sprint plan, track progress. Use when managing multiple features simultaneously.
 ---
 
 # 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.
+## Goal
+Manage backlog and sprints for the project — break PRD/SRS into stories, create plans, 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
+`$ARGUMENTS` — action to perform:
+- `plan` — create a new sprint plan from PRD/epics
+- `status` — view current sprint status
+- `story <id>` — create a detailed story file for a single 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ể
+## When to use
+- After `/vsaf-discover` when a PRD is available
+- When the project has multiple features that need prioritization
+- When visibility into overall progress is needed
 
-## Các bước thực hiện
+## Steps
 
-### Mode: `plan` — Lập sprint plan mới
+### Mode: `plan` — Create a new sprint plan
 
-#### Bước 1 — 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)
+#### Step 1 — Break into Epics + Stories
+- Use skill `bmad-create-epics-and-stories` with PRD/SRS as input
+- Output: list of epics, each epic containing user stories
+- Each story has: description, acceptance criteria, estimated complexity (S/M/L/XL)
 
-#### Bước 2 — 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`
+#### Step 2 — Sprint Planning
+- Use skill `bmad-sprint-planning` to:
+  - Prioritize stories (MoSCoW or WSJF)
+  - Assign stories to sprint based on capacity
+  - Identify dependencies between stories
+- Save sprint plan to `docs/project/planning-artifacts/sprint-plan.md`
 
-#### Bước 3 — Output
+#### Step 3 — Output
 ```
 ## Sprint Plan: [sprint name/number]
 
@@ -52,21 +52,21 @@ Quản lý backlog và sprint cho dự án — từ PRD/SRS chia thành stories,
 |-------|--------|
 
 ### 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
+Run /vsaf-sprint story <id> to create a detailed story file
+Or: /vsaf-plan <story description> to start the first feature
 ```
 
 ---
 
-### Mode: `status` — Xem trạng thái sprint
+### Mode: `status` — View sprint status
 
-#### Bước 1 — Collect status
-- Dùng skill `bmad-sprint-status` để:
+#### Step 1 — Collect status
+- Use skill `bmad-sprint-status` to:
   - Scan sprint plan file
-  - Check git log cho completed stories
+  - Check git log for completed stories
   - Surface: blocked items, risks, velocity trend
 
-#### Bước 2 — Output
+#### Step 2 — Output
 ```
 ## Sprint Status: [sprint name]
 
@@ -89,23 +89,23 @@ Hoặc: /vsaf-plan <story description> để bắt đầu feature đầu tiên
 
 ---
 
-### Mode: `story <id>` — Tạo story file chi tiết
+### Mode: `story <id>` — Create a detailed story file
 
-#### 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`
+#### Step 1 — Create story file
+- Use skill `bmad-create-story` with story ID from the sprint plan
+- Story file includes: full context, acceptance criteria, technical notes, dependencies
+- Save to `docs/project/planning-artifacts/stories/story-[id].md`
 
-#### Bước 2 — Output
+#### Step 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
+Run /vsaf-plan <story description> to 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
+## Notes
+- Sprint plan is a living document — update when changes occur
+- Re-run `/vsaf-sprint status` daily or after each `/vsaf-ship`
+- If sprint is delayed >20%: use `bmad-correct-course` to adjust scope