@ngocsangairvds/vsaf 3.0.12 → 3.1.1

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

@@ -1,90 +1,116 @@
 ---
 name: vsaf-build
-description: Implement code theo SRS + testcase đã có. Dùng sau /vsaf-doc và /vsaf-test. Tự động search MemPalace trước khi code.
+description: Implement code following existing PRD + SRS + testcases. Use after /vsaf-doc-srs and /vsaf-test. Brainstorm before plan, TDD with verification after each task.
 ---
 
 # VSAF Build
 
-## Mục tiêu
-Implement code đúng theo SRS và testcase, từng task một, với TDD — đảm bảo mỗi commit có tests pass.
+## Objective
+Implement code strictly following PRD, SRS, and testcases, one task at a time, with TDD — ensuring each commit has tests passing AND is verified against spec.
 
-## Điều kiện tiên quyết
-- Đã chạy `/vsaf-doc` và có SRS được approve
-- Đã chạy `/vsaf-test` và có testcase docs (implementation readiness = PASS)
-- User đã xác nhận phạm vi implement
+## Prerequisites
+- Have run `/vsaf-doc-prd` and have an approved PRD
+- Have run `/vsaf-doc-srs` and have an approved SRS
+- Have run `/vsaf-test` and have testcase docs (implementation readiness = PASS)
+- User has confirmed the implementation scope
 
-## Các bước thực hiện
+## Execution Steps
 
-### Bước 0 — Kiểm tra Superpowers (bắt buộc kiểm tra)
-- Kiểm tra xem Superpowers plugin đã được cài trong Claude Code chưa
-- Nếu **chưa cài** → hiển thị:
+### Step 0 — Check Superpowers (mandatory check)
+- Check whether the Superpowers plugin is installed in Claude Code
+- If **not installed** → display:
   ```
-  ⚠️  Superpowers chưa được cài đặt.
-  Superpowers giúp tăng chất lượng implement (TDD execution, plan execution, debugging, code review).
-  Để cài, chạy trong Claude Code:
+  ⚠️  Superpowers is not installed.
+  Superpowers improves implementation quality (TDD execution, plan execution, debugging, code review).
+  To install, run in Claude Code:
     /plugin install superpowers@claude-plugins-official
-  Sau đó restart Claude Code.
+  Then restart Claude Code.
 
-  → Tiếp tục build không có Superpowers (fallback mode).
+  → Continuing build without Superpowers (fallback mode).
   ```
-- Nếu **đã cài** → ghi nhận `HAS_SUPERPOWERS = true`, hiển thị:
+- If **installed** → record `HAS_SUPERPOWERS = true`, display:
   ```
-  ✓ Superpowers available — sẽ sử dụng: execute-plan, test-driven-development, code-review
+  ✓ Superpowers available — will use: brainstorming, writing-plans, executing-plans, test-driven-development, verification-before-completion
   ```
 
-### 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 SRS + testcase
-- Đọc file SRS trong `docs/project/srs/`
-- Đọc file testcase trong `docs/project/testcases/`
-- Xác nhận mapping FR/NFR -> testcase trước khi bắt đầu
-
-### Bước 3 — Sinh plan từ SRS (có/không Superpowers)
-- **Nếu HAS_SUPERPOWERS**: dùng `superpowers:write-plan` để sinh atomic task list từ SRS + testcase
-- **Nếu không**: tự tạo task list thủ công từ FR/NFR → testcase mapping
-- Mỗi task phải có verification step rõ ràng
-
-### Bước 4 — Implement từng task (TDD)
-- **Nếu HAS_SUPERPOWERS**: dùng `superpowers:execute-plan` — tự động chạy TDD cycles (RED → GREEN → REFACTOR) theo plan
-  - Superpowers sẽ gọi `superpowers:test-driven-development` cho mỗi task
-  - Nếu plan lớn (20+ tasks): dùng `superpowers:subagent-driven-development` để dispatch song song
-- **Nếu không**: implement thủ công theo TDD:
-  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
-- Sau mỗi task: chạy `mcp__gitnexus__detect_changes` để verify chỉ đúng files thay đổi
-- Commit: `git commit -m "<type>: <task description>"`
-
-### Bước 4.5 — Checkpoint review (mỗi 3-5 tasks)
-- Sau mỗi 3-5 tasks hoàn thành: dùng skill `bmad-checkpoint-preview`
-- Mục đích: human-in-the-loop review — "walk me through changes so far"
-- Checkpoint sẽ:
-  - Tóm tắt: đã làm gì, files nào thay đổi, tests status
-  - Highlight: điểm cần chú ý, potential issues
-  - Hỏi user: tiếp tục / điều chỉnh / dừng?
-- **Bỏ qua checkpoint nếu**: plan < 5 tasks tổng (chỉ checkpoint cuối)
-
-### Bước 5 — Xử lý khi fail hoặc scope drift
-- **Nếu HAS_SUPERPOWERS**: dùng `superpowers:systematic-debugging` — bắt buộc hypothesis → experiment → conclusion
-- **Nếu không**: thử approach khác thủ công
-- Fail 3 lần cùng 1 task: DỪNG, báo user, quay lại `/vsaf-plan`
-- **Nếu phát hiện scope drift** (feature cần thay đổi lớn so với SRS):
-  - Dùng skill `bmad-correct-course` để đánh giá impact + đề xuất điều chỉnh
-  - DỪNG và trình bày cho user: tiếp tục với điều chỉnh / quay lại `/vsaf-plan` re-plan
-
-### Bước 6 — Output sau mỗi task
+### Step 1 — Read PRD + SRS + testcase (mandatory — must read all 3 fully)
+- Read the PRD file in `docs/project/planning-artifacts/` — understand WHY and WHAT
+- Read the SRS file in `docs/project/srs/` — understand HOW, FRs/NFRs
+- Read the testcase file in `docs/project/testcases/` — understand acceptance criteria
+- Confirm FR/NFR → testcase mapping before starting
+- If a gap is found (FR/NFR without testcase, or testcase contradicts SRS): NOTIFY USER before continuing
+- **Do NOT start coding without having read all 3 documents**
+
+### Step 1b — Brainstorm implementation approaches (mandatory)
+- **If HAS_SUPERPOWERS**: use `superpowers:brainstorming` — structured exploration:
+  - Brainstorm 2-3 implementation approaches
+  - Evaluate trade-offs, risks, constraints for each approach
+  - Choose the best approach before committing to a plan
+- **If not**: brainstorm manually — list at least 2 approaches, choose 1 with clear reasoning
+- **Do NOT jump straight into planning without brainstorming**
+
+### Step 2 — Generate plan from SRS (with/without Superpowers)
+- **If HAS_SUPERPOWERS**: use `superpowers:writing-plans` to generate an atomic task list from SRS + testcase
+- **If not**: manually create a task list from FR/NFR → testcase mapping
+- Each task must:
+  - Map to ≥1 FR/NFR
+  - Have a clear verification step
+  - Be small enough for 1 commit
+
+### Step 2b — Subagent dispatch (large plans, optional)
+- If plan has ≥ 20 tasks AND HAS_SUPERPOWERS: use `superpowers:subagent-driven-development`
+  - Dispatch tasks to sub-agents with a two-phase review pipeline
+  - Each sub-agent still runs its own TDD cycle (RED → GREEN → REFACTOR)
+  - Review phase ensures consistent output
+
+### Step 3 — Implement each task (TDD + Verification)
+- **If HAS_SUPERPOWERS**: use `superpowers:executing-plans` — automatically runs TDD cycles following the plan
+  - Superpowers will call `superpowers:test-driven-development` for each task
+- **If not**: implement manually following TDD:
+  1. **RED**: Write test first, run test → must fail
+  2. **GREEN**: Write minimal code to make the test pass
+  3. **REFACTOR**: Clean up code, keep tests passing
+
+- After each task, run sequentially:
+  1. `mcp__gitnexus__detect_changes` — verify only the expected files changed
+  2. **Verification against spec** (mandatory):
+     - **If HAS_SUPERPOWERS**: use `superpowers:verification-before-completion` — confirm outcome matches SRS intent, not just "tests pass"
+     - **If not**: self-verify: re-read the corresponding FR/NFR in SRS, confirm behavior is correct, record verification result
+  3. Commit: `git commit -m "<type>: <task description>"`
+
+### Step 3.5 — Checkpoint review (every 3-5 tasks)
+- After every 3-5 completed tasks: use skill `bmad-checkpoint-preview`
+- Purpose: human-in-the-loop review — "walk me through changes so far"
+- Checkpoint will:
+  - Summarize: what was done, which files changed, tests status
+  - Highlight: points of concern, potential issues
+  - Ask user: continue / adjust / stop?
+- **Skip checkpoint if**: plan has < 5 tasks total (only checkpoint at the end)
+
+### Step 4 — Handling failures or scope drift
+- **If HAS_SUPERPOWERS**: use `superpowers:systematic-debugging` — mandatory hypothesis → experiment → conclusion
+- **If not**: try a different approach manually
+- Fail 3 times on the same task: **STOP** — this is an architecture problem, not an execution one. Re-read SRS + testcase, redesign the task. If still failing: go back to `/vsaf-plan`
+- **If scope drift is detected** (feature requires major changes compared to SRS):
+  - Use skill `bmad-correct-course` to assess impact + propose adjustments
+  - If requirements have changed → STOP, update SRS first (`/vsaf-doc-srs` EDIT mode), re-run `/vsaf-test`
+  - STOP and present to user: continue with adjustments / go back to `/vsaf-plan` to re-plan
+
+### Step 5 — Output after each task
 ```
-✓ Task [N]: [tên task]
-  - Files changed: [danh sách]
+✓ Task [N]: [task name]
+  - FR/NFR: [mapped requirement IDs]
+  - Files changed: [list]
   - Tests: [X passed]
+  - Verification: [PASS — outcome matches SRS intent / FAIL — details]
   - Commit: [hash]
-  - Superpowers: [used/not available]
+  - Superpowers: [brainstorming ✓ / writing-plans ✓ / executing-plans ✓ / verification ✓]
   - Checkpoint: [due at task N+X / completed]
 ```
 
-## Lưu ý
-- 1 commit = 1 task, không gộp nhiều tasks vào 1 commit
-- Không sửa file ngoài scope của task hiện tại
-- Sau khi hoàn thành tất cả tasks: chạy `/vsaf-ship`
+## Notes
+- 1 commit = 1 task, do not bundle multiple tasks into 1 commit
+- Do not modify files outside the scope of the current task
+- Brainstorm is mandatory before planning — do not skip
+- Verification is mandatory after each task — do not skip
+- After completing all tasks: run `/vsaf-test run` then `/vsaf-ship`

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

@@ -1,82 +1,70 @@
 ---
 name: vsaf-discover
-description: Product discovery — nghiên cứu domain, market, feasibility trước khi plan feature. Dùng khi bắt đầu dự án mới hoặc explore hướng phát triển sản phẩm.
+description: Product discovery — research domain, market, feasibility before planning a feature. Use when starting a new project or exploring product development directions.
 ---
 
 # VSAF Discover
 
-## Mục tiêu
-Hiểu rõ domain, market, user needs, và technical feasibility trước khi commit vào bất kỳ feature nào. Đảm bảo build đúng thứ.
+## Objective
+Thoroughly understand the domain, market, user needs, and technical feasibility before committing to any feature. Ensure we build the right thing.
 
 ## Input
-`$ARGUMENTS` — mô tả product/domain cần khám phá (ví dụ: "nền tảng quản lý đơn hàng cho SME")
+`$ARGUMENTS` — description of the product/domain to explore (e.g.: "order management platform for SMEs")
 
-## Khi nào dùng
-- Bắt đầu dự án mới (chưa có PRD/SRS)
-- Explore hướng phát triển sản phẩm mới
-- Trước khi chạy `/vsaf-plan` cho feature lớn mà chưa hiểu rõ domain
+## When to Use
+- Starting a new project (no PRD/SRS yet)
+- Exploring new product development directions
+- Before running `/vsaf-plan` for a large feature where the domain is not well understood
 
-## Các bước thực hiện
+## Execution Steps
 
-### Bước 1 — Search MemPalace
-- Gọi `mcp__mempalace__mempalace_search` với keyword từ `$ARGUMENTS`
-- Kiểm tra: đã có research cũ nào liên quan chưa?
-- Nếu có: tóm tắt findings cũ, tránh lặp lại
-
-### Bước 2 — Domain Research
-- Dùng skill `bmad-domain-research` để deep dive domain/industry
+### Step 1 — Domain Research
+- Use skill `bmad-domain-research` to deep dive into the domain/industry
 - Output: terminology, business rules, regulatory constraints, domain patterns
-- Lưu vào `docs/project/planning-artifacts/domain-research-[topic].md`
+- Save to `docs/project/planning-artifacts/domain-research-[topic].md`
 
-### Bước 3 — Market Research
-- Dùng skill `bmad-market-research` để phân tích:
-  - Competition landscape: ai đang làm gì, strengths/weaknesses
+### Step 2 — Market Research
+- Use skill `bmad-market-research` to analyze:
+  - Competition landscape: who is doing what, strengths/weaknesses
   - Customer needs: pain points, underserved segments
-  - Market trends: hướng đi nào đang tăng trưởng
-- Lưu vào `docs/project/planning-artifacts/market-research-[topic].md`
+  - Market trends: which directions are growing
+- Save to `docs/project/planning-artifacts/market-research-[topic].md`
 
-### Bước 4 — Technical Feasibility
-- Dùng skill `bmad-technical-research` để đánh giá:
+### Step 3 — Technical Feasibility
+- Use skill `bmad-technical-research` to assess:
   - Tech stack options + trade-offs
   - Integration constraints
   - Performance/scale requirements
   - Build vs buy decisions
-- Lưu vào `docs/project/planning-artifacts/tech-research-[topic].md`
-
-### Bước 5 — Product Brief
-- Dùng skill `bmad-product-brief` để tổng hợp findings thành product brief
-- Product brief = bản tóm tắt: vấn đề gì, cho ai, giải pháp gì, tại sao bây giờ
-- Lưu vào `docs/project/planning-artifacts/product-brief-[name].md`
-
-### Bước 6 — PRFAQ Challenge (Working Backwards)
-- Dùng skill `bmad-prfaq` để stress-test product concept
-- Viết press release giả lập: nếu product thành công, bài báo sẽ nói gì?
-- Viết FAQ: internal FAQ (team hỏi gì) + external FAQ (customer hỏi gì)
-- Mục đích: phát hiện concept yếu **trước khi** đầu tư thời gian code
-
-### Bước 7 — Tạo PRD (Product Requirements Document)
-- Dùng skill `bmad-agent-pm` (John) để dẫn dắt quá trình tạo PRD
-- John sẽ gọi skill `bmad-create-prd` để sinh PRD chuẩn từ product brief
-- PRD bao gồm: vision, goals, FRs, NFRs, epics, user stories, success metrics
-- Sau khi tạo xong: dùng skill `bmad-validate-prd` để validate PRD đạt chuẩn
-- Nếu validate FAIL: John sẽ dùng `bmad-edit-prd` để fix issues ngay
-- Lưu vào `docs/project/planning-artifacts/prd-[name].md`
-
-### Bước 8 — Multi-agent Review (Party Mode)
-- Dùng skill `bmad-party-mode` để tổ chức roundtable:
-  - PM (John) trình bày PRD
-  - Analyst (Mary) challenge requirements
-  - Architect (Winston) challenge feasibility
-- Ghi nhận consensus và open questions
-
-### Bước 9 — Lưu insights vào MemPalace
-- Gọi `mcp__mempalace__mempalace_add_drawer` để lưu:
-  - Market insights
-  - Domain knowledge
-  - Product decisions + rationale
-  - Open questions chưa trả lời
-
-### Bước 10 — Output cho user
+- Save to `docs/project/planning-artifacts/tech-research-[topic].md`
+
+### Step 4 — Product Brief
+- Use skill `bmad-product-brief` to synthesize findings into a product brief
+- Product brief = summary of: what problem, for whom, what solution, why now
+- Save to `docs/project/planning-artifacts/product-brief-[name].md`
+
+### Step 5 — PRFAQ Challenge (Working Backwards)
+- Use skill `bmad-prfaq` to stress-test the product concept
+- Write a simulated press release: if the product succeeds, what would the article say?
+- Write FAQ: internal FAQ (what the team would ask) + external FAQ (what customers would ask)
+- Purpose: discover weak concepts **before** investing time in code
+
+### Step 6 — Create PRD (Product Requirements Document)
+- Use skill `bmad-agent-pm` (John) to lead the PRD creation process
+- John will call skill `bmad-create-prd` to generate a standard PRD from the product brief
+- PRD includes: vision, goals, FRs, NFRs, epics, user stories, success metrics
+- After creation: use skill `bmad-validate-prd` to validate the PRD meets standards
+- If validation FAILs: John will use `bmad-edit-prd` to fix issues immediately
+- Save to `docs/project/planning-artifacts/prd-[name].md`
+
+### Step 7 — Multi-agent Review (Party Mode)
+- Use skill `bmad-party-mode` to organize a roundtable:
+  - PM (John) presents the PRD
+  - Analyst (Mary) challenges requirements
+  - Architect (Winston) challenges feasibility
+- Record consensus and open questions
+
+### Step 8 — Output to user
 ```
 ## Discovery Complete: [product/domain]
 
@@ -88,17 +76,17 @@ Hiểu rõ domain, market, user needs, và technical feasibility trước khi co
 - PRD:              docs/project/planning-artifacts/prd-[name].md
 
 ### Key findings
-- [3-5 bullet points tóm tắt]
+- [3-5 bullet point summary]
 
 ### Open questions
-- [Những gì cần validate thêm]
+- [Items that need further validation]
 
 ### Recommended next steps
-- Chạy /vsaf-sprint để break PRD thành epics + stories
-- Hoặc: chạy /vsaf-plan <first-feature> để bắt đầu feature đầu tiên
+- Run /vsaf-sprint to break PRD into epics + stories
+- Or: run /vsaf-plan <first-feature> to start the first feature
 ```
 
-## Lưu ý
-- Flow này **không sinh code** — chỉ research + document
-- Nếu domain quá rộng: đề nghị focus vào 1 vertical/segment trước
-- Commit docs sau mỗi bước: `git commit -m "docs: discovery [topic]"`
+## Notes
+- This flow **does not generate code** — research + documentation only
+- If the domain is too broad: suggest focusing on 1 vertical/segment first
+- Commit docs after each step: `git commit -m "docs: discovery [topic]"`

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

@@ -1,79 +1,22 @@
 ---
 name: vsaf-doc
-description: Viết tài liệu plan cho feature đã được phân tích. Dùng sau /vsaf-plan, khi đã có scope và approach rõ ràng, cần chuyển thành tài liệu có cấu trúc với task list atomic.
+description: DEPRECATED — Has been split into 2 separate commands. Use /vsaf-doc-prd to write the PRD, then /vsaf-doc-srs to write the SRS.
 ---
 
-# VSAF Doc
+# VSAF Doc — DEPRECATED
 
-## Mục tiêu
-Chuyển kết quả plan thành tài liệu chính thức: SRS có traceability rõ ràng để làm testcase và implementation.
+This skill has been split into 2 separate commands:
 
-## Đ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.
+1. `/vsaf-doc-prd` — Write PRD (Product Requirements Document) from `/vsaf-plan` output
+2. `/vsaf-doc-srs` — Write SRS (Software Requirements Specification) from the existing PRD
 
-## Các bước thực hiện
+## New Workflow
 
-### Bước 0 — Xác định mode: Tạo mới hay Chỉnh sửa
-- Kiểm tra xem đã có SRS/PRD trong `docs/project/srs/` cho feature này chưa
-- **Nếu chưa có** → Mode: CREATE (tạo mới từ đầu)
-- **Nếu đã có** → Mode: EDIT (chỉnh sửa dựa trên feedback/changes)
-  - Hỏi user: "SRS đã tồn tại. Bạn muốn tạo mới hoàn toàn hay chỉnh sửa?"
-
-### 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 2 — Sinh hoặc Chỉnh sửa SRS
-
-#### Mode CREATE:
-- Viết tài liệu SRS từ output `/vsaf-plan`
-- Nếu user muốn format PRD chuẩn: dùng skill `bmad-create-prd` để sinh PRD đầy đủ
-- SRS/PRD phải bao gồm: scope, FRs, NFRs, assumptions, out-of-scope, acceptance criteria
-- Thêm traceability ID cho FR/NFR để map sang testcase
-- Lưu vào `docs/project/srs/[feature].md`
-
-#### Mode EDIT:
-- Dùng skill `bmad-edit-prd` để chỉnh sửa SRS/PRD đã có
-- bmad-edit-prd sẽ: đọc SRS hiện tại, nhận changes từ user/plan, update in-place
-- Giữ nguyên traceability IDs đã có — chỉ thêm/sửa/xoá sections cần thiết
-- Đảm bảo: changes không break consistency với testcases đã sinh (nếu có)
-- Nếu thay đổi lớn: cảnh báo user rằng testcases cần re-run `/vsaf-test`
-
-### Bước 3 — Validate SRS (BMAD validate)
-- Dùng skill `bmad-validate-prd` để validate SRS vừa sinh/sửa
-- Kiểm tra: FRs đủ rõ ràng? NFRs đo lường được? Acceptance criteria kiểm chứng được?
-- Nếu có issues: fix ngay trong SRS, không chờ đến build
-- Nếu mode EDIT và validate FAIL: dùng `bmad-edit-prd` lần nữa để fix
-- Ghi nhận validation result (PASS/FAIL + findings)
-
-### Bước 4 — Chuẩn hoá implement notes
-- Tạo implement notes bám SRS: module ảnh hưởng, ràng buộc kỹ thuật, rollout notes
-- Không viết code trong bước này
-
-### Bước 5 — 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
 ```
-## Tài liệu đã tạo/cập nhật
-
-### SRS
-- docs/project/srs/[feature].md
-- Mode: [CREATE / EDIT]
-- Validation: [PASS / FAIL — chi tiết nếu fail]
-- Testcases impact: [None / Need re-run /vsaf-test]
-
-### Architecture Decision
-- Đã lưu vào MemPalace
-
-## Next step
-Chạy /vsaf-test docs/project/srs/[feature].md để sinh testcase
-[Nếu EDIT và testcases cũ bị ảnh hưởng]: Re-run /vsaf-test bắt buộc
+/vsaf-plan <requirement>    # scope + impact + approach
+/vsaf-doc-prd              # write PRD from approved scope
+/vsaf-doc-srs              # write SRS from PRD
+/vsaf-test <path/to/srs>   # generate testcases from SRS
 ```
 
-## Lưu ý
-- Không bắt đầu code trong bước này
-- Nếu scope quá lớn (>3 modules): đề nghị split thành nhiều PRs
-- Commit docs trước khi chuyển sang build: `git commit -m "docs: plan for <feature>"`
-- Khi edit PRD: luôn check impact lên testcases đã sinh
+Please use `/vsaf-doc-prd` or `/vsaf-doc-srs` instead of this skill.

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

@@ -0,0 +1,57 @@
+---
+name: vsaf-doc-prd
+description: Write PRD (Product Requirements Document) from /vsaf-plan output. Use after /vsaf-plan when scope and approach are clear.
+---
+
+# VSAF Doc PRD
+
+## Goal
+Convert plan output into a formal PRD: vision, goals, FRs, NFRs, epics, user stories, success metrics.
+
+## Prerequisites
+Must have run `/vsaf-plan` and have its output before running this skill.
+
+## Steps
+
+### Step 0 — Determine mode: Create or Edit
+- Check if a PRD already exists in `docs/project/planning-artifacts/` for this feature
+- **If none exists** → Mode: CREATE (create from scratch)
+- **If one exists** → Mode: EDIT (edit based on feedback/changes)
+  - Ask user: "A PRD already exists. Do you want to create a new one from scratch or edit the existing one?"
+
+### Step 1 — Generate or Edit PRD
+
+#### Mode CREATE:
+- Use skill `bmad-agent-pm` (John) to guide the PRD creation process from `/vsaf-plan` output
+- John will call skill `bmad-create-prd` to generate a standard PRD
+- PRD must include: vision, goals, FRs, NFRs, epics, user stories, success metrics, scope, out-of-scope, assumptions
+- Save to `docs/project/planning-artifacts/prd-[feature].md`
+
+#### Mode EDIT:
+- Use skill `bmad-edit-prd` to edit the existing PRD
+- Preserve existing structure and IDs — only add/modify/remove sections as needed
+- If changes are significant: warn user that SRS and testcases need to be re-run
+
+### Step 2 — Validate PRD (BMAD validate)
+- Use skill `bmad-validate-prd` to validate the generated/edited PRD
+- Check: Are FRs clear enough? Are NFRs measurable? Are acceptance criteria verifiable?
+- If issues found: fix immediately in the PRD, do not wait until build
+- Record validation result (PASS/FAIL + findings)
+
+### Step 3 — Output to user
+```
+## PRD Created/Updated
+
+### File
+- docs/project/planning-artifacts/prd-[feature].md
+- Mode: [CREATE / EDIT]
+- Validation: [PASS / FAIL — details if fail]
+
+## Next step
+Run /vsaf-doc-srs to write SRS from this PRD
+```
+
+## Notes
+- Do not start coding in this step
+- If scope is too large (>3 modules): suggest splitting into multiple PRs
+- Commit docs before moving to SRS: `git commit -m "docs: prd for <feature>"`