@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/core/templates/product-definition.template.md

@@ -1,14 +1,14 @@
 # {TICKET-ID} Product Definition — {Feature Name}
 
 <!--
-  This template is used by the /define-product workflow.
-  AI Agent fills each section through phased Q&A with PO.
-  Output is structured input for /generate-prd.
-
-  RULES:
-  - Each section corresponds to 1 phase in the workflow
-  - Incomplete section → keep placeholder, MUST NOT proceed to next phase
-  - PO confirmation status is recorded in each section
+  Template này được dùng bởi workflow /define-product.
+  AI Agent điền từng section qua Q&A theo từng phase với PO.
+  Output là input có cấu trúc cho /generate-prd.
+
+  QUY TẮC:
+  - Mỗi section tương ứng với 1 phase trong workflow
+  - Section chưa đủ → giữ placeholder, KHÔNG được sang phase tiếp theo
+  - Trạng thái xác nhận của PO được ghi trong mỗi section
 -->
 
 ---
@@ -18,151 +18,164 @@
 | Field              | Value                          |
 |--------------------|--------------------------------|
 | **Ticket**         | {TICKET-ID}                    |
-| **Feature**        | {Feature name}                 |
+| **Feature**        | {tên tính năng}                |
 | **Domain**         | {domain}                       |
-| **PO**             | {PO name}                      |
+| **PO**             | {tên PO}                       |
 | **Created**        | {YYYY-MM-DD}                   |
 | **Status**         | in-progress / completed        |
-| **Completed Phase**| {last completed phase number}  |
+| **Completed Phase**| {số phase hoàn thành gần nhất} |
 
 ---
 
-## Phase 0: Knowledge Sync
+## Phase 0: Đồng bộ tri thức (Knowledge Sync)
 
-> AI syncs system knowledge. No PO input needed.
+> ⚙️ AI tự thu thập — đây là **bối cảnh hệ thống**, KHÔNG phải yêu cầu nghiệp vụ do PO viết. Mục đích: chuẩn hoá thuật ngữ và nhận biết phần đã có để tái sử dụng. Không cần input từ PO.
 
-### Related Entities
-- {Entity 1} — {brief description}
-- {Entity 2} — {brief description}
+### Khái niệm / dữ liệu nghiệp vụ liên quan
+- {Khái niệm 1} — {mô tả ngắn}
+- {Khái niệm 2} — {mô tả ngắn}
 
-### Related Modules
-- {Module 1}
-- {Module 2}
+### Phần hệ thống / feature liên quan
+- {Phần 1}
+- {Phần 2}
 
-### Existing Rules / Logic
-- {Rule/logic from existing PRDs or domain knowledge}
+### Rule / Logic có sẵn
+- {Rule/logic từ các PRD có sẵn hoặc domain knowledge}
 
-### Terminology Normalization
-| Term in PO input | Canonical term (business-dictionary) |
-|-------------------|--------------------------------------|
-| {original term}   | {canonical term}                     |
+### Chuẩn hoá thuật ngữ
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
 
 ---
 
-## Phase 1: Feature Definition
+## Phase 1: Định nghĩa tính năng (Feature Definition)
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-### Context
-{Business context leading to this feature}
+### Bối cảnh (Context)
+{Bối cảnh nghiệp vụ dẫn đến tính năng này}
 
-### Problem Statement
-{Problem to solve}
+### Tuyên bố vấn đề (Problem Statement)
+{Vấn đề cần giải quyết}
 
-### Goal
-{Feature objective}
+### Mục tiêu (Goal)
+{Mục tiêu của tính năng}
 
-### Actors
-| Actor    | Role               | Primary/Secondary |
-|----------|--------------------|-------------------|
-| {Actor}  | {Role description} | Primary           |
+### Actor
+| Actor    | Vai trò            | Chính/Phụ |
+|----------|--------------------|-----------|
+| {Actor}  | {mô tả vai trò}    | Primary   |
 
-### Scope (In Scope)
-- {Function 1}
-- {Function 2}
+### Phạm vi (In Scope)
+- {Chức năng 1}
+- {Chức năng 2}
+
+### Ngoài phạm vi (Out of Scope)
+- {Hạng mục KHÔNG làm trong ticket này — kèm lý do / để dành pha sau}
 
 ### User Story
-- **As a** {User role}
-- **I want to** {User goal}
-- **So that** {Business value}
+- **Là một (As a)** {vai trò}
+- **Tôi muốn (I want to)** {mục tiêu}
+- **Để (So that)** {giá trị nghiệp vụ}
+
+### Phụ thuộc liên service *(mức nghiệp vụ)*
+
+> Feature này cần **dữ liệu/năng lực** gì từ feature/team khác — KHÔNG mô tả API/event/callback (đó là kỹ thuật, thuộc Tech-docs).
+
+- {Cần {dữ liệu/năng lực} từ {feature/team} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
 ---
 
-## Phase 2: User Flow Definition
+## Phase 2: Định nghĩa User Flow
+
+> ✅ PO xác nhận: {Có/Không}
 
-> ✅ PO Confirmed: {Yes/No}
+### Điểm vào (Entry Point)
+{Người dùng bắt đầu tương tác với tính năng như thế nào}
 
-### Entry Point
-{How user starts interacting with the feature}
+### Các bước của Flow
+| Bước | Hành động       | Trạng thái/Kết quả nghiệp vụ | Ghi chú    |
+|------|-----------------|------------------------------|------------|
+| 1    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
+| 2    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
 
-### Flow Steps
-| Step | Action          | Screen/State     | Notes       |
-|------|-----------------|------------------|-------------|
-| 1    | {User action}   | {Screen/State}   | {Notes}     |
-| 2    | {User action}   | {Screen/State}   | {Notes}     |
+### Điểm ra (Exit Point)
+{Kết quả cuối khi flow hoàn thành}
 
-### Exit Point
-{Final outcome when flow completes}
+### Edge Cases / Luồng lỗi & ngoại lệ
+> Các kịch bản thất bại nghiệp vụ ngoài happy path — input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng.
+- {Kịch bản: khi {điều kiện bất thường} → {kết quả nghiệp vụ kỳ vọng}}
 
 ---
 
-## Phase 3: Clarification Log
+## Phase 3: Nhật ký làm rõ (Clarification Log)
 
-> Records all questions and answers across rounds.
+> Ghi lại mọi câu hỏi và câu trả lời qua các vòng.
 
-### Round {N}
-| # | Category | Question   | PO Answer  |
+### Vòng {N}
+| # | Nhóm     | Câu hỏi    | PO trả lời |
 |---|----------|------------|------------|
-| 1 | Context  | {question} | {answer}   |
-| 2 | Flow     | {question} | {answer}   |
-| 3 | Logic    | {question} | {answer}   |
+| 1 | Context  | {câu hỏi}  | {trả lời}  |
+| 2 | Flow     | {câu hỏi}  | {trả lời}  |
+| 3 | Logic    | {câu hỏi}  | {trả lời}  |
 
-### Unresolved Items
-- {Unresolved item — if any remain, MUST NOT proceed to Phase 4}
+### Mục chưa giải quyết
+- {Mục chưa giải quyết — nếu còn tồn đọng, KHÔNG được sang Phase 4}
 
 ---
 
 ## Phase 4: Business Rules
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-| Rule ID | Action/Trigger      | Rule                | Condition            |
-|---------|---------------------|---------------------|----------------------|
-| BR-1    | {Action from flow}  | {Business rule}     | {Applicable condition} |
-| BR-2    | {Action from flow}  | {Business rule}     | {Applicable condition} |
+| Rule ID | Hành động/Trigger   | Quy tắc             | Điều kiện              |
+|---------|---------------------|---------------------|------------------------|
+| BR-1    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
+| BR-2    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
 
 ---
 
 ## Phase 5: Business Logic
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-| Rule ID | System Behavior                          | Data State Change    | UI Behavior          | Error Handling        |
-|---------|------------------------------------------|----------------------|----------------------|-----------------------|
-| BR-1    | {How system processes when rule triggers} | {Data changes}       | {enable/disable/...} | {Error message/action}|
-| BR-2    | {How system processes when rule triggers} | {Data changes}       | {enable/disable/...} | {Error message/action}|
+| Rule ID | Logic nghiệp vụ (rẽ nhánh / công thức / điều kiện) | Thông báo/kết quả nghiệp vụ khi lỗi |
+|---------|---------------------------------------------------|-------------------------------------|
+| BR-1    | {logic nghiệp vụ khi rule kích hoạt}              | {vd: báo "Số dư không đủ"}           |
+| BR-2    | {logic nghiệp vụ khi rule kích hoạt}              | {…}                                 |
 
 ---
 
 ## Phase 6: Acceptance Criteria
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-| AC ID | Description            | Expected Behavior         | Derived from |
+| AC ID | Mô tả                  | Hành vi kỳ vọng           | Bắt nguồn từ |
 |-------|------------------------|---------------------------|--------------|
-| AC-1  | {Criterion description} | {Expected behavior}       | BR-{N}       |
-| AC-2  | {Criterion description} | {Expected behavior}       | BR-{N}       |
+| AC-1  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
+| AC-2  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
 
 ---
 
-## Phase 7: Validation Report
+## Phase 7: Báo cáo kiểm chứng (Validation Report)
 
-### Coverage Matrix
-| Flow Action | Has Rule? | Has Logic? | Has AC? | Status |
-|-------------|-----------|------------|---------|--------|
-| {Action 1}  | ✅/❌     | ✅/❌      | ✅/❌   | OK/GAP |
+### Ma trận độ phủ (Coverage Matrix)
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
 
-### Conflicts Detected
-- {Conflict description — or "None"}
+### Xung đột phát hiện
+- {Mô tả xung đột — hoặc "None"}
 
-### Missing Items
-- {Missing rule/AC/logic — or "None"}
+### Mục còn thiếu
+- {Rule/AC/logic còn thiếu — hoặc "None"}
 
 ---
 
 <!--
   NEXT STEPS:
-  When Product Definition is complete (Status: completed), run:
+  Khi Product Definition hoàn tất (Status: completed), chạy:
   /generate-prd {path-to-this-file} --jira {TICKET-ID}
-  to generate a PRD from this Product Definition.
+  để sinh PRD từ Product Definition này.
 -->

package/core/templates/project-context.yaml

@@ -25,7 +25,7 @@ project:
 # All paths are relative to workspace root.
 paths:
   # Feature-Package Layout:
-  #   specs/{domain}/{prd-slug}/prd.md           — PRD document
+  #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  — PRD document
   #   specs/{domain}/{prd-slug}/bdd/             — BDD .feature files
   #   specs/{domain}/{prd-slug}/tech-docs/       — Technical design docs
   #   specs/{domain}/{prd-slug}/design-spec/     — Design specs (FE/App only)
@@ -39,7 +39,7 @@ paths:
   bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
   trace_report: "specs/.trace/trace-report.md"
 
-  # PRD template (PRDs are now at specs/{domain}/{prd-slug}/prd.md)
+  # PRD template (PRDs are at specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md)
   prd_template: "specs/templates/prd.template.md"
   refinement_dir: ".agent/review"
 

package/docs/01-getting-started/core-concepts.md

@@ -33,7 +33,7 @@ Discovery → PRD → BDD Spec → Tech Design → Code → Dev Self-Check
 | Phase | Ai | Lệnh chính | Output |
 |-------|-----|-----------|--------|
 | Discovery | PO + AI | `/define-product` | `specs/product-definition/{slug}.md` |
-| PRD | AI → SA/PO | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/{domain}/{prd-slug}/prd.md` |
+| PRD | AI → SA/PO | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` |
 | Design Spec *(FE/App)* | AI → Designer/PO | `/generate-design-spec` | `specs/{domain}/{prd-slug}/design-spec/...` |
 | BDD Spec | AI → SA/Dev | `/generate-bdd`, `/review-context` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` |
 | Tech Design | AI → SA/Lead | `/generate-tech-docs`, `/review-tech-docs` | `tech-docs/{domain}/{UC-ID}-tech-design.md` |

package/docs/01-getting-started/quickstart.md

@@ -42,16 +42,16 @@ Discovery → PRD → BDD → Tech Design → Code → Dev self-check:
 
 # PHASE 2 — PRD
 /generate-prd specs/product-definition/{slug}.md
-    → specs/{domain}/{prd-slug}/prd.md
-/refine-prd specs/{domain}/{prd-slug}/prd.md         # AI suggestions → Review Board
-/refine-prd --resume specs/{domain}/{prd-slug}/prd.md  # apply + bump version
-/review-context specs/{domain}/{prd-slug}/prd.md      # quality gate (P1–P4)
-/review-context --resume specs/{domain}/{prd-slug}/prd.md
+    → specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
+/refine-prd specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md         # AI suggestions → Review Board
+/refine-prd --resume specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  # apply + bump version
+/review-context specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md      # quality gate (P1–P4)
+/review-context --resume specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
     → ✅ APPROVED → tiếp Phase 3
 
 # PHASE 3 — SPEC & DESIGN
-# (FE/App only) /generate-design-spec specs/{domain}/{prd-slug}/prd.md → designer + PO sign-off
-/generate-bdd specs/{domain}/{prd-slug}/prd.md
+# (FE/App only) /generate-design-spec specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md → designer + PO sign-off
+/generate-bdd specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
     → specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
 /review-context specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
 /review-context --resume specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature   # apply + bump bdd_version

package/docs/02-guides/developer/bdd-and-trace.md

@@ -70,7 +70,7 @@ Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi
 ### Ví dụ trace chain hoàn chỉnh
 
 ```
-specs/auth/login/prd.md                              ← @trace.domain: auth, @trace.status: approved
+specs/auth/login/{TICKET-ID}-login.md                              ← @trace.domain: auth, @trace.status: approved
     ↓
 specs/auth/login/bdd/system/FT-001-UC1-login.feature ← @trace.prd: FT-001 · web/app/system riêng (system tổng hợp từ web+app)
     ↓

package/docs/02-guides/developer/scenarios.md

@@ -20,7 +20,7 @@
 1. git submodule update --remote my-project-specs
    (lấy PRD + BDD mới nhất từ PO)
 
-2. /review-context my-project-specs/specs/payment/checkout/prd.md
+2. /review-context my-project-specs/specs/payment/checkout/{TICKET-ID}-checkout.md
    → Kiểm tra @trace.status = approved (không code khi còn draft)
    → Đọc kỹ AC, UC, BR
 
@@ -109,7 +109,7 @@ PO notify: "FT-042 updated — BR7 thay đổi giới hạn từ 5tr → 10tr"
         │
         ▼
 Dev chạy:
-/review-context specs/payment/checkout/prd.md
+/review-context specs/payment/checkout/{TICKET-ID}-checkout.md
 → Xem diff từ v1.0 sang v1.1 (agent highlight thay đổi)
         │
         ▼
@@ -185,7 +185,7 @@ Service  : BE
 Severity : Major
 
 Spec context:
-  PRD      : specs/auth/login/prd.md (v1.0)
+  PRD      : specs/auth/login/{TICKET-ID}-login.md (v1.0)
   BDD      : free-trial-specs/specs/auth/login/bdd/system/FT-001-login.feature
              → Scenario: "Lock account after 5 failed attempts"
   Tech Doc : free-trial-specs/specs/auth/login/tech-docs/FT-001-auth-api.md
@@ -212,7 +212,7 @@ Code: ???                                      → kiểm tra tiếp
 Chạy:
 ```
 /fix-bug "BUG-20260605-003: FT-001-UC2-BR3 — account not locked after 5 failures
-  PRD: specs/auth/login/prd.md
+  PRD: specs/auth/login/{TICKET-ID}-login.md
   BDD: free-trial-specs/specs/auth/login/bdd/system/FT-001-login.feature"
 ```
 Agent sẽ: đọc BDD scenario được chỉ định · tìm code implement scenario đó (theo `@trace.bdd`) · so sánh logic thực tế vs spec · propose fix có giải thích.
@@ -253,7 +253,7 @@ PO thông báo: "FT-042 Design Spec + BDD đã sẵn sàng"
 git submodule update --remote my-project-specs
 
 FE dev đọc:
-- my-project-specs/specs/payment/checkout/prd.md                   (business rules)
+- my-project-specs/specs/payment/checkout/{TICKET-ID}-checkout.md                   (business rules)
 - my-project-specs/specs/payment/checkout/design-spec/FT-042-*.md  (screens, components)
 - my-project-specs/specs/payment/checkout/bdd/web/FT-042-UC*.feature  (BDD đã gen sẵn)
         │

package/docs/02-guides/product-owner/handoff-checklist.md

@@ -34,7 +34,7 @@ Trước khi thông báo dev team bắt đầu, kiểm tra:
 - [ ] Tất cả BDD files đã được review và không có `MISSING` trong Coverage Matrix
 
 **Git:**
-- [ ] Đã commit và push toàn bộ feature-package (`specs/{domain}/{prd-slug}/` — gồm `prd.md`, `design-spec/`, `bdd/`) lên spec repo
+- [ ] Đã commit và push toàn bộ feature-package (`specs/{domain}/{prd-slug}/` — gồm `{TICKET-ID}-{prd-slug}.md`, `design-spec/`, `bdd/`) lên spec repo
 - [ ] Thông báo dev team domain name và BDD path để họ cập nhật `git submodule update --remote`
 
 ---

package/docs/02-guides/product-owner/scenarios.md

@@ -20,11 +20,11 @@ Output: `specs/product-definition/FEAT-01-login.md`
 ```
 Agent tự động: đọc product definition · expand thành PRD đầy đủ với UC, AC, BR · nhắc nếu bạn viết UI details · kiểm tra terminology với business-dictionary.
 
-Output: `specs/auth/FEAT-01-login/prd.md`
+Output: `specs/auth/FEAT-01-login/FEAT-01-login.md`
 
 **Bước 3 — Review nội dung:**
 ```
-/refine-prd specs/auth/FEAT-01-login/prd.md
+/refine-prd specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Agent fan-out 4 lens (QA/DEV/SA/PO) chạy song song, rồi chạy completeness-critic loop cho đến khi một vòng không tìm ra finding mới, cuối cùng dedup + resolve conflict. Findings đầy đủ trong 1 lần chạy.
 
@@ -33,12 +33,12 @@ Mở findings file, xem xét từng finding: `accepted` → apply · `modified`
 > **Finding khó hiểu? Bấm 💬 Giải thích.** Nếu một finding mô tả nặng tính kỹ thuật, dùng nút **💬 Giải thích** trên Review Board (extension Spec Driven Docs Tools). Claude sẽ giải thích lại bằng ngôn ngữ no-tech + đề xuất phương án cụ thể (cover cả edge case) ngay trong terminal, và **chờ bạn confirm trước khi apply** vào PRD — tránh refine nhiều vòng. Prompt sửa được qua setting `reviewBoard.clarifyPrompt` (không cần cài lại extension).
 
 ```
-/review-context --resume specs/auth/FEAT-01-login/prd.md
+/review-context --resume specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 **Bước 4 — Final check:**
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
 
@@ -51,7 +51,7 @@ Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
 
 **Bước 6 — Tạo Design Spec (FE/App):**
 ```
-/generate-design-spec specs/auth/FEAT-01-login/prd.md
+/generate-design-spec specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Agent hỏi platform (web / app). PO phải cung cấp **Figma link node-level** (URL chứa `?node-id=`, lấy bằng right-click vào frame → "Copy link to selection") cho **mỗi screen**. Screen nào thiếu link → bị flag ❌ Missing, Status giữ `draft`, `/generate-bdd` bị BLOCKED cho đến khi đủ link.
 
@@ -59,7 +59,7 @@ Sau khi Designer review + confirm đủ Figma node-id links → `@trace.status:
 
 **Bước 7 — Generate BDD:**
 ```
-/generate-bdd specs/auth/FEAT-01-login/prd.md
+/generate-bdd specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Agent hỏi: **"Platform? (1) web  (2) app  (3) system"**
 - Chọn `web` → `specs/auth/FEAT-01-login/bdd/web/FEAT-01-UC1-login-web.feature`
@@ -111,7 +111,7 @@ git push
 
 **Bước 1 — Design Spec:**
 ```
-/generate-design-spec specs/auth/FEAT-01-login/prd.md
+/generate-design-spec specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Output: `specs/auth/FEAT-01-login/design-spec/FEAT-01-design-spec-web.md`
 
@@ -119,7 +119,7 @@ Mỗi screen cần Figma link node-id. Screen thiếu → flag ❌ Missing, BLOC
 
 **Bước 2 — Generate BDD:**
 ```
-/generate-bdd specs/auth/FEAT-01-login/prd.md
+/generate-bdd specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 | Lần | Platform | Output |
@@ -147,12 +147,12 @@ cat .agent/review/FEAT-01-login-prd-review-context-findings.yaml
 
 **Bước 3 — Apply:**
 ```
-/review-context --resume specs/auth/FEAT-01-login/prd.md
+/review-context --resume specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 **Bước 4 — Re-review:**
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Lặp lại cho đến khi `recommendation: APPROVED`.
 
@@ -167,12 +167,12 @@ Lặp lại cho đến khi `recommendation: APPROVED`.
 
 **Bước 2 — Sửa nội dung:**
 ```
-/refine-prd specs/auth/FEAT-01-login/prd.md "Thêm yêu cầu: hỗ trợ đăng nhập bằng OTP"
+/refine-prd specs/auth/FEAT-01-login/FEAT-01-login.md "Thêm yêu cầu: hỗ trợ đăng nhập bằng OTP"
 ```
 
 **Bước 3 — Review lại:**
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 /review-context --resume    (nếu cần fix)
 ```
 
@@ -183,7 +183,7 @@ Lặp lại cho đến khi `recommendation: APPROVED`.
                          # major bump (2.0) nếu thay đổi cơ bản
 ```
 ```bash
-git add specs/auth/FEAT-01-login/prd.md
+git add specs/auth/FEAT-01-login/FEAT-01-login.md
 git commit -m "feat(auth): update FEAT-01 PRD v1.1 — add OTP login AC"
 git push
 ```
@@ -239,7 +239,7 @@ services:
 2. Quyết định PRD nào đúng.
 3. Sửa file:
    ```
-   /review-context --resume specs/auth/FEAT-01-login/prd.md
+   /review-context --resume specs/auth/FEAT-01-login/FEAT-01-login.md
    # với finding P3: modified: "session timeout cập nhật thành 2 giờ theo FEAT-05"
    ```
 4. Cả 2 PRD phải nhất quán trước khi dev team generate BDD.
@@ -268,20 +268,20 @@ git push
 ```
 specs/
 ├── auth/
-│   ├── FEAT-01-login/prd.md          (approved)
-│   └── FEAT-08-sso/prd.md            (draft)
+│   ├── FEAT-01-login/FEAT-01-login.md          (approved)
+│   └── FEAT-08-sso/FEAT-08-sso.md            (draft)
 ├── payment/
-│   ├── FEAT-03-checkout/prd.md       (approved)
-│   └── FEAT-11-refund/prd.md         (draft)
+│   ├── FEAT-03-checkout/FEAT-03-checkout.md       (approved)
+│   └── FEAT-11-refund/FEAT-11-refund.md         (draft)
 └── loyalty/
-    └── FEAT-06-points/prd.md         (in-review)
+    └── FEAT-06-points/FEAT-06-points.md         (in-review)
 ```
 
 **Gợi ý:** Hoàn thiện 1 PRD đến `approved` trước khi bắt đầu PRD tiếp theo. Chỉ PRD `approved` mới được dev team sử dụng.
 
 ```bash
 # Xem nhanh tất cả PRDs và status:
-grep -r "@trace.status" specs/ --include="prd.md"
+grep -r "@trace.status" specs/ --include="*.md"
 ```
 
 ---
@@ -297,7 +297,7 @@ grep -r "@trace.status" specs/ --include="prd.md"
 ```
 
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 → Phải thấy recommendation: APPROVED và 0 critical findings
 ```
 
@@ -306,13 +306,13 @@ grep -r "@trace.status" specs/ --include="prd.md"
 [FEAT-01] PRD Login đã approved — sẵn sàng implement
 
 Domain: auth
-File: my-project-specs/specs/auth/FEAT-01-login/prd.md
+File: my-project-specs/specs/auth/FEAT-01-login/FEAT-01-login.md
 Version: 1.0
 Design Spec (Web): my-project-specs/specs/auth/FEAT-01-login/design-spec/FEAT-01-design-spec-web.md
 
 Lệnh để bắt đầu:
   git submodule update --remote my-project-specs
-  /review-context my-project-specs/specs/auth/FEAT-01-login/prd.md
+  /review-context my-project-specs/specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 ---

package/docs/02-guides/tester/bug-reporting.md

@@ -45,7 +45,7 @@ Service  : BE / Web / App
 Severity : Critical / Major / Minor
 
 Spec context:
-  PRD      : specs/{domain}/{prd-slug}/prd.md (v{x.x})
+  PRD      : specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (v{x.x})
   BDD      : {bdd path} → Scenario: "{scenario title}"
   Tech Doc : {tech_docs path}
 
@@ -77,7 +77,7 @@ Service  : BE
 Severity : Major
 
 Spec context:
-  PRD      : specs/auth/FT-001-login/prd.md (v1.0)
+  PRD      : specs/auth/FT-001-login/FT-001-login.md (v1.0)
   BDD      : free-trial-specs/specs/auth/FT-001-login/bdd/system/FT-001-login.feature
              → Scenario: "Lock account after 5 failed attempts"
   Tech Doc : free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-auth-api.md

package/docs/02-guides/tester/reading-specs.md

@@ -18,7 +18,7 @@ Sau khi chạy `/generate-spec-manifest`, tra manifest để lấy paths:
 ```yaml
 # spec-manifest.yaml
 FT-001:
-  prd:          "my-project-specs/specs/auth/FT-001-login/prd.md"
+  prd:          "my-project-specs/specs/auth/FT-001-login/FT-001-login.md"
   bdd:
     be:   "my-project-specs/specs/auth/FT-001-login/bdd/system/FT-001-UC1-login-system.feature"
     web:  "my-project-specs/specs/auth/FT-001-login/bdd/web/FT-001-UC1-login-web.feature"
@@ -26,7 +26,7 @@ FT-001:
     be:   "my-project-specs/specs/auth/FT-001-login/tech-docs/FT-001-auth-api.md"
 ```
 
-**Bước 1: Đọc PRD** tại `my-project-specs/specs/auth/FT-001-login/prd.md`
+**Bước 1: Đọc PRD** tại `my-project-specs/specs/auth/FT-001-login/FT-001-login.md`
 *(nằm trong spec submodule — shared repo của PO)*
 
 ```markdown

package/docs/02-guides/tester/scenarios.md

@@ -16,7 +16,7 @@ git pull && git submodule update --remote --recursive
 # 3. Kiểm tra status
 # FT-042:
 #   status: approved  ← ✅ có thể test
-#   prd: "specs/payment/FT-042-checkout/prd.md"
+#   prd: "specs/payment/FT-042-checkout/FT-042-checkout.md"
 #   bdd:
 #     be:  "free-trial-specs/specs/payment/FT-042-checkout/bdd/system/FT-042-UC1-checkout-system.feature"
 #     web: "free-trial-specs/specs/payment/FT-042-checkout/bdd/web/FT-042-UC1-checkout-web.feature"

package/docs/02-guides/tester/spec-manifest.md

@@ -4,14 +4,14 @@
 
 ## Spec-Manifest Là Gì Và Tại Sao Cần
 
-Trong umbrella repo (có `spec_source`), **mọi spec đều nằm trong spec submodule** — gom theo feature-package: mỗi PRD có một thư mục `specs/{domain}/{prd-slug}/` chứa tất cả artifact (`prd.md`, `bdd/{platform}/`, `tech-docs/`, `design-spec/`), trải trên nhiều domain:
+Trong umbrella repo (có `spec_source`), **mọi spec đều nằm trong spec submodule** — gom theo feature-package: mỗi PRD có một thư mục `specs/{domain}/{prd-slug}/` chứa tất cả artifact (`{TICKET-ID}-{prd-slug}.md`, `bdd/{platform}/`, `tech-docs/`, `design-spec/`), trải trên nhiều domain:
 
 ```
 free-trial-umbrella/                              ← umbrella (Claude Code mở ở đây)
 ├── free-trial-specs/                             ← SPEC submodule — TẤT CẢ spec ở đây
 │   └── specs/
 │       └── auth/FT-001-login/                    ← feature-package (1 PRD = 1 thư mục)
-│           ├── prd.md                            ← PRD
+│           ├── {TICKET-ID}-{prd-slug}.md                            ← PRD
 │           ├── design-spec/...                   ← Design Spec
 │           ├── bdd/system/...                    ← BDD System (BE)
 │           ├── bdd/web/...                        ← BDD Web (FE)
@@ -30,7 +30,7 @@ features:
   FT-001:
     domain: auth
     status: approved
-    prd: "specs/auth/FT-001-login/prd.md"
+    prd: "specs/auth/FT-001-login/FT-001-login.md"
     pdd: "specs/product-definition/auth/FT-001-def.md"
     tech_docs:
       be:  "free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-UC1-auth-api.md"

package/docs/02-guides/tester/workflow.md

@@ -16,7 +16,7 @@ git pull && git submodule update --remote --recursive
 Lookup FT-042 trong spec-manifest.yaml
 → status: approved? ✅ (nếu draft → dừng, báo PO)
 → ghi lại paths (tất cả đều nằm trong submodule):
-    prd:          {spec_source}/specs/{domain}/{prd-slug}/prd.md
+    prd:          {spec_source}/specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
     bdd.system:   {spec_source}/specs/{domain}/{prd-slug}/bdd/system/FT-042-*.feature
     bdd.web:      {spec_source}/specs/{domain}/{prd-slug}/bdd/web/FT-042-*.feature
     tech_docs.be: {spec_source}/specs/{domain}/{prd-slug}/tech-docs/FT-042-*.md