spec-lite 1.4.2 → 1.4.3

package/README.md

@@ -29,17 +29,17 @@ Chạy một lần để bootstrap main artifacts, sau đó vào Integration Pip
 ```
 
 #### `/spec-prd`
-Tạo hoặc cập nhật `specs/main/prd.md` thông qua interview có cấu trúc. Đồng thời scaffold `specs/main/domain.md` skeleton. Nhận tùy chọn một nguồn baseline (path/@file/paste proposal/BRD) để pre-fill interview.
+Tạo hoặc cập nhật `.specs/main/prd.md` thông qua interview có cấu trúc. Đồng thời scaffold `.specs/main/domain.md` skeleton. Nhận tùy chọn một nguồn baseline (path/@file/paste proposal/BRD) để pre-fill interview.
 
 Sections: Problem Statement · Target Users · Scope · Features · Components · Non-Functional Requirements · Business Constraints
 
 #### `/spec-sad`
-Tạo hoặc cập nhật `specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` đã tồn tại.
+Tạo hoặc cập nhật `.specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` đã tồn tại.
 
 Sections: Architectural Style · System Overview · Tech Stack · Cross-Cutting Concerns · Inter-Service Communication · Infrastructure Overview · Architectural Guardrails
 
 #### `/spec-frd [F-XXX]` *(tùy chọn)*
-BA author `specs/main/feature/{F-XXX}-*/frd.md` trực tiếp qua interview, **trước** khi DEV bắt đầu integration — spec-first ở feature level. Cặp greenfield đối xứng với `/spec-brownfield-feature`. Nhận F-XXX (hoặc chọn từ Feature Index) + tùy chọn nguồn baseline (path/@file/paste).
+BA author `.specs/main/feature/{F-XXX}-*/frd.md` trực tiếp qua interview, **trước** khi DEV bắt đầu integration — spec-first ở feature level. Cặp greenfield đối xứng với `/spec-brownfield-feature`. Nhận F-XXX (hoặc chọn từ Feature Index) + tùy chọn nguồn baseline (path/@file/paste).
 
 **Hai gate input (làm chặt):** (1) **Single-feature** — nguồn liên quan đúng 1 feature; xác định >1 → dừng, mô tả rõ lý do tách, redirect `/spec-prd`. (2) **Create-only** — frd.md đã tồn tại → dừng, redirect `/spec-new` (thay đổi feature đã spec đi qua integration để delta cascade + tech/test). Feature mới đơn lẻ chưa có trong Index → skill offer **register một row vào prd Features** rồi author.
 
@@ -114,19 +114,19 @@ Mỗi requirement mới đều đi qua pipeline này.
 ```
 
 #### `/spec-new [requirement]`
-Tạo `specs/integrations/{slug}/spec.md` cho một integration mới.
+Tạo `.specs/integrations/{slug}/spec.md` cho một integration mới.
 
 - Có argument → dùng trực tiếp làm raw requirement
 - Không có argument → hiển thị danh sách features TODO từ `prd.md` để chọn
 
 #### `/spec-tech [number]`
-Tạo `specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve. Chạy bởi **DEV**.
+Tạo `.specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve. Chạy bởi **DEV**.
 
 - Có argument → chọn integration theo số thứ tự luôn
 - Không có argument → hiển thị danh sách tất cả integrations
 
 #### `/spec-test [number]`
-Tạo `specs/integrations/{slug}/test.md` sau khi `spec.md` được approve. Chạy bởi **QC**, **song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → Feature AC TC), priority deterministic. Cascade lên `feature/{F-XXX}/tsd.md` qua Changes blocks. Gate: integration phải có `features:` non-empty (component-thuần không áp dụng).
+Tạo `.specs/integrations/{slug}/test.md` sau khi `spec.md` được approve. Chạy bởi **QC**, **song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → Feature AC TC), priority deterministic. Cascade lên `feature/{F-XXX}/tsd.md` qua Changes blocks. Gate: integration phải có `features:` non-empty (component-thuần không áp dụng).
 
 #### `/plan`
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`.
@@ -143,7 +143,7 @@ Review implementation sau `/build` theo năm trục: correctness, readability, a
 #### `/review-everything`
 Review toàn bộ codebase ở **project level** đối chiếu với `prd.md` / `domain.md` / `sad.md`. Spawn 5 subagent song song theo năm axis của `code-review-and-quality`.
 
-Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Critical+Required / +Optional / All / Bỏ qua). Nếu chọn fix → gom selected findings thành raw requirement và auto-invoke `/spec-new` để tạo integration. Findings full snapshot được lưu vào `specs/integrations/{NNN}-{slug}/review-findings.md`.
+Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Critical+Required / +Optional / All / Bỏ qua). Nếu chọn fix → gom selected findings thành raw requirement và auto-invoke `/spec-new` để tạo integration. Findings full snapshot được lưu vào `.specs/integrations/{NNN}-{slug}/review-findings.md`.
 
 ---
 
@@ -162,20 +162,20 @@ Pre-flight yêu cầu git working tree clean — rollback dùng `git checkout --
 
 | Command | Output |
 |---------|--------|
-| `/spec-prd` | `specs/main/prd.md`, `specs/main/domain.md` (skeleton) |
-| `/spec-sad` | `specs/main/sad.md` |
-| `/spec-frd` | `specs/main/feature/{F-XXX}-*/frd.md` *(+ register feature row vào `prd.md` nếu feature mới)* |
-| `/spec-brownfield-init` | `specs/main/prd.md`, `specs/main/domain.md`, `specs/main/sad.md` |
-| `/spec-brownfield-component` | `specs/main/component/{C-XXX}-*/crd.md + cdd.md` |
-| `/spec-brownfield-feature` | `specs/main/feature/{F-XXX}-*/frd.md + fdd.md` |
-| `/spec-tsd` | `specs/main/feature/{F-XXX}-*/tsd.md` |
+| `/spec-prd` | `.specs/main/prd.md`, `.specs/main/domain.md` (skeleton) |
+| `/spec-sad` | `.specs/main/sad.md` |
+| `/spec-frd` | `.specs/main/feature/{F-XXX}-*/frd.md` *(+ register feature row vào `prd.md` nếu feature mới)* |
+| `/spec-brownfield-init` | `.specs/main/prd.md`, `.specs/main/domain.md`, `.specs/main/sad.md` |
+| `/spec-brownfield-component` | `.specs/main/component/{C-XXX}-*/crd.md + cdd.md` |
+| `/spec-brownfield-feature` | `.specs/main/feature/{F-XXX}-*/frd.md + fdd.md` |
+| `/spec-tsd` | `.specs/main/feature/{F-XXX}-*/tsd.md` |
 | `/spec-frd-update` | *(modify in-place `feature/*/frd.md` + cascade refs)* |
-| `/spec-new` | `specs/integrations/{slug}/spec.md` |
-| `/spec-tech` | `specs/integrations/{slug}/tech.md` |
-| `/spec-test` | `specs/integrations/{slug}/test.md`, cascade: `feature/{F-XXX}/tsd.md` |
-| `/plan` | `specs/integrations/{slug}/plan.md`, `todo.md` |
+| `/spec-new` | `.specs/integrations/{slug}/spec.md` |
+| `/spec-tech` | `.specs/integrations/{slug}/tech.md` |
+| `/spec-test` | `.specs/integrations/{slug}/test.md`, cascade: `feature/{F-XXX}/tsd.md` |
+| `/plan` | `.specs/integrations/{slug}/plan.md`, `todo.md` |
 | `/build` | *(implements tasks từ `plan.md`/`todo.md`)* |
 | `/review-integration` | *(findings report — không tạo file)* |
-| `/review-everything` | `specs/integrations/{NNN}-{slug}/review-findings.md` *(qua /spec-new)* |
+| `/review-everything` | `.specs/integrations/{NNN}-{slug}/review-findings.md` *(qua /spec-new)* |
 
 Feature artifacts (`frd.md`) ở greenfield có thể author trước bằng `/spec-frd`, hoặc mọc dần qua **cascade proposals** từ integrations (`/spec-new` fallback). Component artifacts (`crd.md`/`cdd.md`) ở greenfield chỉ mọc qua cascade — không có skill author trực tiếp (`/spec-frd` chỉ reference component, không tạo crd/cdd).

package/package.json

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

package/skills/ado-config/SKILL.md

@@ -176,7 +176,7 @@ options:
 ```
 
 Nếu user chọn **"Dùng nội dung từ spec artifact"**:
-- Hỏi đường dẫn file (ví dụ `specs/integrations/001-implement-auth/spec.md`)
+- Hỏi đường dẫn file (ví dụ `.specs/integrations/001-implement-auth/spec.md`)
 - Đọc file → dùng toàn bộ nội dung làm description của Epic (format Markdown)
 
 Nếu user chọn **"Tự nhập mô tả"**:

package/skills/ado-create/SKILL.md

@@ -12,7 +12,7 @@ description: Tạo Feature và User Story tickets trên ADO từ spec.md của m
 ## Prerequisites
 
 - `.claude/ado.yaml` phải tồn tại và có `epic.id` (chạy `/ado-config` nếu chưa có)
-- `frd.md` tương ứng phải tồn tại trong `specs/main/features/` cho mỗi feature
+- `frd.md` tương ứng phải tồn tại trong `.specs/main/features/` cho mỗi feature
 
 ---
 
@@ -49,7 +49,7 @@ Không resolve được ADO identity ID cho <email>. Kiểm tra lại PAT token
 
 ### Bước 2: Chọn integration
 
-List tất cả thư mục trong `specs/integrations/` trừ `000-scaffold`. Với mỗi thư mục, đọc frontmatter của `spec.md` để lấy `title` và `status`.
+List tất cả thư mục trong `.specs/integrations/` trừ `000-scaffold`. Với mỗi thư mục, đọc frontmatter của `spec.md` để lấy `title` và `status`.
 
 Hỏi user bằng `AskUserQuestion`:
 
@@ -120,7 +120,7 @@ Thực hiện tuần tự với từng Feature chưa có ADO ticket:
 
 **5.1 Tìm frd.md:**
 
-Map `F-NNN` → tìm thư mục `specs/main/features/` bắt đầu bằng `NNN-`. Đọc `frd.md` trong thư mục đó.
+Map `F-NNN` → tìm thư mục `.specs/main/features/` bắt đầu bằng `NNN-`. Đọc `frd.md` trong thư mục đó.
 
 Nếu không tìm thấy `frd.md` → cảnh báo, dùng phần mô tả Feature từ `spec.md` làm description thay thế.
 
@@ -226,7 +226,7 @@ Sau khi tất cả tickets đã được tạo, cập nhật `spec.md`:
 
 ### Bước 8: Cập nhật prd.md
 
-Mở `specs/main/prd.md`. Tìm bảng `## Features`.
+Mở `.specs/main/prd.md`. Tìm bảng `## Features`.
 
 **Nếu bảng chưa có cột `ADO`:** Thêm cột vào header và separator row:
 
@@ -284,9 +284,9 @@ Tìm section `## ADO Tickets` trong file.
   ✓ #12348 — [SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-003 — Đăng xuất  → F-001 #12345
 
   Files đã cập nhật:
-  ✓ specs/integrations/001-implement-auth/spec.md
-  ✓ specs/main/features/001-auth/frd.md
-  ✓ specs/main/prd.md
+  ✓ .specs/integrations/001-implement-auth/spec.md
+  ✓ .specs/main/features/001-auth/frd.md
+  ✓ .specs/main/prd.md
 
   {nếu có lỗi tạo ticket}
   ✗ US-F001-004 — ... → tạo thất bại: <lý do>

package/skills/ado-update/SKILL.md

@@ -92,7 +92,7 @@ Nếu `environments` trống hoặc không tồn tại trong file → dừng:
 
 ### Bước 2: Chọn integration
 
-List tất cả thư mục trong `specs/integrations/` trừ `000-scaffold`. Với mỗi thư mục, đọc frontmatter của `spec.md` để lấy `title` và `status`.
+List tất cả thư mục trong `.specs/integrations/` trừ `000-scaffold`. Với mỗi thư mục, đọc frontmatter của `spec.md` để lấy `title` và `status`.
 
 Hỏi user bằng `AskUserQuestion`:
 

package/skills/archive/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: archive
-description: Archive một integration từ specs/integrations sang specs/archive. Dùng khi một integration đã hoàn thành hoặc không còn active và cần được lưu trữ ra khỏi thư mục làm việc chính.
+description: Archive một integration từ .specs/integrations sang .specs/archive. Dùng khi một integration đã hoàn thành hoặc không còn active và cần được lưu trữ ra khỏi thư mục làm việc chính.
 ---
 
 # archive
 
 ## Overview
 
-Di chuyển một integration từ `specs/integrations/` sang `specs/archive/` để dọn dẹp thư mục làm việc chính trong khi vẫn giữ nguyên toàn bộ nội dung integration đó.
+Di chuyển một integration từ `.specs/integrations/` sang `.specs/archive/` để dọn dẹp thư mục làm việc chính trong khi vẫn giữ nguyên toàn bộ nội dung integration đó.
 
 ## When to Use
 
 - Integration đã hoàn thành (Done) và không cần active nữa
 - Integration bị cancel hoặc deferred vô thời hạn
-- Muốn dọn dẹp `specs/integrations/` khỏi các integration cũ
+- Muốn dọn dẹp `.specs/integrations/` khỏi các integration cũ
 
 ## When NOT to Use
 
@@ -26,9 +26,9 @@ Di chuyển một integration từ `specs/integrations/` sang `specs/archive/`
 
 ### Bước 1: Kiểm tra thư mục archive
 
-Kiểm tra `specs/archive/` đã tồn tại chưa.
+Kiểm tra `.specs/archive/` đã tồn tại chưa.
 
-**Nếu chưa tồn tại** → tạo thư mục `specs/archive/`.
+**Nếu chưa tồn tại** → tạo thư mục `.specs/archive/`.
 
 **Nếu đã tồn tại** → tiếp tục.
 
@@ -36,12 +36,12 @@ Kiểm tra `specs/archive/` đã tồn tại chưa.
 
 ### Bước 2: Liệt kê integrations
 
-Quét `specs/integrations/` để tìm tất cả các integration (mỗi integration là một thư mục con).
+Quét `.specs/integrations/` để tìm tất cả các integration (mỗi integration là một thư mục con).
 
 **Nếu không có integration nào:**
 
 ```
-Không có integration nào trong specs/integrations/.
+Không có integration nào trong .specs/integrations/.
 ```
 
 Dừng lại.
@@ -49,7 +49,7 @@ Dừng lại.
 **Nếu có integrations**, hiển thị danh sách dạng numbered list, kèm trạng thái nếu đọc được từ `spec.md` (frontmatter `status` hoặc heading):
 
 ```
-Integrations trong specs/integrations/:
+Integrations trong .specs/integrations/:
 
   [1]  001-user-authentication      (approved)
   [2]  002-payment-integration      (draft)
@@ -70,8 +70,8 @@ Sau khi user chọn, hiển thị xác nhận trước khi di chuyển:
 ```
 Sẽ archive các integration sau:
 
-  specs/integrations/001-user-authentication/  →  specs/archive/001-user-authentication/
-  specs/integrations/003-notification-service/ →  specs/archive/003-notification-service/
+  .specs/integrations/001-user-authentication/  →  .specs/archive/001-user-authentication/
+  .specs/integrations/003-notification-service/ →  .specs/archive/003-notification-service/
 
 Xác nhận? (yes/no)
 ```
@@ -84,13 +84,13 @@ Nếu user không confirm → hủy, không làm gì.
 
 Với mỗi integration đã được confirm:
 
-- Di chuyển toàn bộ thư mục `specs/integrations/{slug}/` sang `specs/archive/{slug}/`
+- Di chuyển toàn bộ thư mục `.specs/integrations/{slug}/` sang `.specs/archive/{slug}/`
 - Giữ nguyên toàn bộ cấu trúc thư mục và file bên trong
 
-Nếu `specs/archive/{slug}/` đã tồn tại (trùng tên) → cảnh báo:
+Nếu `.specs/archive/{slug}/` đã tồn tại (trùng tên) → cảnh báo:
 
 ```
-⚠ specs/archive/001-user-authentication/ đã tồn tại. Bỏ qua integration này để tránh ghi đè.
+⚠ .specs/archive/001-user-authentication/ đã tồn tại. Bỏ qua integration này để tránh ghi đè.
 ```
 
 Và bỏ qua integration đó, tiếp tục với các integration còn lại.
@@ -103,14 +103,14 @@ Thông báo kết quả:
 
 ```
 ✓ Đã archive:
-  specs/archive/001-user-authentication/
-  specs/archive/003-notification-service/
+  .specs/archive/001-user-authentication/
+  .specs/archive/003-notification-service/
 
 {nếu có lỗi}
 ⚠ Bỏ qua (đã tồn tại):
-  specs/archive/005-foo/
+  .specs/archive/005-foo/
 
-specs/integrations/ hiện còn {N} integration(s).
+.specs/integrations/ hiện còn {N} integration(s).
 ```
 
 ---
@@ -119,7 +119,7 @@ specs/integrations/ hiện còn {N} integration(s).
 
 Trước khi di chuyển:
 
-- [ ] `specs/archive/` đã tồn tại (tạo nếu chưa có)
+- [ ] `.specs/archive/` đã tồn tại (tạo nếu chưa có)
 - [ ] User đã chọn ít nhất 1 integration
 - [ ] User đã confirm trước khi di chuyển
-- [ ] Không ghi đè nếu slug đã tồn tại trong `specs/archive/`
+- [ ] Không ghi đè nếu slug đã tồn tại trong `.specs/archive/`

package/skills/build/SKILL.md

@@ -17,13 +17,13 @@ Invoke `incremental-implementation` và `test-driven-development` cùng nhau cho
 
 **Nếu có ARGUMENT:**
 - Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
-- Quét `specs/integrations/*/todo.md`, tìm integration khớp với argument
+- Quét `.specs/integrations/*/todo.md`, tìm integration khớp với argument
 - Nếu không tìm thấy → báo lỗi:
   > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
-- Nếu tìm thấy → dùng `specs/integrations/{slug}/` làm working integration, bắt đầu luôn
+- Nếu tìm thấy → dùng `.specs/integrations/{slug}/` làm working integration, bắt đầu luôn
 
 **Nếu không có ARGUMENT:**
-- Quét `specs/integrations/*/todo.md`, liệt kê tất cả integrations có todo.md, đánh dấu tiến độ:
+- Quét `.specs/integrations/*/todo.md`, liệt kê tất cả integrations có todo.md, đánh dấu tiến độ:
 
 ```
 Integrations:
@@ -40,7 +40,7 @@ Chọn số integration:
 
 ### Bước 0a: Gate check — plan.md phải approved
 
-Đọc frontmatter của `specs/integrations/{slug}/plan.md`.
+Đọc frontmatter của `.specs/integrations/{slug}/plan.md`.
 
 Nếu `plan.md` chưa tồn tại:
 
@@ -59,7 +59,7 @@ Nếu `plan.md` tồn tại nhưng `status` **không phải** `approved`:
 > ⛔ `plan.md` của integration **{slug}** chưa được approve (status hiện tại: `{status}`).
 >
 > Để tiếp tục:
-> 1. Review `specs/integrations/{slug}/plan.md`
+> 1. Review `.specs/integrations/{slug}/plan.md`
 > 2. Đổi `status: draft` → `status: approved` trong frontmatter
 >
 > Sau khi approve xong, chạy lại `/build`.

package/skills/plan/SKILL.md

@@ -29,14 +29,14 @@ Mọi quyết định về sizing, slicing đều thuộc về `planning-and-tas
 
 **Nếu có ARGUMENT:**
 - Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
-- Quét `specs/integrations/*/`, tìm integration khớp với argument
+- Quét `.specs/integrations/*/`, tìm integration khớp với argument
 - Nếu không tìm thấy → báo lỗi:
   > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
 - Nếu tìm thấy → dùng integration đó, bắt đầu luôn
 
 **Nếu không có ARGUMENT:**
 
-Quét `specs/integrations/`. Liệt kê tất cả integrations:
+Quét `.specs/integrations/`. Liệt kê tất cả integrations:
 
 ```
 Integrations:
@@ -55,7 +55,7 @@ Nếu plan.md / todo.md đã tồn tại → hỏi trước khi ghi đè.
 
 ### Bước 1b: Gate check — spec.md và tech.md phải approved
 
-Đọc frontmatter của `specs/integrations/{slug}/spec.md` và `specs/integrations/{slug}/tech.md`.
+Đọc frontmatter của `.specs/integrations/{slug}/spec.md` và `.specs/integrations/{slug}/tech.md`.
 
 Nếu `tech.md` chưa tồn tại → coi như `status: missing`.
 
@@ -83,9 +83,9 @@ Nếu cả hai đều `approved` → tiếp tục sang Bước 2.
 
 Load:
 
-- `specs/integrations/{slug}/spec.md` — Requirements, Acceptance Criteria (ghi chú số AC và IDs)
-- `specs/integrations/{slug}/tech.md` — Technical Design, Interface Changes, Data Model Changes, Implementation Notes
-- `specs/main/domain.md` — Entities và Business Rules liên quan
+- `.specs/integrations/{slug}/spec.md` — Requirements, Acceptance Criteria (ghi chú số AC và IDs)
+- `.specs/integrations/{slug}/tech.md` — Technical Design, Interface Changes, Data Model Changes, Implementation Notes
+- `.specs/main/domain.md` — Entities và Business Rules liên quan
 
 Surface tóm tắt để planning-and-task-breakdown có đủ context:
 

package/skills/review-everything/SKILL.md

@@ -35,9 +35,9 @@ Khác với `/review-integration` (chạy sau `/build`, đối chiếu với spe
 
 Kiểm tra các file sau tồn tại và **có nội dung** (không phải template rỗng):
 
-- `specs/main/prd.md`
-- `specs/main/domain.md`
-- `specs/main/sad.md`
+- `.specs/main/prd.md`
+- `.specs/main/domain.md`
+- `.specs/main/sad.md`
 
 Nếu thiếu hoặc rỗng → dừng:
 
@@ -65,7 +65,7 @@ CONTEXT
 
 SOURCE SCOPE
 - Roots: src/, packages/api/, …
-- Excluded: node_modules/, dist/, .claude/, specs/
+- Excluded: node_modules/, dist/, .claude/, .specs/
 
 Tiếp tục review? (y/n)
 ```
@@ -175,7 +175,7 @@ options:
     description: "Không tạo integration. Findings vẫn được lưu nếu cần tham chiếu sau."
 ```
 
-Nếu user chọn "Bỏ qua" → ghi findings ra `specs/main/review/{YYYY-MM-DD-HHmm}.md` (tạo thư mục nếu chưa có) rồi dừng.
+Nếu user chọn "Bỏ qua" → ghi findings ra `.specs/main/review/{YYYY-MM-DD-HHmm}.md` (tạo thư mục nếu chưa có) rồi dừng.
 
 Nếu user chọn một tier → tiếp Bước 6.
 
@@ -212,7 +212,7 @@ Gọi `Skill` tool: `skill=spec-new`, `args={raw requirement ở Bước 6}`.
 1. Nhận ARGUMENT làm raw requirement (bỏ qua nhánh "chọn từ prd.md").
 2. Load context (prd / domain / frd / crd liên quan).
 3. Interview 4 phần (Problem Statement, Requirements, Acceptance Criteria, Out of Scope) — agent **gợi ý sẵn** dựa trên findings, user chỉnh.
-4. Sinh `specs/integrations/{NNN}-{slug}/spec.md` + cascade lên main artifacts.
+4. Sinh `.specs/integrations/{NNN}-{slug}/spec.md` + cascade lên main artifacts.
 
 **Khi `/spec-new` đề xuất slug**, gợi ý mặc định:
 - `review-{YYYY-MM-DD}` — ngắn, có ngày để truy ngược review nào.
@@ -222,12 +222,12 @@ Gọi `Skill` tool: `skill=spec-new`, `args={raw requirement ở Bước 6}`.
 
 ### Bước 8: Sau khi /spec-new tạo xong integration → lưu findings file
 
-`/spec-new` ghi `specs/integrations/{NNN}-{slug}/spec.md`. Đọc lại path đó để biết `{NNN}-{slug}`.
+`/spec-new` ghi `.specs/integrations/{NNN}-{slug}/spec.md`. Đọc lại path đó để biết `{NNN}-{slug}`.
 
 Ghi **toàn bộ findings** (không chỉ selected — giữ full để tham chiếu sau) vào:
 
 ```
-specs/integrations/{NNN}-{slug}/review-findings.md
+.specs/integrations/{NNN}-{slug}/review-findings.md
 ```
 
 Nội dung:
@@ -270,7 +270,7 @@ Thông báo:
 
   Findings: {N} total ({C} Critical · {R} Required · {O} Optional · {Ni} Nit · {F} FYI)
   Selected: {tier} → {K} findings
-  Integration: specs/integrations/{NNN}-{slug}/
+  Integration: .specs/integrations/{NNN}-{slug}/
     ├── spec.md            (đã tạo bởi /spec-new + cascade)
     └── review-findings.md (full snapshot)
 

package/skills/review-integration/SKILL.md

@@ -11,10 +11,10 @@ Invoke `code-review-and-quality` để review toàn bộ thay đổi sau `/build
 
 Trước khi bắt đầu review, load context từ working integration:
 
-1. `specs/integrations/{slug}/spec.md` — yêu cầu nghiệp vụ, acceptance criteria
-2. `specs/integrations/{slug}/tech.md` — thiết kế kỹ thuật, API contract, data model
-3. `specs/integrations/{slug}/plan.md` — task breakdown và acceptance criteria chi tiết
-4. `specs/integrations/{slug}/todo.md` — task nào đã được implement (`[x]`)
+1. `.specs/integrations/{slug}/spec.md` — yêu cầu nghiệp vụ, acceptance criteria
+2. `.specs/integrations/{slug}/tech.md` — thiết kế kỹ thuật, API contract, data model
+3. `.specs/integrations/{slug}/plan.md` — task breakdown và acceptance criteria chi tiết
+4. `.specs/integrations/{slug}/todo.md` — task nào đã được implement (`[x]`)
 
 Chạy lệnh sau để lấy thay đổi cần review — diff từ điểm branch tách ra, không phải từ tip của base branch:
 
@@ -25,7 +25,7 @@ git diff $(git merge-base HEAD $BASE)...HEAD
 
 ## Xác định integration
 
-**Nếu có ARGUMENT:** Parse số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`). Quét `specs/integrations/*/todo.md`, dùng integration khớp.
+**Nếu có ARGUMENT:** Parse số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`). Quét `.specs/integrations/*/todo.md`, dùng integration khớp.
 
 **Nếu không có ARGUMENT:** Liệt kê integrations có task đã done, cho user chọn.
 
@@ -45,7 +45,7 @@ Nhóm các findings thành tasks cụ thể có thể implement được. Mỗi
 
 Lấy short SHA hiện tại: `git rev-parse --short HEAD`.
 
-Ghi findings vào `specs/integrations/{slug}/techdebt.md`.
+Ghi findings vào `.specs/integrations/{slug}/techdebt.md`.
 
 Nếu file chưa tồn tại, tạo mới từ `.claude/templates/integrations/techdebt-template.md`, điền `slug`, `title`, `created`.
 
@@ -141,7 +141,7 @@ Sau khi cập nhật xong plan.md và todo.md, invoke ngay `/build` để thực
 Thông báo:
 
 ```
-Findings đã được lưu vào specs/integrations/{slug}/techdebt.md.
+Findings đã được lưu vào .specs/integrations/{slug}/techdebt.md.
 Chạy /review-integration lại hoặc /build khi sẵn sàng xử lý.
 ```
 

package/skills/scaffold/SKILL.md

@@ -7,7 +7,7 @@ description: Khởi tạo project scaffold dựa trên sad.md — tạo plan.md
 
 ## Overview
 
-Đọc `specs/main/sad.md`, phân rã thành plan.md và todo.md cho bước khởi tạo project, sau đó thực thi từng task theo thứ tự.
+Đọc `.specs/main/sad.md`, phân rã thành plan.md và todo.md cho bước khởi tạo project, sau đó thực thi từng task theo thứ tự.
 
 Khác với `/plan` — skill này không dừng lại sau khi sinh plan. Sau khi user confirm, nó execute luôn.
 
@@ -18,7 +18,7 @@ Khác với `/plan` — skill này không dừng lại sau khi sinh plan. Sau kh
 
 ## When NOT to Use
 
-- `specs/main/sad.md` chưa có → chạy `/spec-sad` trước
+- `.specs/main/sad.md` chưa có → chạy `/spec-sad` trước
 - Project đã được khởi tạo rồi → implement trực tiếp
 
 ---
@@ -27,14 +27,14 @@ Khác với `/plan` — skill này không dừng lại sau khi sinh plan. Sau kh
 
 ### Bước 1: Kiểm tra preconditions
 
-Đọc `specs/main/sad.md`:
+Đọc `.specs/main/sad.md`:
 
 - **Không tồn tại hoặc là template** → dừng ngay:
   > `sad.md` chưa có nội dung. Hãy chạy `/spec-sad` trước.
 
 - **Đã có nội dung** → tiếp tục.
 
-Kiểm tra `specs/integrations/000-scaffold/`:
+Kiểm tra `.specs/integrations/000-scaffold/`:
 
 - **Không có plan.md và todo.md** → tiếp tục Bước 2 (sinh mới).
 
@@ -214,11 +214,11 @@ Chỉ tiếp tục sau khi user confirm. Nếu cần chỉnh → cập nhật dr
 
 ### Bước 5: Ghi file
 
-Tạo thư mục `specs/integrations/000-scaffold/` nếu chưa có.
+Tạo thư mục `.specs/integrations/000-scaffold/` nếu chưa có.
 
 Ghi:
-- `specs/integrations/000-scaffold/plan.md`
-- `specs/integrations/000-scaffold/todo.md`
+- `.specs/integrations/000-scaffold/plan.md`
+- `.specs/integrations/000-scaffold/todo.md`
 
 ---
 
@@ -269,8 +269,8 @@ Sau khi tất cả tasks pass:
 ```
 ✓ Scaffold hoàn thành
 
-  specs/integrations/000-scaffold/plan.md
-  specs/integrations/000-scaffold/todo.md
+  .specs/integrations/000-scaffold/plan.md
+  .specs/integrations/000-scaffold/todo.md
 
 Tất cả tasks: {N}/{N} ✓
 

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

@@ -7,7 +7,7 @@ description: Discover components từ code, generate crd.md + cdd.md cho từng
 
 ## Overview
 
-Tạo `specs/main/component/{C-XXX}-{component-name}/crd.md` và `cdd.md` cho các components trong brownfield project.
+Tạo `.specs/main/component/{C-XXX}-{component-name}/crd.md` và `cdd.md` cho các components trong brownfield project.
 
 Skill này **tự discover** component boundaries từ code (không dựa vào init), sau đó scan sâu từng component để extract responsibilities, entities, public interface, business rules. Khi hoàn thành, **điền Component Index vào prd.md** và **đề xuất Shared Entities cascade vào domain.md**.
 
@@ -30,8 +30,8 @@ Skill này **tự discover** component boundaries từ code (không dựa vào i
 **Path:** Nếu có ARGUMENT là path → dùng làm root. Nếu không → CWD.
 
 **Load:**
-- `specs/main/prd.md` — kiểm tra tồn tại; đọc problem statement và NFRs để hiểu business context
-- `specs/main/domain.md` — đọc Glossary để reuse business terms
+- `.specs/main/prd.md` — kiểm tra tồn tại; đọc problem statement và NFRs để hiểu business context
+- `.specs/main/domain.md` — đọc Glossary để reuse business terms
 
 Nếu `prd.md` không tồn tại → dừng:
 > `prd.md` chưa có nội dung. Hãy chạy `/spec-brownfield-init` trước.
@@ -178,7 +178,7 @@ Nếu có Shared Entities được phát hiện ở Bước 5:
 SHARED ENTITIES DETECTED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Các entities sau được dùng bởi nhiều components.
-Đề xuất thêm vào specs/main/domain.md (Shared Entities):
+Đề xuất thêm vào .specs/main/domain.md (Shared Entities):
 
   Entity: Order (Owner: C-003-payment)
     Dùng bởi: C-003-payment, C-005-inventory
@@ -191,7 +191,7 @@ Các entities sau được dùng bởi nhiều components.
 Apply cascade proposals vào domain.md? [y/n/edit]
 ```
 
-Nếu `y` → update `specs/main/domain.md` Shared Entities section, đồng thời append entry vào `## Change History` của domain.md (theo `conventions.md` §5.5):
+Nếu `y` → update `.specs/main/domain.md` Shared Entities section, đồng thời append entry vào `## Change History` của domain.md (theo `conventions.md` §5.5):
 
 ```markdown
 ### {YYYY-MM-DD} — manual — update
@@ -209,10 +209,10 @@ Nếu `edit` → hỏi chỉnh sửa từng entity trước khi apply.
 
 ```
 Sẽ tạo {N} components ({2N} files):
-  ✓ specs/main/component/C-001-auth/crd.md     (3 NEEDS_CLARIFY)
-  ✓ specs/main/component/C-001-auth/cdd.md     (1 NEEDS_CLARIFY)
-  ✓ specs/main/component/C-002-user/crd.md     (0 NEEDS_CLARIFY)
-  ✓ specs/main/component/C-002-user/cdd.md     (2 NEEDS_CLARIFY)
+  ✓ .specs/main/component/C-001-auth/crd.md     (3 NEEDS_CLARIFY)
+  ✓ .specs/main/component/C-001-auth/cdd.md     (1 NEEDS_CLARIFY)
+  ✓ .specs/main/component/C-002-user/crd.md     (0 NEEDS_CLARIFY)
+  ✓ .specs/main/component/C-002-user/cdd.md     (2 NEEDS_CLARIFY)
   ...
 
 Ghi tất cả? [y] hoặc review từng file trước [r]:
@@ -273,8 +273,8 @@ Khi apply → đồng thời append entry vào `## Change History` của prd.md
 
 ```
 ✓ Generated {N} components:
-  specs/main/component/C-001-auth/    (crd.md + cdd.md)
-  specs/main/component/C-002-user/    (crd.md + cdd.md)
+  .specs/main/component/C-001-auth/    (crd.md + cdd.md)
+  .specs/main/component/C-002-user/    (crd.md + cdd.md)
   ...
 
 ✓ prd.md Component Index: {N} entries đã được điền