spec-lite 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # spec-lite
 
-Bộ skills spec-driven development cho Claude Code — phỏng vấn có cấu trúc để xây dựng PRD, domain knowledge, kiến trúc hệ thống và integration specs.
+Bộ skills spec-driven development cho Claude Code — phỏng vấn có cấu trúc để xây dựng PRD, kiến trúc hệ thống, và integration specs. Domain knowledge và component/feature artifacts mọc dần qua cascade từ integrations.
 
 > **Lưu ý:** Hiện tại chỉ hoạt động với [Claude Code](https://claude.ai/code) (thư mục `.claude/`).
 
@@ -19,17 +19,17 @@ Các skill được gọi bằng slash command bên trong Claude Code.
 ### Thứ tự thực hiện
 
 ```
-/spec-prd → /spec-domain → /spec-sad
-                                │
-                    (có requirement mới)
-                                │
-                          /spec-new
-                                │
-                          /spec-tech
-                                │
-                          /plan
-                                │
-                          /build
+/spec-prd → /spec-sad
+              │
+   (có requirement mới)
+              │
+        /spec-new
+              │
+        /spec-tech
+              │
+        /plan
+              │
+        /build
 ```
 
 ---
@@ -37,17 +37,12 @@ Các skill được gọi bằng slash command bên trong Claude Code.
 ### Seed skills — chạy một lần khi bắt đầu dự án
 
 #### `/spec-prd`
-Tạo hoặc cập nhật `specs/main/prd.md` thông qua interview có cấu trúc.
+Tạo hoặc cập nhật `specs/main/prd.md` thông qua interview có cấu trúc. Đồng thời scaffold `specs/main/domain.md` skeleton.
 
-Sections: Problem Statement · Target Users · Scope · Features · Non-Functional Requirements · Business Constraints
-
-#### `/spec-domain`
-Tạo hoặc cập nhật `specs/main/domain.md`. Yêu cầu `prd.md` phải có nội dung trước.
-
-Sections: Terminology · Entities · Business Rules · Domain Events
+Sections: Problem Statement · Target Users · Scope · Features · Components · Non-Functional Requirements · Business Constraints
 
 #### `/spec-sad`
-Tạo hoặc cập nhật `specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` phải có nội dung trước.
+Tạo hoặc cập nhật `specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` đã tồn tại.
 
 Sections: Architectural Style · System Overview · Tech Stack · Cross-Cutting Concerns · Inter-Service Communication · Infrastructure Overview · Architectural Guardrails
 
@@ -70,16 +65,20 @@ Tạo `specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve.
 #### `/plan`
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`.
 
+#### `/build`
+Implement từng task trong `plan.md`/`todo.md` theo TDD incremental.
+
 ---
 
 ### Files được tạo ra
 
 | Command | Output |
 |---------|--------|
-| `/spec-prd` | `specs/main/prd.md` |
-| `/spec-domain` | `specs/main/domain.md` |
+| `/spec-prd` | `specs/main/prd.md`, `specs/main/domain.md` (skeleton) |
 | `/spec-sad` | `specs/main/sad.md` |
 | `/spec-new` | `specs/integrations/{slug}/spec.md` |
 | `/spec-tech` | `specs/integrations/{slug}/tech.md` |
 | `/plan` | `specs/integrations/{slug}/plan.md`, `todo.md` |
 | `/build` | _(implements tasks từ `plan.md`/`todo.md`)_ |
+
+Component (`crd.md`, `cdd.md`) và feature (`frd.md`, `fdd.md`) artifacts mọc dần qua **cascade proposals** từ integrations — không có skill chuyên biệt để tạo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/plan/SKILL.md

@@ -66,10 +66,12 @@ Surface tóm tắt để planning-and-task-breakdown có đủ context:
 ```
 CONTEXT CHO PLANNING:
 - Integration: {title}
+- Features: {từ spec.md frontmatter}
+- Components: {từ spec.md frontmatter}
 - Yêu cầu chính: {tóm tắt từ spec.md — 2-4 bullet}
-- Acceptance Criteria: {số lượng} — Feature-level: {AC-F-001, AC-F-002...} / Story-level: {AC-S-001, AC-S-002...}
+- Acceptance Criteria: {tổng số AC — list IDs theo nhóm Feature/Component như spec.md}
 - Thay đổi kỹ thuật: {modules, data model, interfaces từ tech.md}
-- Entities liên quan: {từ domain.md}
+- Shared entities liên quan: {từ domain.md}
 
 ASSUMPTIONS:
 1. {assumption về ordering nếu có}

package/skills/spec-new/SKILL.md

@@ -19,7 +19,7 @@ Tạo `spec.md` cho một integration mới trong `specs/integrations/{NNN}-{slu
 
 ## When NOT to Use
 
-- `prd.md` hoặc `domain.md` chưa có → chạy `/spec-prd`, `/spec-domain` trước
+- `prd.md` chưa có → chạy `/spec-prd` trước (skill đó scaffold cả `domain.md` skeleton)
 - Muốn thiết kế technical design → dùng `/spec-tech` (cần `spec.md` đã approve trước)
 - Chỉ muốn cập nhật spec đã có → edit file trực tiếp
 
@@ -50,7 +50,7 @@ Features trong PRD:
 Chọn số feature để bắt đầu spec:
 ```
 
-Ghi chú `→ frd.md tồn tại` nếu file `specs/main/features/{feature-id}-*/frd.md` đã có.
+Ghi chú `→ frd.md tồn tại` nếu file `specs/main/feature/{F-XXX}-*/frd.md` đã có.
 
 Nếu tất cả features đều Done → thông báo:
 > Tất cả features trong prd.md đã được implement. Nếu có yêu cầu mới, hãy truyền nó trực tiếp: `/spec-new <yêu cầu>`.
@@ -84,11 +84,12 @@ Lưu lại lựa chọn section.
 
 ### Bước 2: Load context
 
-Load các file sau (bất kể input là raw requirement hay từ prd.md):
+Từ raw requirement, agent xác định features và components liên quan, rồi load các file sau:
 
-- `specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, và mô tả feature liên quan nếu có
-- `specs/main/domain.md` — đọc Entities và Business Rules
-- Nếu input từ prd.md và có `specs/main/features/{feature-id}/frd.md` → đọc User Stories và Acceptance Criteria
+- `specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index
+- `specs/main/domain.md` — đọc Glossary và Shared Entities
+- `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature liên quan (nếu file đã tồn tại)
+- `specs/main/component/{C-XXX}-{slug}/crd.md` — cho mỗi component bị touched (nếu file đã tồn tại)
 
 Tóm tắt context và surface assumptions:
 
@@ -96,15 +97,19 @@ Tóm tắt context và surface assumptions:
 TỪ PRD & DOMAIN TÔI HIỂU:
 - Vấn đề đang giải quyết: {problem statement ngắn từ prd}
 - Personas liên quan: {từ prd Target Users}
-- Entities liên quan: {từ domain.md}
-{nếu có feature cụ thể} - Feature: {ID} — {tên} — {mô tả}
+- Glossary terms liên quan: {từ domain.md}
+- Shared entities liên quan: {từ domain.md}
+{nếu có feature liên quan} - Features: {F-XXX — tên — mô tả ngắn}
+{nếu có component liên quan} - Components: {C-XXX — tên — mô tả ngắn}
 
 ASSUMPTIONS TÔI ĐANG ĐẶT RA:
 1. {assumption về scope}
-2. {assumption về persona}
+2. {assumption về features/components bị touched}
 → Sửa lại nếu sai trước khi tiếp tục.
 ```
 
+Nếu integration giới thiệu feature mới hoặc component mới chưa có trong PRD Index → ghi nhận để cascade ở Bước 5.
+
 ---
 
 ### Bước 3: Interview
@@ -120,11 +125,11 @@ Hỏi tuần tự, từng phần — không hỏi tất cả cùng lúc:
 > Hoặc liệt kê functional requirements nếu không theo user story format.
 
 **Phần 3 — Acceptance Criteria:**
-> Điều kiện nào để biết integration này là done? Phân theo 2 loại:
-> - **Feature-level AC** (`AC-F-xxx`): criterion áp dụng cho toàn flow — không gắn với story cụ thể (ví dụ: error format, auth guard, cross-story constraints)
-> - **Story-level AC** (`AC-S-xxx`): criterion gắn với từng user story cụ thể
-> Viết theo cú pháp: GIVEN {precondition} / WHEN {action} / THEN {expected outcome}
-> `AC-F` và `AC-S` đánh số độc lập, tăng dần xuyên suốt toàn spec (không reset qua feature/story).
+> Điều kiện nào để biết integration này là done? Format Given/When/Then.
+> Agent tự nhóm AC theo cách phù hợp với bản chất integration:
+> - Có user-facing flow → group theo Feature → User Story → AC, dùng ID `AC-{F_ID}-{seq}`
+> - Thuần technical (refactor / capability nội tại) → group theo Component, dùng ID `AC-{C_ID}-{seq}`, không cần user story
+> - Mixed (vừa thêm feature, vừa thay đổi component) → có thể có cả 2 nhóm
 
 **Phần 4 — Out of Scope:**
 > Có gì liên quan nhưng sẽ KHÔNG làm trong integration này không? Ghi rõ lý do.
@@ -157,34 +162,59 @@ Tổng hợp và viết draft `spec.md`:
 
 **Cấu trúc file**: dùng `.claude/templates/integrations/spec-template.md` làm skeleton, điền nội dung từ interview vào.
 
-**Cascade Proposals** — điền theo hướng dẫn sau:
+**Cascade Proposals** — agent đề xuất delta cho main artifacts theo các targets sau (chỉ điền nếu thực sự có thay đổi, không thì ghi "Không có thay đổi đề xuất."):
 
 ### prd.md
 
-{Đề xuất cập nhật nếu phát hiện scope/feature mới cần ghi lại, hoặc "Không có thay đổi đề xuất."}
+Đề xuất cập nhật nếu integration này:
+- Giới thiệu feature mới chưa có trong Feature Index → đề xuất thêm row vào Features (auto-pick `F-XXX` next ID, slug từ context)
+- Giới thiệu component mới chưa có trong Component Index → đề xuất thêm row vào Components (auto-pick `C-XXX` next ID)
+- Đổi status feature từ `TODO` sang `In Progress`
+- Có scope hoặc NFR thay đổi
 
 ### domain.md
 
-{Đề xuất cập nhật nếu phát hiện entity hoặc business rule mới, hoặc "Không có thay đổi đề xuất."}
+Đề xuất cập nhật nếu integration này:
+- Giới thiệu glossary term mới → đề xuất thêm vào Glossary
+- Giới thiệu shared entity mới (entity sẽ được dùng bởi 2+ component) → đề xuất thêm vào Shared Entities với field `Owner: C-XXX`
+
+### component/{C-XXX}-{component-name}/crd.md
+
+Liệt kê **tất cả** components bị touched trong integration và đánh giá từng cái:
+
+| Component | crd.md | Đề xuất |
+| --- | --- | --- |
+| C-001 — auth | tồn tại | **Cập nhật** — thêm responsibility "rate limiting", thêm endpoint `POST /auth/rate-check` |
+| C-003 — payment | chưa có | **Tạo mới** crd + cdd |
+
+Với từng component có đề xuất:
+
+**Tạo mới** `specs/main/component/{C-XXX}-{component-slug}/crd.md` *(và `cdd.md` cascade ở spec-tech)*
+- Dùng khi integration này là lần đầu tiên giới thiệu component này
+- Auto-pick C-XXX (next available) và slug kebab-case từ context
+- Đề xuất nội dung crd: Role, Responsibilities, Owned Entities, Public Interface, Business Rules, Dependencies — dựa trên spec.md
 
-### frd.md
+**Cập nhật** `specs/main/component/{C-XXX}-{component-slug}/crd.md`
+- Dùng khi crd.md đã tồn tại và integration bổ sung thêm responsibility, interface, hoặc business rule
+- Ghi rõ section nào bị touched và delta cụ thể
 
-Liệt kê **tất cả** features từ PRD và đánh giá từng cái:
+### feature/{F-XXX}-{feature-name}/frd.md
+
+Liệt kê **tất cả** features liên quan đến integration và đánh giá từng cái:
 
 | Feature | Status | frd.md | Đề xuất |
 | --- | --- | --- | --- |
 | F-001 — Authentication | In Progress | tồn tại | **Cập nhật** — bổ sung US-003, AC mới về rate limiting |
 | F-002 — User Profile | TODO | chưa có | **Tạo mới** |
-| F-003 — Credit System | Done | tồn tại | Không liên quan |
 
-Với từng feature có đề xuất thay đổi, ghi rõ:
+Với từng feature có đề xuất thay đổi:
 
-**Tạo mới** `specs/main/features/{number}-{feature-slug}/frd.md`
+**Tạo mới** `specs/main/feature/{F-XXX}-{feature-slug}/frd.md`
 - Dùng khi integration này là lần đầu tiên implement feature này
-- Thư mục đặt tên theo convention: `{number}-{feature-slug}` (ví dụ: `001-authentication`)
-- Nội dung đề xuất: {tóm tắt User Stories và Acceptance Criteria từ spec.md}
+- Thư mục đặt tên: `{F-XXX}-{feature-slug}` (ví dụ: `F-001-authentication`)
+- Nội dung đề xuất: User Stories, AC, Components consumed (reference C-XXX) — từ spec.md
 
-**Cập nhật** `specs/main/features/{number}-{feature-slug}/frd.md`
+**Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/frd.md`
 - Dùng khi frd.md đã tồn tại và integration này bổ sung thêm stories hoặc criteria
 - Đọc file frd.md hiện tại, liệt kê các sections và hỏi user muốn update section nào:
 
@@ -193,10 +223,11 @@ frd.md — F-001 Authentication đã tồn tại.
 Sections hiện có:
 
   [1] Overview
-  [2] Feature-level Acceptance Criteria
-  [3] User Stories
-  [4] Scope (In Scope / Out of Scope)
-  [5] Dependencies
+  [2] Components Consumed
+  [3] Feature-level Acceptance Criteria
+  [4] User Stories
+  [5] Scope (In Scope / Out of Scope)
+  [6] Dependencies
   [A] All — viết lại toàn bộ từ đầu
 
 Chọn section cần cập nhật (có thể chọn nhiều, ví dụ: 2 3):
@@ -225,9 +256,9 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 Tạo thư mục `specs/integrations/{NNN}-{slug}/` nếu chưa có.
 
-Ghi nội dung đã confirm vào `specs/integrations/{NNN}-{slug}/spec.md`.
+Ghi nội dung đã confirm vào `specs/integrations/{NNN}-{slug}/spec.md`. Frontmatter `features` và `components` phải được điền theo những gì đã nhận diện ở Bước 2.
 
-Nếu integration này đến từ prd.md, cập nhật `specs/main/prd.md`: đổi Status của feature từ `TODO` → `In Progress` và điền link vào cột FRD.
+Nếu integration này gắn với feature từ prd.md, cập nhật `specs/main/prd.md`: đổi Status của feature từ `TODO` → `In Progress`.
 
 Thông báo kết quả:
 ```
@@ -235,7 +266,8 @@ Thông báo kết quả:
 {nếu có} ✓ prd.md — F-XXX status cập nhật: TODO → In Progress
 
 Bước tiếp theo:
-  - Review và approve spec.md
+  - Review spec.md và apply Cascade Proposals (nếu có) vào main artifacts thủ công
+  - Approve spec.md (đổi status: draft → approved)
   - /spec-tech → thiết kế technical design dựa trên spec.md này
 ```
 

package/skills/spec-prd/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: spec-prd
-description: Điền hoặc cập nhật prd.md — Product Requirements Document ở product level. Dùng khi prd.md còn là template rỗng hoặc cần review/cập nhật.
+description: Điền hoặc cập nhật prd.md — Product Requirements Document ở product level. Cũng scaffold domain.md skeleton (glossary placeholder + Shared Entities rỗng). Dùng khi prd.md còn là template rỗng hoặc cần review/cập nhật.
 ---
 
 # spec-prd
 
 ## Overview
 
-Tạo nội dung cho `specs/main/prd.md` thông qua interview có cấu trúc. PRD là nguồn sự thật ở product level — nó định nghĩa vấn đề, users, scope, và NFRs trước khi bất kỳ technical decision nào được đưa ra.
+Tạo nội dung cho `specs/main/prd.md` thông qua interview có cấu trúc. PRD là nguồn sự thật ở product level — nó định nghĩa vấn đề, users, scope, features, components, và NFRs trước khi bất kỳ technical decision nào được đưa ra.
 
-PRD không chứa: tech stack, implementation details, entity schema, hay bất cứ thứ gì thuộc về `sad.md` hoặc `domain.md`.
+Skill này cũng scaffold `specs/main/domain.md` skeleton nếu chưa tồn tại — domain.md sẽ được mọc dần qua cascade từ integrations (glossary terms, shared entities).
+
+PRD không chứa: tech stack, implementation details, entity schema, glossary, business rules — những thứ đó thuộc về `sad.md` hoặc `domain.md`.
 
 ## When to Use
 
@@ -19,8 +21,8 @@ PRD không chứa: tech stack, implementation details, entity schema, hay bất
 
 ## When NOT to Use
 
-- Đang muốn thiết kế kiến trúc kỹ thuật → dùng `/spec.sad`
-- Đang muốn định nghĩa domain entities → dùng `/spec.domain`
+- Đang muốn thiết kế kiến trúc kỹ thuật → dùng `/spec-sad`
+- Cập nhật domain entities cụ thể → đi qua integration (`/spec-new`) và để cascade mechanism handle
 
 ---
 
@@ -44,8 +46,9 @@ PRD không chứa: tech stack, implementation details, entity schema, hay bất
   | 2 | Target Users | ✓ đã có / ✗ trống/thiếu |
   | 3 | Scope | ✓ đã có / ✗ trống/thiếu |
   | 4 | Features | ✓ đã có / ✗ trống/thiếu |
-  | 5 | Non-Functional Requirements | ✓ đã có / ✗ trống/thiếu |
-  | 6 | Business Constraints | ✓ đã có / ✗ trống/thiếu |
+  | 5 | Components | ✓ đã có / ✗ trống/thiếu |
+  | 6 | Non-Functional Requirements | ✓ đã có / ✗ trống/thiếu |
+  | 7 | Business Constraints | ✓ đã 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.
 
@@ -60,8 +63,9 @@ PRD không chứa: tech stack, implementation details, entity schema, hay bất
     [3] Scope                   ✓ đã có
     [4] Risks                   ⚠ không có trong template
     [5] Features                ✗ chưa có — cần bổ sung
-    [6] Non-Functional Req.     ✓ đã có
-    [7] Business Constraints    ✓ đã có
+    [6] Components              ✗ chưa có — cần bổ sung
+    [7] Non-Functional Req.     ✓ đã có
+    [8] Business Constraints    ✓ đã có
     [A] Interview tất cả sections
 
   Chọn số hoặc A:
@@ -101,11 +105,15 @@ Sau đó hỏi tuần tự, từng phần một — không hỏi tất cả cùn
 > Hệ thống cần implement những features gì? Mỗi feature gồm: tên ngắn, mô tả 1 câu (làm gì, cho ai), priority (Must/Should/Could).
 > (Đây sẽ là Feature Index mà các FRD sau này sẽ tham chiếu.)
 
-**Phần 5 — Non-Functional Requirements:**
+**Phần 5 — Components:**
+> Hệ thống có những thành phần kỹ thuật (component) nào? Mỗi component gồm: tên ngắn (kebab-case, ví dụ `auth`, `payment`), mô tả 1 câu — component chịu trách nhiệm gì.
+> (Đây là Component Index — agent có thể bỏ trống nếu user chưa rõ; component sẽ được thêm dần qua cascade từ integrations sau này.)
+
+**Phần 6 — Non-Functional Requirements:**
 > Có yêu cầu về performance, security, availability, scalability không?
 > Mỗi NFR cần: category, mô tả cụ thể, target đo được, priority (Must/Should/Could).
 
-**Phần 6 — Business Constraints:**
+**Phần 7 — Business Constraints:**
 > Có ràng buộc kinh doanh nào không? (deadline, budget, compliance, vendor lock-in, v.v.)
 > Có giả định nào quan trọng cần ghi lại không?
 
@@ -134,15 +142,24 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 ### Bước 5: Save
 
-Ghi nội dung đã được confirm vào `specs/main/prd.md`, thay thế toàn bộ nội dung cũ.
+**5a. Ghi `specs/main/prd.md`** — nội dung đã được confirm, thay thế toàn bộ nội dung cũ.
+
+**5b. Scaffold `specs/main/domain.md`** *(chỉ khi file này chưa tồn tại)*:
+
+- Copy `.claude/templates/main/domain-template.md` thành `specs/main/domain.md`.
+- Section **Glossary** giữ format bảng rỗng — terms sẽ được thêm dần qua cascade từ integrations.
+- Section **Shared Entities** giữ block placeholder — entities sẽ mọc dần qua cascade khi integration giới thiệu shared entity.
+
+Nếu `domain.md` đã tồn tại với nội dung thực → không đụng tới.
 
 Thông báo kết quả:
 ```
 ✓ specs/main/prd.md đã được cập nhật (status: draft)
+{nếu vừa scaffold} ✓ specs/main/domain.md đã được scaffold (skeleton — sẽ mọc dần qua cascade)
 
 Bước tiếp theo:
-  - /spec-domain → định nghĩa domain entities và business rules
-  - (sau domain) /spec-sad → thiết kế kiến trúc kỹ thuật
+  - /spec-sad → thiết kế kiến trúc kỹ thuật
+  - (sau sad) /spec-new → bắt đầu integration đầu tiên
 ```
 
 ---
@@ -172,5 +189,7 @@ Trước khi kết thúc, kiểm tra:
 - [ ] Mỗi persona có: tên vai trò, mục tiêu, pain point
 - [ ] Out of Scope có ít nhất 1 item với lý do
 - [ ] Features có ít nhất 1 item, mỗi item có ID (F-XXX), tên, mô tả, priority
+- [ ] Components: nếu có item, mỗi item có ID (C-XXX), tên, mô tả ngắn (có thể trống nếu chưa rõ)
 - [ ] Mỗi NFR có target đo được (không phải "nhanh", "bảo mật chung chung")
+- [ ] domain.md tồn tại (đã scaffold skeleton hoặc có nội dung sẵn)
 - [ ] User đã confirm trước khi file được ghi

package/skills/spec-sad/SKILL.md

@@ -39,10 +39,10 @@ SAD không chứa: feature-level design, business rules, entity details — nh
 
 **Đọc `specs/main/domain.md`:**
 
-- **Chưa tồn tại hoặc là template** → dừng ngay:
-  > `domain.md` chưa có nội dung. Hãy chạy `/spec-domain` trước.
+- **Chưa tồn tại** → dừng ngay:
+  > `domain.md` chưa được scaffold. Hãy chạy `/spec-prd` trước (skill này scaffold cả `prd.md` và `domain.md` skeleton).
 
-- **Đã có nội dung** → đọc để hiểu: các entities chính, có event-driven behavior không, volume ước tính.
+- **Đã tồn tại** → đọc để hiểu: glossary và shared entities (nếu có). Lưu ý `domain.md` có thể chỉ mới là skeleton vì nội dung chi tiết mọc dần qua cascade từ integrations — không cần dừng nếu file mỏng.
 
 **Đọc `specs/main/sad.md`:**
 

package/skills/spec-tech/SKILL.md

@@ -60,18 +60,24 @@ Nếu integration đã có `tech.md` → hỏi trước khi tiếp tục:
 
 Load các file sau:
 
-- `specs/integrations/{slug}/spec.md` — đọc toàn bộ: Problem Statement, Requirements, Acceptance Criteria, Out of Scope
+- `specs/integrations/{slug}/spec.md` — đọc toàn bộ + frontmatter (`features`, `components`)
 - `specs/main/sad.md` — đọc Tech Stack và Architectural Guardrails
-- `specs/main/domain.md` — đọc Entities và Business Rules
+- `specs/main/domain.md` — đọc Glossary và Shared Entities
+- `specs/main/component/{C-XXX}-{slug}/cdd.md` — cho mỗi component trong frontmatter `components` (nếu cdd.md tồn tại)
+- `specs/main/feature/{F-XXX}-{slug}/fdd.md` — cho mỗi feature trong frontmatter `features` (nếu fdd.md tồn tại)
 
 Tóm tắt context và surface assumptions:
 
 ```
 TỪ SPEC & SAD TÔI HIỂU:
 - Integration: {title}
+- Features liên quan: {từ frontmatter — F-XXX, ...}
+- Components bị touched: {từ frontmatter — C-XXX, ...}
 - Yêu cầu chính: {tóm tắt requirements từ spec.md}
 - Tech stack: {từ sad.md}
-- Entities liên quan: {từ domain.md}
+- Shared entities liên quan: {từ domain.md}
+- Component design hiện tại: {tóm tắt từ cdd.md(s) — bỏ qua nếu chưa tồn tại}
+- Inter-component flow hiện tại: {tóm tắt từ fdd.md(s) — bỏ qua nếu chưa tồn tại}
 - Guardrails cần tuân theo: {list GUARD-XXX từ sad.md}
 
 ASSUMPTIONS TÔI ĐANG ĐẶT RA:
@@ -119,29 +125,56 @@ Tổng hợp và viết draft `tech.md`:
 
 **Cấu trúc file**: dùng `.claude/templates/integrations/tech-template.md` làm skeleton, điền nội dung từ interview vào.
 
-**Cascade Proposals** — điền theo hướng dẫn sau:
+**Cascade Proposals** — agent đề xuất delta cho main artifacts theo các targets sau (chỉ điền nếu thực sự có thay đổi, không thì ghi "Không có thay đổi đề xuất."):
 
 ### sad.md
 
-{Đề xuất cập nhật nếu phát hiện quyết định kiến trúc mới, tech stack thay đổi, hoặc guardrail mới cần thêm. Hoặc "Không có thay đổi đề xuất."}
+Đề xuất cập nhật nếu integration này:
+- Thêm cross-cutting concern mới (logging strategy, caching, ...)
+- Thay đổi tech stack
+- Thêm guardrail mới
 
 ### domain.md
 
-{Đề xuất cập nhật nếu phát hiện entity hoặc business rule mới trong quá trình thiết kế. Hoặc "Không có thay đổi đề xuất."}
+Đề xuất cập nhật nếu integration này:
+- Thay đổi shared entity (entity được dùng bởi 2+ component)
+- Thêm shared entity mới phát sinh từ thiết kế kỹ thuật
 
-### fdd.md
+### component/{C-XXX}-{component-name}/cdd.md
 
-{Một trong hai:}
+Liệt kê **tất cả** components bị touched trong frontmatter và đánh giá từng cái:
 
-**Tạo mới** `specs/main/features/{feature-id}-{feature-slug}/fdd.md`
-- Dùng khi feature chưa có fdd.md
-- Thư mục theo convention: `{number}-{feature-slug}` (ví dụ: `001-authentication`)
-- Nội dung đề xuất: {tóm tắt Module Structure, Data Flow, Interfaces từ tech.md}
+| Component | cdd.md | Đề xuất |
+| --- | --- | --- |
+| C-001 — auth | tồn tại | **Cập nhật** — thêm module RateLimiter, đổi storage strategy cho session |
+| C-003 — payment | chưa có | **Tạo mới** — full cdd skeleton |
 
-**Cập nhật** `specs/main/features/{feature-id}-{feature-slug}/fdd.md`
-- Dùng khi fdd.md đã tồn tại, ghi rõ thay đổi cụ thể cần thêm/sửa
+Với từng component có đề xuất:
 
-{Hoặc "Không liên quan" nếu integration không gắn với feature cụ thể nào trong prd.md.}
+**Tạo mới** `specs/main/component/{C-XXX}-{component-slug}/cdd.md`
+- Dùng khi component này được giới thiệu lần đầu trong integration (cascade từ spec.md đã đề xuất tạo crd, giờ tech.md đề xuất tạo cdd)
+- Nội dung: Module Structure, Internal Data Flow, Storage & Persistence, Internal Interfaces, Technical Decisions
+
+**Cập nhật** `specs/main/component/{C-XXX}-{component-slug}/cdd.md`
+- Khi cdd.md đã tồn tại và integration thay đổi internal design
+
+### feature/{F-XXX}-{feature-name}/fdd.md
+
+Liệt kê **tất cả** features liên quan trong frontmatter và đánh giá:
+
+| Feature | fdd.md | Đề xuất |
+| --- | --- | --- |
+| F-001 — Checkout | tồn tại | **Cập nhật** — thêm sequence khi payment fail |
+| F-002 — Refund | chưa có | **Tạo mới** |
+
+**Tạo mới** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
+- Khi feature gắn với integration nhưng chưa có fdd.md
+- Nội dung: Inter-component data flow, Orchestration, Cross-component invariants — từ tech.md (chỉ phần inter-component, không lặp internal design của component)
+
+**Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
+- Khi fdd.md đã tồn tại, ghi rõ thay đổi flow nào
+
+Bỏ block fdd.md nếu integration không gắn với feature nào (`features: []`).
 ```
 
 Hiển thị draft cho user xem — **chưa ghi file**.
@@ -167,10 +200,10 @@ Thông báo kết quả:
 ✓ specs/integrations/{slug}/tech.md đã được tạo (status: draft)
 
 Bước tiếp theo:
-  - Review và approve tech.md
+  - Review tech.md và apply Cascade Proposals (nếu có) vào main artifacts thủ công
+  - Approve tech.md (đổi status: draft → approved)
   - /plan → tạo plan.md và todo.md cho integration này
-  - Sau khi done: đổi status F-XXX trong prd.md thành DONE
-  - Nếu Cascade Proposals có thay đổi → chạy /spec-domain hoặc /spec-sad
+  - Sau khi tất cả tasks done: đổi status F-XXX trong prd.md thành DONE
 ```
 
 ---

package/templates/integrations/plan-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 status: draft
 created: {YYYY-MM-DD}
 referenced_by:

package/templates/integrations/spec-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 status: draft
 created: {YYYY-MM-DD}
 referenced_by:
@@ -12,36 +13,51 @@ referenced_by:
 
 ## Context
 
-<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (prd.md, domain.md, frd.md), để file self-contained -->
+<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (prd.md, domain.md, frd.md, crd.md), để file self-contained -->
 
 ## Problem Statement
 
 <!-- Vấn đề cần giải quyết là gì, tại sao cần giải quyết -->
 
-## Features
+## Acceptance Criteria
 
-<!-- Lặp lại block Feature bên dưới cho mỗi feature thuộc spec này -->
+<!--
+Agent tự chọn cách tổ chức phù hợp với bản chất integration. Có thể mix nếu integration vừa thêm feature, vừa thay đổi component.
 
-### Feature: {feature-name}
+AC ID format:
+- AC liên quan feature: `AC-{F_ID}-{seq}` — feature-scoped, cascade vào frd.md
+- AC liên quan component: `AC-{C_ID}-{seq}` — component-scoped, cascade vào responsibilities/interface/rules của crd.md
 
-**Feature-level Acceptance Criteria:**
+Format Given/When/Then. Bỏ block không dùng.
+-->
 
-- [ ] AC-F-001
+### Feature: {feature-name} *(bỏ nếu integration không touch feature; lặp lại block cho mỗi feature)*
+
+**Feature-level AC:**
+
+- [ ] `AC-{F_ID}-{seq}`
   - **Given** {precondition}
   - **When** {action}
   - **Then** {expected outcome}
 
-<!-- Lặp lại block Story bên dưới cho mỗi user story thuộc feature này -->
-
-#### US-001: {Story title}
+#### US-{F_ID}-{seq}: {Story title}
 
 **{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
 **Priority:** Must / Should / Could
 
-**Acceptance Criteria:**
+**Story AC:**
 
-- [ ] AC-S-001
+- [ ] `AC-{F_ID}-{seq}`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
+
+### Component: `{C-XXX}-{component-name}` *(bỏ nếu integration không touch component; lặp lại block cho mỗi component)*
+
+**AC theo responsibility / interface / rule:**
+
+- [ ] `AC-{C_ID}-{seq}` — {responsibility / interface / rule mô tả}
   - **Given** {precondition}
   - **When** {action}
   - **Then** {expected outcome}
@@ -67,8 +83,14 @@ Không có thay đổi đề xuất.
 
 Không có thay đổi đề xuất.
 
+### component/{C-XXX}-{component-name}/crd.md
+
+<!-- Lặp lại section này cho mỗi component liên quan đến spec. Bỏ nếu integration không touch component nào. -->
+
+Không có thay đổi đề xuất.
+
 ### feature/{F-XXX}-{feature-name}/frd.md
 
-<!-- Lặp lại section này cho mỗi feature liên quan đến spec -->
+<!-- Lặp lại section này cho mỗi feature liên quan đến spec. Bỏ nếu integration không gắn với feature nào. -->
 
 Không có thay đổi đề xuất.

package/templates/integrations/tech-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 status: draft
 created: {YYYY-MM-DD}
 referenced_by:
@@ -12,7 +13,7 @@ referenced_by:
 
 ## Context
 
-<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (sad.md, domain.md, fdd.md, spec.md) -->
+<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (sad.md, domain.md, cdd.md, fdd.md, spec.md) -->
 
 ## Solution Overview
 
@@ -54,6 +55,14 @@ Không có thay đổi đề xuất.
 
 Không có thay đổi đề xuất.
 
+### component/{C-XXX}-{component-name}/cdd.md
+
+<!-- Lặp lại section này cho mỗi component bị touched. Bỏ nếu integration không touch component nào. -->
+
+Không có thay đổi đề xuất.
+
 ### feature/{F-XXX}-{feature-name}/fdd.md
 
+<!-- Lặp lại section này cho mỗi feature liên quan. Bỏ nếu integration không gắn feature nào. -->
+
 Không có thay đổi đề xuất.

package/templates/integrations/todo-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 created: {YYYY-MM-DD}
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.6 todo.md > Cấu trúc

package/templates/main/component/cdd-template.md

@@ -0,0 +1,63 @@
+---
+id: cdd-{component}
+type: cdd
+status: draft
+owner: "{Tech Lead / Senior Dev}"
+component_id: "{Component ID, ví dụ C-001}"
+referenced_by:
+  - conventions.md > 3. Main Artifacts > 3.2 Component level > cdd.md > Cấu trúc
+  - skills/spec-tech/SKILL.md > Process > Cascade Proposals > component cdd.md
+---
+
+# Component Design: {Component Name}
+
+> File này mô tả **internal design** của component — cách nó được tổ chức bên trong.
+>
+> Vai trò, public interface, business rules nằm trong `crd.md`. Cross-cutting concerns (auth, logging, ...) nằm trong `sad.md`.
+
+## Module Structure
+
+Các module/sub-component bên trong component và responsibility của từng module.
+
+| Module | Responsibility |
+| --- | --- |
+| {module} | {mô tả} |
+
+## Internal Data Flow
+
+Luồng dữ liệu nội bộ component — từ input đến output, qua những module nào.
+
+```mermaid
+sequenceDiagram
+    ...
+```
+
+## Storage & Persistence
+
+Cách component lưu trữ data. Bỏ section nếu component stateless.
+
+### Tables / Collections
+
+| Name | Mục đích | Key columns / Indexes |
+| --- | --- | --- |
+| {table_name} | {mục đích} | PK: {cols}, Index: {cols} |
+
+### Cache Strategy *(bỏ nếu dùng global strategy từ SAD)*
+
+{Mô tả cache strategy nội bộ component nếu khác SAD.}
+
+## Internal Interfaces
+
+Contract giữa các module bên trong component. Public interface (ra ngoài) đã được mô tả trong `crd.md`.
+
+| Caller | Callee | Purpose |
+| --- | --- | --- |
+| {module A} | {module B} | {gọi để làm gì} |
+
+## Technical Decisions
+
+Các quyết định kỹ thuật đặc thù của component và lý do.
+
+| Quyết định | Lý do | Alternatives đã cân nhắc |
+| --- | --- | --- |
+| {decision} | {lý do cụ thể} | {option A vs B} |

package/templates/main/component/crd-template.md

@@ -0,0 +1,88 @@
+---
+id: crd-{component}
+type: crd
+status: draft
+owner: "{BA / Tech Lead}"
+component_id: "{Component ID từ PRD Component Index, ví dụ C-001}"
+referenced_by:
+  - conventions.md > 3. Main Artifacts > 3.2 Component level > crd.md > Cấu trúc
+  - skills/spec-new/SKILL.md > Process > Cascade Proposals > component crd.md
+---
+
+# Component: {Component Name}
+
+## Role
+
+{1-2 câu mô tả vai trò của component trong hệ thống. Component này là "nơi chịu trách nhiệm" cho cái gì?}
+
+## Responsibilities
+
+Trách nhiệm cụ thể của component — phải làm gì, **không** làm gì.
+
+### Does
+
+- {responsibility 1}
+- {responsibility 2}
+
+### Does NOT
+
+- {responsibility thuộc component khác — ghi rõ component nào sở hữu}
+- {responsibility nằm ngoài scope}
+
+## Owned Entities
+
+Entities mà component này sở hữu canonical definition. Nếu entity được dùng bởi 2+ component, định nghĩa chính sẽ ở `domain.md` (Shared Entities) thay vì ở đây — chỉ ghi reference.
+
+### {Entity Name}
+
+{Mô tả entity này đại diện cho cái gì.}
+
+**Attributes:**
+
+| Attribute | Type | Required | Validation |
+| --- | --- | --- | --- |
+| {tên} | {business type} | Yes/No | {rule} |
+
+**State Machine:** *(bỏ nếu entity không có lifecycle)*
+
+| From | To | Trigger | Guard |
+| --- | --- | --- | --- |
+| {state} | {state} | {sự kiện} | {điều kiện} |
+
+## Public Interface
+
+Các interface mà component expose ra ngoài — signature level, không bao gồm implementation.
+
+### API Endpoints *(bỏ nếu component không expose HTTP API)*
+
+| Method | Path | Purpose | Auth |
+| --- | --- | --- | --- |
+| {GET/POST/...} | {/path} | {mục đích} | required/public |
+
+### Events Published *(bỏ nếu không emit event)*
+
+| Event | Trigger | Payload chính |
+| --- | --- | --- |
+| {EventName} | {khi nào emit} | {fields chính} |
+
+### Events Consumed *(bỏ nếu không consume event)*
+
+| Event | Source Component | Action |
+| --- | --- | --- |
+| {EventName} | {C-XXX} | {component này làm gì khi nhận event} |
+
+## Business Rules
+
+Các quy tắc nghiệp vụ thuộc về component này. Rule cross-component thuộc về `fdd.md` của feature liên quan.
+
+| ID | Rule | Condition | Exception |
+| --- | --- | --- | --- |
+| {C-XXX-R01} | {mô tả rule} | {khi nào apply} | {ngoại lệ nếu có} |
+
+## Dependencies
+
+Các component khác mà component này phụ thuộc.
+
+| Component | Loại dependency | Cách dùng |
+| --- | --- | --- |
+| `{C-XXX}-{name}` | sync call / event subscription / shared entity | {cụ thể: gọi API nào, subscribe event nào} |

package/templates/main/domain-template.md

@@ -5,22 +5,35 @@ status: draft
 owner: "{BA/Domain Expert}"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.1 Product level > domain.md > Cấu trúc
-  - skills/spec-domain/SKILL.md > Process > Bước 1: Kiểm tra preconditions
-  - skills/spec-domain/SKILL.md > Process > Bước 3: Write — sinh draft
+  - skills/spec-prd/SKILL.md > Process > Bước 5: Save (scaffold domain.md skeleton)
+  - skills/spec-new/SKILL.md > Process > Cascade Proposals > domain.md
+  - skills/spec-tech/SKILL.md > Process > Cascade Proposals > domain.md
 ---
 
 # Domain
 
-## Terminology
+> File này mỏng — chỉ chứa **shared vocabulary** và **shared entities** (entities được dùng bởi 2+ component).
+>
+> Business rules, domain events, internal entities thuộc về component sở hữu — xem `specs/main/component/{C-XXX}-{component-name}/crd.md`.
 
-| Term | Definition |
-| --- | --- |
-| {term} | {definition chính xác, không mơ hồ} |
+## Glossary
 
-## Entities
+Định nghĩa các thuật ngữ business — đây là **nơi duy nhất** chứa glossary trong toàn dự án.
+
+| Term | Definition | Example / Context |
+| --- | --- | --- |
+| {term} | {định nghĩa chính xác, không mơ hồ} | {context hoặc ví dụ minh họa nếu cần} |
+
+## Shared Entities
+
+Chỉ liệt kê entity được dùng bởi **2 hoặc nhiều component**. Entity nội bộ một component không vào đây — chúng nằm trong `crd.md` của component đó.
 
 ### {Entity Name}
 
+**Owner:** `{C-XXX}-{component-name}` *(component sở hữu canonical definition)*
+
+**Used by:** `{C-XXX}`, `{C-YYY}` *(các component reference entity này)*
+
 {Mô tả entity này đại diện cho cái gì trong business context.}
 
 **Attributes:**
@@ -39,22 +52,10 @@ Type là business type (text, number, money, date, email, phone) — không ph
 
 ## Entity Relationships
 
+Quan hệ giữa các shared entities. Quan hệ giữa entity nội bộ component thuộc về `cdd.md` của component đó.
+
 ```mermaid
 erDiagram
     EntityA ||--o{ EntityB : ""
     EntityB }o--|| EntityC : ""
 ```
-
-## Business Rules
-
-| ID | Rule | Condition | Exception |
-| --- | --- | --- | --- |
-| {DOMAIN-R01} | {mô tả rule} | {khi nào apply} | {ngoại lệ nếu có} |
-
-## Domain Events
-
-*(Bỏ nếu không có event-driven behavior)*
-
-| Event | Trigger | Payload |
-| --- | --- | --- |
-| {EventName} | {khi nào xảy ra} | {data đi kèm} |

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

@@ -5,51 +5,48 @@ status: draft
 owner: "{Tech Lead / Senior Dev}"
 feature_id: "{Feature ID}"
 referenced_by:
-  - conventions.md > 3. Main Artifacts > 3.2 Feature level > fdd.md > Cấu trúc
+  - conventions.md > 3. Main Artifacts > 3.3 Feature level > fdd.md > Cấu trúc
   - skills/spec-tech/SKILL.md > Process > Bước 4: Write — sinh draft > Cascade Proposals > fdd.md
 ---
 
 # Feature Design: {Feature Name}
 
-## Module Structure
+> File này mỏng — chỉ mô tả **cách các component tương tác với nhau** để thực hiện feature.
+>
+> Internal design của từng component nằm trong `cdd.md` của component đó. Cross-cutting concerns nằm trong `sad.md`.
 
-{Mô tả các module/layer trong feature này và responsibility của từng module.}
+## Inter-Component Data Flow
 
-| Module | Responsibility |
-| --- | --- |
-| {module} | {mô tả} |
-
-## Data Flow
-
-{Mô tả data flow nội bộ feature — từ input đến output, qua những bước nào.}
+Luồng dữ liệu đi qua các component — sequence diagram là form chính, có thể bổ sung mô tả prose.
 
 ```mermaid
 sequenceDiagram
-    ...
+    participant User
+    participant {C-XXX} as ComponentA
+    participant {C-YYY} as ComponentB
+
+    User->>ComponentA: {request}
+    ComponentA->>ComponentB: {call}
+    ComponentB-->>ComponentA: {response}
+    ComponentA-->>User: {result}
 ```
 
-## Interfaces
-
-### API Endpoints
+{Mô tả ngắn các bước nếu sequence diagram chưa đủ rõ.}
 
-| Method | Path | Purpose | Auth |
-| --- | --- | --- | --- |
-| {GET/POST/...} | {/path} | {mục đích} | required/public |
+## Orchestration
 
-### Events *(bỏ nếu không dùng)*
+Logic ở cấp feature — không thuộc component nào riêng lẻ. Bỏ section nếu feature đơn giản (1-2 component, không cần retry/fallback đặc biệt).
 
-| Event | Direction | Payload chính |
-| --- | --- | --- |
-| {EventName} | emit/consume | {fields} |
-
-## Caching & Queue Strategy
-
-*(Bỏ nếu dùng global strategy từ SAD)*
+| Concern | Handling |
+| --- | --- |
+| Retry policy | {ví dụ: retry 3 lần với exponential backoff khi gọi component X} |
+| Timeout | {ví dụ: timeout tổng feature 5s; per-component 2s} |
+| Fallback | {ví dụ: nếu component X fail, dùng cached data} |
+| Error propagation | {ví dụ: lỗi từ component Y được map thành 503 cho user} |
 
-{Mô tả strategy riêng của feature nếu khác SAD.}
+## Cross-Component Invariants
 
-## Technical Decisions
+Các invariant cần đảm bảo xuyên component — consistency, transactional boundary, ordering. Bỏ section nếu không có.
 
-| Quyết định | Lý do | Alternatives đã cân nhắc |
-| --- | --- | --- |
-| {decision} | {lý do cụ thể} | {option A vs B} |
+- {ví dụ: Order chỉ được đánh dấu `paid` sau khi Payment component confirm thành công}
+- {ví dụ: Inventory phải được reserve trước khi Order được tạo, rollback nếu Payment fail}

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,18 +15,29 @@ 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).
 
-- [ ]
+- `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}
 
 **{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
@@ -34,18 +45,18 @@ Criteria áp dụng cho toàn bộ feature — không gắn với story cụ th
 
 **Acceptance Criteria:**
 
-- [ ]
+- `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}
 
 **{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
@@ -53,7 +64,7 @@ Criteria áp dụng cho toàn bộ feature — không gắn với story cụ th
 
 **Acceptance Criteria:**
 
-- [ ]
+- `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