spec-lite 1.0.1 → 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.1",
+  "version": "1.1.0",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/build/SKILL.md

@@ -13,10 +13,35 @@ Invoke `incremental-implementation` và `test-driven-development` cùng nhau cho
 
 ## Quy trình
 
+### Bước 0: Xác định integration
+
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/todo.md`, tìm integration khớp với argument
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
+- Nếu tìm thấy → dùng `specs/integrations/{slug}/` làm working integration, bắt đầu luôn
+
+**Nếu không có ARGUMENT:**
+- Quét `specs/integrations/*/todo.md`, liệt kê tất cả integrations có todo.md, đánh dấu tiến độ:
+
+```
+Integrations:
+
+  [1] 001-implement-auth    — Implement Auth             (8/8 done) ✓
+  [2] 002-implement-todo    — Implement Todo Management  (0/10 pending)
+
+Chọn số integration:
+```
+
+  Format: `({done}/{total} done)` hoặc `({pending} pending)` — đếm từ todo.md
+  - Nếu chỉ có 1 integration có task pending → chọn luôn, không hỏi
+  - Nếu tất cả đều done → thông báo: "Tất cả integration đã hoàn thành."
+
 ### Với mỗi task pending
 
 **1. Chọn task** (`incremental-implementation` — Increment Cycle)
-Lấy task `[ ]` tiếp theo trong `todo.md`. Đọc acceptance criteria trong `plan.md`.
+Lấy task `[ ]` tiếp theo trong `todo.md` của integration đã chọn. Đọc acceptance criteria trong `plan.md` tương ứng.
 
 **2. Load context** (`incremental-implementation` — Rule 0: Simplicity First)
 Đọc code, types, patterns liên quan. Hỏi: "Cách đơn giản nhất có thể làm việc là gì?"
@@ -50,7 +75,7 @@ Build phải thành công trước khi commit. Nếu fail → invoke `debugging-
 Commit với message mô tả rõ, giới hạn trong phạm vi task này. Một thay đổi logic mỗi commit.
 
 **8. Đánh dấu hoàn thành và tiếp tục**
-Check `[x]` trong `todo.md`. Lặp lại từ bước 1 cho task tiếp theo.
+Check `[x]` trong `todo.md` của integration đang build. Lặp lại từ bước 1 cho task tiếp theo.
 
 ## Dấu hiệu task UI/UX
 

package/skills/plan/SKILL.md

@@ -27,22 +27,28 @@ Mọi quyết định về sizing, slicing đều thuộc về `planning-and-tas
 
 ### Bước 1: Xác định integration
 
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/`, tìm integration khớp với argument
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
+- Nếu tìm thấy → dùng integration đó, bắt đầu luôn
+
+**Nếu không có ARGUMENT:**
+
 Quét `specs/integrations/`. Liệt kê tất cả integrations:
 
 ```
 Integrations:
 
-  [1] f001-authentication       — User Authentication        spec✓ tech✓  plan—
-  [2] f003-app-browsing         — App Browsing & Opt-in      spec✓ tech—
-  [3] f004-credit-system        — Credit System              spec—
+  [1] 001-implement-auth    — Implement Auth             spec✓ tech✓ plan✓
+  [2] 002-implement-todo    — Implement Todo Management  spec✓ tech✓ plan—
 
 Chọn số integration:
 ```
 
 Legend: `✓` = có, `—` = chưa có
 
-Nếu có ARGUMENT → chọn luôn, không hiển thị danh sách.
-
 Nếu plan.md / todo.md đã tồn tại → hỏi trước khi ghi đè.
 
 ---
@@ -60,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ó}
@@ -84,77 +92,7 @@ Invoke `planning-and-task-breakdown` với context đã load. Skill đó sẽ th
 
 ### plan.md
 
-```markdown
----
-id: "{slug}"
-slug: "{slug}"
-title: "{title} — Implementation Plan"
-features: ["{F-XXX}"]
-status: draft
-created: {YYYY-MM-DD}
----
-
-## Summary
-
-[2-3 sentences on what will be implemented]
-
-## Dependency Graph
-
-[ASCII diagram — bottom = foundations, top = UI. Ví dụ:]
-
-    UI Components
-         │
-    API Routes ──── Middleware
-         │
-      Services
-         │
-    Prisma Schema
-
-## Tasks
-
-### Phase 1: [Phase name]
-
-#### T001 · [task title — starts with a verb]
-
-**Mục tiêu:** [One sentence: what this task delivers]
-
-**depends:** — (hoặc T-IDs)
-
-**Các bước:**
-1. [Concrete implementation step]
-2. [Concrete implementation step]
-
-**Verification:**
-- [ ] [AC-F-001] [specific test case]
-- [ ] [smoke check or observable result]
-
----
-
-### Phase N: Verification
-
-#### T00N · Integration tests — [flow name]
-
-**Mục tiêu:** [End-to-end flow being tested]
-
-**depends:** T001, T002, ...
-
-**Các bước:**
-1. [Test setup / seed data]
-2. [Execute happy path]
-3. [Execute error cases]
-
-**Verification:**
-- [ ] Happy path: [description]
-- [ ] Error case: [description]
-
----
-
-## Definition of Done
-
-- [ ] [AC-F-001 / AC-S-001] [AC description — concise, preserve intent]
-- [ ] All unit tests pass
-- [ ] All integration tests pass
-```
+Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền nội dung từ breakdown vào từng section.
 
 **Lưu ý format:**
 - Task ID dùng `·` (middle dot), không dùng `—`
@@ -164,16 +102,7 @@ created: {YYYY-MM-DD}
 
 ### todo.md
 
-```markdown
-# [title] — Todo
-
-### Phase 1: [Phase name]
-- [ ] T001 · [task title]
-- [ ] T002 · [task title]
-
-### Phase N: Verification
-- [ ] T00N · Integration tests — [flow name]
-```
+Dùng `.claude/templates/integrations/todo-template.md` làm skeleton, điền nội dung từ breakdown vào từng section.
 
 ---
 

package/skills/planning-and-task-breakdown/SKILL.md

@@ -41,15 +41,19 @@ Map what depends on what:
 ```
 Database schema
     │
-    ├── API models/types
+    ├── Domain models
     │       │
-    │       ├── API endpoints
-    │       │       │
-    │       │       └── Frontend API client
-    │       │               │
-    │       │               └── UI components
-    │       │
-    │       └── Validation logic
+    │       └── Services
+    │               │
+    │               ├── Validation logic
+    │               │
+    │               └── API endpoints
+    │                       │
+    │                       ├── Middleware
+    │                       │
+    │                       └── Frontend API client
+    │                               │
+    │                               └── UI components
     │
     └── Seed data / migrations
 ```

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`:**