@ngocsangairvds/vsaf 5.1.5 → 5.1.7

package/skills/sdlc/hotfix/ship/commit-pr/step.md

@@ -0,0 +1,58 @@
+### 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 gitnexus analyze` and `/graphify` to re-index locally.
+```
+
+```
+[HOTFIX-SHIP] [4/5] Commit + push + create PR... ✅
+```

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

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-entry
+description: "Hotfix Ship 1/5 — check prerequisites"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 1/5 — check prerequisites
+
+@include(step.md)

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

@@ -0,0 +1,20 @@
+## 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... ✅
+```

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

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

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

@@ -0,0 +1,31 @@
+## 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/hotfix/ship/gitignore/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-gitignore
+description: "Hotfix Ship 2/5 — .gitignore enforcement"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 2/5 — .gitignore enforcement
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/gitignore/step.md

@@ -0,0 +1,22 @@
+### 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... ✅
+```

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

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-report
+description: "Hotfix Ship 5/5 — ship report"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 5/5 — ship report
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/report/step.md

@@ -0,0 +1,47 @@
+### 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 gitnexus analyze` — re-index code
+- `/graphify` — rebuild knowledge graph
+```
+
+```
+[HOTFIX-SHIP] [5/5] Writing ship report... ✅
+```

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

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-test-gate
+description: "Hotfix Ship 3/5 — final test gate"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 3/5 — final test gate
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/test-gate/step.md

@@ -0,0 +1,17 @@
+### 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... ✅
+```

package/skills/sdlc/implement/build-run/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-build-run
+description: "Implement 7/8 — build + run verification"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 7/8 — build + run verification
+
+@include(step.md)

package/skills/sdlc/implement/build-run/step.md

@@ -0,0 +1,85 @@
+### Step 7: Build & Run Verification
+
+```
+[IMPLEMENT] [7/8] Build & run verification... ⏳
+```
+
+**MANDATORY** — code MUST compile and run successfully before exiting the phase.
+
+1. **Compile check**: Build the entire project → MUST have 0 errors
+   - Java: `mvn compile` or `gradle build`
+   - Node: `npm run build` / `tsc --noEmit`
+   - Angular: `ng build`
+   - Go: `go build ./...`
+   - If FAIL → fix immediately, DO NOT skip
+
+2. **Run verification**: Start application → MUST start successfully
+   - If the project has `docker-compose.yml` → `docker compose up`
+   - If not → use native run command
+   - Check health endpoint / startup log OK
+
+3. **Environment check**:
+   - Detect required runtime (JDK, Node, Python, Go, etc.)
+   - If runtime missing → ⚠️ **WARNING**: "Missing {runtime}. Cannot verify build."
+   - **Recommend Docker**: "Recommend using Docker to ensure a consistent environment. Create a Dockerfile if one does not exist."
+   - If Docker available → prefer building in container
+
+4. **Test suite run**: `npm test` / `mvn test` / equivalent → All tests PASS
+
+5. **Final SonarQube sweep**: Scan all new code one last time before exiting
+   - Confirm both New Code and Overall Code conditions are green per the shared `quality-gate.md` (single source of truth)
+   - If FAIL → fix immediately, this is a hard gate
+
+⚠️ **DO NOT exit the phase if code does not compile.** This is a hard gate — no exceptions.
+
+```
+[IMPLEMENT] [7/8] Build & run verification... ✅
+```
+
+## Multi-machine Branching
+
+```
+Single repo:
+  main → feat/{feature} → feat/{feature}/epic-1 (Subagent A)
+                         → feat/{feature}/epic-2 (Subagent B)
+
+Multi-repo:
+  Subagent A: cd user-service && git checkout -b feat/{feature}
+  Subagent B: cd payment-service && git checkout -b feat/{feature}
+```
+
+## Output
+
+- `.vsaf/docs/features/{feature-name}/07-impl-plan.md` — task plan + TDD log
+- Code changes on feature branch
+- All tests GREEN
+- SonarQube metrics PASS (verified during coding)
+
+## Phase Exit Protocol
+
+In PHASE REPORT:
+- Done: N tasks completed, M tests written, K subagents dispatched
+- Result: all tests PASS/FAIL
+- SonarQube (New Code): {PASS/FAIL vs shared gate} — Issues={N}, Blocker={N}, Critical={N}, Major={N}, Code Smells={N}, Vulns={N}, Hotspots Reviewed={N}%, Duplication={N}%
+- SonarQube (Overall): {PASS/FAIL vs shared gate} — Bugs={N}, Code Smells={N}, Duplication={N}%, ratings={A..E}
+- Output files: `07-impl-plan.md`
+- Code changes: {list files changed}
+- Suggestions: [1] Phase 7 Review (`/sdlc-review`) [2] Save artifacts
+
+Update `.vsaf/docs/STATUS.md`.
+
+**Notify the user:**
+> Artifacts have been 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 (#2 TDD)
+- **MANDATORY** use `/superpowers:subagent-driven-development` — do not run sequential
+- **SonarQube rules apply DURING coding** — do not wait for review
+- Follow the Conflict Map — only modify files assigned to your epic
+- 3-strike rule: task fails 3 times → STOP, escalate
+- Impact analysis MUST run before each commit
+- Smart Zone: clear context every 5 tasks (#4)
+- **Code MUST compile successfully** — hard gate, no exceptions
+- **Recommend Docker** if runtime is missing or containerization is not set up
+- ⛔ DO NOT modify `graphify-out/` or `.gitnexus/`

package/skills/sdlc/implement/checkpoint/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-checkpoint
+description: "Implement 3.5/8 — checkpoint review"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 3.5/8 — checkpoint review
+
+@include(step.md)

package/skills/sdlc/implement/checkpoint/step.md

@@ -0,0 +1,20 @@
+### Step 3.5: Checkpoint Review (every 3-5 tasks)
+
+```
+[IMPLEMENT] [3.5/8] Checkpoint review... ⏳
+```
+
+After every 3-5 completed tasks: invoke `/bmad-checkpoint-preview` (human-in-the-loop walkthrough).
+
+Purpose: pause and let the user review progress before continuing.
+
+The checkpoint will:
+- Summarize: what was done, which files changed, current tests status
+- Highlight: points of concern, potential issues
+- Ask user: continue / adjust / stop?
+
+**Skip checkpoint if** the total plan has fewer than 5 tasks — checkpoint only at the end in that case.
+
+```
+[IMPLEMENT] [3.5/8] Checkpoint review... ✅
+```

package/skills/sdlc/implement/debug/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-debug
+description: "Implement 5/8 — debug if needed"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 5/8 — debug if needed
+
+@include(step.md)

package/skills/sdlc/implement/debug/step.md

@@ -0,0 +1,25 @@
+### Step 5: Debug (if needed)
+
+```
+[IMPLEMENT] [5/8] Debug (if there are test failures)... ⏳
+```
+
+Use `/superpowers:systematic-debugging` — when a test does not turn GREEN:
+- Hypothesis → Experiment → Conclusion
+- If it fails 3 times → STOP, escalate
+
+**Scope-drift detection:**
+
+If during implementation you detect the feature requires CHANGES NOT IN THE SRS:
+1. Invoke `/bmad-correct-course` — assess impact + propose adjustments
+2. If requirements have genuinely changed:
+   - STOP implementation
+   - Update SRS first via `/sdlc-srs` EDIT mode
+   - Re-run `/sdlc-test-design` to generate new test cases
+   - Restart Phase 6 from Step 3
+3. If only minor adjustments needed: document the adjustment in `07-impl-plan.md` §Scope Adjustments and continue
+4. If unclear whether scope changed: STOP and present to user — let them decide
+
+```
+[IMPLEMENT] [5/8] Debug (if there are test failures)... ✅
+```

package/skills/sdlc/implement/impact/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-impact
+description: "Implement 6/8 — impact verification"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 6/8 — impact verification
+
+@include(step.md)

package/skills/sdlc/implement/impact/step.md

@@ -0,0 +1,12 @@
+### Step 6: Impact Verification
+
+```
+[IMPLEMENT] [6/8] Impact verification via GitNexus... ⏳
+```
+
+Use GitNexus `impact` — verify no other code is broken.
+Use GitNexus `rename` — safe multi-file refactoring if needed.
+
+```
+[IMPLEMENT] [6/8] Impact verification via GitNexus... ✅
+```

package/skills/sdlc/implement/plan/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-plan
+description: "Implement 3/8 — task planning"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 3/8 — task planning
+
+@include(step.md)

package/skills/sdlc/implement/plan/step.md

@@ -0,0 +1,13 @@
+### Step 3: Task Planning
+
+```
+[IMPLEMENT] [3/8] Task planning from testcases + ADR... ⏳
+```
+
+Use `/superpowers:writing-plans` — create granular task plan from testcases + ADR.
+Each task maps to ≥1 FR/NFR.
+Write to `07-impl-plan.md`.
+
+```
+[IMPLEMENT] [3/8] Task planning from testcases + ADR... ✅
+```

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

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-prereq
+description: "Implement 1/8 — input artifacts"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 1/8 — input artifacts
+
+@include(step.md)

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

@@ -0,0 +1,21 @@
+## Phase Entry Protocol
+
+```
+[IMPLEMENT] [1/8] Checking input artifacts... ⏳
+```
+
+1. Input:
+   - `.vsaf/docs/features/{feature-name}/06-testcases.md`
+   - `.vsaf/docs/features/{feature-name}/03-adr.md`
+   - `.vsaf/docs/features/{feature-name}/04-epics.md`
+2. Verify ALL 3 files exist:
+   - Any file missing → Ask: "File not found. Have you pulled it yet?"
+3. Read `.vsaf/docs/STATUS.md`
+4. Read `CONTEXT.md`
+5. Query `graph.json` for code structure
+
+```
+[IMPLEMENT] [1/8] Checking input artifacts... ✅
+```
+
+**Note:** This phase MUST run via `/superpowers:subagent-driven-development` — dispatch parallel subagents for each epic according to the Conflict Map in `04-epics.md`.

package/skills/sdlc/implement/subagents/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-subagents
+description: "Implement 2/8 — subagent setup"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 2/8 — subagent setup
+
+@include(step.md)

package/skills/sdlc/implement/subagents/step.md

@@ -0,0 +1,38 @@
+## Subagent-Driven Development Protocol
+
+```
+[IMPLEMENT] [2/8] Initializing subagent-driven development... ⏳
+```
+
+**MANDATORY** — Check and activate `/superpowers:subagent-driven-development`:
+1. If not already in subagent mode → **switch immediately**
+2. Analyze `04-epics.md` → identify Conflict Map
+3. Dispatch each epic/story as a separate subagent running in parallel
+4. Each subagent follows the Conflict Map — only modify files assigned to its epic
+
+```
+[IMPLEMENT] [2/8] Initializing subagent-driven development... ✅
+```
+
+## SonarQube Quality Gate — Apply DURING Coding
+
+⚠️ **DO NOT wait for review phase.** Each subagent MUST self-check the `sonar-viettel` gate WHILE writing code.
+
+> **Standard (single source of truth):** **`.claude/skills/_shared/sdlc/sonar-viettel/quality-gate.md`** — full New Code + Overall Code tables, the 357-rule parameters, and the importable `sonar-viettel-profile.xml` / `sonar-viettel-gate.json`. **Read it.** Phase 7 (`/sdlc-review`) re-checks the **same** file — anything that passes here must pass there. Do NOT invent stricter or looser values.
+
+**Hard fails to self-check (summary — see the shared doc for the full gate):**
+- New Code: Issues / Blocker / Critical / Major / Vulnerabilities = **0**; Code Smells **≤ 20**; Security Hotspots Reviewed = **100%**; Duplicated **≤ 45%**; Maintainability / Reliability / Security Rating **≥ A**.
+- Overall Code: Bugs = **0**; Code Smells **≤ 50**; same Blocker/Critical/Major/Vuln/Duplication/rating rules.
+- Honour the parametrised rules — S107 (params), S3776 (complexity), S110 (inheritance), S1479 (switch), S1192 (literals), S2068/S2077 (secrets/injection), S100/S101/S115 (naming). **Thresholds live authoritatively in the profile XML** — derive them via the snippet in the shared `quality-gate.md`, do not memorise numbers.
+
+**How to apply during coding:**
+- **After each function** → self-review: security vulnerabilities? code smells? duplication?
+- **After each class** → check SOLID violations, naming conventions, interface segregation
+- **Before each commit** → scan changed files for: SQL injection, XSS, command injection, hardcoded secrets, null dereference, resource leaks, concurrency issues, duplicated blocks
+- **Auto-detect SonarQube:** check whether `sonar-scanner` is on PATH.
+  - Present → import the profile + gate from the shared folder, then run `sonar-scanner` incremental.
+  - Absent → print `Sonar not found → self-checklist mode` and self-review against the shared `quality-gate.md`. This is a fully supported path, not a fallback to apologise for — SonarQube is OPTIONAL.
+
+**Goal:** Review phase should only need to RE-CHECK, not find bugs for the first time.
+
+## Tasks

package/skills/sdlc/implement/tdd/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-tdd
+description: "Implement 4/8 — TDD cycle"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 4/8 — TDD cycle
+
+@include(step.md)

package/skills/sdlc/implement/tdd/step.md

@@ -0,0 +1,24 @@
+### Step 4: TDD Cycle (per subagent)
+
+```
+[IMPLEMENT] [4/8] TDD cycle — RED → GREEN → REFACTOR... ⏳
+```
+
+Use `/superpowers:test-driven-development`:
+
+For each test case in `06-testcases.md`:
+1. **RED**: Write test → run → MUST FAIL
+2. **GREEN**: Write minimal code → run → MUST PASS
+   - ⚠️ **While writing GREEN code** → apply SonarQube rules immediately:
+     - Do not create security vulnerabilities
+     - No code smells (long method, deep nesting)
+     - No duplicated code
+     - Null-safe, proper error handling
+3. **REFACTOR**: Clean code, do not change behavior
+   - Refactor MUST improve SonarQube metrics, not degrade them
+
+Use `/superpowers:executing-plans` — execute plan in order.
+
+```
+[IMPLEMENT] [4/8] TDD cycle — RED → GREEN → REFACTOR... ✅
+```

package/skills/sdlc/init/SKILL.md

@@ -23,6 +23,13 @@ Icon: `⏳` running, `✅` done, `❌` error.
 
 > ⛔ DO NOT modify `graphify-out/` or `.gitnexus/` — only READ and DO NOT write to these directories.
 
+## Artifact Write Boundary
+
+- Create generated knowledge, documentation, SDLC artifacts, reports, and agent-readable markdown only at the project root beside `.vsaf` or inside the root `.vsaf/` directory.
+- Do NOT create `docs/`, `.vsaf/`, `CONTEXT.md`, `AGENTS.md`, knowledge files, reports, or generated artifacts inside service/subproject folders.
+- For service-specific notes, write under root `.vsaf/docs/` using the service name in the path or filename.
+- Write inside a service/subproject folder only when the user explicitly authorizes that path, or when the task is a source-code/test change for that service.
+
 ## Input
 
 - Project path: `$ARGUMENTS` (or current directory)

package/skills/sdlc/onboard-code/SKILL.md

@@ -21,6 +21,13 @@ Icon: `⏳` running, `✅` done, `❌` error.
 
 > ⛔ DO NOT modify `graphify-out/` or `.gitnexus/` — only GitNexus tools are allowed to write to `.gitnexus/`.
 
+## Artifact Write Boundary
+
+- Create generated knowledge, documentation, SDLC artifacts, reports, and agent-readable markdown only at the project root beside `.vsaf` or inside the root `.vsaf/` directory.
+- Do NOT create `docs/`, `.vsaf/`, `CONTEXT.md`, `AGENTS.md`, knowledge files, reports, or generated artifacts inside service/subproject folders.
+- For service-specific notes, write under root `.vsaf/docs/` using the service name in the path or filename.
+- Write inside a service/subproject folder only when the user explicitly authorizes that path, or when the task is a source-code/test change for that service.
+
 ## Clear Responsibility Assignment
 
 | Tool | Scope | Notes |

package/skills/sdlc/onboard-docs/SKILL.md

@@ -22,6 +22,13 @@ Icon: `⏳` running, `✅` done, `❌` error.
 > ⛔ DO NOT modify `graphify-out/` or `.gitnexus/` DIRECTLY — only graphify is allowed to write to `graphify-out/`.
 > **Exception:** Phase 3 supplements nodes/edges directly into `graph.json` after graphify has built it — this is the only permitted direct modification.
 
+## Artifact Write Boundary
+
+- Create generated knowledge, documentation, SDLC artifacts, reports, and agent-readable markdown only at the project root beside `.vsaf` or inside the root `.vsaf/` directory.
+- Do NOT create `docs/`, `.vsaf/`, `CONTEXT.md`, `AGENTS.md`, knowledge files, reports, or generated artifacts inside service/subproject folders.
+- For service-specific notes, write under root `.vsaf/docs/` using the service name in the path or filename.
+- Write inside a service/subproject folder only when the user explicitly authorizes that path, or when the task is a source-code/test change for that service.
+
 ## Input
 
 - Project path: `$ARGUMENTS` (or current directory)