spec-lite 1.0.1 → 1.1.0

package/templates/main/feature/frd-template.md

@@ -5,7 +5,7 @@ status: draft
 owner: "{BA}"
 feature_id: "{Feature ID từ PRD Feature Index}"
 referenced_by:
-  - conventions.md > 3. Main Artifacts > 3.2 Feature level > frd.md > Cấu trúc
+  - conventions.md > 3. Main Artifacts > 3.3 Feature level > frd.md > Cấu trúc
   - skills/spec-new/SKILL.md > Process > Bước 5: Write — sinh draft > Cascade Proposals > frd.md
 ---
 
@@ -15,44 +15,59 @@ referenced_by:
 
 {Mô tả feature này giải quyết vấn đề gì cho user nào, trong 2-3 câu.}
 
+## Components Consumed
+
+Các component mà feature này dùng — tham chiếu đến `specs/main/component/{C-XXX}-...`.
+
+| Component | Vai trò trong feature |
+| --- | --- |
+| `{C-XXX}-{component-name}` | {component này phục vụ cái gì cho feature này} |
+
 ## Feature-level Acceptance Criteria
 
 Criteria áp dụng cho toàn bộ feature — không gắn với story cụ thể (ví dụ: performance, security, accessibility).
+AC ID format: `AC-F{NNN}-{seq}` — đánh số tăng dần toàn feature (không reset giữa sections).
 
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
+- `AC-{F_ID}-001`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ## User Stories
 
-### US-001: {Story title}
+US ID format: `US-F{NNN}-{seq}` — đánh số tăng dần toàn feature.
+
+### US-{F_ID}-001: {Story title}
 
-As a {persona}, I want to {action} so that {value}.
+**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
 **Priority:** Must / Should / Could
 
 **Acceptance Criteria:**
 
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
+- `AC-{F_ID}-{seq}`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
+- `AC-{F_ID}-{seq}`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ---
 
-### US-002: {Story title}
+### US-{F_ID}-002: {Story title}
 
-As a {persona}, I want to {action} so that {value}.
+**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
 **Priority:** Must / Should / Could
 
 **Acceptance Criteria:**
 
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
+- `AC-{F_ID}-{seq}`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ---
 

package/templates/main/prd-template.md

@@ -39,6 +39,14 @@ Tại sao cần giải quyết bây giờ.
 | --- | --- | --- | --- | --- |
 | F-001 | {tên feature} | {mô tả ngắn — feature làm gì, cho ai} | High/Medium/Low | TODO/DONE |
 
+## Components
+
+Các thành phần kỹ thuật của hệ thống — chi tiết về vai trò và thiết kế nằm trong `specs/main/component/{C-XXX}-{component-name}/`.
+
+| ID | Component | Mô tả ngắn | Status |
+| --- | --- | --- | --- |
+| C-001 | {tên component} | {1 câu — component này chịu trách nhiệm gì} | TODO/DONE |
+
 ## Non-Functional Requirements
 
 | ID | Category | Requirement | Target | Priority |

package/skills/spec-domain/SKILL.md

@@ -1,176 +0,0 @@
----
-name: spec-domain
-description: Điền hoặc cập nhật domain.md — Domain Knowledge (entities, business rules, terminology). Dùng sau khi prd.md đã có nội dung.
----
-
-# spec-domain
-
-## Overview
-
-Tạo nội dung cho `specs/main/domain.md` thông qua interview có cấu trúc. Domain là ngôn ngữ chung của hệ thống — nó định nghĩa các khái niệm business, entities, business rules, và events mà toàn bộ team (cả business lẫn tech) dùng chung.
-
-Domain không chứa: implementation details, DB schema, framework-specific code, hay bất cứ thứ gì thuộc về `sad.md`, `fdd.md`.
-
-## When to Use
-
-- `domain.md` chưa có hoặc còn rỗng, và `prd.md` đã có nội dung
-- Cần bổ sung entity hoặc business rule mới phát sinh từ một integration
-- Cascade proposals từ `spec.md` hoặc `tech.md` yêu cầu cập nhật domain
-
-## When NOT to Use
-
-- `prd.md` chưa có nội dung → chạy `/spec-prd` trước
-- Đang muốn thiết kế kiến trúc kỹ thuật → dùng `/spec-sad`
-- Đang muốn định nghĩa feature-level requirements → dùng `/spec-frd`
-
----
-
-## Process
-
-### Bước 1: Kiểm tra preconditions
-
-**Đọc `specs/main/prd.md`:**
-
-- **Chưa tồn tại hoặc là template** → dừng ngay:
-  > `prd.md` chưa có nội dung. Hãy chạy `/spec-prd` trước để có PRD trước khi định nghĩa domain.
-
-- **Đã có nội dung** → đọc để lấy context: scope, problem statement, target users. Dùng làm nền để hỏi về entities.
-
-**Đọc `specs/main/domain.md`:**
-
-- **Chưa tồn tại** → tạo thư mục `specs/main/` nếu chưa có, tiến hành Bước 2 (full interview).
-
-- **Đã có nội dung thực** → quét toàn bộ sections, hiển thị trạng thái từng section, rồi hỏi user muốn làm gì.
-
-  **Các sections cần quét** (theo thứ tự):
-
-  | # | Section | Có nội dung thực? |
-  | --- | --- | --- |
-  | 1 | Terminology | ✓ đã có / ✗ trống/thiếu |
-  | 2 | Entities | ✓ đã có / ✗ trống/thiếu |
-  | 3 | Business Rules | ✓ đã có / ✗ trống/thiếu |
-  | 4 | Domain Events | ✓ đã có / ✗ trống/thiếu |
-
-  Một section được coi là **trống/thiếu** nếu: không tồn tại trong file, hoặc chỉ chứa placeholder template (dấu `{}`), hoặc không có dòng nội dung thực. Ngoài các sections trên, **ghi nhận các sections thừa** — những `##` heading có trong file nhưng không có trong template.
-
-  Sau khi quét, liệt kê tất cả sections **theo đúng thứ tự xuất hiện trong file**, đánh số liên tục:
-
-  ```
-  domain.md hiện tại:
-    [1] Terminology         ✓ đã có
-    [2] Entities            ✓ đã có
-    [3] Business Rules      ✗ chưa có — cần bổ sung
-    [4] Risks               ⚠ không có trong template
-    [5] Domain Events       ✓ đã có
-    [A] Interview tất cả sections
-
-  Chọn số hoặc A:
-  ```
-
-  - User chọn số section thuộc template → interview section đó rồi merge vào file.
-  - User chọn số section thừa (⚠) → xoá section đó khỏi file ngay, không hỏi thêm.
-  - User chọn A → interview tuần tự tất cả sections thuộc template (sections thừa không bị đụng tới).
-
----
-
-### Bước 2: Gather — interview có cấu trúc
-
-Trước khi hỏi, tóm tắt ngắn context đọc được từ `prd.md` (nếu có) và surface assumptions:
-
-```
-TỪ PRD TÔI HIỂU:
-- Hệ thống giải quyết: {problem statement ngắn gọn}
-- Các khái niệm tôi thấy xuất hiện: {list terms từ prd}
-
-ASSUMPTIONS TÔI ĐANG ĐẶT RA:
-1. {assumption 1}
-2. {assumption 2}
-→ Sửa lại nếu sai trước khi tiếp tục.
-```
-
-Sau đó hỏi tuần tự từng phần — không hỏi tất cả cùng lúc:
-
-**Phần 1 — Terminology:**
-> Có thuật ngữ nghiệp vụ nào đặc thù cần định nghĩa rõ không? (Ví dụ: "đơn hàng" trong hệ thống này nghĩa là gì chính xác?)
-> Liệt kê những term hay bị dùng sai hoặc có nhiều cách hiểu.
-
-**Phần 2 — Entities:**
-> Hệ thống làm việc với những "đối tượng" nghiệp vụ nào? (Ví dụ: User, Order, Product...)
-> Với mỗi entity: nó đại diện cho cái gì trong business? Attributes nào quan trọng? Có lifecycle (state machine) không?
-
-Với mỗi entity được đề cập, hỏi tiếp:
-> Entity này có trạng thái (state) thay đổi theo thời gian không? Nếu có, các trạng thái đó là gì và khi nào chuyển đổi?
-
-**Phần 3 — Business Rules:**
-> Có quy tắc nghiệp vụ nào bất biến không? (Ví dụ: "Không thể hủy đơn hàng đã giao", "User chưa verify không được thanh toán")
-> Ghi theo format: rule — khi nào apply — ngoại lệ nếu có.
-
-**Phần 4 — Domain Events:** *(hỏi nếu hệ thống có event-driven behavior)*
-> Có sự kiện nghiệp vụ nào quan trọng cần track không? (Ví dụ: OrderPlaced, PaymentFailed...)
-> Khi nào xảy ra? Data gì đi kèm?
-
-Nếu câu trả lời vague → hỏi lại. Ví dụ:
-- "có nhiều loại user" → "liệt kê cụ thể từng loại và điểm khác nhau giữa chúng là gì?"
-- "đơn hàng có nhiều trạng thái" → "liệt kê hết các trạng thái và vẽ luồng chuyển đổi"
-
----
-
-### Bước 3: Write — sinh draft
-
-Dùng `.claude/templates/main/domain-template.md` làm skeleton, điền nội dung từ interview vào từng section.
-
-Hiển thị draft cho user xem — **chưa ghi file**.
-
----
-
-### Bước 4: Review — xác nhận với user
-
-Trình bày draft và hỏi:
-> Draft Domain trên đã đúng chưa? Có entity nào thiếu, business rule nào sai không?
-
-Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → cập nhật draft → hỏi lại.
-
----
-
-### Bước 5: Save
-
-Ghi nội dung đã được confirm vào `specs/main/domain.md`.
-
-Thông báo kết quả:
-```
-✓ specs/main/domain.md đã được cập nhật (status: draft)
-
-Bước tiếp theo:
-  - /spec-sad → thiết kế kiến trúc kỹ thuật (dùng prd.md + domain.md làm context)
-  - (sau sad) /spec-frd {feature-name} → định nghĩa requirements của từng feature
-```
-
----
-
-## Common Rationalizations
-
-| Rationalization | Reality |
-| --- | --- |
-| "Entities thì ai cũng biết rồi, không cần ghi" | Entity chưa được viết ra là entity chưa được đồng thuận. Dev và BA có thể hiểu khác nhau. |
-| "Business rules thì ghi trong code thôi" | Business rules trong code không ai đọc được ngoài dev. Domain là ngôn ngữ chung cho cả team. |
-| "State machine phức tạp, thêm sau" | State machine ảnh hưởng trực tiếp đến data model và API design. Thiếu nó là thiếu constraint quan trọng. |
-| "Terminology thì khỏi cần, ai cũng hiểu" | "Order" trong hệ thống bán lẻ khác "Order" trong hệ thống sản xuất. Định nghĩa rõ tránh miscommunication. |
-
-## Red Flags
-
-- Entity chỉ có tên, không có attributes hay mô tả
-- Business rules ghi dưới dạng technical ("validate bằng regex") thay vì business ("số điện thoại phải là số Việt Nam")
-- Terminology section trống trong khi domain có nhiều thuật ngữ đặc thù
-- Attributes dùng DB type (`VARCHAR`, `INT`) thay vì business type (`text`, `number`)
-
-## Verification
-
-Trước khi kết thúc, kiểm tra:
-
-- [ ] Frontmatter đầy đủ và đúng schema
-- [ ] Mỗi term trong Terminology có definition rõ ràng, không mơ hồ
-- [ ] Mỗi entity có mô tả business context (không chỉ là tên)
-- [ ] Attributes dùng business type, không phải DB type
-- [ ] State machine chỉ có ở entity có lifecycle thực sự
-- [ ] Business rules có ID (`DOM-R01`...), condition, và exception rõ ràng
-- [ ] User đã confirm trước khi file được ghi