@ngocsangairvds/vsaf 5.5.0 → 5.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -142,7 +142,10 @@ Icon: `⏳` running, `✅` done, `❌` error.
|
|
|
142
142
|
- Code module (from GitNexus) → is there a corresponding business concept? (check graph.json)
|
|
143
143
|
- YES → record mapping
|
|
144
144
|
- NO → technical module (infra, utils) — OK, record note
|
|
145
|
-
17. Update `CONTEXT.md` with technical terms from code
|
|
145
|
+
17. Update `CONTEXT.md` with technical terms from code — IDEMPOTENTLY (never overwrite the whole file, never
|
|
146
|
+
blind-append; re-runs must not bloat it): PRESERVE the `## Shared Language` section written by onboard-docs;
|
|
147
|
+
own `## Cross-Domain Verification` + `## Technical Terms` — if a section exists REPLACE its body in place,
|
|
148
|
+
else append it; one row per mapping/term (dedupe, update rather than duplicate):
|
|
146
149
|
|
|
147
150
|
```markdown
|
|
148
151
|
## Technical Terms
|
|
@@ -155,7 +155,10 @@ Print conversion summary:
|
|
|
155
155
|
[ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
-
15. From the completed graph, extract domain terms → `CONTEXT.md`
|
|
158
|
+
15. From the completed graph, extract domain terms → `CONTEXT.md` — update IDEMPOTENTLY (never overwrite the
|
|
159
|
+
whole file, never blind-append; re-runs must not bloat it): ensure one top `# Project Context: {name}`
|
|
160
|
+
heading, then own the `## Shared Language` section — if it exists REPLACE its body in place, else append it;
|
|
161
|
+
leave other sections (`## Technical Terms`, `## Cross-Domain Verification`) untouched; one row per Term (dedupe).
|
|
159
162
|
16. Format Shared Language table:
|
|
160
163
|
|
|
161
164
|
```markdown
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
name: onboard-code
|
|
2
|
+
description: |
|
|
3
|
+
Onboard Code — GitNexus index + verify + environment setup + cross-domain verify (mirrors the
|
|
4
|
+
sdlc-onboard-code skill, one node per phase). Detect structure -> GitNexus index -> verify index ->
|
|
5
|
+
env/Docker -> cross-domain verify (reads graphify-out/graph.json from onboard-docs) -> summary.
|
|
6
|
+
GitNexus is the SINGLE SOURCE OF TRUTH for code; graphify/graph.json is docs-only and READ-ONLY here.
|
|
7
|
+
provider: claude
|
|
8
|
+
model: sonnet
|
|
9
|
+
nodes:
|
|
10
|
+
- id: detect-structure
|
|
11
|
+
description: Code 1/6 — detect project structure (single / multi-repo / non-git)
|
|
12
|
+
permission_mode: bypassPermissions
|
|
13
|
+
workspace: false
|
|
14
|
+
timeout: 900000
|
|
15
|
+
prompt: |
|
|
16
|
+
You are a Senior DevOps + Code Architect onboarding a codebase. Project path: $ARGUMENTS (or current dir).
|
|
17
|
+
Print `[ONBOARD-CODE] [1/6] Detect project structure... ⏳/✅`.
|
|
18
|
+
|
|
19
|
+
Determine structure: root `.git`? → single repo. No root `.git` → scan 1–2 levels for `.git/`:
|
|
20
|
+
found N → multi-repo/microservice (list {path, remote, branch}); none → non-git project.
|
|
21
|
+
Record the result under `## Project Structure` in `.vsaf/docs/onboarding/env-setup.md`.
|
|
22
|
+
Artifact boundary: write only at project root or under root `.vsaf/`. ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`.
|
|
23
|
+
|
|
24
|
+
- id: gitnexus-index
|
|
25
|
+
description: Code 2/6 — build the GitNexus code index (single unified index at project root)
|
|
26
|
+
workspace: false
|
|
27
|
+
timeout: 3600000
|
|
28
|
+
depends_on:
|
|
29
|
+
- detect-structure
|
|
30
|
+
bash: |
|
|
31
|
+
set -e
|
|
32
|
+
echo "[ONBOARD-CODE] [2/6] GitNexus index... ⏳"
|
|
33
|
+
# Use the LOCAL binary — do NOT use `npx -y gitnexus@latest` (native-module crash on Node 24+).
|
|
34
|
+
if [ -d .git ]; then
|
|
35
|
+
echo "[ONBOARD-CODE] git repo at root → npx gitnexus analyze ."
|
|
36
|
+
npx gitnexus analyze .
|
|
37
|
+
else
|
|
38
|
+
echo "[ONBOARD-CODE] no root .git → npx gitnexus analyze . --skip-git (covers sub-repos too)"
|
|
39
|
+
npx gitnexus analyze . --skip-git
|
|
40
|
+
fi
|
|
41
|
+
echo "[ONBOARD-CODE] [2/6] GitNexus index... ✅ (single .gitnexus/ at project root)"
|
|
42
|
+
|
|
43
|
+
- id: verify-index
|
|
44
|
+
description: Code 3/6 — map + verify the GitNexus index via MCP (do NOT trust blindly)
|
|
45
|
+
permission_mode: bypassPermissions
|
|
46
|
+
workspace: false
|
|
47
|
+
timeout: 1800000
|
|
48
|
+
depends_on:
|
|
49
|
+
- gitnexus-index
|
|
50
|
+
prompt: |
|
|
51
|
+
Print `[ONBOARD-CODE] [3/6] Verify GitNexus index... ⏳/✅`.
|
|
52
|
+
|
|
53
|
+
Claude MUST review the index — do not assume it is correct. Using the GitNexus MCP tools:
|
|
54
|
+
- `group_sync` if the index needs (re)syncing; `list_repos` — confirm the project root is indexed (one unified index).
|
|
55
|
+
- `route_map` — confirm API routes from ALL repos are mapped; `tool_map` + `context` on 3–5 key entry points per repo.
|
|
56
|
+
Check: main entry points indexed? inter-module dependencies correct? for multi-repo, cross-service calls
|
|
57
|
+
(HTTP/gRPC/event) captured? If something is missing, re-run `group_sync` or record
|
|
58
|
+
"{module/route} not indexed — needs manual review" in `.vsaf/docs/onboarding/env-setup.md`.
|
|
59
|
+
⛔ Only GitNexus writes `.gitnexus/`; do not edit it directly.
|
|
60
|
+
|
|
61
|
+
- id: env-docker
|
|
62
|
+
description: Code 4/6 — environment check + Docker setup suggestion
|
|
63
|
+
permission_mode: bypassPermissions
|
|
64
|
+
workspace: false
|
|
65
|
+
timeout: 1800000
|
|
66
|
+
depends_on:
|
|
67
|
+
- verify-index
|
|
68
|
+
prompt: |
|
|
69
|
+
Print `[ONBOARD-CODE] [4/6] Environment check + Docker setup... ⏳/✅`.
|
|
70
|
+
|
|
71
|
+
Detect the tech stack (read package.json, pom.xml, build.gradle, requirements.txt, Dockerfile, docker-compose.yml).
|
|
72
|
+
Check the current env (`java -version`, `node -v`, `docker -v`, `python3 --version`, …); compare required vs present
|
|
73
|
+
and suggest installs. Docker: if no Dockerfile/docker-compose.yml, suggest creating them (app + DB/cache/broker as needed);
|
|
74
|
+
if present, sanity-check the config. Record everything under `.vsaf/docs/onboarding/env-setup.md`
|
|
75
|
+
(this is the only md file this phase creates — no project-overview/codebase-map).
|
|
76
|
+
|
|
77
|
+
- id: cross-domain
|
|
78
|
+
description: Code 5/6 — cross-domain verify (GitNexus code ↔ docs graph.json) + technical terms
|
|
79
|
+
permission_mode: bypassPermissions
|
|
80
|
+
workspace: false
|
|
81
|
+
timeout: 1800000
|
|
82
|
+
depends_on:
|
|
83
|
+
- env-docker
|
|
84
|
+
prompt: |
|
|
85
|
+
Print `[ONBOARD-CODE] [5/6] Cross-domain verify... ⏳/✅`.
|
|
86
|
+
|
|
87
|
+
Read `graphify-out/graph.json` (the docs graph from onboard-docs — READ ONLY) and query the code via GitNexus (`query`, `context`). Cross-reference:
|
|
88
|
+
- business concept (graph.json) → is there a matching code module? YES → record `{concept} ↔ {module/class}`; NO → "{concept} not yet implemented".
|
|
89
|
+
- code module (GitNexus) → matching business concept? YES → mapping; NO → technical module (infra/utils), record as such.
|
|
90
|
+
Update `CONTEXT.md` IDEMPOTENTLY — never overwrite the whole file, and never blind-append (re-runs would bloat it). Manage BY SECTION:
|
|
91
|
+
- PRESERVE the `## Shared Language` section written by onboard-docs — do NOT delete or rewrite it.
|
|
92
|
+
- You OWN `## Cross-Domain Verification` (the concept↔module mappings above) and `## Technical Terms`
|
|
93
|
+
(table: | Term | Definition | Maps to Business Concept |). If a section already exists, REPLACE its body in place; otherwise append it.
|
|
94
|
+
- Keep ONE row per mapping/term (dedupe by key) — update rather than duplicate.
|
|
95
|
+
Flag any cross-database access. If `graphify-out/graph.json` is absent, note that onboard-docs must run first.
|
|
96
|
+
|
|
97
|
+
- id: summary
|
|
98
|
+
description: Code 6/6 — onboarding summary report
|
|
99
|
+
model: haiku
|
|
100
|
+
workspace: false
|
|
101
|
+
timeout: 600000
|
|
102
|
+
depends_on:
|
|
103
|
+
- cross-domain
|
|
104
|
+
prompt: |
|
|
105
|
+
Print `[ONBOARD-CODE] [6/6] Create summary report... ⏳/✅` then the report table:
|
|
106
|
+
Project structure / GitNexus index (N repos) / Index verification / Tech stack / Environment (ready or missing) /
|
|
107
|
+
Docker (exists or suggested) / Cross-domain mapping (N mapped, M gaps) / CONTEXT.md updated.
|
|
108
|
+
End with: "Artifacts saved. If interrupted, re-run the next phase — data is safe."
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
name: onboard-docs
|
|
2
|
+
description: |
|
|
3
|
+
Onboard Docs — build & verify the documentation knowledge graph (mirrors the sdlc-onboard-docs
|
|
4
|
+
skill, one node per phase). Scan/import docs -> graphify build -> Claude verify & supplement ->
|
|
5
|
+
extract domain terms. Graphify runs ONLY on docs (never source code — that is onboard-code/GitNexus).
|
|
6
|
+
provider: claude
|
|
7
|
+
model: sonnet
|
|
8
|
+
nodes:
|
|
9
|
+
- id: scan-import
|
|
10
|
+
description: Docs 1/4 — scan & import documents (markitdown conversion + tier fallbacks)
|
|
11
|
+
permission_mode: bypassPermissions
|
|
12
|
+
workspace: false
|
|
13
|
+
timeout: 1800000
|
|
14
|
+
prompt: |
|
|
15
|
+
You are a Knowledge Engineer onboarding project documents. Project path: $ARGUMENTS (or current dir).
|
|
16
|
+
Print progress as `[ONBOARD-DOCS] [1/4] Scan & import documents... ⏳/✅`.
|
|
17
|
+
|
|
18
|
+
1. Scan ALL documents: README, docs/, wiki/, specs/, *.md, *.txt (+ complex binaries). List them.
|
|
19
|
+
2. Resolve markitdown python:
|
|
20
|
+
VENVS=$(pipx environment --value PIPX_LOCAL_VENVS 2>/dev/null)
|
|
21
|
+
MARKITDOWN_PYTHON="${VENVS}/markitdown/bin/python" (fallback ~/.local/pipx/venvs/markitdown/bin/python)
|
|
22
|
+
If markitdown is missing, skip conversion and route ALL complex files through fallbacks (step 4).
|
|
23
|
+
3. Classify each complex file into a tier:
|
|
24
|
+
- Tier 1 (graphify-native): PDF, DOCX, XLSX, PNG, JPG, GIF, WEBP
|
|
25
|
+
- Tier 2 (graphify-blind): HTML, PPTX, EPUB, ZIP
|
|
26
|
+
- .md/.txt are NOT complex (read directly).
|
|
27
|
+
4. For each complex file: attempt `"$MARKITDOWN_PYTHON" "<this-skill-dir>/convert.py" --input {file} --output .vsaf/docs/onboarding/doc-imports/{name}.md`.
|
|
28
|
+
Verify the output has real content (not just headers, not an LLM refusal, not hallucinated). On success use it.
|
|
29
|
+
On failure/verify-fail: Tier 1 -> append original path to `.vsaf/docs/onboarding/graphify-direct-read.txt`;
|
|
30
|
+
Tier 2 HTML -> Read the file + write clean markdown to doc-imports/{name}.md; Tier 2 PPTX/EPUB/ZIP -> skip.
|
|
31
|
+
5. Print a conversion summary (markitdown OK / graphify-direct / Claude-Read / skipped counts).
|
|
32
|
+
|
|
33
|
+
Artifact boundary: write generated artifacts ONLY at project root or under root `.vsaf/`. ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`.
|
|
34
|
+
|
|
35
|
+
- id: graphify-build
|
|
36
|
+
description: Docs 2/4 — graphify build over a docs-only staging dir -> graph.json
|
|
37
|
+
permission_mode: bypassPermissions
|
|
38
|
+
workspace: false
|
|
39
|
+
timeout: 3600000
|
|
40
|
+
depends_on:
|
|
41
|
+
- scan-import
|
|
42
|
+
prompt: |
|
|
43
|
+
Print progress `[ONBOARD-DOCS] [2/4] Graphify build for docs... ⏳/✅`.
|
|
44
|
+
|
|
45
|
+
1. Create `.vsaf/docs/onboarding/graphify-staging/` and populate it with ALL doc inputs:
|
|
46
|
+
original text docs (.md/.txt/README), converted .md from `.vsaf/docs/onboarding/doc-imports/`,
|
|
47
|
+
and the original binaries listed in `.vsaf/docs/onboarding/graphify-direct-read.txt`.
|
|
48
|
+
This staging dir is the SINGLE input to graphify — it guarantees graphify sees docs only, never code.
|
|
49
|
+
2. Run `/graphify .vsaf/docs/onboarding/graphify-staging/`.
|
|
50
|
+
3. Output: `graphify-out/graph.json`.
|
|
51
|
+
|
|
52
|
+
⛔ CRITICAL: graphify is ONLY for docs — DO NOT run graphify on source code (code = GitNexus, in onboard-code).
|
|
53
|
+
Only graphify may write `graphify-out/`.
|
|
54
|
+
|
|
55
|
+
- id: verify-fix
|
|
56
|
+
description: Docs 3/4 — Claude verifies graph vs docs and supplements missing nodes/edges
|
|
57
|
+
permission_mode: bypassPermissions
|
|
58
|
+
workspace: false
|
|
59
|
+
timeout: 3600000
|
|
60
|
+
depends_on:
|
|
61
|
+
- graphify-build
|
|
62
|
+
prompt: |
|
|
63
|
+
Print progress `[ONBOARD-DOCS] [3/4] Verify & fix graph... ⏳/✅`.
|
|
64
|
+
|
|
65
|
+
Do NOT trust the graph blindly. For EACH original doc:
|
|
66
|
+
1. Re-read it — extract concepts, relationships, business rules, constraints.
|
|
67
|
+
2. Read `graphify-out/graph.json` — find the corresponding nodes/edges.
|
|
68
|
+
3. Compare: concept/relationship/rule present in the doc but missing in the graph = MISSING.
|
|
69
|
+
4. Supplement any MISSING nodes/edges DIRECTLY into `graph.json` (this Phase-3 supplementation is the
|
|
70
|
+
ONLY permitted direct write to graph.json). Report per doc: "{doc}: +N nodes, +M edges".
|
|
71
|
+
|
|
72
|
+
Every missing concept/relationship MUST be supplemented, not skipped.
|
|
73
|
+
|
|
74
|
+
- id: extract-terms
|
|
75
|
+
description: Docs 4/4 — extract domain terms from the graph into CONTEXT.md (Shared Language)
|
|
76
|
+
model: haiku
|
|
77
|
+
permission_mode: bypassPermissions
|
|
78
|
+
workspace: false
|
|
79
|
+
timeout: 900000
|
|
80
|
+
depends_on:
|
|
81
|
+
- verify-fix
|
|
82
|
+
prompt: |
|
|
83
|
+
Print progress `[ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳/✅`.
|
|
84
|
+
|
|
85
|
+
From the completed `graph.json`, extract DOMAIN terms (business vocabulary, not technical/code terms —
|
|
86
|
+
those are added later by onboard-code).
|
|
87
|
+
|
|
88
|
+
Update `CONTEXT.md` at the project root IDEMPOTENTLY — never overwrite the whole file, and never blind-append
|
|
89
|
+
(re-running onboarding would bloat it). Manage the file BY SECTION:
|
|
90
|
+
- Ensure a single top `# Project Context: {project-name}` heading (create once if missing).
|
|
91
|
+
- You OWN the `## Shared Language` section: if it already exists, REPLACE its body in place; otherwise append it.
|
|
92
|
+
Leave every other section (e.g. `## Technical Terms`, `## Cross-Domain Verification`) untouched.
|
|
93
|
+
- Keep ONE row per Term (dedupe by term name) — update an existing term's row instead of adding a duplicate.
|
|
94
|
+
|
|
95
|
+
## Shared Language
|
|
96
|
+
|
|
97
|
+
| Term | Definition | Example |
|
|
98
|
+
|------|-----------|---------|
|
|
99
|
+
| {term} | {1-line definition} | {concrete example} |
|
|
100
|
+
|
|
101
|
+
The graph is the single source of truth — do NOT create redundant overview/summary md files.
|
|
102
|
+
Then print: "Artifacts saved. If interrupted, re-run the next phase — data is safe."
|
|
@@ -1,11 +1,28 @@
|
|
|
1
1
|
name: onboarding
|
|
2
|
-
description:
|
|
2
|
+
description: |
|
|
3
|
+
Phase 0 — Onboarding orchestrator (utility; NOT part of the master SDLC flow). Runs the two
|
|
4
|
+
step-level phase workflows in ONE run/workspace via sub-workflow includes:
|
|
5
|
+
init artifact structure -> onboard-docs (docs knowledge graph) -> onboard-code (GitNexus index +
|
|
6
|
+
env/Docker + cross-domain verify). Ordering matters: onboard-code reads graphify-out/graph.json
|
|
7
|
+
produced by onboard-docs, so docs MUST run before code.
|
|
8
|
+
Prerequisite (one-time, per machine): run `/sdlc-setup` to install tooling (GitNexus, markitdown).
|
|
3
9
|
nodes:
|
|
4
|
-
- id:
|
|
5
|
-
description:
|
|
6
|
-
|
|
10
|
+
- id: init
|
|
11
|
+
description: Phase 0.1 — initialize .vsaf artifact structure (.vsaf/docs, CONTEXT.md, .gitignore)
|
|
12
|
+
model: haiku
|
|
13
|
+
permission_mode: bypassPermissions
|
|
7
14
|
workspace: false
|
|
15
|
+
timeout: 600000
|
|
16
|
+
command: sdlc-init
|
|
17
|
+
|
|
18
|
+
- id: docs
|
|
19
|
+
description: Phase 0.2 — onboard-docs (build + verify docs knowledge graph)
|
|
20
|
+
depends_on:
|
|
21
|
+
- init
|
|
22
|
+
workflow: sdlc/onboard-docs
|
|
23
|
+
|
|
8
24
|
- id: code
|
|
9
|
-
description:
|
|
10
|
-
|
|
11
|
-
|
|
25
|
+
description: Phase 0.3 — onboard-code (index code + env/Docker + cross-domain verify)
|
|
26
|
+
depends_on:
|
|
27
|
+
- docs
|
|
28
|
+
workflow: sdlc/onboard-code
|