@edupia-tutor/spec-driven-docs 0.14.0

package/core/templates/prd.template.md

@@ -0,0 +1,327 @@
+# {TICKET-ID} Tên tính năng/Feature Name
+
+<!--
+  Template này được sử dụng bởi workflow /generate-prd.
+  AI Agent sẽ điền các section dựa trên input từ PO.
+  Các placeholder {…} cần được thay thế bằng nội dung thực tế.
+
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  TERMINOLOGY RULES — Business Dictionary Enforcement               ║
+  ║  Source: specs/domain-knowledge/business-dictionary.md              ║
+  ║  AI Agent PHẢI tuân thủ 100% khi sinh nội dung PRD.                ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  THUẬT NGỮ BẮT BUỘC (phải dùng đúng keyword):
+  ┌─────────────────────────┬──────────────────────────────────────────┐
+  │ Keyword chuẩn           │ Ngữ cảnh                                │
+  ├─────────────────────────┼──────────────────────────────────────────┤
+  │ Consumer                │ Khách hàng (global entity)              │
+  │ Merchant / Tenant       │ Merchant = nghiệp vụ, Tenant = kỹ thuật│
+  │ Online Storefront       │ Tính năng bán hàng trên Zalo Mini App   │
+  │ Branch                  │ Chi nhánh vật lý (projection từ KVS)    │
+  │ Loyalty Member          │ Quan hệ Consumer ↔ Merchant             │
+  │ Order                   │ Đơn hàng (chỉ completed → Loyalty)      │
+  │ OrderItem               │ Chi tiết dòng hàng trong Order           │
+  │ Product                 │ Hàng hóa (projection từ KVS)            │
+  │ ProductCategory         │ Nhóm hàng (hierarchical)                │
+  │ ProductAttribute        │ Định nghĩa loại thuộc tính              │
+  │ ProductAttributeMap     │ Mapping thuộc tính → sản phẩm cụ thể    │
+  │ ProductImage            │ Hình ảnh sản phẩm (nhiều ảnh, có rank)  │
+  │ Address                 │ Địa chỉ đa hình (polymorphic)           │
+  │ SourceSystem            │ Hệ thống partner (map → X-App-Id)       │
+  │ ExternalId              │ ID tham chiếu từ hệ thống nguồn (KVS)   │
+  │ Onboarding              │ Quy trình khởi tạo gian hàng lần đầu    │
+  │ revision                │ Row version — delta sync                 │
+  │ KVLoyalty Widget        │ Thư viện tích hợp frontend (JS qua CDN) │
+  └─────────────────────────┴──────────────────────────────────────────┘
+
+  THUẬT NGỮ BỊ CẤM — TUYỆT ĐỐI KHÔNG xuất hiện trong PRD:
+  ┌─────────────────────────┬─────────────────────────────────────────────────┐
+  │ ❌ KHÔNG dùng           │ ✅ Thay thế bằng                               │
+  ├─────────────────────────┼─────────────────────────────────────────────────┤
+  │ Customer                │ Consumer                                        │
+  │ SKU                     │ Product + ProductAttribute + ProductAttributeMap│
+  │ JS SDK / JavaScript SDK │ KVLoyalty Widget                                │
+  │ CDC                     │ Event bus (Kafka)                               │
+  │ primaryBranchId         │ Branch.isPrimary                                │
+  │ Cửa hàng (= storefront)│ Online Storefront / Gian hàng online            │
+  └─────────────────────────┴─────────────────────────────────────────────────┘
+
+  QUY TẮC BỔ SUNG:
+  - Luôn dùng SourceSystem cho partners, ExternalId cho external references.
+  - Status/Enum values → tham chiếu core-entities.md Global Enum Registry.
+  - Khi nhắc "SKU" → diễn giải bằng Product con (masterProductId) + ProductAttributeMap.
+  - Consumer là global entity — 1 Consumer có thể mua hàng ở nhiều Merchant.
+  - Nếu phát hiện banned term trong input PO → thay thế bằng term chuẩn và ghi chú trong "Giả định AI".
+  - CROSS-REFERENCE (BẮT BUỘC): Bất kỳ chỗ nào trong tài liệu có nhắc đến một tính năng/ticket khác
+    (dù là pre-condition, business rule, giả định, AC, hay bất kỳ section nào) → PHẢI gắn inline link:
+      [TICKET-ID](./TICKET-ID-slug.md)
+    Không được để TICKET-ID dạng plain text nếu tồn tại file PRD tương ứng.
+    Ngoài ra, ghi rõ quan hệ phụ thuộc trong "Tài liệu tham khảo" ở Appendix.
+  - NEW TERM DETECTION: Nếu trong input PO xuất hiện thuật ngữ CHƯA CÓ trong business-dictionary.md
+    và thuật ngữ đó lặp lại ≥ 2 lần → DỪNG lại, hỏi PO confirm trước khi tiếp tục:
+      + Thuật ngữ đó có nghĩa gì trong ngữ cảnh hệ thống?
+      + English term chuẩn nên dùng là gì?
+      + Có cần bổ sung vào business-dictionary.md không?
+    Sau khi PO confirm → cập nhật business-dictionary.md (nếu PO đồng ý) rồi mới tiếp tục sinh PRD.
+-->
+
+---
+
+## Metadata
+
+| Field         | Value                           |
+|---------------|---------------------------------|
+| **PRD ID**    | {TICKET-ID}                     |
+| **Version**   | 1.0                             |
+| **Status**    | draft / review / approved       |
+| **Author**    | {PO name or "AI-assisted"}      |
+| **Domain**    | {domain: loyalty, identity, …}  |
+| **Created**   | {YYYY-MM-DD}                    |
+| **Updated**   | {YYYY-MM-DD}                    |
+
+---
+
+# Feature
+
+{Tên tính năng chính và mô tả capability hoặc chức năng mà sản phẩm cung cấp.}
+
+---
+
+# 1. Tổng quan
+
+## a. User Story
+
+<!--
+  ĐỊNH NGHĨA: Mô tả ngắn gọn nhu cầu của người dùng theo góc nhìn nghiệp vụ.
+  Trả lời câu hỏi: "Ai cần gì và tại sao?" — KHÔNG mô tả kỹ thuật.
+
+  QUY TẮC VIẾT:
+  - {User role}     → Vai trò người dùng (ví dụ: Consumer, Merchant Admin, Cashier)
+  - {User goal}     → Mục tiêu người dùng muốn đạt được (hành động/chức năng cụ thể)
+  - {Business value}→ Giá trị nghiệp vụ mang lại (lý do tại sao người dùng cần điều này)
+-->
+
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
+
+## b. Phạm vi
+
+<!--
+  ĐỊNH NGHĨA: Liệt kê danh sách các chức năng thuộc feature này.
+  Trả lời câu hỏi: "Feature này làm gì?" — giúp xác định ranh giới, tránh scope creep.
+
+  QUY TẮC VIẾT:
+  - Mỗi dòng là một chức năng/capability cụ thể mà feature này cung cấp.
+  - Chỉ liệt kê những gì được làm trong ticket này. Nếu có chức năng liên quan nhưng
+    KHÔNG thuộc ticket này → KHÔNG đưa vào danh sách.
+  - Viết ngắn gọn, súc tích, đủ để người đọc hiểu mà không cần giải thích thêm.
+-->
+
+**In Scope**
+
+- {Chức năng thuộc feature}
+
+---
+
+# 2. Acceptance Criteria
+
+<!--
+  ĐỊNH NGHĨA: Danh sách điều kiện cần thỏa mãn để tính năng được coi là hoàn thành.
+  Trả lời câu hỏi: "Khi nào thì feature này được coi là DONE?" — tiêu chí để QA kiểm thử và PO sign-off.
+
+  QUY TẮC VIẾT:
+  - Viết theo góc nhìn người dùng: "Người dùng có thể...", "Hệ thống cho phép..."
+  - Mỗi AC phải testable (có thể kiểm tra được — pass hoặc fail rõ ràng).
+  - Chỉ ghi các tiêu chí CỐT LÕI — khi tính năng đạt được những điều này thì người dùng
+    đã có thể sử dụng được. Không ghi tiêu chí phụ hoặc edge case nhỏ.
+
+  KHÔNG viết AC về:
+  - UI/UX (màu sắc, vị trí nút, font chữ, animation) → thuộc Wireframe.
+  - Chi tiết kỹ thuật hoặc logic xử lý nội bộ → thuộc Business Rule / Business Logic.
+-->
+
+- **AC1:** {Điều kiện chấp nhận}
+- **AC2:** {Điều kiện chấp nhận}
+- **AC3:** {Điều kiện chấp nhận}
+
+---
+
+# 3. Use Case
+
+<!--
+  ĐỊNH NGHĨA — USE CASE (UC):
+  Mô tả một kịch bản nghiệp vụ cụ thể từ góc nhìn người dùng tương tác với hệ thống.
+  Trả lời câu hỏi: "Người dùng tương tác với hệ thống như thế nào trong từng tình huống?"
+  - Actor         → Ai thực hiện hành động trong kịch bản này
+  - Description   → Tóm tắt kịch bản bằng 1 câu
+  - Pre-condition → Điều kiện PHẢI đúng TRƯỚC KHI Use Case bắt đầu (trạng thái hệ thống, quyền, dữ liệu)
+  - Post-condition→ Trạng thái/kết quả SAU KHI Use Case hoàn thành thành công
+
+  ĐỊNH NGHĨA — BUSINESS RULE (BR):
+  Quy tắc nghiệp vụ mà hệ thống bắt buộc phải tuân theo — viết thành một câu rõ ràng, ngắn gọn, dễ hiểu.
+  Trả lời câu hỏi: "Hệ thống PHẢI làm gì / KHÔNG được làm gì?" (WHAT)
+  - Là ràng buộc không thể thương lượng, xuất phát từ yêu cầu nghiệp vụ.
+  - Mỗi BR chỉ phát biểu MỘT quy tắc duy nhất, không gộp nhiều quy tắc vào một dòng.
+
+  ĐỊNH NGHĨA — BUSINESS LOGIC (BL):
+  Cách thực thi cụ thể của một Business Rule — mô tả các điều kiện và logic chi tiết.
+  Trả lời câu hỏi: "Hệ thống thực hiện quy tắc đó cụ thể như thế nào?" (HOW)
+  - Các điều kiện rẽ nhánh (if/else, trường hợp A / trường hợp B)
+  - Công thức tính toán hoặc quy tắc áp dụng theo từng trường hợp
+  - Thứ tự xử lý, ưu tiên, các trường hợp ngoại lệ
+  - Đây là input trực tiếp để developer implement.
+
+  NUMBERING CONVENTION:
+  - UC ID: format {TICKET_ID}-UC{N}
+    + {TICKET_ID} = Jira Ticket ID (e.g., LOYAL-29)
+    + {N} = UC number within this PRD (1, 2, 3, ...)
+    + E.g.: LOYAL-29-UC1, LOYAL-29-UC2, LOYAL-29-UC3, ...
+  - BR ID: format {TICKET_ID}-UC{N}-BR{M}
+    + {M} = BR number incrementing from 1 across the PRD (not reset per UC, not global)
+    + E.g.: LOYAL-29-UC1-BR1, LOYAL-29-UC1-BR2, LOYAL-29-UC2-BR3, ...
+-->
+
+#### {TICKET_ID}-UC1: {Tên Use Case}
+
+- **Actor:** {Người dùng thực hiện}
+- **Description:** {Mô tả ngắn gọn kịch bản nghiệp vụ}
+- **Pre-condition:** {Điều kiện cần trước khi Use Case bắt đầu}
+- **Post-condition:** {Kết quả sau khi Use Case hoàn thành}
+
+**Business Rule**
+
+| ID | Business Rule |
+|----|---------------|
+| {TICKET_ID}-UC1-BR1 | |
+
+**Business Logic**
+
+**{TICKET_ID}-UC1-BR1:**
+- Logic 1
+- Logic 2
+- Logic 3
+
+---
+
+# 4. UI/UX Guidelines
+
+## a. User Flow
+
+<!--
+  ĐỊNH NGHĨA: Sơ đồ trực quan mô tả trình tự các bước và nhánh quyết định mà người dùng đi qua.
+  Trả lời câu hỏi: "Người dùng đi qua những bước nào và hệ thống phản hồi ra sao?"
+
+  QUY TẮC VIẾT (Mermaid flowchart):
+  - Start/Entry  → Điểm vào: người dùng bắt đầu từ đâu (màn hình nào, hành động nào)
+  - Process      → Bước xử lý: hình chữ nhật [ ] — hành động hoặc hiển thị của hệ thống
+  - Decision     → Điểm rẽ nhánh: hình thoi { } — điều kiện dẫn đến kết quả khác nhau
+  - End State    → Trạng thái kết thúc: kết quả cuối cùng người dùng nhận được
+
+  Mỗi nhánh Decision phải có label rõ ràng (|Có|, |Không|, |Thành công|, |Thất bại|...).
+  Bao gồm cả luồng lỗi / luồng ngoại lệ quan trọng (không chỉ happy path).
+-->
+
+{Flowchart mô tả trình tự các bước và các nhánh quyết định (Start/Entry → Process → Decision → End State)}
+
+```mermaid
+flowchart TD
+    A[Bước 1: ...] --> B[Bước 2: ...]
+    B --> C{Điều kiện?}
+    C -->|Có| D[Bước 3a: ...]
+    C -->|Không| E[Bước 3b: ...]
+```
+
+## b. Wireframe
+
+<!--
+  ĐỊNH NGHĨA: Mô tả bố cục và thành phần UI của từng màn hình.
+  Trả lời câu hỏi: "Màn hình trông như thế nào và người dùng tương tác với nó ra sao?"
+  Là cầu nối giữa nghiệp vụ và thiết kế UI. Có thể kèm link Figma hoặc ảnh mockup.
+
+  CẤU TRÚC BẢNG CHUẨN (3 thành phần chính):
+  - Screen     → Tên màn hình / modal / trạng thái đang mô tả
+  - Components → Danh sách các thành phần UI hiển thị (button, label, list, input, bar...)
+  - Actions    → Hành động người dùng thực hiện và kết quả/màn hình tiếp theo tương ứng
+
+  LƯU Ý — CẤU TRÚC LINH HOẠT THEO ĐỘ PHỨC TẠP:
+  Với màn đơn giản → dùng bảng 3 cột chuẩn (Screen / Components / Actions) là đủ.
+  Với màn phức tạp (nhiều trạng thái, nhiều modal, nhiều luồng lỗi) → có thể mở rộng:
+  - Tách riêng từng màn / modal / trạng thái thay vì gộp chung một bảng.
+  - Thêm các field chi tiết hơn nếu cần (UI Pattern, Header, Footer, Toast, Entry Point...).
+  Nguyên tắc: ưu tiên sự rõ ràng hơn tuân thủ cứng nhắc cấu trúc —
+  miễn là designer, dev, QA đọc vào hiểu đúng ý định của màn hình đó.
+-->
+
+**Screen N: {Tên màn hình}**
+
+**Screen:** {Tên màn hình}
+
+**Components:**
+- {Component 1}
+- {Component 2}
+- {Component 3}
+
+**Actions:**
+- {Hành động 1} → {Kết quả}
+- {Hành động 2} → {Kết quả}
+
+<!-- Figma Design: {Link Figma — xóa dòng này nếu không có URL} -->
+
+<!-- ![Wireframe mô tả](./assets/wireframe-name.png) -->
+
+---
+
+# Appendix
+
+## Input gốc từ PO
+
+> Lưu lại nguyên văn input ban đầu (text + links đến hình ảnh).
+
+{Paste original input here}
+
+## Tài liệu tham khảo
+
+<!--
+  Cross-reference PRD liên quan dùng format: [TICKET-ID](./TICKET-ID-slug.md) — {quan hệ phụ thuộc}
+  Ví dụ:
+  - [LOYAL-23](./LOYAL-23-cau-hinh-chi-nhanh.md) — Pre-condition: Branch phải được cấu hình trước
+  - [LOYAL-10](./LOYAL-10-onboarding-merchant.md) — Entity dùng chung: Merchant/Tenant
+-->
+
+- {[TICKET-ID](./TICKET-ID-slug.md) — mô tả quan hệ phụ thuộc}
+
+## Giả định AI
+
+> Các giả định AI đưa ra khi PO chọn "skip" hoặc thông tin chưa đầy đủ.
+> Mỗi giả định cần được PO review và confirm.
+
+- {Giả định 1 — [AI DRAFT]}
+- {Giả định 2 — [AI DRAFT]}
+
+---
+
+## Changelog
+
+<!--
+  Version history — mỗi lần PRD được cập nhật (qua /refine-prd --resume hoặc PO tự sửa)
+  → thêm 1 dòng mới vào đầu bảng này với version mới.
+
+  Version bumping rules:
+  - Major (X.0 → X+1.0): thêm/xoá Use Case, thay đổi scope lớn, breaking BR change
+  - Minor (x.Y → x.Y+1): làm rõ AC/BR, thêm edge case, cập nhật wording
+
+  BDD và Code đọc version này qua @trace.prd_version để detect drift.
+-->
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | {YYYY-MM-DD} | Initial version |
+
+<!-- 
+  NEXT STEPS:
+  Khi PRD được approve (status: approved), chạy:
+  /generate-bdd "path/to/this-prd.md"
+  để sinh BDD feature specs từ PRD này.
+-->

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

@@ -0,0 +1,168 @@
+# {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
+-->
+
+---
+
+## Metadata
+
+| Field              | Value                          |
+|--------------------|--------------------------------|
+| **Ticket**         | {TICKET-ID}                    |
+| **Feature**        | {Feature name}                 |
+| **Domain**         | {domain}                       |
+| **PO**             | {PO name}                      |
+| **Created**        | {YYYY-MM-DD}                   |
+| **Status**         | in-progress / completed        |
+| **Completed Phase**| {last completed phase number}  |
+
+---
+
+## Phase 0: Knowledge Sync
+
+> AI syncs system knowledge. No PO input needed.
+
+### Related Entities
+- {Entity 1} — {brief description}
+- {Entity 2} — {brief description}
+
+### Related Modules
+- {Module 1}
+- {Module 2}
+
+### Existing Rules / Logic
+- {Rule/logic from existing PRDs or domain knowledge}
+
+### Terminology Normalization
+| Term in PO input | Canonical term (business-dictionary) |
+|-------------------|--------------------------------------|
+| {original term}   | {canonical term}                     |
+
+---
+
+## Phase 1: Feature Definition
+
+> ✅ PO Confirmed: {Yes/No}
+
+### Context
+{Business context leading to this feature}
+
+### Problem Statement
+{Problem to solve}
+
+### Goal
+{Feature objective}
+
+### Actors
+| Actor    | Role               | Primary/Secondary |
+|----------|--------------------|-------------------|
+| {Actor}  | {Role description} | Primary           |
+
+### Scope (In Scope)
+- {Function 1}
+- {Function 2}
+
+### User Story
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
+
+---
+
+## Phase 2: User Flow Definition
+
+> ✅ PO Confirmed: {Yes/No}
+
+### Entry Point
+{How user starts interacting with the feature}
+
+### Flow Steps
+| Step | Action          | Screen/State     | Notes       |
+|------|-----------------|------------------|-------------|
+| 1    | {User action}   | {Screen/State}   | {Notes}     |
+| 2    | {User action}   | {Screen/State}   | {Notes}     |
+
+### Exit Point
+{Final outcome when flow completes}
+
+---
+
+## Phase 3: Clarification Log
+
+> Records all questions and answers across rounds.
+
+### Round {N}
+| # | Category | Question   | PO Answer  |
+|---|----------|------------|------------|
+| 1 | Context  | {question} | {answer}   |
+| 2 | Flow     | {question} | {answer}   |
+| 3 | Logic    | {question} | {answer}   |
+
+### Unresolved Items
+- {Unresolved item — if any remain, MUST NOT proceed to Phase 4}
+
+---
+
+## Phase 4: Business Rules
+
+> ✅ PO Confirmed: {Yes/No}
+
+| Rule ID | Action/Trigger      | Rule                | Condition            |
+|---------|---------------------|---------------------|----------------------|
+| BR-1    | {Action from flow}  | {Business rule}     | {Applicable condition} |
+| BR-2    | {Action from flow}  | {Business rule}     | {Applicable condition} |
+
+---
+
+## Phase 5: Business Logic
+
+> ✅ PO Confirmed: {Yes/No}
+
+| 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}|
+
+---
+
+## Phase 6: Acceptance Criteria
+
+> ✅ PO Confirmed: {Yes/No}
+
+| AC ID | Description            | Expected Behavior         | Derived from |
+|-------|------------------------|---------------------------|--------------|
+| AC-1  | {Criterion description} | {Expected behavior}       | BR-{N}       |
+| AC-2  | {Criterion description} | {Expected behavior}       | BR-{N}       |
+
+---
+
+## Phase 7: Validation Report
+
+### Coverage Matrix
+| Flow Action | Has Rule? | Has Logic? | Has AC? | Status |
+|-------------|-----------|------------|---------|--------|
+| {Action 1}  | ✅/❌     | ✅/❌      | ✅/❌   | OK/GAP |
+
+### Conflicts Detected
+- {Conflict description — or "None"}
+
+### Missing Items
+- {Missing rule/AC/logic — or "None"}
+
+---
+
+<!--
+  NEXT STEPS:
+  When Product Definition is complete (Status: completed), run:
+  /generate-prd {path-to-this-file} --jira {TICKET-ID}
+  to generate a PRD from this Product Definition.
+-->

package/core/templates/project-context.yaml

@@ -0,0 +1,161 @@
+# =============================================================
+# Project Context — AI-First Spec-Driven Development
+# =============================================================
+# This is the SINGLE SOURCE OF TRUTH for project-specific
+# paths, tools, and routing used by all workflows.
+#
+# Workflows reference this file for WHERE to find things.
+# Workflow steps define WHAT to do (universal best practices).
+# =============================================================
+#
+# HOW AI AGENTS USE THIS FILE:
+# 1. Open this file at the start of any workflow
+# 2. Parse the YAML structure
+# 3. When a workflow says "→ key.subkey", look up that key
+#    and use the resolved value as the actual path
+# 4. All paths are RELATIVE to workspace root
+# 5. For "{domain}", substitute from spec's @trace.domain
+# =============================================================
+
+project:
+  name: "{{PROJECT_NAME}}"
+  description: "{{PROJECT_DESCRIPTION}}"
+
+# ----- File Paths -----
+# All paths are relative to workspace root.
+paths:
+  # Feature-Package Layout:
+  #   specs/{domain}/{prd-slug}/prd.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)
+  #   .trace/{domain}/{prd-slug}/{UC-ID}.tsv     — Trace state
+  #
+  # specs_dir is the unified root for all spec artifact types (PRD, BDD, tech-docs, design-spec).
+  # prd-slug is derived from the PRD folder path — not a separate config variable.
+  specs_dir: "specs"
+  templates_dir: "specs/templates"
+  feature_template: "specs/templates/feature.template"
+  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: "specs/templates/prd.template.md"
+  refinement_dir: ".agent/review"
+
+  # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
+  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
+  # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
+  qc_dir: "docs"
+
+  # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
+  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
+  # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
+  # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten
+  # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path).
+  qc_skills_dir: ".agent/skills/qc"
+
+  # Product Definitions
+  product_definitions_dir: "specs/product-definition"
+  product_definition_template: "specs/templates/product-definition.template.md"
+
+  # Domain Knowledge
+  domain_knowledge_dir: "specs/domain-knowledge"
+  business_dictionary: "specs/domain-knowledge/business-dictionary.md"
+  core_entities: "specs/domain-knowledge/core-entities.md"
+
+  # Project Lessons (guardrails accumulated via /learn — loaded by context-loader Step 6.7)
+  # Single-service default below. In umbrella/service mode, set this in each service's
+  # .agent/project-context.yaml to ".agent/project-lessons.md" (resolved per service_root).
+  lessons_file: "specs/domain-knowledge/lessons-learned.md"
+
+  # Tech Docs (BE-authored API contract).
+  # Merged into specs_dir in the feature-package layout:
+  # tech-docs live at specs/{domain}/{prd-slug}/tech-docs/.
+  # In umbrella mode with spec_source set, context-loader auto-routes this to
+  # {spec_source}/specs so FE/App read the contract via the spec submodule.
+  tech_docs_dir: "specs"
+
+  # Design Specs (FE/App platforms only — web, app).
+  # In the feature-package layout, design-specs live at specs/{domain}/{prd-slug}/design-spec/.
+  # This variable is no longer needed as a separate path — derived from specs_dir.
+  # design_spec_dir: "specs/design-spec"   ← removed; use specs_dir instead
+
+  # Trace (internal structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv)
+  trace_dir: ".trace"
+
+  # Tester / QC feedback (written by /report-bug and /propose-scenario).
+  # These live in the SHARED spec repo so PO/Dev see them on their next /sync.
+  # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/.
+  bug_reports_dir: "feedback/bug-reports"
+  bdd_proposals_dir: "feedback/bdd-proposals"
+  # PRD change requests (new requirement found in test, not covered by any AC) —
+  # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd.
+  prd_change_requests_dir: "feedback/prd-change-requests"
+
+tech_stack:
+  language: "{{LANGUAGE}}"              # e.g., Java 17 / TypeScript / C# / Go
+  framework: "{{FRAMEWORK}}"           # e.g., Spring Boot 3.2 / Angular 17 / .NET 8
+  build_tool: "{{BUILD_TOOL}}"         # e.g., Maven / npm / dotnet / go
+  test_framework: "{{TEST_FRAMEWORK}}" # e.g., JUnit 5 + Mockito / Jest / xUnit
+  database: "{{DATABASE}}"             # e.g., PostgreSQL / MySQL / MongoDB
+  module: "{{MODULE}}"                 # e.g., java-spring / angular / dotnet / golang / context-engineering
+
+conventions:
+  build_command: "{{BUILD_COMMAND}}"   # e.g., mvn clean install -DskipTests
+  test_command: "{{TEST_COMMAND}}"     # e.g., mvn test
+  service_run: "{{RUN_COMMAND}}"       # e.g., mvn spring-boot:run
+  ticket_prefix: "{{TICKET_PREFIX}}"  # e.g., PROJ / FEAT / UC
+
+domains:
+  - "{{DOMAIN_1}}"
+  # - "{{DOMAIN_2}}"
+
+# ----- Multi-Service / Umbrella Setup -----
+# Fill this section ONLY if this is an UMBRELLA repo that contains multiple
+# service submodules. Leave commented out for single-service projects.
+#
+# setup:
+#   mode: umbrella                            # "umbrella" | "single" (default: single)
+#   spec_source: "{{SPEC_SUBMODULE_PATH}}"   # path to PO spec submodule, e.g. "free-trial-specs"
+#
+# When spec_source is set, context-loader auto-derives (ALL specs live in the spec repo
+# using the feature-package layout; service submodules hold only code):
+#   specs_dir            → {spec_source}/specs                # unified root — PRD/BDD/tech-docs/design-spec
+#   tech_docs_dir        → {spec_source}/specs                # merged into specs_dir
+#   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
+#   trace_dir            → {spec_source}/.trace               # structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+# (You can still override these manually in paths: section below.)
+# With spec_source set, only ONE override is needed instead of four separate dir vars.
+#
+# services:                                   # domain → service submodule routing
+#   {{DOMAIN_1}}:                             # must match @trace.domain in PRD files
+#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
+#     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
+#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
+#
+# IMPORTANT — per-service CLAUDE.md:
+#   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its
+#   architecture + coding standards for ITS stack. context-loader loads CLAUDE.md in two
+#   layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay,
+#   wins on conflict for architecture/coding-standards). The agent sits at the umbrella
+#   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
+#   (likely the wrong stack). Generate one per service via /setup-ai-first inside each.
+#   {{DOMAIN_2}}:
+#     path: "{{SERVICE_2_DIR}}"
+#     module: "{{STACK_MODULE}}"
+#     specs_dir: "{{SERVICE_2_DIR}}/specs"
+#     tech_docs_dir: "{{SERVICE_2_DIR}}/specs"
+
+# ----- Architecture -----
+architecture:
+  style: "{{ARCH_STYLE}}"              # e.g., Layered / Clean / Hexagonal
+  layers: "{{LAYER_STACK}}"            # e.g., Controller → Facade → Service → Repository
+  key_rules:
+    - "{{ARCH_RULE_1}}"
+    - "{{ARCH_RULE_2}}"

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

@@ -0,0 +1,19 @@
+[📚 Docs](../README.md) › Getting Started
+
+# Getting Started
+
+Bắt đầu với spec-driven-docs framework — cài đặt, chạy feature đầu tiên, và nắm các khái niệm cốt lõi trong vài phút.
+
+## Mục lục (this section)
+
+- [installation.md](installation.md) — Cài framework, prerequisites (Node, Claude Code), QC automation stack, và VS Code extension (Review Board + Living Docs panels).
+- [quickstart.md](quickstart.md) — Chạy feature đầu tiên end-to-end: Discovery → PRD → BDD → Tech Design → Code → Dev self-check.
+- [core-concepts.md](core-concepts.md) — Khái niệm trong 5 phút: spec-as-source-of-truth, pipeline phases, traceability, dev_selftest vs qc_status, umbrella/spec-module.
+
+## Đọc gì trước?
+
+1. Mới hoàn toàn? → bắt đầu ở [core-concepts.md](core-concepts.md) để hiểu triết lý.
+2. Sẵn sàng cài? → [installation.md](installation.md).
+3. Đã cài xong? → [quickstart.md](quickstart.md) để chạy feature đầu tiên.
+
+> Cần đào sâu hơn? Xem các section khác trong [📚 Docs](../README.md) — concepts, multi-repo/umbrella, QC pipeline, command reference, architecture.