spec-lite 1.4.2 → 1.4.5

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,10 +7,12 @@ 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`.
 
+**Một side-effect cascade lên `domain.md`:** carve component là việc *thiết kế hệ thống* (HOW), nên `/spec-sad` là nơi gán **`Owner`** cho các shared entity mà pha *mô tả hệ thống* (WHAT — qua `/spec-prd`/`/spec-frd`/`/spec-new`) đã định nghĩa nhưng để `Owner: TBD`. SAD không chứa entity content; nó chỉ điền cột ownership còn trống. Xem two-phase cascade ở `conventions.md` §5.5.
+
 **Guardrails là phần quan trọng nhất của SAD.** Thiếu guardrails = agent tự quyết định tech pattern mà không có constraint.
 
 ## When to Use
@@ -30,21 +32,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.
+- **Đã 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. **Ghi nhận các shared entity có `Owner: TBD`** (do pha mô tả seed) → đây là danh sách cần gán owner ở Bước 2 (Phần 1.6).
 
-**Đọ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).
 
@@ -61,6 +63,7 @@ SAD không chứa: feature-level design, business rules, entity details — nh
   | 5 | Inter-Service Communication | ✓ đã có / ✗ trống/thiếu |
   | 6 | Infrastructure Overview | ✓ đã có / ✗ trống/thiếu |
   | 7 | Architectural Guardrails | ✓ đã có / ✗ trống/thiếu |
+  | 8 | ADR Log | ✓ đã 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.
 
@@ -73,9 +76,10 @@ SAD không chứa: feature-level design, business rules, entity details — nh
     [3] Tech Stack                   ✓ đã có
     [4] Cross-Cutting Concerns       ✗ chưa có — cần bổ sung
     [5] Inter-Service Communication  ✓ đã có
-    [6] ADR Log                      ⚠ không có trong template
-    [7] Infrastructure Overview      ✓ đã có
-    [8] Architectural Guardrails     ✓ đã có
+    [6] Infrastructure Overview      ✓ đã có
+    [7] Architectural Guardrails     ✓ đã có
+    [8] ADR Log                      ✗ chưa có — cần bổ sung
+    [9] Deployment Diagram           ⚠ không có trong template
     [A] Interview tất cả sections
 
   Chọn số hoặc A:
@@ -117,6 +121,20 @@ Nếu user muốn đề xuất → đề xuất 2-3 option với trade-offs rõ
 
 Nếu `prd.md > Components` còn rỗng (brownfield init chưa scan code, hoặc greenfield chưa biết component) → để placeholder và note rằng bảng này sẽ được điền khi Component Index có nội dung (qua `/spec-brownfield-component` hoặc cascade từ integration).
 
+**Phần 1.6 — Gán Owner cho shared entity (cascade lên domain):**
+
+Sau khi component boundaries đã rõ (từ Components table), với mỗi shared entity có `Owner: TBD` (ghi nhận ở Bước 1):
+> Entity **{Entity}** (định nghĩa ở domain) nên được component nào sở hữu canonical definition?
+>   - {C-XXX} — {tên}
+>   - {C-YYY} — {tên}
+> Và những component nào reference nó (Used by)?
+
+- Gán `Owner: C-XXX` (component giữ canonical definition) + `Used by: C-XXX, C-YYY`.
+- Nếu hoá ra entity chỉ một component dùng → vẫn ghi `Owner`, `Used by` chỉ component đó; cân nhắc note rằng nó có thể chuyển về `crd.md` nội bộ (không bắt buộc xử lý ở đây).
+- Component Index còn rỗng → để nguyên `Owner: TBD`, gán sau khi component được carve.
+
+Đây là nửa **thiết kế hệ thống (HOW)** của domain cascade — bổ sung ownership cho định nghĩa entity mà pha mô tả đã tạo. Ghi xuống ở Bước 5.
+
 **Phần 2 — Tech Stack:**
 > Tech stack cho từng layer: Frontend, Backend, Database, Infrastructure?
 > Với mỗi lựa chọn: lý do chọn là gì? (performance, team familiarity, ecosystem...)
@@ -146,6 +164,12 @@ Nếu user chưa quyết định layer nào → đề xuất options dựa trên
 - Nếu có external API → `GUARD-XXX: Mọi external API call phải có retry + timeout`
 - Nếu layered architecture → `GUARD-XXX: Không để business logic trong API/controller layer`
 
+**Phần 7 — ADR Log:**
+> Trong quá trình thảo luận vừa rồi, những quyết định nào là *quan trọng và có đánh đổi*? (chọn architectural style, tech chính, sync vs async...)
+> Với mỗi cái, tôi sẽ ghi một ADR entry: quyết định + bối cảnh/lý do + hệ quả.
+
+Tự đề xuất ADR-001+ từ chính các lựa chọn user đã chốt ở Phần 1–6 (style, tech stack, communication) — không bắt user nhập lại từ đầu. Status mặc định `accepted`. Nếu chưa có quyết định nào đáng ghi → để placeholder.
+
 ---
 
 ### Bước 3: Write — sinh draft
@@ -167,7 +191,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):
 
@@ -179,9 +203,21 @@ Ghi nội dung đã được confirm vào `specs/main/sad.md`.
 
 Nếu chạy lần thứ N (sad.md đã có) → operation = `update`, body liệt kê section đã đổi với mô tả ngắn.
 
+**Cascade Owner lên `domain.md` (nếu Phần 1.6 gán owner cho entity TBD):** apply `[MODIFY Owner]` + `[MODIFY Used by]` vào các entity tương ứng trong `domain.md > Shared Entities`, rồi append **một** Change History entry vào `domain.md`, operation = `manual`:
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Shared Entities**:
+  - [MODIFY Owner] {Entity} — TBD → {C-XXX} (gán ownership qua /spec-sad)
+```
+
+Atomic với việc ghi sad.md. Không tạo entity mới ở đây (đó là pha mô tả); chỉ điền `Owner`/`Used by` còn `TBD`.
+
 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)
+{nếu có} ✓ domain.md — gán Owner cho {N} shared entity (TBD → C-XXX)
 
 Bước tiếp theo:
   - /spec-new {feature-name} → định nghĩa requirements của từng feature
@@ -216,4 +252,5 @@ Trước khi kết thúc, kiểm tra:
 - [ ] Mỗi tech stack item có lý do chọn rõ ràng
 - [ ] Tất cả 4 cross-cutting concerns đã được điền (auth, error, logging, caching)
 - [ ] Guardrails có ít nhất 3 item, mỗi item cụ thể và actionable
+- [ ] Shared entity có `Owner: TBD` đã được gán `Owner: C-XXX` + `Used by` (nếu Component Index đã có nội dung); cascade `[MODIFY Owner]` lên domain.md + Change History entry operation `manual`
 - [ ] User đã confirm — đặc biệt phần Guardrails — trước khi ghi file

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}

package/skills/spec-tsd/SKILL.md

@@ -7,7 +7,7 @@ description: Tạo tsd.md (Test Spec Document) trực tiếp tại feature level
 
 ## Overview
 
-Tạo `specs/main/feature/{F-XXX}-{slug}/tsd.md` trực tiếp từ frd.md của feature đó — **không qua integration**, không cascade.
+Tạo `.specs/main/feature/{F-XXX}-{slug}/tsd.md` trực tiếp từ frd.md của feature đó — **không qua integration**, không cascade.
 
 Skill này song hành với `/spec-prd` và `/spec-sad`: skill có acronym suffix (`prd`/`sad`/`tsd`) → tạo main artifact trực tiếp. Phân biệt với `/spec-test` — skill đó tạo `test.md` integration-level và cascade qua Changes blocks.
 
@@ -39,13 +39,13 @@ Quy tắc:
 
 **Nếu có ARGUMENT:**
 - Parse argument: có thể là feature ID (`F-001`, `001`) hoặc slug (`F-001-auth`, `auth`)
-- Quét `specs/main/feature/*/frd.md`, tìm feature khớp
+- Quét `.specs/main/feature/*/frd.md`, tìm feature khớp
 - Nếu không tìm thấy → báo lỗi:
-  > Không tìm thấy feature khớp với "{argument}". Kiểm tra `specs/main/feature/`.
+  > Không tìm thấy feature khớp với "{argument}". Kiểm tra `.specs/main/feature/`.
 
 **Nếu không có ARGUMENT:**
 
-Quét `specs/main/feature/`. Liệt kê **tất cả** features có `frd.md`, đánh dấu trạng thái tsd:
+Quét `.specs/main/feature/`. Liệt kê **tất cả** features có `frd.md`, đánh dấu trạng thái tsd:
 
 ```
 Features có frd.md:
@@ -66,12 +66,12 @@ Nếu không có feature nào có frd → thông báo:
 
 **Check 1 — frd.md tồn tại:**
 
-Nếu `specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại → dừng:
+Nếu `.specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại → dừng:
 > ⛔ `feature/{F-XXX}-{slug}/frd.md` không tồn tại. `/spec-tsd` cần frd làm input.
 
 **Check 2 — tsd.md đã tồn tại:**
 
-Nếu `specs/main/feature/{F-XXX}-{slug}/tsd.md` đã tồn tại:
+Nếu `.specs/main/feature/{F-XXX}-{slug}/tsd.md` đã tồn tại:
 
 > ⚠ `tsd.md` đã tồn tại cho feature **{F-XXX} — {slug}**.
 >
@@ -90,8 +90,8 @@ Nếu user chọn yes → backup tsd.md cũ thành `tsd.md.bak.{timestamp}` rồ
 
 Load các file sau:
 
-- `specs/main/feature/{F-XXX}-{slug}/frd.md` — **bắt buộc**, source của TC
-- `specs/main/feature/{F-XXX}-{slug}/fdd.md` — optional, đọc nếu tồn tại để hint Components Used (cho Dependencies section của tsd)
+- `.specs/main/feature/{F-XXX}-{slug}/frd.md` — **bắt buộc**, source của TC
+- `.specs/main/feature/{F-XXX}-{slug}/fdd.md` — optional, đọc nếu tồn tại để hint Components Used (cho Dependencies section của tsd)
 
 Tóm tắt context:
 
@@ -183,7 +183,7 @@ Hiển thị draft đầy đủ — chưa ghi file.
 
 ### Bước 6: Save
 
-Ghi `specs/main/feature/{F-XXX}-{slug}/tsd.md` với status `draft` (feature-level artifact có lifecycle riêng, không phải `approved` — QC còn fill placeholders nên status `draft` cho đến khi đầy đủ).
+Ghi `.specs/main/feature/{F-XXX}-{slug}/tsd.md` với status `draft` (feature-level artifact có lifecycle riêng, không phải `approved` — QC còn fill placeholders nên status `draft` cho đến khi đầy đủ).
 
 Nếu overwrite — file backup `tsd.md.bak.{timestamp}` đã tạo ở Bước 2.
 
@@ -200,7 +200,7 @@ Nếu overwrite tsd.md cũ → entry vẫn dùng operation `create` (vì IDs reg
 Thông báo kết quả:
 
 ```
-✓ specs/main/feature/{F-XXX}-{slug}/tsd.md đã được tạo (status: draft)
+✓ .specs/main/feature/{F-XXX}-{slug}/tsd.md đã được tạo (status: draft)
   Coverage: N Flows → N TS, M US/AC → M Functional TC, P VR → ~2P Validation TC, Q FAC → Q Feature AC TC
   {nếu overwrite: backup tại tsd.md.bak.{timestamp}}