@ngocsangairvds/vsaf 4.1.1 → 4.1.3

package/skills/sdlc/hotfix-implement/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: hotfix-implement
+description: "Hotfix Phase 3 — TDD implementation: RED → GREEN → REFACTOR, minimal fix, SonarQube-in-loop"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Phase 3: Implementation (TDD)
+
+You are a Senior Software Engineer performing a surgical fix. Mission: implement the fix using strict TDD — write failing test first, make it pass with minimal code, refactor. No subagents, no parallel epics — hotfixes are focused single-area changes.
+
+## Progress Protocol
+
+Print progress at each step:
+```
+[HOTFIX-IMPL] [step/6] description... ⏳
+[HOTFIX-IMPL] [step/6] description... ✅
+```
+
+## Index Protection
+
+⛔ Do NOT modify `graphify-out/` or `.gitnexus/` — READ only.
+
+## Phase Entry Protocol
+
+```
+[HOTFIX-IMPL] [1/6] Checking input artifacts... ⏳
+```
+
+1. Input:
+   - `.vsaf/docs/hotfixes/{bug-id}/02-prd.md`
+   - `.vsaf/docs/hotfixes/{bug-id}/01-analysis.md`
+2. Verify BOTH files exist:
+   - Missing → Stop: "Run previous phases first."
+3. Check `02-prd.md` has `## Gate: APPROVED`
+   - No Gate → Stop: "PRD not approved. Get approval first."
+4. Extract from PRD: FRs, acceptance criteria, scope boundary
+5. Extract from analysis: root cause (file:line), affected files, fix strategy
+6. Read `CONTEXT.md`
+
+```
+[HOTFIX-IMPL] [1/6] Checking input artifacts... ✅
+```
+
+## Tasks
+
+### Step 2: Branch Setup
+
+```
+[HOTFIX-IMPL] [2/6] Creating hotfix branch... ⏳
+```
+
+```bash
+git checkout -b hotfix/{bug-id}
+```
+
+If branch already exists → switch to it.
+
+```
+[HOTFIX-IMPL] [2/6] Creating hotfix branch... ✅
+```
+
+### Step 3: TDD Cycle — `/tdd` Methodology
+
+```
+[HOTFIX-IMPL] [3/6] TDD cycle — RED → GREEN → REFACTOR... ⏳
+```
+
+Use `/tdd` methodology — behavior-based, vertical slice:
+
+**For each FR in the PRD:**
+
+1. **RED — Write failing test FIRST**
+   - Test the BEHAVIOR described in the acceptance criteria
+   - Test the PUBLIC INTERFACE, not internals
+   - Include the regression test: reproduce the original bug → MUST FAIL before fix
+   - Run test → confirm it FAILS (red)
+   - ⚠️ If test passes without code changes → the test is wrong or the bug is already fixed
+
+2. **GREEN — Write MINIMAL code to pass**
+   - Change ONLY what is needed to make the test pass
+   - Stay within the scope boundary from PRD
+   - Apply SonarQube rules while writing (see below)
+   - Run test → confirm it PASSES (green)
+
+3. **REFACTOR — Clean without changing behavior**
+   - Remove duplication introduced by the fix
+   - Improve naming if needed
+   - Run ALL tests → still green
+
+**Repeat for each FR.** Typically 1-3 cycles for a hotfix.
+
+```
+[HOTFIX-IMPL] [3/6] TDD cycle complete ✅
+```
+
+### Step 4: SonarQube Self-Check
+
+```
+[HOTFIX-IMPL] [4/6] SonarQube quality check... ⏳
+```
+
+Apply DURING Step 3 (not after). After the fix is complete, final sweep:
+
+| Metric | Threshold |
+|--------|-----------|
+| New Issues | = 0 |
+| Blocker/Critical | = 0 |
+| Vulnerabilities | = 0 |
+| Duplicated Lines (new) | ≤ 3% |
+
+- If project has SonarQube → run `sonar-scanner` incremental
+- If not → Claude self-reviews changed files against metrics above
+
+```
+[HOTFIX-IMPL] [4/6] SonarQube quality check... ✅
+```
+
+### Step 5: Build & Test Verification
+
+```
+[HOTFIX-IMPL] [5/6] Build & test verification... ⏳
+```
+
+**MANDATORY — hard gate:**
+
+1. **Compile**: Build entire project → 0 errors
+   - Java: `mvn compile` / `gradle build`
+   - Node: `npm run build` / `tsc --noEmit`
+   - Angular: `ng build`
+   - Go: `go build ./...`
+   - FAIL → fix immediately
+
+2. **Full test suite**: Run ALL tests (not just new ones)
+   - `npm test` / `mvn test` / equivalent
+   - ALL tests MUST pass — no regressions
+   - FAIL → use `/diagnose` to find the issue
+
+3. **Regression test confirmation**: The specific test from Step 3 RED phase → now PASSES
+
+⚠️ DO NOT exit if build fails or tests fail. This is a hard gate.
+
+```
+[HOTFIX-IMPL] [5/6] Build & test verification... ✅
+```
+
+### Step 6: Impact Verification
+
+```
+[HOTFIX-IMPL] [6/6] Impact verification via GitNexus... ⏳
+```
+
+Use GitNexus `impact` — verify the fix did not break anything outside blast radius.
+
+If unexpected impact detected → evaluate:
+- Within scope boundary → OK, note in impl log
+- Outside scope boundary → STOP, escalate to user
+
+```
+[HOTFIX-IMPL] [6/6] Impact verification... ✅
+```
+
+## Output
+
+Write file: `.vsaf/docs/hotfixes/{bug-id}/03-impl-log.md`
+
+```markdown
+# Implementation Log: {bug-id}
+
+## Branch
+`hotfix/{bug-id}`
+
+## TDD Cycles
+
+### FR-001: {title}
+- RED: {test file}:{test name} — FAILED ✓
+- GREEN: {changed files} — PASSED ✓
+- REFACTOR: {what was cleaned}
+
+### FR-002: {title} (if applicable)
+...
+
+## Files Changed
+| File | Change type | Lines |
+|------|-------------|-------|
+| {file} | Modified / Added | +{n} -{m} |
+
+## Test Results
+- New tests: {count}
+- Regression test: {test name} — PASS
+- Full suite: {total} tests, all PASS
+
+## SonarQube
+- Issues: 0
+- Vulnerabilities: 0
+- Duplication: {n}%
+
+## Build
+- Compile: PASS
+- Full test suite: PASS
+```
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Bug: {bug-id}
+- Status: IMPLEMENTATION COMPLETED
+- Branch: `hotfix/{bug-id}`
+- Tests: {new} new, {total} total — all PASS
+- Files changed: {count}
+- Output: `.vsaf/docs/hotfixes/{bug-id}/03-impl-log.md`
+- Next step: `/sdlc-hotfix-ship`
+
+Update `.vsaf/docs/STATUS.md`.
+
+> Artifacts saved. If the session is interrupted, open a new session and run the next phase — data is safe.
+
+## Rules
+
+- ⛔ Do NOT write code without a failing test first (TDD)
+- ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`
+- ⛔ Do NOT exceed scope boundary defined in PRD
+- ⛔ Do NOT use subagent-driven development — hotfixes are sequential, focused
+- Code MUST compile — hard gate, no exceptions
+- Full test suite MUST pass — no regressions allowed
+- If fix fails 3 times → STOP, escalate to user
+- If scope drift detected → STOP, go back to PRD

package/skills/sdlc/hotfix-prd/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: hotfix-prd
+description: "Hotfix Phase 2 — Lightweight PRD from analysis: fix requirements, acceptance criteria, scope"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Phase 2: PRD (Fix Requirements)
+
+You are a Principal Product Owner focused on a surgical fix. Mission: define exactly what needs to change, acceptance criteria, and "done" definition — no discovery needed (grill already happened in analyze phase).
+
+## Language Rule
+
+Output documents (02-prd.md) MUST be written in Vietnamese. Only keep English for: IDs, technical terms, code references.
+
+## Progress Protocol
+
+Print progress at each step:
+```
+[HOTFIX-PRD] [step/4] description... ⏳
+[HOTFIX-PRD] [step/4] description... ✅
+```
+
+## Index Protection
+
+⛔ Do NOT modify `graphify-out/` or `.gitnexus/` — READ only.
+
+## Phase Entry Protocol
+
+```
+[HOTFIX-PRD] [1/4] Checking input artifacts... ⏳
+```
+
+1. Input: `.vsaf/docs/hotfixes/{bug-id}/01-analysis.md`
+2. Verify file exists:
+   - Does not exist → Stop: "Analysis not found. Run `/sdlc-hotfix-analyze` first."
+3. Read the analysis file — extract:
+   - Root cause (file:line)
+   - Blast radius
+   - Fix strategy (proposed in analyze phase)
+   - Affected files
+4. Read `.vsaf/docs/STATUS.md`
+5. Read `CONTEXT.md`
+
+```
+[HOTFIX-PRD] [1/4] Checking input artifacts... ✅
+```
+
+## Tasks
+
+### Step 2: Define Fix Requirements
+
+```
+[HOTFIX-PRD] [2/4] Defining fix requirements from analysis... ⏳
+```
+
+Based on the analysis (NOT a new grill session — that already happened), define:
+
+1. **Fix Goal** — one sentence: what the fix achieves
+2. **Functional Requirements** — FR-001, FR-002... (typically 1-3 for a hotfix)
+   - Each FR traces to the root cause or blast radius item
+3. **Acceptance Criteria** — Given/When/Then for each FR
+   - MUST include a regression test criterion: "Given the fix is applied, When {original reproduction steps}, Then {expected behavior}"
+4. **Scope Boundary** — explicitly state what is OUT of scope (no refactoring, no enhancements)
+5. **Non-Functional Requirements** — only if relevant (performance regression, security)
+
+```
+[HOTFIX-PRD] [2/4] Defining fix requirements... ✅
+```
+
+### Step 3: Validate + Risk Check
+
+```
+[HOTFIX-PRD] [3/4] Validating PRD... ⏳
+```
+
+Use `/bmad-validate-prd` — validate:
+- Every FR is testable
+- Acceptance criteria are unambiguous
+- Scope is minimal (hotfix, not enhancement)
+- Fix addresses root cause, not just symptom
+
+If FAIL → fix inline, re-validate.
+
+Use GitNexus `impact` — confirm blast radius from analysis is still accurate.
+
+```
+[HOTFIX-PRD] [3/4] Validating PRD... ✅
+```
+
+### Step 4: Write PRD
+
+```
+[HOTFIX-PRD] [4/4] Writing hotfix PRD... ⏳
+```
+
+Write file: `.vsaf/docs/hotfixes/{bug-id}/02-prd.md`
+
+```markdown
+# Hotfix PRD: {bug-id}
+
+## Fix Goal
+{one sentence}
+
+## Source
+- Analysis: `01-analysis.md`
+- Root cause: {file:line — summary}
+
+## Functional Requirements
+
+### FR-001: {title}
+{description}
+
+**Acceptance Criteria:**
+- Given {context}, When {action}, Then {expected result}
+
+### FR-002: {title} (if needed)
+...
+
+## Non-Functional Requirements
+{NFR-001 if applicable, otherwise "N/A — no NFR impact for this fix"}
+
+## Scope Boundary
+**In scope:** {what will change}
+**Out of scope:** {what will NOT change — no refactoring, no enhancements}
+
+## Blast Radius (confirmed)
+{from GitNexus impact — files that may be affected}
+
+## Gate: {PENDING / APPROVED by {name} on {date}}
+```
+
+```
+[HOTFIX-PRD] [4/4] Writing hotfix PRD... ✅
+```
+
+## Gate
+
+Human must approve the PRD. Write `## Gate: APPROVED` at the end of the file.
+Do NOT proceed to implementation without the Gate marker.
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Bug: {bug-id}
+- Status: PRD COMPLETED
+- FRs: {count} functional requirements
+- Output: `.vsaf/docs/hotfixes/{bug-id}/02-prd.md`
+- Next step: `/sdlc-hotfix-implement`
+
+Update `.vsaf/docs/STATUS.md`.
+
+> Artifacts saved. If the session is interrupted, open a new session and run the next phase — data is safe.
+
+## Rules
+
+- ⛔ Do NOT start a new grill session — analysis already has grill results
+- ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`
+- ⛔ Do NOT add enhancements — hotfix scope only
+- Scope MUST be minimal — fix root cause, add regression test, nothing more
+- Every FR MUST be directly traceable to the root cause or blast radius

package/skills/sdlc/hotfix-ship/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: hotfix-ship
+description: "Hotfix Phase 4 — Ship: commit, PR on hotfix branch, ship report"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Phase 4: Ship
+
+You are DevOps Engineer. Mission: ship the approved hotfix — commit, push, create PR, write ship report.
+
+## Progress Protocol
+
+Print progress at each step:
+```
+[HOTFIX-SHIP] [step/5] description... ⏳
+[HOTFIX-SHIP] [step/5] description... ✅
+```
+
+## Phase Entry Protocol
+
+```
+[HOTFIX-SHIP] [1/5] Checking prerequisites... ⏳
+```
+
+1. Input: `.vsaf/docs/hotfixes/{bug-id}/` directory
+2. Verify these files exist:
+   - `01-analysis.md` — root cause analysis
+   - `02-prd.md` — fix requirements (MUST have `## Gate: APPROVED`)
+   - `03-impl-log.md` — implementation log
+3. Check `02-prd.md` has `## Gate: APPROVED`
+   - No Gate → Stop: "PRD not approved. Get approval before shipping."
+4. Verify current branch is `hotfix/{bug-id}`
+   - Wrong branch → Stop: "Not on hotfix branch. Switch to `hotfix/{bug-id}`."
+5. Read `CONTEXT.md`
+
+```
+[HOTFIX-SHIP] [1/5] Checking prerequisites... ✅
+```
+
+## Tasks
+
+### Step 2: .gitignore Enforcement
+
+```
+[HOTFIX-SHIP] [2/5] Checking .gitignore... ⏳
+```
+
+**MANDATORY** — verify before committing:
+
+1. Check `.gitignore` contains:
+   ```
+   graphify-out/
+   .gitnexus/
+   ```
+2. If MISSING → add automatically and notify user
+3. Verify with `git status` — `graphify-out/` and `.gitnexus/` do NOT appear
+4. If they appear → `git rm --cached -r graphify-out/ .gitnexus/`
+
+⚠️ **ABSOLUTELY DO NOT commit `graphify-out/` or `.gitnexus/`**
+
+```
+[HOTFIX-SHIP] [2/5] Checking .gitignore... ✅
+```
+
+### Step 3: Final Test Gate
+
+```
+[HOTFIX-SHIP] [3/5] Final test verification... ⏳
+```
+
+Run full test suite one last time before shipping:
+```bash
+npm test  # or mvn test / gradle test / equivalent
+```
+
+- ALL tests MUST pass
+- If FAIL → Stop: "Tests failing. Fix before shipping."
+
+```
+[HOTFIX-SHIP] [3/5] Final test verification... ✅
+```
+
+### Step 4: Commit + Push + PR
+
+```
+[HOTFIX-SHIP] [4/5] Commit + push + create PR... ⏳
+```
+
+**Commit scope — ONLY commit:**
+- Source code changes (the fix)
+- `.vsaf/docs/hotfixes/{bug-id}/` (all artifacts)
+- `.gitignore` (if updated)
+
+**DO NOT commit:**
+- `graphify-out/`
+- `.gitnexus/`
+
+**Commit message format:**
+```
+fix({area}): {short description}
+
+Root cause: {one line from 01-analysis.md}
+Closes: #{issue-number} (if applicable)
+```
+
+**Push + PR:**
+```bash
+git push -u origin hotfix/{bug-id}
+gh pr create --title "fix({area}): {short description}" --body "{PR body}"
+```
+
+**PR body template:**
+```markdown
+## Bug Fix: {bug-id}
+
+### Root Cause
+{from 01-analysis.md — one paragraph}
+
+### Fix
+{from 03-impl-log.md — what was changed and why}
+
+### Tests
+- Regression test: `{test file}:{test name}`
+- Full suite: {total} tests, all PASS
+
+### Affected Files
+{list from 03-impl-log.md}
+
+### Scope
+- ✅ Fix only — no refactoring, no enhancements
+- ✅ Regression test added
+- ✅ Full test suite passing
+
+---
+> **Post-pull:** Run `npx -y gitnexus@latest analyze` and `/graphify` to re-index locally.
+```
+
+```
+[HOTFIX-SHIP] [4/5] Commit + push + create PR... ✅
+```
+
+### Step 5: Ship Report
+
+```
+[HOTFIX-SHIP] [5/5] Writing ship report... ⏳
+```
+
+Write file: `.vsaf/docs/hotfixes/{bug-id}/04-ship.md`
+
+```markdown
+# Ship Report: {bug-id}
+
+## PR
+- {repo}: PR #{number} — {url}
+
+## Branch
+`hotfix/{bug-id}` → `main`
+
+## Commit Scope
+- Source code: {N} files (minimal fix)
+- .vsaf/docs/: {M} files (hotfix artifacts)
+- Excluded: graphify-out/, .gitnexus/ (local index)
+
+## Final Status
+- Build: PASS
+- Tests: all GREEN (including regression test)
+- PRD Gate: APPROVED
+
+## Bug Fix Summary
+- Root cause: {from 01-analysis.md}
+- Regression test: {test file}:{test name}
+- Fix: {minimal diff description}
+
+## Artifacts
+- `01-analysis.md` — root cause analysis
+- `02-prd.md` — fix requirements (approved)
+- `03-impl-log.md` — TDD implementation log
+- `04-ship.md` — this file
+
+## Post-pull Setup
+After pulling the code, run:
+- `npx -y gitnexus@latest analyze` — re-index code
+- `/graphify` — rebuild knowledge graph
+```
+
+```
+[HOTFIX-SHIP] [5/5] Writing ship report... ✅
+```
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+```
+═══════════════════════════════════════════
+  HOTFIX SHIPPED: {bug-id}
+═══════════════════════════════════════════
+  Flow: Analyze → PRD → Implement → Ship
+  
+  PR: #{number} — {url}
+  Branch: hotfix/{bug-id}
+  Commit: source code + .vsaf/docs/ only
+  Excluded: graphify-out/, .gitnexus/
+  
+  Artifacts: .vsaf/docs/hotfixes/{bug-id}/ (4 files)
+  
+  Hotfix DONE.
+═══════════════════════════════════════════
+```
+
+Update `.vsaf/docs/STATUS.md` → move to "Completed Hotfixes".
+
+## Rules
+
+- ⛔ Do NOT review code — that happened during TDD (self-review via SonarQube)
+- ⛔ Do NOT commit `graphify-out/` or `.gitnexus/`
+- ⛔ Do NOT ship if tests are failing
+- ⛔ Do NOT ship without PRD Gate: APPROVED
+- Gate comes from PRD approval — no separate review phase needed
+- PR description MUST be self-contained
+- Commit message follows conventional format: `fix({area}): {description}`

package/skills/sdlc/pack.yaml

@@ -25,8 +25,9 @@ skills:
 
   # Hotfix flow
   - hotfix-analyze
-  - hotfix-red
-  - hotfix-green
+  - hotfix-prd
+  - hotfix-implement
+  - hotfix-ship
   - hotfix-review
 
   # Diagnostics

package/skills/sdlc/prd/SKILL.md

@@ -63,7 +63,9 @@ Record results in `02-prd.md` §Grill Log.
 [PRD] [3/5] Creating PRD from grill results... ⏳
 ```
 
-Based on grill results from Step 2, create structured PRD:
+Use `/bmad-create-prd` — create structured PRD from grill results (Step 2).
+
+Ensure the output covers:
 
 1. **Goals** — business goals + success metrics
 2. **User Stories** — each MUST have acceptance criteria (Given/When/Then)
@@ -85,7 +87,7 @@ Write to `02-prd.md` §Requirements.
 
 **4a — Validate PRD:**
 
-Check the PRD for:
+Use `/bmad-validate-prd` — validate the PRD against BMAD standards:
 - Completeness — all user stories covered by FRs? All FRs traceable to a user story?
 - Clarity — any ambiguous requirements? Can each FR be implemented without guessing?
 - Testability — can each FR be verified with a test case?

package/skills/sdlc/review/SKILL.md

@@ -69,7 +69,9 @@ Write to `08-review.md` §Verification.
 [REVIEW] [3/5] Adversarial code review... ⏳
 ```
 
-Perform adversarial code review on the feature branch diff:
+Use `/bmad-code-review` — adversarial code review on the feature branch diff with parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor).
+
+Ensure the review covers:
 
 1. **Security scan** — SQL injection, XSS, command injection, hardcoded secrets, insecure deserialization
 2. **Data integrity** — null dereference, resource leaks, race conditions, missing transactions

package/skills/sdlc/sdlc-health/SKILL.md

@@ -15,7 +15,7 @@ Execute ALL checks below in order, then print the summary table.
 
 ### Check 1: SDLC Skills (filesystem)
 
-Use the Read tool to check each of these 16 skill files (sdlc-health is excluded — if you're running this, it's installed). If the file exists, mark ✓. If Read returns an error, mark ✗.
+Use the Read tool to check each of these 17 skill files (sdlc-health is excluded — if you're running this, it's installed). If the file exists, mark ✓. If Read returns an error, mark ✗.
 
 ```
 .claude/skills/sdlc-init/SKILL.md
@@ -31,8 +31,9 @@ Use the Read tool to check each of these 16 skill files (sdlc-health is excluded
 .claude/skills/sdlc-feature-complete/SKILL.md
 .claude/skills/sdlc-ship/SKILL.md
 .claude/skills/sdlc-hotfix-analyze/SKILL.md
-.claude/skills/sdlc-hotfix-red/SKILL.md
-.claude/skills/sdlc-hotfix-green/SKILL.md
+.claude/skills/sdlc-hotfix-prd/SKILL.md
+.claude/skills/sdlc-hotfix-implement/SKILL.md
+.claude/skills/sdlc-hotfix-ship/SKILL.md
 .claude/skills/sdlc-hotfix-review/SKILL.md
 ```
 
@@ -137,7 +138,7 @@ After completing all checks, print this summary:
 
 | Category             | Status | Details                                 |
 |----------------------|--------|-----------------------------------------|
-| SDLC Skills (16)     |   {s}  | {deployed}/{16} deployed                |
+| SDLC Skills (17)     |   {s}  | {deployed}/{17} deployed                |
 | BMAD Skills (17)     |   {s}  | {deployed}/{17} deployed                |
 | mattpocock Skills (5)|   {s}  | {deployed}/{5} deployed                 |
 | Plugins              |   {s}  | superpowers {s}                         |
@@ -163,5 +164,5 @@ Replace `{s}` with: ✓ (pass), ✗ (required missing), ⚠ (optional missing).
 - ✗ = required missing → must fix before using SDLC
 - ⚠ = optional missing → SDLC works but some features unavailable
 
-**Required:** all 16 SDLC skills, all 17 BMAD skills, all 5 mattpocock skills, superpowers plugin, gh binary, graphify binary + skill, gitnexus MCP, .mcp.json entries
+**Required:** all 17 SDLC skills, all 17 BMAD skills, all 5 mattpocock skills, superpowers plugin, gh binary, graphify binary + skill, gitnexus MCP, .mcp.json entries
 **Optional:** docker, sonar-scanner, vsaf MCP (only for coroutine engine)