spec-lite 1.4.1 → 1.4.3

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

@@ -7,7 +7,7 @@ description: Discover features từ code, generate frd.md + fdd.md cho từng fe
 
 ## Overview
 
-Tạo `specs/main/feature/{F-XXX}-{feature-name}/frd.md` và `fdd.md` cho các features trong brownfield project.
+Tạo `.specs/main/feature/{F-XXX}-{feature-name}/frd.md` và `fdd.md` cho các features trong brownfield project.
 
 Skill này **tự discover** features từ routes, use cases, và test files, sau đó scan sâu để extract user stories, AC, và inter-component flows. Khi hoàn thành, **điền Feature Index vào prd.md**.
 
@@ -33,9 +33,9 @@ Skill này **tự discover** features từ routes, use cases, và test files, sa
 **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 Component Index đã được điền
-- `specs/main/domain.md` — đọc Glossary và Shared Entities
-- `specs/main/component/*/crd.md` — đọc Public Interface của từng component (để cross-reference trong fdd.md)
+- `.specs/main/prd.md` — kiểm tra Component Index đã được điền
+- `.specs/main/domain.md` — đọc Glossary và Shared Entities
+- `.specs/main/component/*/crd.md` — đọc Public Interface của từng component (để cross-reference trong fdd.md)
 
 **Kiểm tra preconditions:**
 
@@ -46,7 +46,7 @@ Nếu `prd.md` Component Index còn trống (không có C-XXX entries) → dừn
 > Component Index chưa có entries. Hãy chạy `/spec-brownfield-component` trước.
 > fdd.md cần tham chiếu C-XXX để mô tả inter-component flows.
 
-Nếu `specs/main/component/` không có crd.md nào → cảnh báo tương tự và dừng.
+Nếu `.specs/main/component/` không có crd.md nào → cảnh báo tương tự và dừng.
 
 **Attachments:**
 > Bạn có tài liệu bổ sung nào không? (user stories, test plans, wireframes, existing specs)
@@ -216,10 +216,10 @@ Với mỗi feature, generate 2 files dùng templates tương ứng:
 
 ```
 Sẽ tạo {N} features ({2N} files):
-  ✓ specs/main/feature/F-001-user-registration/frd.md  (4 NEEDS_CLARIFY)
-  ✓ specs/main/feature/F-001-user-registration/fdd.md  (2 NEEDS_CLARIFY)
-  ✓ specs/main/feature/F-002-authentication/frd.md     (1 NEEDS_CLARIFY)
-  ✓ specs/main/feature/F-002-authentication/fdd.md     (0 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-001-user-registration/frd.md  (4 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-001-user-registration/fdd.md  (2 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-002-authentication/frd.md     (1 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-002-authentication/fdd.md     (0 NEEDS_CLARIFY)
   ...
 
 Ghi tất cả? [y] hoặc review từng file trước [r]:
@@ -237,7 +237,7 @@ Ghi tất cả? [y] hoặc review từng file trước [r]:
 
 ### Bước 8: Điền Feature Index vào prd.md
 
-Sau khi artifacts đã được ghi, update `specs/main/prd.md` Feature Index:
+Sau khi artifacts đã được ghi, update `.specs/main/prd.md` Feature Index:
 
 ```
 Sẽ điền Feature Index vào prd.md:
@@ -267,8 +267,8 @@ Khi apply → đồng thời append entry vào `## Change History` của prd.md
 
 ```
 ✓ Generated {N} features:
-  specs/main/feature/F-001-user-registration/  (frd.md + fdd.md)
-  specs/main/feature/F-002-authentication/     (frd.md + fdd.md)
+  .specs/main/feature/F-001-user-registration/  (frd.md + fdd.md)
+  .specs/main/feature/F-002-authentication/     (frd.md + fdd.md)
   ...
 
 ✓ prd.md Feature Index: {N} entries đã được điền
@@ -279,7 +279,7 @@ NEEDS_CLARIFY summary — {total} items:
   ...
 
 Brownfield init hoàn tất! Main artifacts:
-  specs/main/
+  .specs/main/
   ├── prd.md           (Component Index: {N} | Feature Index: {N})
   ├── domain.md        (Glossary: {N} terms | Shared Entities: {N})
   ├── sad.md

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

@@ -7,7 +7,7 @@ description: Khởi tạo main artifacts (prd.md, domain.md, sad.md) cho brownfi
 
 ## Overview
 
-Tạo `specs/main/prd.md`, `specs/main/domain.md`, và `specs/main/sad.md` cho một project đã tồn tại.
+Tạo `.specs/main/prd.md`, `.specs/main/domain.md`, và `.specs/main/sad.md` cho một project đã tồn tại.
 
 Skill này chỉ tập trung vào **product và architecture level** — những gì có thể extract từ README, docs, config, và kiến trúc tổng thể. Component Index và Feature Index trong prd.md sẽ **để trống** — chúng sẽ được điền bởi `/spec-brownfield-component` và `/spec-brownfield-feature` sau khi scan code chuyên sâu.
 
@@ -17,9 +17,9 @@ Mỗi file output được sinh ra từ template tương ứng — đọc templa
 
 | Output file | Template |
 | --- | --- |
-| `specs/main/prd.md` | `templates/main/prd-template.md` |
-| `specs/main/domain.md` | `templates/main/domain-template.md` |
-| `specs/main/sad.md` | `templates/main/sad-template.md` |
+| `.specs/main/prd.md` | `templates/main/prd-template.md` |
+| `.specs/main/domain.md` | `templates/main/domain-template.md` |
+| `.specs/main/sad.md` | `templates/main/sad-template.md` |
 
 Giữ nguyên cấu trúc section và frontmatter từ template. Điền nội dung thu thập được từ scan và interview vào đúng vị trí.
 
@@ -32,7 +32,7 @@ Thông tin không thể detect từ code được đánh dấu nhất quán:
 ## When to Use
 
 - Onboarding một brownfield project vào SDD workflow
-- `specs/main/prd.md` chưa có hoặc còn trống
+- `.specs/main/prd.md` chưa có hoặc còn trống
 
 ## When NOT to Use
 
@@ -63,14 +63,14 @@ Load tất cả attachments trước khi scan. Dùng làm context bổ sung tron
 
 ### Bước 2: Kiểm tra existing specs
 
-Kiểm tra `specs/main/prd.md`, `specs/main/domain.md`, `specs/main/sad.md`:
+Kiểm tra `.specs/main/prd.md`, `.specs/main/domain.md`, `.specs/main/sad.md`:
 
 Nếu một trong ba đã có nội dung thực → cảnh báo:
 
 ```
 ⚠ File đã có nội dung:
-  - specs/main/prd.md
-  - specs/main/sad.md
+  - .specs/main/prd.md
+  - .specs/main/sad.md
 
 Skill này sẽ overwrite các file trên. Tiếp tục? [y/n]
 ```
@@ -253,7 +253,7 @@ Hiển thị draft từng file lần lượt. Với mỗi file:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-DRAFT: specs/main/{file}
+DRAFT: .specs/main/{file}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 {nội dung draft}
 
@@ -270,7 +270,7 @@ Confirm? [y] Bỏ qua [n] Chỉnh sửa [e]:
 
 ### Bước 9: Save
 
-Tạo `specs/main/` nếu chưa có. Ghi các files đã được confirm.
+Tạo `.specs/main/` nếu chưa có. Ghi các files đã được confirm.
 
 **Change History:** Append entry vào section `## Change History` cuối mỗi file vừa ghi (`prd.md`, `domain.md`, `sad.md`) theo `conventions.md` §5.5:
 
@@ -281,9 +281,9 @@ Tạo `specs/main/` nếu chưa có. Ghi các files đã được confirm.
 ```
 
 ```
-✓ specs/main/prd.md        (Component Index và Feature Index: placeholder — chưa có)
-✓ specs/main/domain.md     (Glossary: {n} terms | Shared Entities: trống — sẽ mọc qua cascade)
-✓ specs/main/sad.md
+✓ .specs/main/prd.md        (Component Index và Feature Index: placeholder — chưa có)
+✓ .specs/main/domain.md     (Glossary: {n} terms | Shared Entities: trống — sẽ mọc qua cascade)
+✓ .specs/main/sad.md
 
 NEEDS_CLARIFY summary — {total} items cần làm rõ:
   prd.md:    {n} — [Problem Statement, Business Constraints, ...]

package/skills/spec-frd/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: spec-frd
+description: Author MỚI frd.md (Feature Requirements Document) trực tiếp ở feature level qua interview. Role BA, chạy trước integration. CREATE-only, đúng một feature/lần: frd đã tồn tại → redirect /spec-new (delta cascade); nguồn nhiều feature → redirect /spec-prd. Nhận F-XXX từ argument (hoặc chọn từ prd Feature Index) + tùy chọn nguồn baseline (path/@file/paste). Chỉ author frd.md (+ register feature row vào prd nếu feature mới) — reference component, KHÔNG tạo crd/cdd.
+---
+
+# spec-frd
+
+## Overview
+
+Author `.specs/main/feature/{F-XXX}-{feature-slug}/frd.md` trực tiếp qua interview — **spec-first ở feature level**, do **BA** chạy trước khi bất kỳ integration nào bắt đầu.
+
+`frd.md` là **what to build** của một feature: Overview, User Flows, Feature AC, User Stories, Verification Rules, Scope, Dependencies. Đây là baseline ổn định, **author một lần** — mọi thay đổi sau đó đi qua `/spec-new` (delta cascade).
+
+Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (vốn reverse-engineer frd từ code). Khác biệt: `/spec-frd` author *forward* từ interview, không scan code.
+
+**Hai ràng buộc input (làm chặt):**
+1. **Đúng một feature mỗi lần chạy** — xác định > 1 feature → DỪNG, mô tả rõ lý do, redirect `/spec-prd` (Bước 1a).
+2. **CREATE-only** — frd.md đã tồn tại → DỪNG, redirect `/spec-new` để phân tích delta + cascade + downstream (tech/test) (Bước 1c).
+
+**Phạm vi hẹp — chủ yếu frd.md:**
+- ✅ Author frd.md (7 sections) cho **một** feature **chưa có frd**.
+- ✅ *Reference* component frd phụ thuộc (Components Used) + ghi component cần-nhưng-chưa-có như **candidate**.
+- ✅ Nếu feature mục tiêu là feature mới chưa có trong Index → **register một row vào `prd.md > Features`** (side-effect hợp lệ duy nhất lên prd).
+- ❌ KHÔNG tạo/sửa `crd.md`/`cdd.md` — component artifacts ra đời ở integration time qua `/spec-new` cascade.
+- ❌ KHÔNG tạo `fdd.md` (inter-component design) hay `tsd.md` (test) — để skill/role khác lo.
+- ❌ KHÔNG đổi status feature đã có, không đụng sad/domain.
+
+## When to Use
+
+- Greenfield: BA muốn đặc tả **một feature chưa có frd** *trước* khi DEV bắt đầu integration.
+- `prd.md` đã tồn tại (feature có thể đã trong Index, hoặc là feature mới đơn lẻ → skill offer register vào Index).
+
+## When NOT to Use
+
+- `prd.md` chưa có → chạy `/spec-prd` trước.
+- **frd.md đã tồn tại** (thay đổi feature đã spec) → dùng `/spec-new` (delta cascade + tech/test). `/spec-frd` không update frd.
+- **Nguồn trải nhiều feature** → dùng `/spec-prd` để khai Feature Index trước.
+- Brownfield onboarding (reverse-engineer từ code) → dùng `/spec-brownfield-feature`.
+- Muốn thiết kế technical / inter-component → `/spec-tech` (integration) hoặc fdd qua cascade.
+
+---
+
+## Process
+
+### Bước 0: Nạp nguồn yêu cầu (tùy chọn)
+
+Giống `/spec-prd` Bước 0. Xác định có nguồn baseline cho feature không (proposal, mô tả feature, ghi chú họp, wireframe note):
+
+1. **ARGUMENT chứa path / `@file`** → đọc file đó (`.md`/`.txt`/PDF).
+2. **ARGUMENT chứa text dài (paste)** → dùng làm nguồn.
+3. **Không có** → hỏi một lần:
+   > Bạn có tài liệu/nguồn cho feature này không? Nhập **đường dẫn file**, **paste nội dung**, hoặc `không` để interview từ đầu.
+
+Lưu ý: ARGUMENT thường vừa chứa **F-XXX** (Bước 1) vừa có thể kèm path — tách hai phần. Nếu chỉ có F-XXX thì hỏi nguồn như trên.
+
+Có nguồn → trích baseline cho từng section frd (overview, flows, stories, AC, rules, scope, dependencies). Đá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** giống `/spec-prd`: reuse những gì có; validate; phần thiếu mới hỏi.
+
+---
+
+### Bước 1: Xác định feature
+
+**Precondition:** đọc `.specs/main/prd.md`. Nếu không tồn tại / template rỗng → dừng:
+> `prd.md` chưa có nội dung. Hãy chạy `/spec-prd` trước.
+
+`/spec-frd` là skill **CREATE-only, đúng một feature mỗi lần chạy**. Xác định feature mục tiêu qua ba gate — phải pass cả ba mới vào interview.
+
+#### 1a. Single-feature gate — chỉ liên quan đúng 1 feature
+
+Đánh giá ARGUMENT + nguồn baseline mô tả **bao nhiêu feature riêng biệt** — mỗi feature = một outcome/luồng nghiệp vụ độc lập (dùng litmus test trong `/spec-prd`).
+
+- **Xác định > 1 feature** → **DỪNG** và **mô tả rõ lý do** tại sao là nhiều feature, không chỉ báo chung chung:
+  > Mình xác định nguồn này trải **{N} feature** riêng biệt:
+  >   1. {tên feature A} — outcome: {…}; persona: {…}; luồng: {…}
+  >   2. {tên feature B} — outcome: {…}; persona: {…}; luồng: {…}
+  > Lý do tách: {mỗi cái có outcome/luồng độc lập, không phải biến thể của cùng một luồng — chiếu litmus test}.
+  >
+  > `/spec-frd` chỉ author một feature mỗi lần. Hãy chạy `/spec-prd` để khai {N} feature này vào Feature Index trước, rồi chạy `/spec-frd F-XXX` cho từng cái.
+
+  (Nếu có F-XXX chỉ định nhưng nguồn vẫn trải nhiều feature → vẫn dừng và mô tả lý do; không tự ý cắt phần thuộc F-XXX, vì BA cần thấy bức tranh đầy đủ để khai Index.)
+- **Đúng 1 feature** → tiếp 1b.
+
+#### 1b. Resolve feature mục tiêu
+
+- **F-XXX có trong Feature Index** → dùng.
+- **Feature mới — KHÔNG có trong Index** (đúng một) → **offer register**:
+  > Feature "{tên}" chưa có trong prd Feature Index. Mình sẽ thêm vào Index rồi author frd:
+  >   F-{auto next} | {tên} | {mô tả 1 câu} | {priority?} | TODO
+  > Đồng ý? [y / sửa / n]
+  - `y` → auto-pick `F-XXX` = max(seq)+1 trong Index; **giữ lại để Bước 7 ghi row `[NEW]` vào prd + Change History**.
+  - `n` → dừng, gợi ý `/spec-prd` để khai feature trước.
+- **Không có F-XXX và không có nguồn** → hiển thị Feature Index để chọn (chỉ feature **chưa có frd.md**):
+
+```
+Features chưa có frd.md:
+
+  [1] F-001 — Authentication        (High)    [TODO]
+  [3] F-003 — App Browsing & Opt-in (High)    [TODO]
+
+(F-002 đã có frd.md → thay đổi đi qua /spec-new)
+
+Chọn feature để author frd:
+```
+
+#### 1c. Create-only gate — frd.md CHƯA tồn tại
+
+Kiểm tra `.specs/main/feature/{F-XXX}-*/frd.md`.
+
+- **Chưa tồn tại** → tiếp Bước 2 (author mới).
+- **Đã tồn tại** → **DỪNG**, redirect `/spec-new`:
+  > frd.md cho {F-XXX} đã tồn tại. Mọi thay đổi feature đã được spec phải đi qua `/spec-new` — skill đó phân tích delta, cascade lên frd/crd/prd/domain, và kéo theo việc kỹ thuật/test (`/spec-tech`, `/spec-test`).
+  > Chạy: `/spec-new {F-XXX}` (hoặc `/spec-new <mô tả thay đổi>`).
+
+  `/spec-frd` **không** update frd đã có — giữ một làn ghi delta duy nhất (`/spec-new`) để đảm bảo traceability và downstream không bị bỏ sót.
+
+---
+
+### Bước 2: Load context
+
+Load:
+- `.specs/main/prd.md` — Problem Statement, Target Users (personas), Scope, **row của feature này** trong Feature Index (tên, mô tả, priority), Component Index, **cột ADO** (nếu feature có ticket → lưu lại để spec.md sau này không tạo duplicate).
+- `.specs/main/domain.md` — Glossary + Shared Entities liên quan.
+- `.specs/main/sad.md` — bảng Components (góc nhìn kiến trúc, để biết C-XXX nào đã có boundary).
+- `.specs/main/component/{C-XXX}-*/crd.md` — Public Interface của các component khả năng feature sẽ dùng (nếu đã tồn tại).
+
+Tóm tắt context + surface assumptions:
+
+```
+TỪ PRD & DOMAIN TÔI HIỂU:
+- Feature: {F-XXX — tên — mô tả ngắn từ prd} (priority: {...})
+- Vấn đề tổng: {problem statement ngắn}
+- Personas liên quan: {từ Target Users}
+- Glossary/entities liên quan: {từ domain.md}
+- Components có sẵn có thể dùng: {C-XXX — tên}
+
+ASSUMPTIONS TÔI ĐANG ĐẶT RA:
+1. {scope của feature}
+2. {component feature có thể phụ thuộc}
+→ Sửa lại nếu sai trước khi tiếp tục.
+```
+
+---
+
+### Bước 3: Interview
+
+Hỏi tuần tự, từng phần — không hỏi tất cả cùng lúc. Nếu Bước 0 có nguồn → trình bày baseline đã trích rồi xin confirm/sửa; phần nguồn không đề cập mới hỏi từ đầu.
+
+**Phần 1 — Overview:**
+> Feature này giải quyết vấn đề gì, cho persona nào? (2-3 câu, góc nhìn user/business)
+
+**Phần 2 — User Flows:**
+> User thao tác qua những bước nào để đạt mục tiêu? Có những nhánh edge case / thất bại nào quan trọng?
+> (Mình sẽ vẽ mỗi luồng thành một Mermaid flowchart — happy case + edge cases.)
+
+**Phần 3 — User Stories:**
+> Liệt kê các stories ở cấp feature: "{Persona} muốn {hành động} để {mục tiêu}". Mỗi story có priority (Must/Should/Could) và acceptance criteria (Given/When/Then).
+
+**Phần 4 — Feature Acceptance Criteria:**
+> Có criteria nào áp cho *toàn* feature mà story lẻ không cover? (e2e liên story, cross-story consistency, NFR như performance/accessibility, data & migration)
+> Mỗi cái Given/When/Then, **Then phải đo được**.
+
+**Phần 5 — Verification Rules:**
+> Với mỗi input field trong các stories, mình sẽ suggest 2-4 phương án validation để BA chọn (xem "Verification Rules — quy ước sinh" bên dưới). BA là người quyết định.
+
+**Phần 6 — Scope:**
+> Feature này làm gì (In Scope)? Có gì liên quan nhưng KHÔNG làm (Out of Scope) + lý do?
+
+**Phần 7 — Dependencies:**
+> - **Feature dependencies:** feature này cần feature nào xong trước, hay chạy song song?
+> - **Components Used:** feature này dùng component nào? (Mình sẽ map sang C-XXX có sẵn; component cần-nhưng-chưa-có sẽ ghi như candidate — xem Bước 4.)
+
+Câu trả lời vague → hỏi lại để làm rõ (ngưỡng đo được, field cụ thể, nhánh xử lý).
+
+---
+
+### Bước 4: Xử lý component (mức reference + candidate)
+
+`/spec-frd` **không carve component**. Chỉ làm hai việc:
+
+1. **Component đã có C-XXX** (trong prd Component Index) → ghi vào `Dependencies > Components Used` với vai trò trong feature.
+
+2. **Component feature cần nhưng chưa có** → KHÔNG tạo crd/cdd, KHÔNG tự thêm vào prd Component Index. Thay vào đó:
+   - Ghi trong Components Used với **tên đề xuất** + flag `(candidate — chưa carve)`.
+   - Thêm một mục vào draft **Open Questions** (hoặc note cuối draft) để `/spec-sad`/architect chốt boundary, hoặc `/spec-new` formal-register + tạo crd/cdd ở integration time.
+
+Lý do: giữ **một authority duy nhất** cho việc carve component (architect qua `/spec-sad`, hoặc cascade qua `/spec-new`). BA chỉ khai báo *nhu cầu*, không quyết boundary. (Xem quy tắc Given/Derived trong `/spec-prd`.)
+
+---
+
+### Bước 5: Write — sinh draft
+
+Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền nội dung từ interview.
+
+**ID assignment** (luôn là create — frd mới): US `US-F{NNN}-001+`, Story AC `AC-F{NNN}-001+`, Feature AC `FAC-F{NNN}-001+` (counter độc lập với Story AC), VR `VR-F{NNN}-001+`. `NNN` = số của F-XXX. Flow đánh số từ 1.
+
+**Frontmatter** frd mới: theo template, `status: draft`, `owner: BA`, `feature_id: F-XXX`.
+
+Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm danh sách component candidate (nếu có) và VR còn `TBD`.
+
+#### Verification Rules — quy ước sinh
+
+Áp dụng khi sinh section Verification Rules. **Tái dùng nguyên quy ước của `/spec-new`** (xem [spec-new SKILL.md](../spec-new/SKILL.md) → "Verification Rules — quy ước sinh"). Tóm tắt:
+
+- VR là **business decision — BA owns**. Agent đóng vai **option-suggester**, KHÔNG tự assert rule.
+- Mỗi input field → suggest 2-4 phương án validation + luôn có `Custom` và `TBD`.
+- BA chọn → auto-assign `VR-F{NNN}-{seq}`. `TBD` → vẫn assign ID, ghi `TBD` ở cột Rule, list ra cuối draft.
+- **Cấm:** tự điền rule chưa hỏi BA; đưa regex/validator/error message vào bảng (đó là HOW/UI copy); dùng tech type (`varchar(255)`) thay vì semantic type.
+- Heuristic suggest theo field name: xem bảng trong spec-new.
+
+---
+
+### Bước 6: Review — xác nhận với user
+
+> Draft frd trên đã đúng chưa?
+> - User Flows có cover đủ happy + edge case không?
+> - User Stories + AC đo được chưa?
+> - Verification Rules đã confirm với BA chưa (không còn TBD ngoài ý muốn)?
+> - Components Used đúng chưa? Component candidate (nếu có) có hợp lý để chuyển cho /spec-sad không?
+
+Chỉ ghi file sau khi user confirm. Yêu cầu chỉnh → cập nhật draft → hỏi lại.
+
+---
+
+### Bước 7: Save
+
+**7a. Ghi `.specs/main/feature/{F-XXX}-{slug}/frd.md`** — tạo thư mục nếu chưa có. Status `draft` (lifecycle riêng của artifact).
+
+Slug feature lấy từ tên trong prd Feature Index, kebab-case (ví dụ F-001 "Authentication" → `F-001-authentication`).
+
+**7b. Append Change History entry** vào `## Change History` cuối frd.md — operation = `manual` (author trực tiếp, không qua integration; cùng quy ước với brownfield skills, theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial feature authoring qua /spec-frd
+```
+
+(Luôn là `create` — `/spec-frd` không update frd đã có; thay đổi đi qua `/spec-new`.)
+
+**7b'. (Chỉ khi Bước 1b register feature mới)** Ghi row `[NEW]` vào `prd.md > Features`:
+
+```
+F-{XXX} | {tên} | {mô tả 1 câu} | {priority} | TODO
+```
+
+Và append Change History entry vào prd.md (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Features**:
+  - [NEW] F-XXX — {tên} (registered qua /spec-frd)
+```
+
+Đây là **side-effect hợp lệ duy nhất** của `/spec-frd` lên prd — thêm một feature row. Việc này atomic với 7a/7b: nếu fail thì rollback cả frd.
+
+**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không tạo crd/cdd/fdd/tsd. Không đụng sad/domain.
+
+**7d. Thông báo kết quả:**
+
+```
+✓ .specs/main/feature/{F-XXX}-{slug}/frd.md đã được tạo (status: draft)
+
+{nếu có} Component candidate cần carve (chuyển cho architect / integration):
+  - {tên đề xuất} — {vai trò}
+
+{nếu có} Verification Rules còn TBD:
+  - VR-F{NNN}-{seq} — {field}
+
+Bước tiếp theo:
+  - /spec-tsd F-XXX  → QC bootstrap test spec từ frd này
+  - /spec-new F-XXX  → DEV bắt đầu integration (frd sẽ được consume, crd/cdd sinh qua cascade)
+  {nếu có candidate} - /spec-sad → architect chốt boundary cho component candidate
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Để /spec-new tự đẻ frd cho nhanh" | frd là *feature requirements* — việc của BA. Để integration đẻ ra = DEV phải đoán yêu cầu. |
+| "BA cứ tạo luôn crd cho component cần" | Carve component là quyết định kiến trúc. BA tạo crd sớm = boundary sai sớm. Chỉ reference. |
+| "Verification rule mình tự điền cho nhanh" | VR là business decision. Agent tự assert = rule sai mà không ai review. |
+| "User Flows vẽ sau cũng được" | Flow buộc phải nghĩ edge case. Không có flow = AC thiếu nhánh thất bại. |
+
+## Red Flags
+
+- frd dùng từ không đo được trong AC ("hoạt động đúng", "nhanh", "đẹp")
+- User Stories không có persona rõ hoặc không có AC
+- Verification Rules tự điền mà chưa hỏi BA
+- Tạo crd.md/cdd.md (vượt phạm vi — đó là integration time)
+- Component candidate không được surface cho architect
+- **Update frd đã tồn tại** thay vì redirect `/spec-new` (vi phạm CREATE-only)
+- Cắt phần thuộc một F-XXX từ nguồn nhiều feature thay vì dừng + mô tả lý do
+
+## Verification
+
+- [ ] `prd.md` tồn tại
+- [ ] **Single-feature gate**: nguồn liên quan đúng 1 feature; nếu >1 đã DỪNG và mô tả rõ lý do tách + redirect `/spec-prd`
+- [ ] **Create-only gate**: frd.md của feature mục tiêu CHƯA tồn tại; nếu đã có đã redirect `/spec-new`
+- [ ] Feature mục tiêu có trong Index, HOẶC feature mới đơn lẻ đã được user đồng ý register (Bước 1b)
+- [ ] frd.md có đủ 7 sections (luôn create mới)
+- [ ] Mỗi User Story có persona + priority + ít nhất 1 AC Given/When/Then
+- [ ] Feature AC dùng ID `FAC-F{NNN}-{seq}` (counter độc lập với `AC-F{NNN}`), Then đo được
+- [ ] Verification Rules đã confirm với BA (không tự assert); không chứa regex/code/error message; semantic type
+- [ ] ID bắt đầu từ 001 (create mới)
+- [ ] Components Used reference C-XXX có sẵn; component mới ghi candidate + surface cho /spec-sad
+- [ ] Nếu register feature mới: prd Features có row [NEW] + Change History entry; status feature đã có KHÔNG đổi
+- [ ] KHÔNG tạo crd/cdd/fdd/tsd; KHÔNG đụng sad/domain
+- [ ] Change History entry operation = `manual` (luôn `create`)
+- [ ] User đã confirm trước khi ghi file

package/skills/spec-frd-update/SKILL.md

@@ -7,7 +7,7 @@ description: Migrate frd.md hiện có lên cấu trúc template mới nhất
 
 ## Overview
 
-Migrate các file `specs/main/feature/{F-XXX}-{slug}/frd.md` hiện có sang **format mới nhất** của [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md).
+Migrate các file `.specs/main/feature/{F-XXX}-{slug}/frd.md` hiện có sang **format mới nhất** của [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md).
 
 Skill này **chỉ làm migration mechanical + propose** — không phải BA interview. Mọi quyết định nội dung mới (Verification Rules content) đều cần user approve trước khi ghi.
 
@@ -67,7 +67,7 @@ Chạy `git status --porcelain`. Nếu output không rỗng (có file modified /
 Hãy commit hoặc stash thay đổi hiện tại trước khi chạy `/spec-frd-update`, rồi chạy lại.
 
 Files dirty:
-  M specs/main/feature/F-001-auth/frd.md
+  M .specs/main/feature/F-001-auth/frd.md
   ?? notes.md
 ```
 
@@ -80,7 +80,7 @@ Nếu repo không phải git repo → cảnh báo và yêu cầu confirm:
 
 ### Bước 1: Discover & classify
 
-Quét `specs/main/feature/*/frd.md`. Với mỗi file:
+Quét `.specs/main/feature/*/frd.md`. Với mỗi file:
 
 1. Parse headings và frontmatter.
 2. Run detection cho V1–V8.
@@ -123,11 +123,11 @@ Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết
 
 | File | Bắt buộc | Mục đích |
 |---|---|---|
-| `specs/main/feature/{F-XXX}-{slug}/frd.md` | ✓ | File cần migrate |
+| `.specs/main/feature/{F-XXX}-{slug}/frd.md` | ✓ | File cần migrate |
 | [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md) | ✓ | Target structure — copy text cho V2/V3/V5 |
-| `specs/main/feature/{F-XXX}-{slug}/fdd.md` | nếu tồn tại | Cascade target cho V4 (AC→FAC rename) |
-| `specs/main/feature/{F-XXX}-{slug}/tsd.md` | nếu tồn tại | Cascade target cho V4 |
-| `specs/main/domain.md` (Shared Entities block) | optional | Cho V6 — match field name với entity glossary để pick semantic type consistent |
+| `.specs/main/feature/{F-XXX}-{slug}/fdd.md` | nếu tồn tại | Cascade target cho V4 (AC→FAC rename) |
+| `.specs/main/feature/{F-XXX}-{slug}/tsd.md` | nếu tồn tại | Cascade target cho V4 |
+| `.specs/main/domain.md` (Shared Entities block) | optional | Cho V6 — match field name với entity glossary để pick semantic type consistent |
 
 **KHÔNG load:**
 - `conventions.md` — template đã self-contained, load là thừa
@@ -183,7 +183,7 @@ Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết
   ```
 
 #### 4.3 Scan cascade references
-- Grep toàn `specs/` cho từng ID cũ.
+- Grep toàn `.specs/` cho từng ID cũ.
 - **CRITICAL**: chỉ remap những match THUỘC Feature AC (Bước 4.1 list). KHÔNG đụng Story AC trùng namespace `AC-F{NNN}-{seq}` — đây là string overlap nhưng khác counter.
 - Tạo bảng impact:
   ```
@@ -358,7 +358,7 @@ Cho mỗi FRD đã migrate:
 
 Nếu artifact chưa có section `## Change History` (vì template cũ) → tạo section mới ở cuối file rồi append entry. Đây cũng là một migration vector ngầm — đảm bảo mọi main artifact sau migration đều có Change History section.
 
-Rollback (nếu user phát hiện sai sau khi skill xong): `git checkout -- specs/main/feature/{F-XXX}-{slug}/` để revert toàn bộ feature dir, hoặc `git restore -p` để revert per-hunk.
+Rollback (nếu user phát hiện sai sau khi skill xong): `git checkout -- .specs/main/feature/{F-XXX}-{slug}/` để revert toàn bộ feature dir, hoặc `git restore -p` để revert per-hunk.
 
 Append vào [changelogs.md](../../changelogs.md) `## [Unreleased]`:
 

package/skills/spec-new/SKILL.md

@@ -7,7 +7,7 @@ description: Tạo spec.md cho một integration mới thông qua interview có
 
 ## Overview
 
-Tạo `spec.md` cho một integration mới trong `specs/integrations/{NNN}-{slug}/`.
+Tạo `spec.md` cho một integration mới trong `.specs/integrations/{NNN}-{slug}/`.
 
 `spec.md` là functional spec — định nghĩa **what to build**: vấn đề, requirements, acceptance criteria, out of scope. Không chứa technical design.
 
@@ -33,7 +33,7 @@ Tạo `spec.md` cho một integration mới trong `specs/integrations/{NNN}-{slu
 
 **Nếu không có ARGUMENT:**
 
-Đọc `specs/main/prd.md`. Nếu file không tồn tại hoặc là template rỗng → dừng:
+Đọc `.specs/main/prd.md`. Nếu file không tồn tại hoặc là template rỗng → dừng:
 > `prd.md` chưa có nội dung. Hãy chạy `/spec-prd` trước.
 
 Đọc toàn bộ bảng Features. Hiển thị **tất cả** features kèm trạng thái — không lọc — để thấy rõ feature nào có FRD cần update:
@@ -50,7 +50,7 @@ Features trong PRD:
 Chọn số feature để bắt đầu spec:
 ```
 
-Ghi chú `→ frd.md tồn tại` nếu file `specs/main/feature/{F-XXX}-*/frd.md` đã có.
+Ghi chú `→ frd.md tồn tại` nếu file `.specs/main/feature/{F-XXX}-*/frd.md` đã có.
 
 Nếu tất cả features đều Done → thông báo:
 > Tất cả features trong prd.md đã được implement. Nếu có yêu cầu mới, hãy truyền nó trực tiếp: `/spec-new <yêu cầu>`.
@@ -88,10 +88,10 @@ Lưu lại lựa chọn section.
 
 Từ raw requirement, agent xác định features và components liên quan, rồi load các file sau:
 
-- `specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index; **đặc biệt ghi nhận cột `ADO` trong bảng Features** — nếu feature đã có ticket ID thì lưu lại `{feature_id → ado_ticket_id, ado_ticket_title, ado_ticket_url}`
-- `specs/main/domain.md` — đọc Glossary và Shared Entities
-- `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature liên quan (nếu file đã tồn tại)
-- `specs/main/component/{C-XXX}-{slug}/crd.md` — cho mỗi component bị touched (nếu file đã tồn tại)
+- `.specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index; **đặc biệt ghi nhận cột `ADO` trong bảng Features** — nếu feature đã có ticket ID thì lưu lại `{feature_id → ado_ticket_id, ado_ticket_title, ado_ticket_url}`
+- `.specs/main/domain.md` — đọc Glossary và Shared Entities
+- `.specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature liên quan (nếu file đã tồn tại)
+- `.specs/main/component/{C-XXX}-{slug}/crd.md` — cho mỗi component bị touched (nếu file đã tồn tại)
 
 Tóm tắt context và surface assumptions:
 
@@ -150,11 +150,11 @@ Từ title của integration, sinh slug:
 - Nếu từ prd.md: dùng `{feature-id}-{feature-slug}`, ví dụ: `f001-authentication`
 
 Xác định số thứ tự (`NNN`):
-- Liệt kê các thư mục hiện có trong `specs/integrations/` theo pattern `{NNN}-*`
+- Liệt kê các thư mục hiện có trong `.specs/integrations/` theo pattern `{NNN}-*`
 - Lấy số lớn nhất hiện có và cộng thêm 1, format 3 chữ số (ví dụ: `001`, `002`, `012`)
 - Nếu chưa có thư mục nào → bắt đầu từ `001`
 
-Output path: `specs/integrations/{NNN}-{slug}/spec.md`
+Output path: `.specs/integrations/{NNN}-{slug}/spec.md`
 
 ---
 
@@ -339,7 +339,7 @@ Chỉ tiến hành Bước 7 sau khi user confirm. Nếu user yêu cầu chỉnh
 
 ### Bước 7: Save + Auto-cascade
 
-Tạo thư mục `specs/integrations/{NNN}-{slug}/` nếu chưa có.
+Tạo thư mục `.specs/integrations/{NNN}-{slug}/` nếu chưa có.
 
 **[7.1] Ghi spec.md** với status `approved` (không phải `draft` — human đã confirm ở Bước 6 chính là approval). Frontmatter `features` và `components` phải được điền theo những gì đã nhận diện ở Bước 2.
 
@@ -391,7 +391,7 @@ Cho mỗi artifact:
 **[7.4] Thông báo kết quả:**
 
 ```
-✓ specs/integrations/{NNN}-{slug}/spec.md đã được tạo (status: approved)
+✓ .specs/integrations/{NNN}-{slug}/spec.md đã được tạo (status: approved)
 
 Auto-cascade applied:
   ✓ prd.md — {summary}