@ngocsangairvds/vsaf 3.0.4 → 3.0.5

package/.claude/skills/vsaf-build/SKILL.md

@@ -1,44 +1,40 @@
 ---
 name: vsaf-build
-description: Implement code theo tài liệu spec đã có. Dùng sau /vsaf-doc, khi PRD và spec đã được approve. Tự động đọc memory trước khi code.
+description: Implement code theo tài liệu spec đã có. Dùng sau /vsaf-doc, khi PRD và plan đã được approve. Tự động search MemPalace trước khi code.
 ---
 
 # VSAF Build
 
 ## Mục tiêu
-Implement code đúng theo spec, từng task một, với TDD — đảm bảo mỗi commit có tests pass.
+Implement code đúng theo plan, từng task một, với TDD — đảm bảo mỗi commit có tests pass.
 
 ## Điều kiện tiên quyết
-- Đã chạy `/vsaf-doc` và có file spec trong `openspec/`
-- User đã approve plan
+- Đã chạy `/vsaf-doc` và có plan được approve
+- User đã xác nhận task list và verification steps
 
 ## Các bước thực hiện
 
-### Bước 1 — Đọc memory tự động trước khi code (bắt buộc)
-Thực hiện AUTO-READ từ `.claude/skills/vsaf-memory-protocol.md` với keyword là tên module/feature sắp implement.
+### Bước 1 — Search MemPalace trước khi code (bắt buộc)
+- Gọi `mcp__mempalace__mempalace_search` với keyword là tên module/feature sắp implement
+- Đảm bảo không có architectural decisions cũ xung đột với approach hiện tại
 
-### Bước 2 — Đọc spec
-- Đọc file spec trong `openspec/` liên quan đến feature hiện tại
+### Bước 2 — Đọc plan
+- Đọc file plan trong `docs/superpowers/plans/` liên quan đến feature hiện tại
 - Xác nhận task list và verification steps với user trước khi bắt đầu
 
 ### Bước 3 — Implement từng task (TDD)
-Với mỗi task trong spec:
+Với mỗi task trong plan:
 1. **RED**: Viết test trước, chạy test → phải fail
 2. **GREEN**: Viết code tối thiểu để test pass
 3. **REFACTOR**: Clean up code, giữ test vẫn pass
 4. Chạy `mcp__gitnexus__detect_changes` để verify chỉ đúng files thay đổi
-5. Chạy `/opsx:verify` để check task đúng spec
-6. Commit: `git commit -m "feat: <task description>"`
+5. Commit: `git commit -m "<type>: <task description>"`
 
-### Bước 4 — Security (tự động)
-- Security hooks chạy tự động — không cần gọi thủ công
-- Nếu bị block: đọc message, không dùng `--no-verify` để bypass
-
-### Bước 5 — Xử lý khi fail
+### Bước 4 — Xử lý khi fail
 - Fail 1-2 lần: thử approach khác
 - Fail 3 lần cùng 1 task: DỪNG, báo user, quay lại `/vsaf-plan`
 
-### Bước 6 — Output sau mỗi task
+### Bước 5 — Output sau mỗi task
 ```
 ✓ Task [N]: [tên task]
   - Files changed: [danh sách]

package/.claude/skills/vsaf-doc/SKILL.md

@@ -6,41 +6,33 @@ description: Viết tài liệu plan cho feature đã được phân tích. Dùn
 # VSAF Doc
 
 ## Mục tiêu
-Chuyển kết quả plan thành tài liệu chính thức: PRD, spec proposal, và task list có verification step.
+Chuyển kết quả plan thành tài liệu chính thức: PRD và task list có verification step.
 
 ## Điều kiện tiên quyết
 Phải đã chạy `/vsaf-plan` và có output trước khi chạy skill này.
 
 ## Các bước thực hiện
 
-### Bước 0 — Đọc memory tự động
-Thực hiện AUTO-READ từ `.claude/skills/vsaf-memory-protocol.md` với keyword từ feature hiện tại.
+### Bước 1 — Search MemPalace
+- Gọi `mcp__mempalace__mempalace_search` với keyword từ feature hiện tại
+- Kiểm tra có decision cũ nào cần reference không?
 
-### Bước 1 — Sinh PRD (BMAD pm)
+### Bước 2 — Sinh PRD (BMAD pm)
 - Dùng skill `bmad-agent-pm` để tạo PRD từ kết quả plan
 - PRD phải bao gồm: FRs, NFRs, Epics, User Stories
 - Lưu vào `docs/` theo cấu trúc project
 
-### Bước 2 — Tạo spec proposal (OpenSpec)
-- Dùng skill `opsx:propose` với tên feature
-- OpenSpec sẽ tạo task list atomic (mỗi task 2-5 phút)
-- Mỗi task PHẢI có verification step rõ ràng
-- Lưu vào `openspec/`
-
-### Bước 3 — Fast-forward docs (OpenSpec)
-- Dùng skill `opsx:explore` để sync tất cả docs liên quan
-- Đảm bảo không có inconsistency giữa PRD và spec
-
-### Bước 4 — Chi tiết hoá task list (Superpowers)
-- Dùng skill `superpowers:writing-plans` để review và làm rõ task list
+### Bước 3 — Chi tiết hoá task list (Superpowers)
+- Dùng skill `superpowers:writing-plans` để tạo task list chi tiết
 - Kiểm tra: mỗi task có đủ context để implement không?
 - Kiểm tra: verification step có đo lường được không?
+- Mỗi task phải atomic (2-5 phút work)
 
-### Bước 5 — Lưu architecture decision (MemPalace)
+### Bước 4 — Lưu architecture decision (MemPalace)
 - Gọi `mcp__mempalace__mempalace_add_drawer` để lưu decision quan trọng
 - Nội dung: approach được chọn, lý do, alternatives đã bỏ qua
 
-### Bước 6 — Output cho user
+### Bước 5 — Output cho user
 Thông báo các file đã tạo:
 
 ```
@@ -49,8 +41,8 @@ Thông báo các file đã tạo:
 ### PRD
 - docs/[feature]-prd.md
 
-### Spec
-- openspec/[feature]-spec.md
+### Plan
+- docs/superpowers/plans/[feature].md
   - [X] tasks, mỗi task có verification step
 
 ### Architecture Decision
@@ -63,4 +55,4 @@ Chạy /vsaf-build để bắt đầu implement
 ## Lưu ý
 - Không bắt đầu code trong bước này
 - Nếu task list quá dài (>10 tasks): đề nghị split thành nhiều PRs
-- Commit docs trước khi chuyển sang build: `git commit -m "spec: <feature>"`
+- Commit docs trước khi chuyển sang build: `git commit -m "docs: plan for <feature>"`

package/.claude/skills/vsaf-onboard/SKILL.md

@@ -10,26 +10,19 @@ Xây dựng full mental model về dự án trước khi chạm vào bất kỳ
 
 ## Các bước thực hiện
 
-### Bước 0 — Đọc memory tự động
-Thực hiện AUTO-READ từ `.claude/skills/vsaf-memory-protocol.md` với keyword "architecture".
-
-### Bước 1 — Kiến trúc tổng thể (Graphify)
-- Đọc file `graphify-out/GRAPH_REPORT.md` nếu đã tồn tại
-- Nếu chưa có: thông báo user chạy `/graphify .` để build graph trước
-- Tóm tắt: các module chính, dependencies, entry points
-
-### Bước 2 — Code intelligence (GitNexus)
-- Dùng `mcp__gitnexus__context` để lấy codebase overview
+### Bước 1 — Code intelligence (GitNexus)
+- Dùng `mcp__gitnexus__query` với query rộng (ví dụ: "main entry point", "core module") để lấy codebase overview
 - Dùng `mcp__gitnexus__group_list` để xem các functional clusters
+- Nếu cần drill-down symbol cụ thể: dùng `mcp__gitnexus__context` với param `name` là tên symbol đó
 - Tóm tắt: execution flows quan trọng, symbols có nhiều dependencies nhất
 
-### Bước 3 — Decisions cũ (MemPalace)
+### Bước 2 — Decisions cũ (MemPalace)
 - Gọi `mcp__mempalace__mempalace_search` với query "architecture"
 - Gọi `mcp__mempalace__mempalace_search` với query "decision"
 - Gọi `mcp__mempalace__mempalace_search` với query "pattern"
 - Tóm tắt: các quyết định kiến trúc quan trọng team đã đưa ra
 
-### Bước 4 — Output cho user
+### Bước 3 — Output cho user
 Trình bày tóm tắt theo format:
 
 ```
@@ -51,5 +44,5 @@ Trình bày tóm tắt theo format:
 
 ## Lưu ý
 - KHÔNG sửa bất kỳ file nào trong bước này
-- Nếu bộ nhớ MemPalace trống: thông báo user chạy `mempalace mine` để populate
+- Nếu bộ nhớ MemPalace trống: thông báo user chạy `vsaf mine` để populate
 - Sau khi hoàn thành: gợi ý user dùng `/vsaf-plan <feature>` để bắt đầu task

package/.claude/skills/vsaf-plan/SKILL.md

@@ -9,12 +9,14 @@ description: Lên plan cho 1 feature/task mới. Dùng khi nhận được yêu
 Hiểu đầy đủ yêu cầu, phân tích impact, và xác định chiến lược implement trước khi viết bất kỳ dòng code nào.
 
 ## Input
-`$ARGUMENTS` — mô tả feature/task cần làm (ví dụ: "tạo module quản lý dashboard")
+`<feature>` — mô tả feature/task cần làm (ví dụ: "tạo module quản lý dashboard")
 
 ## Các bước thực hiện
 
-### Bước 1 — Đọc memory tự động (bắt buộc)
-Thực hiện AUTO-READ từ `.claude/skills/vsaf-memory-protocol.md` với keyword từ `$ARGUMENTS`.
+### Bước 1 — Search MemPalace (bắt buộc)
+- Gọi `mcp__mempalace__mempalace_search` với keyword từ `<feature>`
+- Tìm kiếm: past decisions, architectural patterns, previous attempts
+- Tóm tắt: có decision nào liên quan không?
 
 ### Bước 2 — Clarify scope (BMAD analyst)
 - Dùng skill `bmad-agent-analyst` để phân tích yêu cầu
@@ -25,20 +27,17 @@ Thực hiện AUTO-READ từ `.claude/skills/vsaf-memory-protocol.md` với keyw
 - Dùng `mcp__gitnexus__impact` với target là module/symbol liên quan
 - Dùng `mcp__gitnexus__query` để tìm code liên quan
 - Báo cáo blast radius: bao nhiêu module bị ảnh hưởng, risk level
+- Nếu risk HIGH/CRITICAL: DỪNG, báo user trước khi tiếp tục
 
-### Bước 4 — Trace dependencies (Graphify)
-- Nếu cần trace path giữa 2 services: dùng `/graphify path ServiceA ServiceB`
-- Xác định: integration points, shared dependencies
-
-### Bước 5 — Architecture decision (BMAD architect)
+### Bước 4 — Architecture decision (BMAD architect)
 - Dùng skill `bmad-agent-architect` để đề xuất architecture approach
 - So sánh alternatives, chọn approach phù hợp nhất
 
-### Bước 6 — Brainstorm (Superpowers)
+### Bước 5 — Brainstorm (Superpowers)
 - Dùng skill `superpowers:brainstorming` để explore alternatives
 - Đặt câu hỏi Socratic: "What if...", "What could go wrong..."
 
-### Bước 7 — Output cho user
+### Bước 6 — Output cho user
 Trình bày kết quả theo format:
 
 ```

package/.claude/skills/vsaf-ship/SKILL.md

@@ -15,54 +15,38 @@ description: Review 3 lớp, ship code, và ghi lại toàn bộ knowledge vào
 ## Các bước thực hiện
 
 ### Bước 1 — Review Layer 1: Methodology (Superpowers)
-- Dùng skill `superpowers:requesting-code-review`
+- Dùng skill `superpowers:code-review`
 - Kiểm tra: code structure, naming, patterns, SOLID principles
 - Fix issues nếu có, commit lại
 
-### Bước 2 — Review Layer 2: Spec compliance (OpenSpec)
-- Dùng skill `opsx:verify` (hoặc `make verify`)
-- Kiểm tra: code có implement đúng tất cả FRs/NFRs trong spec không
-- Nếu fail: quay lại `/vsaf-build` để fix
-
-### Bước 3 — Review Layer 3: Security (Security)
-- Chạy `vsaf verify`
-- Fix tất cả issues trước khi tiếp tục
-- Không skip warnings
-
-### Bước 4 — Re-index knowledge graph
+### Bước 2 — Review Layer 2: Knowledge graph sync
 - Chạy `gitnexus analyze` để cập nhật call graph
-- Chạy `/graphify . --update` để cập nhật visual graph
-- Hoặc: `make index`
-
-### Bước 5 — Archive spec
-- Dùng skill `opsx:archive` để đóng spec proposal đã hoàn thành
-- Lưu vào `openspec/archived/`
+- Hoặc: `vsaf index`
+- Đây là layer cuối cùng — đảm bảo index reflect đúng code mới
 
-### Bước 6 — Ghi nhớ tự động (MemPalace)
-Thực hiện AUTO-WRITE từ `.claude/skills/vsaf-memory-protocol.md`.
+### Bước 3 — 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
 
-### Bước 9 — Push PR
+### Bước 4 — Push PR
 ```bash
 git push origin feature/<name>
 ```
 PR description phải bao gồm:
-- Link OpenSpec proposal
 - Impact summary (từ GitNexus)
 - Test results summary
 
-### Bước 10 — Output cho user
+### Bước 5 — Output cho user
 ```
 ## Ship Complete: [feature]
 
 ### Reviews
 - Layer 1 (Methodology): PASS
-- Layer 2 (Spec):         PASS
-- Layer 3 (Security):     PASS
+- Layer 2 (Graph sync):   PASS
 
 ### Knowledge saved
 - Diary entry: ✓
 - Decisions: [X entries]
-- Reasoning chain: ✓
 
 ### PR
 - Branch: feature/[name]
@@ -73,4 +57,4 @@ Workflow hoàn tất. Chạy /vsaf-plan <next-feature> cho task tiếp theo.
 
 ## Lưu ý
 - Không ship nếu bất kỳ layer review nào fail
-- `mempalace mine ~/chats/` — chạy weekly, không phải mỗi feature
+- `vsaf mine` — chạy weekly, không phải mỗi feature

package/.claude/skills/vsaf-test/SKILL.md

@@ -10,14 +10,14 @@ Tạo tài liệu test coverage đầy đủ từ spec, sau đó thực thi và
 
 ## Điều kiện tiên quyết
 - Đã chạy `/vsaf-build` và tất cả tasks đã commit
-- Có file spec trong `openspec/`
+- Có file PRD trong `docs/` (được tạo bởi `/vsaf-doc`)
 
 ## Các bước thực hiện
 
 ### Bước 1 — Sinh test cases từ spec (BMAD qa)
-- Dùng skill `bmad-qa-generate-e2e-tests` với spec file làm input
+- Dùng skill `bmad-qa-generate-e2e-tests` với PRD file trong `docs/` làm input
 - Test cases phải cover: happy path, edge cases, error cases, NFRs
-- Nguồn gốc: từ FRs/NFRs trong spec — KHÔNG dựa trên implementation
+- Nguồn gốc: từ FRs/NFRs trong PRD — KHÔNG dựa trên implementation
 
 ### Bước 2 — Đối chiếu coverage
 - So sánh test cases với task list trong spec

package/README.md

@@ -1,8 +1,8 @@
 # VSAF — SDLC Agentic Framework
 
-A spec-driven development framework for Claude Code. Write specs first, let AI
-agents plan and execute, review in 3 layers, track every decision. 8 integrated
-tools, $20/month total.
+A development framework for Claude Code built on 4 integrated tools. Plan with
+AI agents, understand impact before coding, execute with TDD guardrails, track
+every decision. $20/month total.
 
 ---
 
@@ -10,13 +10,17 @@ tools, $20/month total.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────┐
-│  PLANNING          BMAD (agents) ──▶ OpenSpec (specs, tasks, verify) │
+│  PLANNING          BMAD (agents)                                      │
+│                    Analyst, PM, Architect, Product Owner              │
 ├──────────────────────────────────────────────────────────────────────┤
-│  CODE INTEL        GitNexus (MCP backbone) + Graphify (multimodal)   │
+│  CODE INTEL        GitNexus (MCP backbone)                            │
+│                    call-graph, impact analysis, blast radius          │
 ├──────────────────────────────────────────────────────────────────────┤
-│  MEMORY            claude-mem (auto) + MemPalace (knowledge base)    │
+│  MEMORY            MemPalace (knowledge base)                         │
+│                    architecture decisions, temporal KG                │
 ├──────────────────────────────────────────────────────────────────────┤
-│  IMPLEMENTATION    Claude Code + Superpowers + security guardrails       │
+│  IMPLEMENTATION    Claude Code + Superpowers                          │
+│                    brainstorm, TDD execution, code review             │
 └──────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -24,14 +28,13 @@ See [1-setup-guide.md](docs/onboarding/1-setup-guide.md#2-how-the-tools-fit-toge
 
 ## Quickstart
 
-Requires **Node.js ≥ 18**, **Python ≥ 3.10**, **Git**, **jq**, and a
+Requires **Node.js ≥ 18**, **Python ≥ 3.10**, **Git**, and a
 **Claude Code subscription** ($20/mo). Full prerequisites in
 [1-setup-guide.md](docs/onboarding/1-setup-guide.md#3-prerequisites).
 
 ```bash
 git clone <this-repo> && cd vsaf
 npx @ngocsangairvds/vsaf@latest init
-npx @ngocsangairvds/vsaf@latest index
 npx @ngocsangairvds/vsaf@latest status
 ```
 
@@ -64,18 +67,18 @@ first 30 days.
 ```
 .
 ├── .claude/
-│   ├── settings.json       # Local AI settings (optional hook policy)
-│   └── skills/              # Coding standards for Go, Rust, Python
+│   ├── settings.json       # Local AI settings (hook policy)
+│   └── skills/             # VSAF + BMAD + GitNexus skills
+├── _bmad/                  # BMAD agent workspace
+├── _bmad-output/           # BMAD generated artifacts (PRDs, arch docs)
 ├── docs/
-│   ├── architecture/        # Architecture documents (from BMAD Architect)
-│   └── onboarding/          # Developer onboarding (see table above)
-├── githooks/                # Optional local hooks (disabled by default)
-├── graphify-out/            # Graphify output (gitignored, regenerated by `vsaf index`)
-├── openspec/                # OpenSpec workspace (proposals, specs, designs, tasks)
+│   ├── architecture/       # Architecture documents (from BMAD Architect)
+│   └── onboarding/         # Developer onboarding (see table above)
+├── assets/templates/       # Project scaffold templates
 ├── scripts/
 │   └── setup-vsaf.sh       # Full setup automation (used by `vsaf init`)
-├── CLAUDE.md                # Claude Code system prompt — workflow rules
-└── Makefile                 # Legacy wrapper (optional; use `vsaf` commands)
+├── CLAUDE.md               # Claude Code system prompt — workflow rules
+└── AGENTS.md               # GitNexus rules for AI agents
 ```
 
 ## Daily Operations
@@ -85,18 +88,15 @@ Run `npx @ngocsangairvds/vsaf@latest --help` for the full list. Highlights:
 | Command | What It Does |
 |---|---|
 | `vsaf init` | Install or update all tools |
-| `vsaf index` | Re-index codebase (GitNexus + Graphify) — run after every merge |
-| `vsaf verify` | Check implementation against OpenSpec specs |
-| `vsaf review` | Full 3-layer review coordinator |
+| `vsaf index` | Re-index codebase (GitNexus) — run after every merge |
+| `vsaf review` | 2-layer review coordinator |
 | `vsaf status` | Show status of all installed tools |
-
-All commands — including BMAD agents, OpenSpec, Superpowers, and GitNexus — are
-listed in [3-cheatsheet.md](docs/onboarding/3-cheatsheet.md).
+| `vsaf mine` | Extract decisions from conversations into MemPalace |
 
 ## Workflow
 
-Every feature follows a **10-step cycle**: scope → plan → spec → impact
-analysis → brainstorm → TDD execute → 3-layer review → push → archive.
+Every feature follows an **8-step cycle**: scope → plan → impact analysis →
+brainstorm → TDD execute → 2-layer review → push.
 Bug fixes ("Quick Flow") skip planning steps and go straight to brainstorm.
 
 See [1-setup-guide.md § Your First Project](docs/onboarding/1-setup-guide.md#5-your-first-project--a-walkthrough)
@@ -109,16 +109,12 @@ for a full command-by-command example.
 |---|---|---|
 | **Claude Code** | AI coding agent — everything else plugs into it | $20/mo |
 | **BMAD Method** | AI agents for planning: Analyst, PM, Architect, Product Owner | Free |
-| **OpenSpec** | Spec-driven development: proposals, specs, designs, task lists, verification | Free |
 | **Superpowers** | Methodology engine: brainstorm, plan, TDD execution, code review | Free |
-| **Security guardrails** | Optional hooks/policies + coding standards (team-defined security scanning) | Free |
 | **GitNexus** | Code knowledge graph via MCP — impact analysis, dependency queries | Free |
-| **Graphify** | Multimodal knowledge graph — visual dependency maps, path tracing | Free |
-| **claude-mem** | Auto-pilot memory — captures sessions, re-injects context next time | Free |
 | **MemPalace** | Knowledge base — verbatim storage of decisions, temporal knowledge graph | Free |
 
 ---
 
-**Core principles:** Spec before code. Context is king. Git is source of truth.
-3-layer review before every PR. Re-index after every merge. Mine decisions
-weekly. Hooks are optional in the current simplified setup.
+**Core principles:** Plan before code. Impact analysis before touching any symbol.
+2-layer review before every PR. Re-index after every merge. Mine decisions
+weekly. MemPalace = decisions. Not CLAUDE.md.