spec-lite 1.0.2 → 1.1.1

package/skills/spec-brownfield-init/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: spec-brownfield-init
+description: Khởi tạo main artifacts (prd.md, domain.md, sad.md) cho brownfield project bằng cách scan codebase và interview với pre-filled options. Dùng khi onboarding một project đã chạy vào SDD workflow.
+---
+
+# spec-brownfield-init
+
+## Overview
+
+Tạo `specs/main/prd.md`, `specs/main/domain.md`, và `specs/main/sad.md` cho một project đã tồn tại.
+
+Skill này chỉ tập trung vào **product và architecture level** — những gì có thể extract từ README, docs, config, và kiến trúc tổng thể. Component Index và Feature Index trong prd.md sẽ **để trống** — chúng sẽ được điền bởi `/spec-brownfield-component` và `/spec-brownfield-feature` sau khi scan code chuyên sâu.
+
+Thông tin không thể detect từ code được đánh dấu nhất quán:
+
+```
+**[NEEDS_CLARIFY]** <mô tả điều chưa rõ và câu hỏi cần trả lời>
+```
+
+## When to Use
+
+- Onboarding một brownfield project vào SDD workflow
+- `specs/main/prd.md` chưa có hoặc còn trống
+
+## When NOT to Use
+
+- Greenfield project chưa có code → dùng `/spec-prd` + `/spec-sad`
+- `prd.md` đã có nội dung đầy đủ → dùng `/spec-prd` hoặc `/spec-sad` để update từng phần
+
+---
+
+## Process
+
+### Bước 1: Xác định target path và load attachments
+
+**Path:**
+- Nếu có ARGUMENT là path → đây là root của project cần scan.
+- Nếu không có → mặc định dùng current working directory.
+
+Thông báo: `Sẽ scan: {path}`
+
+**Attachments:**
+Hỏi ngay đầu — không hỏi lại sau:
+
+> Bạn có tài liệu bổ sung nào không? (README, API spec, wiki, ADR, existing docs)
+> Paste nội dung hoặc cung cấp file path. Nhập `không` để bỏ qua.
+
+Load tất cả attachments trước khi scan. Dùng làm context bổ sung trong mọi bước tiếp theo.
+
+---
+
+### Bước 2: Kiểm tra existing specs
+
+Kiểm tra `specs/main/prd.md`, `specs/main/domain.md`, `specs/main/sad.md`:
+
+Nếu một trong ba đã có nội dung thực → cảnh báo:
+
+```
+⚠ File đã có nội dung:
+  - specs/main/prd.md
+  - specs/main/sad.md
+
+Skill này sẽ overwrite các file trên. Tiếp tục? [y/n]
+```
+
+Nếu user chọn `n` → dừng.
+
+---
+
+### Bước 3: Scan codebase
+
+Scan tuần tự. **Không hỏi user trong bước này** — chỉ thu thập thông tin.
+
+**3a. Package & tech stack:**
+Đọc (nếu tồn tại): `package.json`, `yarn.lock`, `pnpm-lock.yaml`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `composer.json`, `Gemfile`, `pubspec.yaml`
+
+Extract: ngôn ngữ, framework chính, major dependencies, build/test scripts.
+
+**3b. README và existing docs:**
+Đọc (nếu tồn tại): `README.md`, `README.*`, `docs/`, `ARCHITECTURE.md`, `DESIGN.md`
+
+Extract: mô tả project, target users được nhắc đến, business context.
+
+**3c. Directory structure — top level:**
+List 1-2 levels từ root — không đọc nội dung file source.
+
+Detect: architecture pattern (monolith / microservices / monorepo). Không cần lấy tên từng module — đó là việc của `/spec-brownfield-component`.
+
+**3d. Auth & middleware:**
+Tìm files liên quan: auth, middleware, interceptor, guard, rate-limit, logging config.
+
+Infer: auth strategy, cross-cutting patterns đang dùng.
+
+**3e. Infrastructure:**
+Đọc (nếu tồn tại): `docker-compose.yml`, `Dockerfile`, `.github/workflows/`, `k8s/`, `terraform/`, `serverless.yml`, `.env.example`
+
+Extract: deployment target, số services (để confirm architecture pattern), số môi trường.
+
+---
+
+### Bước 4: Tóm tắt scan và xác nhận tiếp tục
+
+```
+SCAN RESULTS — {path}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tech stack:    {e.g. TypeScript / NestJS / PostgreSQL / Redis}
+Architecture:  {e.g. Modular Monolith}
+Auth pattern:  {e.g. JWT Bearer / Session / không detect được}
+Docs loaded:   {list files đọc được}
+
+Tiếp tục với brownfield init? [y/n]
+```
+
+Nếu `n` → dừng.
+
+---
+
+### Bước 5: Interview — prd.md
+
+Hỏi tuần tự từng phần. Mỗi câu hỏi có options pre-filled từ scan. Luôn có `[0] Chưa rõ → NEEDS_CLARIFY`. Khi user chọn `[0]` → đánh dấu và tiếp tục, không dừng lại.
+
+**Phần 1 — Problem Statement:**
+
+```
+❓ Hệ thống này giải quyết vấn đề gì?
+  [1] {Trích từ README: "..."}
+  [2] Nhập mô tả khác
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+**Phần 2 — Target Users:**
+
+```
+❓ Ai là người dùng chính?
+  [1] {Detected từ auth guards / README: e.g. "admin, user, guest"}
+  [2] Nhập personas khác
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+Nếu user chọn [1] → hỏi thêm một câu: "Bạn muốn mô tả thêm mục tiêu / pain point cho từng role không? [y/n]"
+
+**Phần 3 — Scope:**
+
+```
+❓ In scope — những gì hệ thống có:
+  [1] {Infer từ README/docs: "..."}
+  [2] Nhập danh sách khác
+  [0] Chưa rõ → NEEDS_CLARIFY
+
+❓ Out of scope — những gì hệ thống KHÔNG làm:
+  [1] Nhập nội dung
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+**Phần 4 — NFRs:**
+
+```
+❓ Non-Functional Requirements:
+  Detected từ config / code:
+    {e.g. Rate limit: 100 req/min (từ rate-limit config)}
+    {e.g. DB pool: max 10 connections (từ DB config)}
+
+  Có thêm NFR nào không? (performance targets, availability SLA, security compliance, scalability)
+  [1] Dùng detected + nhập thêm nếu có
+  [2] Nhập lại từ đầu
+  [0] Chưa rõ → NEEDS_CLARIFY tất cả
+```
+
+**Phần 5 — Business Constraints:**
+
+```
+❓ Business constraints và assumptions:
+  (deadline, budget, compliance, vendor lock-in, team constraints)
+  [1] Nhập nội dung
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+**Lưu ý:** prd.md sẽ có Component Index và Feature Index **để trống** với placeholder. Chúng sẽ được điền bởi `/spec-brownfield-component` và `/spec-brownfield-feature`.
+
+---
+
+### Bước 6: Tạo domain.md — Glossary
+
+domain.md ở bước này chỉ có **Glossary** — Shared Entities để trống, sẽ được mọc qua cascade proposals từ `/spec-brownfield-component` khi nó phát hiện cross-component entities.
+
+Extract glossary terms từ: README/docs (business terms được nhắc đến), tên các key concepts trong problem statement vừa thu thập.
+
+Hỏi:
+```
+❓ Glossary terms cần define:
+  Tôi nhận diện được các terms sau từ docs:
+    - {term 1}: {định nghĩa inferred hoặc NEEDS_CLARIFY}
+    - {term 2}: {định nghĩa inferred hoặc NEEDS_CLARIFY}
+
+  [1] Dùng list này — có thể thêm/sửa/xóa
+  [2] Nhập danh sách mới
+  [0] Chưa rõ / bỏ qua → để trống, điền sau
+```
+
+---
+
+### Bước 7: Auto-generate — sad.md
+
+Phần lớn auto từ scan. Chỉ hỏi 2 câu.
+
+**7a. Auto-fill từ scan:**
+- Tech stack: từ package files
+- Architecture style: infer từ directory structure top-level + docker-compose
+- Cross-cutting concerns: infer từ middleware / interceptors / guards detected
+- Inter-service communication: infer từ message queue / HTTP client usage
+- Infrastructure: infer từ docker-compose, cloud configs
+
+**7b. Hỏi Guardrails:**
+
+```
+❓ Architectural Guardrails:
+  Dựa trên {stack}, tôi đề xuất:
+    GUARD-001: {rule cụ thể}
+    GUARD-002: {rule cụ thể}
+    ...
+
+  [1] Dùng set này — có thể thêm/bớt
+  [2] Nhập guardrails khác
+  [0] Chưa rõ → NEEDS_CLARIFY tất cả
+```
+
+**7c. Hỏi additional constraints:**
+
+```
+❓ Có architectural decision nào quan trọng chưa detect được không?
+  (patterns bắt buộc dùng, patterns bị cấm, third-party services phải dùng)
+  [1] Nhập thêm
+  [0] Không có thêm
+```
+
+---
+
+### Bước 8: Review drafts
+
+Hiển thị draft từng file lần lượt. Với mỗi file:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DRAFT: specs/main/{file}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{nội dung draft}
+
+[NEEDS_CLARIFY trong file này: {count} items]
+
+Confirm? [y] Bỏ qua [n] Chỉnh sửa [e]:
+```
+
+- `y` → ghi file, chuyển sang file tiếp theo
+- `n` → bỏ qua file này
+- `e` → hỏi chỉnh sửa cụ thể, show lại draft, hỏi confirm lần nữa
+
+---
+
+### Bước 9: Save
+
+Tạo `specs/main/` nếu chưa có. Ghi các files đã được confirm.
+
+```
+✓ specs/main/prd.md        (Component Index và Feature Index: placeholder — chưa có)
+✓ specs/main/domain.md     (Glossary: {n} terms | Shared Entities: trống — sẽ mọc qua cascade)
+✓ specs/main/sad.md
+
+NEEDS_CLARIFY summary — {total} items cần làm rõ:
+  prd.md:    {n} — [Problem Statement, Business Constraints, ...]
+  domain.md: {n} — [glossary terms, ...]
+  sad.md:    {n} — [guardrails, ...]
+
+Bước tiếp theo:
+  /spec-brownfield-component → scan code, generate crd.md + cdd.md, điền Component Index
+  /spec-brownfield-feature   → scan code, generate frd.md + fdd.md, điền Feature Index
+  (chạy component trước — feature phụ thuộc vào component)
+```
+
+---
+
+## NEEDS_CLARIFY Convention
+
+Format chuẩn — dùng nhất quán trong tất cả artifacts:
+
+```markdown
+**[NEEDS_CLARIFY]** Mô tả ngắn điều chưa rõ. Câu hỏi cần trả lời để fill in.
+```
+
+---
+
+## Verification
+
+- [ ] Scan results đã được hiển thị và user confirm trước khi interview
+- [ ] Mọi section có ít nhất một trong ba: nội dung thực / pre-filled option / NEEDS_CLARIFY
+- [ ] prd.md có Component Index placeholder (chưa có entries — sẽ điền sau)
+- [ ] prd.md có Feature Index placeholder (chưa có entries — sẽ điền sau)
+- [ ] domain.md có Glossary (ít nhất skeleton) và Shared Entities trống
+- [ ] sad.md có Architectural Guardrails section
+- [ ] NEEDS_CLARIFY items được list đầy đủ trong summary cuối
+- [ ] User đã confirm từng file trước khi ghi

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