@ngocsangairvds/vsaf 3.0.12 → 3.1.1

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,91 +1,111 @@
 ---
 name: vsaf-ship
-description: Review 2 lớp, ship code, và ghi lại knowledge vào bộ nhớ. 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à ghi lại toàn bộ knowledge để các session sau kế thừa được.
-
-## Điều kiện tiên quyết
-- Đã chạy `/vsaf-build` với SRS + testcase
-- Không có failing tests
-
-## Các bước thực hiện
-
-### 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 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
+## Objective
+Multi-layer review, verify scope, validate architecture, push PR. Ensure code has passed all gates before shipping.
+
+## 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
+
+## Steps
+
+### 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
+
+### 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
-
-### 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 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 6 — Push PR
+  - **MUST FIX**: fix immediately before shipping
+  - **SHOULD FIX**: create a follow-up task
+  - **NOTED**: acknowledged, no action needed
+
+### Step 4 — Architectural constraint check (GitNexus)
+- Run `gitnexus_shape_check` — validate no architectural constraints are violated
+- If there are violations: **STOP** — fix before proceeding
+
+### 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
+
+### 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 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 8 — 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
-
-### Knowledge saved
-- Diary entry: ✓
-- Decisions: [X entries]
-- Follow-up tasks: [N items]
+- 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.
-[Nếu cuối epic]: Retrospective đã chạy — lessons saved to MemPalace.
+## 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
-- `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
+## 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,49 +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 — 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?
+#### 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 — 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 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 — 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
+#### Step 3 — Output
 ```
 ## Sprint Plan: [sprint name/number]
 
@@ -60,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]
 
@@ -97,24 +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