@ngocsangairvds/vsaf 5.1.4 → 5.1.6

package/skills/sdlc/architecture/readiness/step.md

@@ -0,0 +1,76 @@
+### Step 6: Readiness Check
+
+```
+[ARCHITECTURE] [6/6] Checking implementation readiness... ⏳
+```
+
+Use `/bmad-check-implementation-readiness` — validate architecture is clear enough to implement:
+
+1. **PRD coverage** — every FR traceable to at least one epic/story?
+2. **Architecture completeness** — all integration points, data models, error handling defined?
+3. **Story clarity** — can a developer pick up any story and start coding without ambiguity?
+4. **Conflict map** — any file claimed by multiple epics without resolution?
+
+Write to `03-adr.md` §Readiness. If FAIL → record what's missing, fix ADR or PRD.
+
+```
+[ARCHITECTURE] [6/6] Checking implementation readiness... ✅
+```
+
+## Gate
+
+Readiness = PASS to proceed to Phase 4.
+If FAIL → record reasoning, go back to fix ADR or PRD.
+
+## Output
+
+- `.vsaf/docs/features/{feature-name}/03-adr.md`
+- `.vsaf/docs/features/{feature-name}/04-epics.md`
+
+### 03-adr.md template:
+
+```markdown
+# ADR: {feature-name}
+
+## Current State
+{from GitNexus context + api_impact}
+
+## Grill Session
+{questions and answers from bmad-advanced-elicitation}
+
+## Decision
+{from bmad-create-architecture, based on grill answers}
+{clearly state: "Based on answer X → chose approach Y because Z"}
+
+## Readiness
+{from bmad-check-implementation-readiness}
+```
+
+## Artifact Auto-Save
+
+After writing the file, print the message:
+
+> Artifacts saved. If the session is interrupted, open a new session and run the next phase — data is safe.
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Feature: {feature-name}
+- Status: COMPLETED
+- Completed: current state analysis, grill session, architecture decision, epic breakdown, readiness check
+- Output files: `03-adr.md`, `04-epics.md`
+- Suggested next steps:
+  [1] Phase 4 SRS → `/sdlc-srs`
+  [2] Save artifacts
+
+Update `.vsaf/docs/STATUS.md`.
+
+## Rules
+
+- ⛔ Do NOT design architecture before asking — Grill session MUST happen before architecture decision
+- ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`
+- Every story MUST be a vertical slice (DB→API→UI), NOT a horizontal layer
+- Conflict Map MUST be clear: which file belongs to which epic, what rules apply for shared files
+- ADR is append-only: after approval do not edit, only create a new ADR to supersede
+- If multi-repo: clearly specify which repo belongs to which epic
+- Architecture decisions MUST reference specific answers from the grill session

package/skills/sdlc/complete/context/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-complete-context
+description: "Feature Complete 2/5 — update CONTEXT"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Feature Complete 2/5 — update CONTEXT
+
+@include(step.md)

package/skills/sdlc/complete/context/step.md

@@ -0,0 +1,14 @@
+### Step 2: Update CONTEXT.md
+
+```
+[FEATURE-COMPLETE] [2/5] Updating CONTEXT.md — extracting new terminology... ⏳
+```
+
+Read all artifacts in `.vsaf/docs/features/{feature-name}/`:
+- Extract new terminology that emerged during the development process
+- Append to `CONTEXT.md` §Shared Language table
+- Only add terminology that is TRULY new — no duplicates
+
+```
+[FEATURE-COMPLETE] [2/5] Updating CONTEXT.md... ✅
+```

package/skills/sdlc/complete/knowledge/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-complete-knowledge
+description: "Feature Complete 3/5 — update KNOWLEDGE"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Feature Complete 3/5 — update KNOWLEDGE
+
+@include(step.md)

package/skills/sdlc/complete/knowledge/step.md

@@ -0,0 +1,22 @@
+### Step 3: Update KNOWLEDGE.md
+
+```
+[FEATURE-COMPLETE] [3/5] Updating KNOWLEDGE.md — patterns, decisions, gotchas... ⏳
+```
+
+Append to `.vsaf/docs/KNOWLEDGE.md`:
+- Lessons learned (patterns, anti-patterns)
+- Noteworthy decisions (from ADR)
+- Gotchas discovered during implementation
+
+Format:
+```markdown
+## {feature-name} ({date})
+- **Pattern**: {pattern learned}
+- **Decision**: {key decision and rationale}
+- **Gotcha**: {unexpected issue and solution}
+```
+
+```
+[FEATURE-COMPLETE] [3/5] Updating KNOWLEDGE.md... ✅
+```

package/skills/sdlc/complete/prereq/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-complete-prereq
+description: "Feature Complete 1/5 — prerequisites"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Feature Complete 1/5 — prerequisites
+
+@include(step.md)

package/skills/sdlc/complete/prereq/step.md

@@ -0,0 +1,16 @@
+## Phase Entry Protocol
+
+```
+[FEATURE-COMPLETE] [1/5] Checking prerequisites... ⏳
+```
+
+1. Input: Feature name `$ARGUMENTS`
+2. Check that `.vsaf/docs/features/{feature-name}/08-review.md` exists
+3. Check for **Gate: APPROVED** in `08-review.md`
+   - No Gate APPROVED → Stop: "Review has not been approved. Run `/sdlc-review` first."
+4. Read `.vsaf/docs/STATUS.md`
+5. Read `CONTEXT.md`
+
+```
+[FEATURE-COMPLETE] [1/5] Checking prerequisites... ✅
+```

package/skills/sdlc/complete/reindex/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-complete-reindex
+description: "Feature Complete 4/5 — re-index"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Feature Complete 4/5 — re-index
+
+@include(step.md)

package/skills/sdlc/complete/reindex/step.md

@@ -0,0 +1,24 @@
+### Step 4: Re-index GitNexus
+
+```
+[FEATURE-COMPLETE] [4/5] Re-index GitNexus + Rebuild Graphify graph... ⏳
+```
+
+1. Run GitNexus `group_sync` — re-index the latest code structure
+   - MUST run BEFORE Graphify (Graphify needs the latest code structure)
+
+2. Run `/graphify` — rebuild graph with **docs only** (DO NOT rebuild code graph)
+   - Target: `.vsaf/docs/` folder — documents, artifacts, CONTEXT.md, KNOWLEDGE.md only
+   - Output: `graphify-out/graph.json` updated
+
+3. Claude verifies graph:
+   - Do new domain terms from CONTEXT.md have nodes in the graph?
+   - Do new patterns from KNOWLEDGE.md have nodes/edges?
+   - Are feature artifacts linked correctly?
+   - If missing → add to `graph.json`
+
+**This is the ONLY phase (besides onboard) allowed to modify `graphify-out/` and `.gitnexus/`.**
+
+```
+[FEATURE-COMPLETE] [4/5] Re-index GitNexus + Rebuild Graphify graph... ✅
+```

package/skills/sdlc/complete/status/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-complete-status
+description: "Feature Complete 5/5 — status + output"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Feature Complete 5/5 — status + output
+
+@include(step.md)

package/skills/sdlc/complete/status/step.md

@@ -0,0 +1,52 @@
+### Step 5: Update STATUS.md
+
+```
+[FEATURE-COMPLETE] [5/5] Updating STATUS.md... ⏳
+```
+
+Update `.vsaf/docs/STATUS.md`:
+- Move feature to "Knowledge Updated" status
+- Record completion timestamp
+
+```
+[FEATURE-COMPLETE] [5/5] Updating STATUS.md... ✅
+```
+
+## Output
+
+Print FEATURE COMPLETE REPORT:
+
+```
+═══════════════════════════════════════════
+  FEATURE COMPLETE: {feature-name}
+═══════════════════════════════════════════
+  Phase: 8 (Feature Complete — before ship)
+  
+  Knowledge updates:
+    - CONTEXT.md: +{N} domain terms
+    - KNOWLEDGE.md: +{N} patterns, +{M} decisions, +{K} gotchas
+    - GitNexus: re-indexed
+    - graph.json: +{N} nodes, +{M} edges (docs only)
+    
+  STATUS: Knowledge Updated — ready to ship
+  
+  Next: `/sdlc-ship` to create PR and ship
+═══════════════════════════════════════════
+```
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Output: CONTEXT.md, KNOWLEDGE.md, graph.json, GitNexus index updated
+- Suggestion: `/sdlc-ship` to commit + create PR
+
+Update `.vsaf/docs/STATUS.md`.
+
+## Rules
+
+- KNOWLEDGE.md is append-only — DO NOT edit old entries
+- GitNexus re-index BEFORE Graphify rebuild
+- Graph verification MUST run — do not skip
+- Graphify rebuild is docs only — DO NOT rebuild code graph in this phase
+- **This is the ONLY phase (besides onboard) allowed to modify `graphify-out/` and `.gitnexus/`**
+- This phase MUST run BEFORE ship — so knowledge is committed with the PR

package/skills/sdlc/discovery/brainstorm/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-discovery-brainstorm
+description: "Discovery 4/6 — dual brainstorming"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Discovery 4/6 — dual brainstorming
+
+@include(step.md)

package/skills/sdlc/discovery/brainstorm/step.md

@@ -0,0 +1,27 @@
+### Step 4: Dual Brainstorming
+
+```
+[DISCOVERY] [4/6] Dual brainstorming based on grill answers... ⏳
+```
+
+Two complementary brainstorming approaches:
+
+**4a — Structured brainstorm**
+
+Based on grill answers + system analysis, propose:
+- 2-3 viable approaches with trade-offs
+- Risk/constraint evaluation per approach
+- Recommended option with reasoning
+
+**4b — Creative brainstorm (BMAD)**
+
+Use `/bmad-brainstorming` to explore alternatives and uncover hidden risks:
+- Facilitator-led, diverse creative techniques
+- Goal: ≥20 ideas/alternatives before reorganizing
+- Surfaces edge cases the structured approach may miss
+
+Record both results in `01-discovery.md` — §Problem Statement (4a) + §Alternatives (4b).
+
+```
+[DISCOVERY] [4/6] Dual brainstorming based on grill answers... ✅
+```

package/skills/sdlc/discovery/domain/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-discovery-domain
+description: "Discovery 5/6 — domain research + code scan"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Discovery 5/6 — domain research + code scan
+
+@include(step.md)

package/skills/sdlc/discovery/domain/step.md

@@ -0,0 +1,13 @@
+### Step 5: Domain Research + Existing Code Scan
+
+```
+[DISCOVERY] [5/6] Domain research + existing code scan... ⏳
+```
+
+Use `/bmad-domain-research` — deep-dive domain knowledge.
+Use GitNexus `query` — find related code/patterns already available in the codebase.
+Record results in `01-discovery.md` §Domain Research + §Existing Code.
+
+```
+[DISCOVERY] [5/6] Domain research + existing code scan... ✅
+```

package/skills/sdlc/discovery/grill/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-discovery-grill
+description: "Discovery 3/6 — grill session"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Discovery 3/6 — grill session
+
+@include(step.md)

package/skills/sdlc/discovery/grill/step.md

@@ -0,0 +1,22 @@
+### Step 3: GRILL Session — ASK questions, do NOT suggest
+
+```
+[DISCOVERY] [3/6] Grill session — asking detailed questions... ⏳
+```
+
+Use `/bmad-advanced-elicitation` — grill questions BASED ON system understanding from Step 2.
+
+**STRICT RULES:**
+- ⛔ Do NOT offer suggestions or recommendations
+- ⛔ Do NOT say "I think we should do X"
+- ✅ ONLY ask questions
+- ✅ Questions MUST be specific, based on actual code/architecture analyzed
+- ✅ Correct example: "The current system has UserService handling auth. Do you want the new feature to interact with the existing auth flow or be separate?"
+- ✅ Correct example: "Route `/api/orders` currently returns 5 fields. What additional fields does the new feature need?"
+- ⛔ Wrong example: "I suggest using event-driven architecture for this feature"
+
+**WAIT** for the user to respond BEFORE continuing to Step 4.
+
+```
+[DISCOVERY] [3/6] Grill session — asking detailed questions... ✅
+```

package/skills/sdlc/discovery/prereq/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-discovery-prereq
+description: "Discovery 1/6 — prerequisites"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Discovery 1/6 — prerequisites
+
+@include(step.md)

package/skills/sdlc/discovery/prereq/step.md

@@ -0,0 +1,16 @@
+## Phase Entry Protocol
+
+```
+[DISCOVERY] [1/6] Checking prerequisites... ⏳
+```
+
+1. Receive feature request: `$ARGUMENTS`
+2. Check if `graphify-out/graph.json` exists:
+   - Does not exist → Ask: "Graph not found. Have you run onboarding?"
+3. Read `.vsaf/docs/STATUS.md` → confirm feature does not already exist or identify current phase
+4. Read `CONTEXT.md`
+5. Query `graph.json` for related business domain context
+
+```
+[DISCOVERY] [1/6] Checking prerequisites... ✅
+```

package/skills/sdlc/discovery/prfaq/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-discovery-prfaq
+description: "Discovery 6/6 — PRFAQ + output"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Discovery 6/6 — PRFAQ + output
+
+@include(step.md)

package/skills/sdlc/discovery/prfaq/step.md

@@ -0,0 +1,68 @@
+### Step 6: PRFAQ (if large feature)
+
+```
+[DISCOVERY] [6/6] PRFAQ (if needed)... ⏳
+```
+
+Use `/bmad-prfaq` — Working Backwards to force clarity.
+Record results in `01-discovery.md` §PRFAQ.
+If the feature is small, record "PRFAQ: Skipped — feature scope does not require it."
+
+```
+[DISCOVERY] [6/6] PRFAQ (if needed)... ✅
+```
+
+## Output
+
+Create directory `.vsaf/docs/features/{feature-name}/` if it does not exist.
+Write file: `.vsaf/docs/features/{feature-name}/01-discovery.md`
+
+```markdown
+# Discovery: {feature-name}
+
+## Grill Session
+{questions and answers from bmad-advanced-elicitation}
+
+## Problem Statement
+{from bmad-brainstorming, based on grill answers}
+
+## Domain Research
+{from bmad-domain-research}
+
+## Existing Code
+{from GitNexus query + context + route_map}
+
+## PRFAQ
+{from bmad-prfaq, if applicable}
+
+## Decision: Proceed / Pivot / Kill
+{recommendation on whether to continue, with reasoning}
+```
+
+## Artifact Auto-Save
+
+After writing the file, print the message:
+
+> Artifacts saved. If the session is interrupted, open a new session and run the next phase — data is safe.
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Feature: {feature-name}
+- Status: COMPLETED
+- Completed: system analysis, grill session, brainstorming, domain research, existing code scan, PRFAQ
+- Output files: `.vsaf/docs/features/{feature-name}/01-discovery.md`
+- Suggested next steps:
+  [1] Continue to Phase 2 PRD → `/sdlc-prd`
+  [2] Save artifacts
+
+Update `.vsaf/docs/STATUS.md`.
+
+## Rules
+
+- ⛔ Do NOT offer suggestions before asking — Grill session MUST happen before brainstorming
+- ⛔ Do NOT read detailed source code — only use GitNexus tools for high-level scanning
+- ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`
+- Every discovery must have a clear Decision: Proceed, Pivot, or Kill
+- If Decision = Kill → record reasoning, stop the flow
+- Questions in the grill session MUST be based on actual system understanding, NOT generic

package/skills/sdlc/discovery/system/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-discovery-system
+description: "Discovery 2/6 — existing system"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Discovery 2/6 — existing system
+
+@include(step.md)

package/skills/sdlc/discovery/system/step.md

@@ -0,0 +1,19 @@
+### Step 2: Understand Existing System FIRST
+
+```
+[DISCOVERY] [2/6] Analyzing current system via GitNexus... ⏳
+```
+
+BEFORE asking any questions, MUST understand the current system:
+
+1. Use GitNexus MCP tools:
+   - `query` — find code/patterns related to the feature request
+   - `route_map` — understand current API routes and flow
+   - `context` — 360° view of related symbols
+2. Read `graphify-out/graph.json` — understand relationships between concepts/modules
+
+Record analysis results internally (do NOT output to user at this step).
+
+```
+[DISCOVERY] [2/6] Analyzing current system via GitNexus... ✅
+```

package/skills/sdlc/hotfix/analyze/entry/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-analyze-entry
+description: "Hotfix Analyze 1/6 — read bug report"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Analyze 1/6 — read bug report
+
+@include(step.md)

package/skills/sdlc/hotfix/analyze/entry/step.md

@@ -0,0 +1,15 @@
+## Phase Entry Protocol
+
+```
+[HOTFIX-ANALYZE] [1/6] Reading bug report... ⏳
+```
+
+1. Input: `$ARGUMENTS` — path to bug report file from tester
+2. Read the bug report file
+3. Read `CONTEXT.md` for domain context
+4. Read `.vsaf/docs/STATUS.md`
+5. Extract a short `{bug-id}` from the report filename or title (e.g., `fix-null-rating`, `fix-auth-timeout`)
+
+```
+[HOTFIX-ANALYZE] [1/6] Reading bug report... ✅
+```

package/skills/sdlc/hotfix/analyze/exit/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-analyze-exit
+description: "Hotfix Analyze — exit protocol and rules"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Analyze — exit protocol and rules
+
+@include(step.md)

package/skills/sdlc/hotfix/analyze/exit/step.md

@@ -0,0 +1,19 @@
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Bug: {bug-id}
+- Status: ANALYSIS COMPLETED
+- Root cause: {one-line summary}
+- Affected files: {count} files
+- Output: `.vsaf/docs/hotfixes/{bug-id}/01-analysis.md`
+- Next step: `/sdlc-hotfix-prd`
+
+Update `.vsaf/docs/STATUS.md`.
+
+## Rules
+
+- ⛔ Do NOT modify code — analysis only
+- ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`
+- GitNexus impact analysis is MANDATORY — never skip it
+- Root cause must reference specific file:line, not vague descriptions
+- `/grill-me` is MANDATORY — used in Step 2 (clarify bug) and Step 5 (validate fix strategy)

package/skills/sdlc/hotfix/analyze/fix-strategy/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-analyze-fix-strategy
+description: "Hotfix Analyze 5/6 — grill fix strategy"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Analyze 5/6 — grill fix strategy
+
+@include(step.md)

package/skills/sdlc/hotfix/analyze/fix-strategy/step.md

@@ -0,0 +1,15 @@
+### Step 5: Grill Fix Strategy
+
+```
+[HOTFIX-ANALYZE] [5/6] Grill session — stress-testing fix strategy... ⏳
+```
+
+Use `/grill-me` again to stress-test the proposed fix strategy with the user:
+- Does the fix address the root cause, not just the symptom?
+- Are there edge cases the fix could miss?
+- Could the fix introduce regressions in related areas?
+- Is the fix scope appropriate for a hotfix (minimal)?
+
+```
+[HOTFIX-ANALYZE] [5/6] Fix strategy validated ✅
+```

package/skills/sdlc/hotfix/analyze/gitnexus/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-analyze-gitnexus
+description: "Hotfix Analyze 3/6 — root cause via GitNexus"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Analyze 3/6 — root cause via GitNexus
+
+@include(step.md)

package/skills/sdlc/hotfix/analyze/gitnexus/step.md

@@ -0,0 +1,17 @@
+### Step 3: Root Cause via GitNexus
+
+```
+[HOTFIX-ANALYZE] [3/6] Mapping code structure via GitNexus... ⏳
+```
+
+1. Use GitNexus `context` — understand the affected module's structure and dependencies
+2. Use GitNexus `impact` — trace which files and symbols are in the blast radius
+3. Use GitNexus `route_map` — map the call chain from entry point to suspected buggy code
+4. Collect:
+   - **Affected files** — files that contain or touch the suspected area
+   - **Call chain** — entry point → intermediate → suspected defect
+   - **Blast radius** — what else could break if this area is changed
+
+```
+[HOTFIX-ANALYZE] [3/6] Mapping code structure via GitNexus... ✅
+```

package/skills/sdlc/hotfix/analyze/grill/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-analyze-grill
+description: "Hotfix Analyze 2/6 — grill bug context"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Analyze 2/6 — grill bug context
+
+@include(step.md)

package/skills/sdlc/hotfix/analyze/grill/step.md

@@ -0,0 +1,23 @@
+### Step 2: Grill Session — Clarify Bug Context
+
+```
+[HOTFIX-ANALYZE] [2/6] Grill session — interviewing user about bug... ⏳
+```
+
+Use `/grill-me` to interview the user about the bug. Walk down each branch of the problem tree:
+- What exactly was observed? Under what conditions?
+- Can it be reproduced consistently? What are the exact steps?
+- When did it start? What changed recently?
+- What is the expected behavior vs actual behavior?
+- Which users/environments are affected?
+- Any workarounds discovered?
+
+Continue grilling until you have a complete understanding. Then extract:
+- **Symptoms** — what the tester/user observed
+- **Reproduction steps** — exact steps to trigger the bug
+- **Expected vs actual behavior**
+- **Affected area** — which feature/module/endpoint
+
+```
+[HOTFIX-ANALYZE] [2/6] Grill session complete ✅
+```