spec-lite 1.4.1 → 1.4.3

package/skills/spec-prd/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: spec-prd
-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.
+description: Điền hoặc cập nhật prd.md — Product Requirements Document ở product level. Nhận tùy chọn một nguồn yêu cầu (đường dẫn file/@file hoặc paste proposal/BRD/ghi chú) làm baseline để pre-fill interview. 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, features, components, 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.
 
-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).
+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
 
-- `specs/main/prd.md` chưa có nội dung hoặc vẫn còn là template
+- `.specs/main/prd.md` chưa có nội dung hoặc vẫn còn là template
 - Cần bổ sung hoặc cập nhật một phần của PRD hiện tại
 - Requirements thay đổi và PRD cần được đồng bộ lại
 
@@ -26,13 +26,101 @@ PRD không chứa: tech stack, implementation details, entity schema, glossary,
 
 ---
 
+## Khái niệm: Feature vs Component
+
+Section này là nền tảng để điền **Phần 4 (Features)** và **Phần 5 (Components)**. Đọc trước khi interview.
+
+### Nguyên tắc gốc
+
+**Component là đơn vị ownership; Feature là đơn vị delivery.** Component bền vững theo thời gian; Feature là một luồng nghiệp vụ consume một hoặc nhiều component. Quan hệ giữa hai khái niệm là **N–N** — không mechanical-derive cái này từ cái kia.
+
+### Litmus test — phân loại một mục là Feature hay Component
+
+Chạy qua các phép thử; đa số phiếu nghiêng đâu thì xếp vào đó:
+
+| Phép thử | → Component | → Feature |
+| --- | --- | --- |
+| **Ownership** (quan trọng nhất) | Sở hữu entity + rule + interface | Điều phối/tiêu thụ dữ liệu & rule của thứ khác |
+| **Lifetime** | Xóa hết luồng nghiệp vụ vẫn còn tồn tại | Bỏ đi, không component nào mất gì |
+| **Hướng cắt** | Ngang — một năng lực dùng lại bởi N luồng | Dọc — UI→logic→data cho một luồng |
+| **Đặt tên** | Danh từ hệ thống (`auth`, `payment`) | Luồng nghiệp vụ (`checkout-flow`, `password-reset`) |
+| **Trả lời** | "Phần nào của hệ thống chịu trách nhiệm X?" | "User làm được gì, nhận giá trị gì?" |
+
+### Quy tắc đặt tên (cho cả Feature và Component)
+
+**Goldilocks:** đặt tên ở mức trừu tượng **cao nhất mà vẫn truyền đạt đúng MỘT trách nhiệm/luồng rõ ràng**. Cao hơn → mất boundary; thấp hơn → rò rỉ chi tiết. Tên dùng kebab-case.
+
+**Component — theo năng lực bền vững, không theo công nghệ hiện tại:**
+- ✅ `notification`, `auth`, `file-storage`, `payment-gateway`
+- ❌ Quá cụ thể (rò rỉ impl): `email-sender` (mai thêm SMS/push?), `stripe-client`, `s3-uploader`
+- ❌ Quá mơ hồ (mất boundary): `core`, `utils`, `manager`, `engine`, `service`, `data`
+- Phép thử: *"Mai đổi nhà cung cấp / thêm kênh, tên còn đúng không?"* Không → quá cụ thể.
+
+**Feature — theo outcome của một luồng hoàn chỉnh:**
+- ✅ `user-registration`, `password-reset`, `checkout`
+- ❌ Quá rộng (thành feature area, ôm nhiều luồng): `user-management`, `account`, `admin`
+- ❌ Quá hẹp (chỉ một biến thể của luồng): `register-with-google`, `reset-password-via-sms-otp`
+- Phép thử: *"Đây là MỘT luồng, hay cái ô chứa nhiều luồng?"* Cái ô → quá rộng.
+
+### Định nghĩa một Component
+
+**Một component = một khối có (1) boundary rõ + interface tường minh, và (2) một lý do duy nhất để thay đổi.**
+
+- Tính chất (1) là điều kiện *cần*; (2) là guardrail chống "tầng kỹ thuật" lọt vào. "Tầng controller" có boundary rõ nhưng đổi vì N lý do (auth đổi, payment đổi...) → cohesion bằng 0 → **không** phải component.
+- Áp đúng tiêu chí "một lý do thay đổi" thì ranh giới theo capability/domain sẽ **tự hiện ra** — không cần áp luật "phải chia theo domain" từ ngoài vào.
+- Mỗi component đồng thời có **mặt domain** (`crd.md` — WHAT/contract) và **mặt kỹ thuật** (`cdd.md` — HOW/internal design). Đừng phân loại component thành "domain component" hay "kỹ thuật component" — đó chỉ là mô tả *nguồn* cohesion, không phải luật cấu trúc.
+
+### Component nào khai ở PRD? — Logic Given vs Derived
+
+Feature Index điền **đầy đủ** ở PRD. Component thì **không** — chỉ khai những component có boundary đã *chín*. Độ chín xác định bằng thủ tục quyết định, không cảm tính.
+
+**Litmus gốc:** *"Cùng bộ yêu cầu này, một architect giỏi khác có thể vẽ boundary này khác đi một cách hợp lý không?"* — KHÔNG (bị ép, một cách vẽ) → **Given, khai ở PRD**. CÓ (một lựa chọn đánh đổi) → **Derived, để `/spec-sad`**.
+
+**Thủ tục 3 câu** (YES đầu tiên thắng):
+
+| # | Câu hỏi | Nếu YES |
+| --- | --- | --- |
+| 1. External | Nó bọc/adapt một hệ thống hay bên thứ ba **ngoài codebase** mà ta buộc phải tích hợp? | **Given** → khai PRD (vd `payment-gateway` tích hợp Stripe, `email-service` tích hợp SendGrid) |
+| 2. Mandated-substrate | Nó là nền tảng kỹ thuật dùng chung mà yêu cầu nói rõ phải có, **độc lập với cách carve lõi nghiệp vụ**? | **Given** → khai PRD (vd `auth`, `file-storage`, `notification`) |
+| 3. Còn lại | Boundary phụ thuộc cách carve lõi nghiệp vụ, hoặc phụ thuộc đánh đổi NFR (scale, isolation, consistency, team topology)? | **Derived** → KHÔNG khai, để `/spec-sad` (vd `order`, `pricing`, `inventory`) |
+
+Ranh giới câu 2 vs câu 3 = **"boundary có độc lập với quyết định chia lõi nghiệp vụ không?"** Độc lập → Given; phụ thuộc → Derived.
+
+### Khi input context đã có sẵn feature/component
+
+Input là **baseline, không phải chân lý tuyệt đối**:
+
+- Reuse tên/ID/boundary nếu input đã có → không tự đẻ cấu trúc song song.
+- Vẫn chạy litmus test (phân loại) + Given/Derived để **validate**. Nếu input gọi X là "component" mà nó fail ownership test → flag, đề xuất reclassify thành feature (không im lặng bê nguyên).
+- Component **Derived** do input cung cấp → ghi nhận như *candidate*, chuyển sang `/spec-sad`, **không** nhồi vào Component Index của PRD.
+- Phần input thiếu → mới interview để bù.
+
+---
+
 ## Process
 
+### Bước 0: Nạp nguồn yêu cầu (tùy chọn)
+
+Trước khi interview, xác định có **nguồn yêu cầu** (proposal, BRD, ghi chú họp, draft cũ) để dùng làm baseline không. Thứ tự ưu tiên:
+
+1. **ARGUMENT là path / `@file`** → đọc file đó. Hỗ trợ `.md`, `.txt`, PDF.
+2. **ARGUMENT là text dài (paste trực tiếp)** → dùng luôn làm nguồn.
+3. **Không có ARGUMENT** → hỏi một lần:
+   > Bạn có tài liệu/nguồn yêu cầu nào để mình tham khảo không? Nhập **đường dẫn file**, **paste nội dung**, hoặc `không` để interview từ đầu.
+
+Nếu có nguồn → đọc và **trích baseline** cho từng section PRD (problem, users, scope, features, components, NFR, constraints). Đánh dấu cái nào trích được, cái nào nguồn không đề cập.
+
+Áp **quy tắc baseline** (xem section "Khi input context đã có sẵn feature/component"): reuse tên/ID/boundary; validate feature/component qua litmus + Given/Derived; flag mục phân loại sai; component Derived → candidate cho `/spec-sad`, không nhồi vào Component Index.
+
+Nếu không có nguồn → bỏ qua, interview từ đầu như bình thường.
+
+---
+
 ### Bước 1: Kiểm tra preconditions
 
-Đọc `specs/main/prd.md`:
+Đọc `.specs/main/prd.md`:
 
-- **File không tồn tại** → tạo thư mục `specs/main/` (nếu chưa có) rồi tiến hành Bước 2 (full interview).
+- **File không tồn tại** → tạo thư mục `.specs/main/` (nếu chưa có) rồi tiến hành Bước 2 (full interview).
 
 - **File là template rỗng** → tiến hành Bước 2 (full interview).
 
@@ -79,6 +167,10 @@ PRD không chứa: tech stack, implementation details, entity schema, glossary,
 
 ### Bước 2: Gather — interview requirements
 
+**Nếu Bước 0 đã nạp được nguồn:** interview chuyển từ "hỏi trắng" thành **xác nhận + bù chỗ thiếu**. Với mỗi phần, trình bày baseline đã trích rồi hỏi user confirm/sửa; chỉ những phần nguồn không đề cập mới hỏi từ đầu. Bỏ qua phần nào nguồn đã đủ rõ và user xác nhận.
+
+**Nếu không có nguồn:** interview từ đầu như mô tả bên dưới.
+
 Trước khi hỏi, list ra các assumptions đang tạm thời:
 
 ```
@@ -105,9 +197,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 — 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 5 — Components (chỉ component có boundary Given):**
+> Hệ thống chắc chắn phải tích hợp hệ thống ngoài nào (vd `payment-gateway`, `email-service`), hoặc cần nền tảng kỹ thuật dùng chung nào độc lập với cách carve lõi nghiệp vụ (vd `auth`, `file-storage`, `notification`)?
+> Mỗi component gồm: tên kebab-case + 1 câu mô tả responsibility.
+>
+> Áp **thủ tục Given vs Derived** (xem section "Khái niệm: Feature vs Component" ở trên) cho mỗi ứng viên:
+> - **Given** (trúng câu 1 External hoặc câu 2 Mandated-substrate) → khai vào Component Index.
+> - **Derived** (câu 3 — boundary phụ thuộc cách carve lõi nghiệp vụ hoặc đánh đổi NFR, vd `order`, `pricing`) → **KHÔNG** khai. Để `/spec-sad` chốt, hoặc mọc qua `/spec-new F-XXX` cascade.
+>
+> **KHÔNG** mechanical-derive components từ feature areas (vd: thấy "Pricing" trong yêu cầu → tạo ngay `C-pricing`; đó là Derived). Section này có thể chỉ có 3-6 entries, hoặc thậm chí trống. Đừng cố fill cho đủ.
 
 **Phần 6 — Non-Functional Requirements:**
 > Có yêu cầu về performance, security, availability, scalability không?
@@ -142,11 +240,11 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 ### Bước 5: Save
 
-**5a. Ghi `specs/main/prd.md`** — nội dung đã được confirm, 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)*:
+**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`.
+- 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.
 
@@ -166,8 +264,8 @@ Nếu `domain.md` đã tồn tại với nội dung thực → không đụng t
 
 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)
+✓ .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-sad → thiết kế kiến trúc kỹ thuật
@@ -200,8 +298,9 @@ Trước khi kết thúc, kiểm tra:
 - [ ] Problem Statement từ góc nhìn business, không mention tech stack
 - [ ] 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õ)
+- [ ] Features có ít nhất 1 item, mỗi item có ID (F-XXX), tên, mô tả, priority. Mỗi item pass litmus test (đơn vị delivery, không phải ownership)
+- [ ] Components: mọi entry là **Given** (trúng câu 1 External hoặc câu 2 Mandated-substrate). Không có component **Derived** (boundary phụ thuộc carve lõi nghiệp vụ — thuộc `/spec-sad`). Có thể trống. Mỗi item có ID (C-XXX), tên kebab-case, mô tả 1 câu
+- [ ] Nếu input context có sẵn feature/component: đã reuse làm baseline, đã validate qua litmus + Given/Derived, đã flag mục phân loại sai (nếu có)
 - [ ] 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-remove/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-remove
-description: Remove một feature toàn diện — tạo removal integration với Code Inventory, Reverse Dependency Audit, reverse-TDD test strategy, và Finalize Plan (move feature artifacts sang specs/removed/ + đóng ADO tickets) như task cuối trong todo.md. Nhận F-XXX làm argument.
+description: Remove một feature toàn diện — tạo removal integration với Code Inventory, Reverse Dependency Audit, reverse-TDD test strategy, và Finalize Plan (move feature artifacts sang .specs/removed/ + đóng ADO tickets) như task cuối trong todo.md. Nhận F-XXX làm argument.
 ---
 
 # spec-remove
@@ -12,7 +12,7 @@ Tạo removal integration cho 1 feature đã tồn tại. Output là `spec.md` v
 - **Code Inventory** — code, route, DB, feature flag, config liên quan
 - **Reverse Dependency Audit** — ai còn reference, an toàn xoá hay không
 - **Test Strategy** — reverse-TDD (regression test "thing is gone")
-- **Finalize Plan** — move feature artifacts sang `specs/removed/` + đóng ADO tickets, được DEV chạy như task cuối trong `todo.md`
+- **Finalize Plan** — move feature artifacts sang `.specs/removed/` + đóng ADO tickets, được DEV chạy như task cuối trong `todo.md`
 - **Changes blocks** — `[REMOVE]` markers cho mọi artifact bị touched
 
 Skill **không** sinh `tech.md` / `plan.md` / `todo.md`. Sau khi `spec.md` được approve, chạy `/spec-tech` → `/plan` → `/build` như flow thường. `spec.md` đủ giàu để 3 skill đó hoạt động không cần modification.
@@ -33,8 +33,8 @@ Skill **không** sinh `tech.md` / `plan.md` / `todo.md`. Sau khi `spec.md` đư
 
 ## Prerequisites
 
-- `specs/main/feature/{F-XXX}-*/frd.md` tồn tại
-- `specs/main/prd.md` có row của feature trong Feature Index
+- `.specs/main/feature/{F-XXX}-*/frd.md` tồn tại
+- `.specs/main/prd.md` có row của feature trong Feature Index
 - (Optional) `.claude/ado.yaml` cấu hình nếu muốn đóng ADO tickets ở finalize step
 
 ---
@@ -49,7 +49,7 @@ Argument BẮT BUỘC là Feature ID dạng `F-XXX` (3 chữ số). Nếu argume
 spec-remove cần Feature ID. Ví dụ: /spec-remove F-001
 ```
 
-Tìm thư mục `specs/main/feature/F-XXX-*/`:
+Tìm thư mục `.specs/main/feature/F-XXX-*/`:
 - 0 matches → báo lỗi feature không tồn tại, dừng.
 - ≥ 2 matches → báo lỗi data inconsistency (nhiều thư mục cùng prefix), dừng.
 - 1 match → tiếp.
@@ -71,20 +71,20 @@ F-XXX đã có status `removed`. Bạn muốn:
 Đọc các file sau:
 
 **Bắt buộc:**
-- `specs/main/feature/{F-XXX}-*/frd.md` — full content
-- `specs/main/feature/{F-XXX}-*/fdd.md` — nếu tồn tại
-- `specs/main/prd.md` — Feature Index (capture ADO ticket ID cho F-XXX), Component Index, NFR
-- `specs/main/domain.md` — Glossary + Shared Entities (xác định entity nào owned bởi component thuộc F-XXX)
+- `.specs/main/feature/{F-XXX}-*/frd.md` — full content
+- `.specs/main/feature/{F-XXX}-*/fdd.md` — nếu tồn tại
+- `.specs/main/prd.md` — Feature Index (capture ADO ticket ID cho F-XXX), Component Index, NFR
+- `.specs/main/domain.md` — Glossary + Shared Entities (xác định entity nào owned bởi component thuộc F-XXX)
 
 **Components used by F-XXX:**
 
 Trích từ `frd.md` section `Components Used` + `fdd.md` section `Components Touched`. Với mỗi C-YYY:
-- `specs/main/component/{C-YYY}-*/crd.md`
-- `specs/main/component/{C-YYY}-*/cdd.md` — nếu tồn tại
+- `.specs/main/component/{C-YYY}-*/crd.md`
+- `.specs/main/component/{C-YYY}-*/cdd.md` — nếu tồn tại
 
 **Reverse dependency scan:**
 
-Với mỗi C-YYY mà F-XXX sử dụng, grep `specs/main/feature/F-*/frd.md` (trừ F-XXX) tìm references tới C-YYY. Mọi feature khác có reference → load `frd.md` của feature đó để hiểu nó dùng C-YYY làm gì.
+Với mỗi C-YYY mà F-XXX sử dụng, grep `.specs/main/feature/F-*/frd.md` (trừ F-XXX) tìm references tới C-YYY. Mọi feature khác có reference → load `frd.md` của feature đó để hiểu nó dùng C-YYY làm gì.
 
 Output context summary cho user:
 
@@ -243,9 +243,9 @@ Sau khi migration deploy xong, chạy lại /spec-remove F-XXX.
 
 Xác định slug và NNN giống `/spec-new`:
 - Slug: `remove-{f-xxx-slug}` (ví dụ `remove-f001-authentication`)
-- NNN: max của thư mục hiện có trong `specs/integrations/` + 1, format 3 chữ số.
+- NNN: max của thư mục hiện có trong `.specs/integrations/` + 1, format 3 chữ số.
 
-Output path: `specs/integrations/{NNN}-remove-{f-xxx-slug}/spec.md`
+Output path: `.specs/integrations/{NNN}-remove-{f-xxx-slug}/spec.md`
 
 Cấu trúc spec.md:
 
@@ -319,20 +319,20 @@ Regression tests **được giữ lại** trong codebase như guardrail — futu
 
 1. **Move feature artifacts:**
    ```bash
-   mkdir -p specs/removed
-   mv specs/main/feature/{F-XXX}-{slug}/ specs/removed/{F-XXX}-{slug}/
+   mkdir -p .specs/removed
+   mv .specs/main/feature/{F-XXX}-{slug}/ .specs/removed/{F-XXX}-{slug}/
    ```
 
-2. **Append Change History** vào `specs/removed/{F-XXX}-{slug}/frd.md` (nếu file còn tồn tại sau move):
+2. **Append Change History** vào `.specs/removed/{F-XXX}-{slug}/frd.md` (nếu file còn tồn tại sau move):
    ```markdown
    ### {YYYY-MM-DD} — [{NNN}-remove-{slug}](../../integrations/{NNN}-remove-{slug}/spec.md) — removed
-   - **Feature decommissioned**: moved from specs/main/feature/ to specs/removed/
+   - **Feature decommissioned**: moved from .specs/main/feature/ to .specs/removed/
    - Reason: {lý do từ Problem Statement}
    ```
 
 3. **Update prd.md Feature Index:**
    - Row F-XXX: status → `Removed`
-   - Add note column hoặc inline: `(see specs/removed/{F-XXX}-{slug}/)`
+   - Add note column hoặc inline: `(see .specs/removed/{F-XXX}-{slug}/)`
 
 4. **Close ADO tickets** (nếu prd.md có ADO ticket ID cho F-XXX):
    - Feature ticket → state `Removed`
@@ -342,8 +342,8 @@ Regression tests **được giữ lại** trong codebase như guardrail — futu
    - Nếu ADO state name khác (vd "Closed") → xem `.claude/ado.yaml` hoặc fetch từ `wit_get_work_item_type`
 
 5. **Verify finalize:**
-   - `ls specs/main/feature/ | grep {F-XXX}` → không còn match
-   - `ls specs/removed/{F-XXX}-{slug}/` → tồn tại
+   - `ls .specs/main/feature/ | grep {F-XXX}` → không còn match
+   - `ls .specs/removed/{F-XXX}-{slug}/` → tồn tại
    - prd.md grep `F-XXX` → status `Removed`
    - ADO ticket fetch → state khớp
 
@@ -356,7 +356,7 @@ Regression tests **được giữ lại** trong codebase như guardrail — futu
 
 #### Features (Feature Index)
 - Row [MODIFY status]: `F-XXX` {current status} → `Removed`
-- {nếu có note column} Row [MODIFY note]: `F-XXX` add note "see specs/removed/"
+- {nếu có note column} Row [MODIFY note]: `F-XXX` add note "see .specs/removed/"
 
 #### Components (Component Index) — chỉ component exclusive với F-XXX
 - Row [MODIFY status]: `C-YYY` {current status} → `Removed`
@@ -367,7 +367,7 @@ Regression tests **được giữ lại** trong codebase như guardrail — futu
 **Format reference:** [frd-template.md](../../templates/main/feature/frd-template.md)
 
 <!--
-Đánh dấu mọi item bằng [REMOVE]. File sẽ bị move sang specs/removed/ ở Finalize step
+Đánh dấu mọi item bằng [REMOVE]. File sẽ bị move sang .specs/removed/ ở Finalize step
 nhưng cascade content vẫn ghi vào file gốc trước (để Change History entry được apply).
 -->
 
@@ -462,7 +462,7 @@ Draft trên đã đúng chưa?
 
 Sau khi confirm, agent sẽ auto-apply Changes blocks lên main artifacts.
 File feature artifacts (frd/fdd) KHÔNG bị move ngay — chỉ apply [REMOVE] markers
-+ Change History entry. Move sang specs/removed/ là task cuối trong todo.md,
++ Change History entry. Move sang .specs/removed/ là task cuối trong todo.md,
 do /build chạy sau khi mọi deletion task khác xong.
 ```
 
@@ -500,7 +500,7 @@ Giống `/spec-new` Bước 7, nhưng với removal-specific extensions.
 **[8.5] Thông báo kết quả:**
 
 ```
-✓ specs/integrations/{NNN}-remove-{f-xxx-slug}/spec.md đã được tạo (status: approved, removal: true)
+✓ .specs/integrations/{NNN}-remove-{f-xxx-slug}/spec.md đã được tạo (status: approved, removal: true)
 
 Auto-cascade applied:
   ✓ prd.md — F-XXX status → Removed; {N} components status → Removed
@@ -509,7 +509,7 @@ Auto-cascade applied:
   ✓ feature/F-XXX-*/frd.md — all items [REMOVE], status → removed
   ✓ feature/F-XXX-*/fdd.md — all items [REMOVE], status → removed
 
-⚠ File feature/F-XXX-*/ vẫn ở specs/main/feature/. Sẽ được move sang specs/removed/ ở task cuối todo.md.
+⚠ File feature/F-XXX-*/ vẫn ở .specs/main/feature/. Sẽ được move sang .specs/removed/ ở task cuối todo.md.
 ⚠ ADO tickets giữ nguyên state. Sẽ được close ở task cuối todo.md (cần .claude/ado.yaml).
 
 Bước tiếp theo:
@@ -583,6 +583,6 @@ Sau khi user confirm (Bước 8):
 - [ ] Auto-cascade chạy đúng thứ tự prd → domain → sad → crd → cdd → frd → fdd
 - [ ] Mọi artifact bị touched có Change History entry
 - [ ] prd.md row F-XXX status = Removed (đổi ngay sau approve)
-- [ ] File feature/F-XXX-*/ VẪN ở specs/main/feature/ (chưa move — chỉ move ở Finalize task)
+- [ ] File feature/F-XXX-*/ VẪN ở .specs/main/feature/ (chưa move — chỉ move ở Finalize task)
 - [ ] ADO tickets KHÔNG bị transition (chưa close — chỉ close ở Finalize task)
 - [ ] Notification cuối ghi rõ 2 ⚠ về việc folder + ADO chưa được động vào

package/skills/spec-sad/SKILL.md

@@ -7,7 +7,7 @@ description: Điền hoặc cập nhật sad.md — System Architecture Document
 
 ## Overview
 
-Tạo nội dung cho `specs/main/sad.md` thông qua interview có cấu trúc. SAD là bản đồ kỹ thuật của hệ thống — nó định nghĩa các quyết định kiến trúc, tech stack, và đặc biệt là **Architectural Guardrails**: các nguyên tắc bất biến mà mọi agent phải tuân theo khi sinh `tech.md`.
+Tạo nội dung cho `.specs/main/sad.md` thông qua interview có cấu trúc. SAD là bản đồ kỹ thuật của hệ thống — nó định nghĩa các quyết định kiến trúc, tech stack, và đặc biệt là **Architectural Guardrails**: các nguyên tắc bất biến mà mọi agent phải tuân theo khi sinh `tech.md`.
 
 SAD không chứa: feature-level design, business rules, entity details — những thứ đó thuộc về `domain.md` và `fdd.md`.
 
@@ -30,21 +30,21 @@ SAD không chứa: feature-level design, business rules, entity details — nh
 
 ### Bước 1: Kiểm tra preconditions
 
-**Đọc `specs/main/prd.md`:**
+**Đọ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ó nội dung** → đọc để lấy: NFRs (performance, security, availability targets), business constraints, scope.
 
-**Đọc `specs/main/domain.md`:**
+**Đọc `.specs/main/domain.md`:**
 
 - **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).
 
 - **Đã 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`:**
+**Đọc `.specs/main/sad.md`:**
 
 - **Chưa tồn tại** → tiến hành Bước 2 (full interview).
 
@@ -167,7 +167,7 @@ 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/sad.md`.
+Ghi nội dung đã được confirm vào `.specs/main/sad.md`.
 
 **Change History:** Append entry vào section `## Change History` cuối `sad.md` (theo `conventions.md` §5.5):
 
@@ -181,7 +181,7 @@ Nếu chạy lần thứ N (sad.md đã có) → operation = `update`, body li
 
 Thông báo kết quả:
 ```
-✓ specs/main/sad.md đã được cập nhật (status: draft)
+✓ .specs/main/sad.md đã được cập nhật (status: draft)
 
 Bước tiếp theo:
   - /spec-new {feature-name} → định nghĩa requirements của từng feature

package/skills/spec-tech/SKILL.md

@@ -7,7 +7,7 @@ description: Tạo tech.md cho một integration dựa trên spec.md đã đư
 
 ## Overview
 
-Tạo `tech.md` cho một integration trong `specs/integrations/{slug}/`.
+Tạo `tech.md` cho một integration trong `.specs/integrations/{slug}/`.
 
 `tech.md` là technical design — định nghĩa **how to build**: solution approach, data model changes, interfaces. Phải có `spec.md` đã approve trước khi chạy skill này.
 
@@ -30,14 +30,14 @@ Tạo `tech.md` cho một integration trong `specs/integrations/{slug}/`.
 
 **Nếu có ARGUMENT:**
 - Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
-- Quét `specs/integrations/*/spec.md`, tìm integration khớp với argument
+- Quét `.specs/integrations/*/spec.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 integration đó, bắt đầu luôn
 
 **Nếu không có ARGUMENT:**
 
-Quét `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
+Quét `.specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
 
 ```
 Integrations:
@@ -58,7 +58,7 @@ Nếu integration đã có `tech.md` → hỏi trước khi tiếp tục:
 
 ### Bước 1b: Gate check — spec.md phải approved
 
-Đọc frontmatter của `specs/integrations/{slug}/spec.md`.
+Đọc frontmatter của `.specs/integrations/{slug}/spec.md`.
 
 Nếu `status` **không phải** `approved`:
 
@@ -76,12 +76,12 @@ Nếu `status: approved` → tiếp tục sang Bước 2.
 
 Load các file sau:
 
-- `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 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}/frd.md` — cho mỗi feature trong frontmatter `features` (đọc `Verification Rules` để sinh `Verification Implementation` trong fdd.md)
-- `specs/main/feature/{F-XXX}-{slug}/fdd.md` — cho mỗi feature trong frontmatter `features` (nếu fdd.md tồn tại)
+- `.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 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}/frd.md` — cho mỗi feature trong frontmatter `features` (đọc `Verification Rules` để sinh `Verification Implementation` trong fdd.md)
+- `.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:
 
@@ -168,11 +168,11 @@ Liệt kê **tất cả** components bị touched trong frontmatter và đánh g
 
 Với từng component có đề xuất:
 
-**Tạo mới** `specs/main/component/{C-XXX}-{component-slug}/cdd.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`
+**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
@@ -184,12 +184,12 @@ Liệt kê **tất cả** features liên quan trong frontmatter và đánh giá:
 | 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`
+**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, **Verification Implementation** — từ tech.md (chỉ phần inter-component, không lặp internal design của component)
 - **Verification Implementation**: với mỗi rule trong `frd.md > Verification Rules` của feature này, sinh row trong bảng `Rule ID | Rule (short) | Layer | Owning component | Error propagation`. Reference rule bằng `VR-F{NNN}-{seq}` ID (lấy nguyên từ FRD, không tạo ID mới). Rule (short) copy ngắn gọn từ FRD để row tự đọc được. Layer = client/gateway/service (có thể combine). Owning component reference C-XXX. KHÔNG đưa regex/validator code/error message wording vào — đó thuộc `cdd.md` của owning component (cascade riêng) hoặc UI copy artifact. Bỏ qua nếu FRD không có Verification Rules.
 
-**Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
+**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
 - Nếu integration thêm/đổi rule trong FRD → cập nhật bảng Verification Implementation tương ứng
 
@@ -216,7 +216,7 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 ### Bước 6: Save + Auto-cascade
 
-**[6.1] Ghi `specs/integrations/{slug}/tech.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` và `components` mirror từ `spec.md`.
+**[6.1] Ghi `.specs/integrations/{slug}/tech.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` và `components` mirror từ `spec.md`.
 
 **[6.2] Auto-apply mỗi Changes block** vào main artifact tương ứng. Thứ tự apply (để tránh forward reference): `sad.md` → `domain.md` → `component/*/cdd.md` → `feature/*/fdd.md`.
 
@@ -265,7 +265,7 @@ Cho mỗi artifact:
 **[6.4] Thông báo kết quả:**
 
 ```
-✓ specs/integrations/{slug}/tech.md đã được tạo (status: approved)
+✓ .specs/integrations/{slug}/tech.md đã được tạo (status: approved)
 
 Auto-cascade applied:
   ✓ sad.md — {summary | no-op}

package/skills/spec-test/SKILL.md

@@ -7,13 +7,13 @@ description: Tạo test.md cho một integration bằng cách mechanical derive
 
 ## Overview
 
-Tạo `test.md` cho một integration trong `specs/integrations/{slug}/`.
+Tạo `test.md` cho một integration trong `.specs/integrations/{slug}/`.
 
 `test.md` là verification design ở integration level — định nghĩa **how to verify** rằng integration đáp ứng `spec.md`. Nội dung gồm Test Strategy (per integration) + Changes blocks cascade lên feature `tsd.md` (Test Spec Document).
 
 **Hai artifact tách bạch:**
-- `specs/integrations/{slug}/test.md` — integration-level, ephemeral, PR record bất biến sau approve (single-word naming như `spec.md` / `tech.md` / `plan.md`).
-- `specs/main/feature/{F-XXX}-{slug}/tsd.md` — feature-level, persistent canonical artifact (3-letter naming như `frd.md` / `fdd.md`). TC content cuối cùng nằm ở đây.
+- `.specs/integrations/{slug}/test.md` — integration-level, ephemeral, PR record bất biến sau approve (single-word naming như `spec.md` / `tech.md` / `plan.md`).
+- `.specs/main/feature/{F-XXX}-{slug}/tsd.md` — feature-level, persistent canonical artifact (3-letter naming như `frd.md` / `fdd.md`). TC content cuối cùng nằm ở đây.
 
 **Role:** QC. Song song với `/spec-tech` (DEV role). Cả hai chỉ phụ thuộc `spec.md` approved — không có thứ tự bắt buộc giữa chúng.
 
@@ -38,14 +38,14 @@ Tạo `test.md` cho một integration trong `specs/integrations/{slug}/`.
 
 **Nếu có ARGUMENT:**
 - Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
-- Quét `specs/integrations/*/spec.md`, tìm integration khớp với argument
+- Quét `.specs/integrations/*/spec.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 integration đó, bắt đầu luôn
 
 **Nếu không có ARGUMENT:**
 
-Quét `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `test.md`:
+Quét `.specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `test.md`:
 
 ```
 Integrations:
@@ -66,7 +66,7 @@ Nếu integration đã có `test.md` → hỏi trước khi tiếp tục:
 
 ### Bước 1b: Gate check
 
-Đọc frontmatter của `specs/integrations/{slug}/spec.md`.
+Đọc frontmatter của `.specs/integrations/{slug}/spec.md`.
 
 **Check 1 — spec.md phải approved:**
 
@@ -77,7 +77,7 @@ Nếu `status` **không phải** `approved`:
 > `/spec-test` cần spec.md approved vì cascade frd.md (nguồn của TC) chỉ apply sau khi approve.
 >
 > Để tiếp tục:
-> 1. Review `specs/integrations/{slug}/spec.md`
+> 1. Review `.specs/integrations/{slug}/spec.md`
 > 2. Approve (đổi `status: draft` → `status: approved`)
 >
 > Sau đó chạy lại `/spec-test`.
@@ -107,10 +107,10 @@ Nếu cả 2 check pass → tiếp tục Bước 2.
 
 Load các file sau:
 
-- `specs/integrations/{slug}/spec.md` — đọc toàn bộ + frontmatter (`features`)
-- `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature trong frontmatter `features` (source của TC — bắt buộc tồn tại vì cascade từ spec.md đã apply)
-- `specs/main/feature/{F-XXX}-{slug}/tsd.md` — cho mỗi feature trong frontmatter `features` (nếu tồn tại — cần để diff và assign next ID)
-- `specs/integrations/{slug}/tech.md` — đọc nếu tồn tại (optional, dùng để hint environment / data set / NFR perf threshold)
+- `.specs/integrations/{slug}/spec.md` — đọc toàn bộ + frontmatter (`features`)
+- `.specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature trong frontmatter `features` (source của TC — bắt buộc tồn tại vì cascade từ spec.md đã apply)
+- `.specs/main/feature/{F-XXX}-{slug}/tsd.md` — cho mỗi feature trong frontmatter `features` (nếu tồn tại — cần để diff và assign next ID)
+- `.specs/integrations/{slug}/tech.md` — đọc nếu tồn tại (optional, dùng để hint environment / data set / NFR perf threshold)
 
 Tóm tắt context:
 
@@ -127,7 +127,7 @@ TÔI HIỂU:
 ```
 
 Nếu frd.md của feature nào không tồn tại → báo lỗi và dừng (lỗi cascade từ spec.md trước đó):
-> ⛔ `specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại nhưng feature có trong `features:` của spec.md. Cascade từ spec.md có thể đã fail. Kiểm tra lại.
+> ⛔ `.specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại nhưng feature có trong `features:` của spec.md. Cascade từ spec.md có thể đã fail. Kiểm tra lại.
 
 ---
 
@@ -284,14 +284,14 @@ Chỉ tiến hành Bước 6 sau khi QC confirm.
 
 ### Bước 6: Save + Auto-cascade
 
-**[6.1] Ghi `specs/integrations/{slug}/test.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` mirror từ `spec.md`.
+**[6.1] Ghi `.specs/integrations/{slug}/test.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` mirror từ `spec.md`.
 
 **[6.2] Auto-apply mỗi Changes block** vào `feature/{F-XXX}/tsd.md` tương ứng. Thứ tự apply: theo thứ tự xuất hiện trong frontmatter `features` (deterministic, không có forward reference giữa các feature tsd.md). Bỏ qua feature có operation `no-op` trong Cascade Summary.
 
 Cho từng block:
 
 - **Operation=create:**
-  - Tạo file `specs/main/feature/{F-XXX}-{slug}/tsd.md`
+  - Tạo file `.specs/main/feature/{F-XXX}-{slug}/tsd.md`
   - Nội dung = nội dung của Changes block (theo format `templates/main/feature/tsd-template.md`)
   - Frontmatter của tsd.md mới: status `draft` (separate lifecycle với integration test.md)
 
@@ -329,7 +329,7 @@ Format entry:
 **[6.4] Thông báo kết quả:**
 
 ```
-✓ specs/integrations/{slug}/test.md đã được tạo (status: approved)
+✓ .specs/integrations/{slug}/test.md đã được tạo (status: approved)
 
 Auto-cascade applied:
   ✓ feature/F-XXX-{slug}/tsd.md — {created | updated: +N TS, +M TC, modify K TC, remove L TC}