spec-lite 1.5.0 → 1.5.2

package/README.md

@@ -151,13 +151,13 @@ Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Criti
 
 Skill ad-hoc dùng khi template đã được update và artifacts hiện có cần migrate. Không phải pipeline — chạy khi cần.
 
-Mỗi template mang `template_version` (số nguyên) trong frontmatter; artifact copy nó lúc được tạo. Khi template đổi structure, artifact cũ thành "lỗi thời" — hai skill dưới phát hiện và migrate. Quy ước đầy đủ: [conventions.md](conventions.md) §7.
+Mỗi **main** template mang `template_version` (số nguyên) trong frontmatter; main artifact copy nó lúc được tạo. Khi template đổi structure, main artifact cũ thành "lỗi thời" — hai skill dưới phát hiện và migrate. **Chỉ áp dụng cho main artifacts** (integration artifacts ephemeral nên không versioned). Quy ước đầy đủ: [conventions.md](conventions.md) §7.
 
 #### `/artifact-audit [type]`
-Phát hiện artifact lỗi thời. So `template_version` của artifact với version đọc thẳng từ template. Versioned: `==` → up-to-date; `!=` → out-dated `(vX → vY)` → migrate. Legacy thiếu version → presence-check (đủ required `##` headings + không còn section đã `migrations.remove`): conform → stamp version; lệch → out-dated. Chỉ phát hiện + stamp, KHÔNG migrate. Scope theo arg (1 type / list) hoặc toàn bộ.
+Phát hiện **main artifact** lỗi thời. So `template_version` của artifact với version đọc thẳng từ template. Versioned: `==` → up-to-date; `!=` → out-dated `(vX → vY)` → migrate. Legacy thiếu version → presence-check (đủ required `##` headings + không còn section đã `migrations.remove`): conform → stamp version; lệch → out-dated. Chỉ phát hiện + stamp, KHÔNG migrate. Scope theo arg (1 main type / list) hoặc mọi main type.
 
 #### `/artifact-migrate [path]`
-Migrate artifact lỗi thời lên structure mới (generic mọi type). Tự chạy `/artifact-audit` (classify-only) để phát hiện, rồi áp delta từ block `migrations` của template: **add** required section thiếu (skeleton từ template; nội dung mới → interview hoặc `NEEDS_CLARIFY`, không bịa), **remove** section đã `migrations.remove` (có confirm; giữ content tác giả khác), **update** section đổi format (giữ section + ngữ nghĩa, vd ASCII → Mermaid; show cũ + đề xuất mới, không bịa). Rename = remove+add → hỏi carry-over. Single-artifact, không cascade. Pre-flight git clean — rollback dùng git, không `.bak`. No-op nếu đã up-to-date.
+Migrate **main artifact** lỗi thời lên structure mới (mọi main type). Tự chạy `/artifact-audit` (classify-only) để phát hiện, rồi áp delta từ block `migrations` của template: **add** required section thiếu (skeleton từ template; nội dung mới → interview hoặc `NEEDS_CLARIFY`, không bịa), **remove** section đã `migrations.remove` (có confirm; giữ content tác giả khác), **update** section đổi format (giữ section + ngữ nghĩa, vd ASCII → Mermaid; show cũ + đề xuất mới, không bịa). Rename = remove+add → hỏi carry-over. Single-artifact, không cascade. Pre-flight git clean — rollback dùng git, không `.bak`. No-op nếu đã up-to-date.
 
 ---
 
@@ -172,8 +172,8 @@ Migrate artifact lỗi thời lên structure mới (generic mọi type). Tự ch
 | `/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` |
-| `/artifact-audit` | *(báo cáo out-dated; + stamp `template_version` cho artifact legacy conform)* |
-| `/artifact-migrate` | *(modify in-place artifact lỗi thời lên structure mới + set `template_version`)* |
+| `/artifact-audit` | *(báo cáo out-dated; + stamp `template_version` cho main artifact legacy conform)* |
+| `/artifact-migrate` | *(modify in-place main artifact lỗi thời lên structure mới + set `template_version`)* |
 | `/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` |

package/package.json

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

package/skills/artifact-audit/SKILL.md

@@ -1,26 +1,28 @@
 ---
 name: artifact-audit
-description: Audit artifacts trong .specs/ xem có lỗi thời so với template không. So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều type làm scope (vd `frd`, `frd,spec`); không có arg → audit mọi type.
+description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so với template không (chỉ main artifacts — prd/domain/sad/frd/fdd/tsd/crd/cdd; integration artifacts ngoài scope). So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều main type làm scope (vd `frd`, `frd,crd`); không có arg → audit mọi main type.
 ---
 
 # artifact-audit
 
 ## Overview
 
-Trả lời một câu hỏi: **artifact nào trong `.specs/` đã lỗi thời so với template mới nhất?**
+Trả lời một câu hỏi: **main artifact nào trong `.specs/main/` đã lỗi thời so với template mới nhất?**
+
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `tsd`, `crd`, `cdd` — đều nằm dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt` dưới `.specs/integrations/`) **không** thuộc scope của skill này — chúng là ephemeral và immutable sau khi `done`, không audit/migrate theo version.
 
 Cơ chế (xem `conventions.md` §7 Template Versioning):
 - **Nguồn sự thật** = `template_version` trong frontmatter template đang cài (`.claude/templates/...`). Đọc thẳng lúc chạy — không manifest, không cache.
 - Mỗi artifact mang `template_version` (copy lúc CREATE bởi skill sinh nó). Audit so số artifact với số template.
 
-Skill này **chỉ phát hiện + stamp legacy**, **KHÔNG migrate**. Việc đưa structure artifact lên format mới là của `/artifact-migrate` (generic cho mọi type).
+Skill này **chỉ phát hiện + stamp legacy**, **KHÔNG migrate**. Việc đưa structure artifact lên format mới là của `/artifact-migrate` (cho mọi main type).
 
 ## When to Use
 
 - Sau khi `git pull` kit mới (template có thể đã bump version) → xem artifact nào cần migrate.
-- Audit định kỳ một type cụ thể (`/artifact-audit frd`) hoặc toàn repo (`/artifact-audit`).
-- Sau khi bump `template_version` của một template → tìm mọi artifact giờ thành `out-dated`.
-- Onboarding repo cũ → stamp version cho artifact legacy khớp structure, lọc ra cái cần migrate.
+- Audit định kỳ một main type cụ thể (`/artifact-audit frd`) hoặc mọi main type (`/artifact-audit`).
+- Sau khi bump `template_version` của một template → tìm mọi main artifact giờ thành `out-dated`.
+- Onboarding repo cũ → stamp version cho main artifact legacy khớp structure, lọc ra cái cần migrate.
 
 ## When NOT to Use
 
@@ -32,7 +34,7 @@ Skill này **chỉ phát hiện + stamp legacy**, **KHÔNG migrate**. Việc đ
 
 ## Type → template map
 
-Type của artifact resolve theo **filename** (integration artifact không có field `type` trong frontmatter). Mỗi type map tới đúng một template:
+Type của main artifact resolve theo **filename**. Mỗi type map tới đúng một template:
 
 | Filename | type | Template (`.claude/templates/...`) |
 | --- | --- | --- |
@@ -44,14 +46,8 @@ Type của artifact resolve theo **filename** (integration artifact không có f
 | `tsd.md` | tsd | `main/feature/tsd-template.md` |
 | `crd.md` | crd | `main/component/crd-template.md` |
 | `cdd.md` | cdd | `main/component/cdd-template.md` |
-| `spec.md` | spec | `integrations/spec-template.md` |
-| `tech.md` | tech | `integrations/tech-template.md` |
-| `test.md` | test | `integrations/test-template.md` |
-| `plan.md` | plan | `integrations/plan-template.md` |
-| `todo.md` | todo | `integrations/todo-template.md` |
-| `techdebt.md` | techdebt | `integrations/techdebt-template.md` |
 
-File không khớp bảng (vd `notes.md`, `*.bak`) → bỏ qua, không phải artifact có template.
+**Chỉ main artifacts.** Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — gặp file integration thì bỏ qua. File không khớp bảng (vd `notes.md`, `*.bak`) → cũng bỏ qua.
 
 ---
 
@@ -59,8 +55,8 @@ File không khớp bảng (vd `notes.md`, `*.bak`) → bỏ qua, không phải a
 
 ### Bước 0: Resolve scope
 
-- **ARGUMENT là 1 type hoặc list** (vd `frd`, `frd,spec,tech`) → chỉ audit các type đó. Type lạ (không có trong map) → cảnh báo và bỏ qua type đó.
-- **Không có ARGUMENT** → audit **mọi** type trong map.
+- **ARGUMENT là 1 main type hoặc list** (vd `frd`, `frd,crd`) → chỉ audit các type đó. Type lạ hoặc type integration (`spec`/`tech`/`test`/`plan`/`todo`/`techdebt`, không có trong map) → cảnh báo và bỏ qua type đó.
+- **Không có ARGUMENT** → audit **mọi** main type trong map.
 
 ### Bước 1: Đọc current version của template
 
@@ -73,13 +69,11 @@ Lưu bảng `currentVersion[type]`.
 
 ### Bước 2: Discover artifacts
 
-Quét artifacts trong:
-- `.specs/main/**` (prd, domain, sad, và feature/component artifacts)
-- `.specs/integrations/**` (spec, tech, test, plan, todo, techdebt)
+Quét **chỉ** main artifacts trong `.specs/main/**` (prd, domain, sad, và feature/component artifacts).
 
-**Bỏ qua** (đã đóng băng — không audit/migrate):
+**Bỏ qua:**
+- Toàn bộ `.specs/integrations/**` — integration artifacts ngoài scope skill này (ephemeral + immutable sau `done`; không audit/migrate theo version).
 - `.specs/archive/**`, `.specs/removed/**`, file `*.bak.*`, file không khớp type map.
-- **Integration folder đã `done`**: nếu `.specs/integrations/{X}/spec.md` có `status: done` → bỏ qua **toàn bộ folder đó** (spec/tech/test/plan/todo/techdebt). Integration artifacts là **immutable sau khi done** (conventions §7 Versioning) — không migrate record bất biến. Folder integration đang active (spec chưa `done`) và mọi **main artifact** thì vẫn audit/migrate bình thường.
 
 Với mỗi file khớp: resolve type theo filename, đọc frontmatter để lấy `template_version` (có thể thiếu).
 
@@ -140,8 +134,8 @@ In bảng phân nhóm (xem Output Format). Skill **không** migrate, **không**
 ## Output Format
 
 ```
-ARTIFACT AUDIT — scope: {all | frd, spec}
-Current template versions: prd v1 · domain v1 · sad v1 · frd v2 · spec v1 · ...
+ARTIFACT AUDIT — scope: {all main | frd, crd}
+Current template versions: prd v1 · domain v1 · sad v1 · frd v2 · crd v1 · ...
 
 OUT-DATED ({n}) — cần migrate:
   feature/F-002-payment/frd.md       frd    v1 → v2   → /artifact-migrate
@@ -149,7 +143,7 @@ OUT-DATED ({n}) — cần migrate:
 
 STAMPED ({n}) — legacy khớp structure, vừa ghi template_version:
   feature/F-001-auth/frd.md          frd    → v2
-  integrations/001-checkout/spec.md  spec   → v1
+  component/C-001-core/crd.md        crd    → v1
 
 UP-TO-DATE ({n}): {đếm, liệt kê path ngắn gọn hoặc gập lại nếu nhiều}
 
@@ -173,14 +167,14 @@ Bước tiếp theo (nếu có out-dated):
 - Stamp `template_version` cho artifact mà chưa đối chiếu structure với template.
 - Tự sửa structure / nội dung artifact (vượt phạm vi — đó là migration skill).
 - Flag out-dated chỉ vì artifact có thêm sub-section / nội dung ngoài template (thừa ≠ lỗi thời; chỉ thiếu/đổi-tên/đổi-format mới tính).
-- Audit/stamp artifact đóng băng: `.specs/archive/`, `.specs/removed/`, hoặc integration folder có spec.md `status: done` (immutable record — bỏ qua).
+- Audit/stamp artifact ngoài scope: bất kỳ file nào trong `.specs/integrations/` (integration artifacts ngoài scope), `.specs/archive/`, `.specs/removed/` — bỏ qua hết.
 - Đọc version từ một manifest/cache thay vì đọc thẳng frontmatter template.
 
 ## Verification
 
-- [ ] Scope resolve đúng từ argument (1 type / list / mọi type)
+- [ ] Scope = **chỉ main artifacts** (`.specs/main/**`); resolve đúng từ argument (1 main type / list / mọi main type)
 - [ ] Current version đọc thẳng từ frontmatter template tại `.claude/templates/...` (không manifest)
-- [ ] Bỏ qua `.specs/archive/`, `.specs/removed/`, `*.bak.*`, file không khớp type map, và integration folder có spec.md `status: done`
+- [ ] Bỏ qua toàn bộ `.specs/integrations/`, `.specs/archive/`, `.specs/removed/`, `*.bak.*`, và file không khớp type map
 - [ ] Versioned: `==` → up-to-date; `!=` → out-dated `(vX → vY)` → migrate
 - [ ] Unversioned: conformance là quan hệ bao hàm (artifact chứa đủ structure bắt buộc; thừa sub-section/nội dung không khai báo remove KHÔNG phải lỗi thời); 2 dấu hiệu out-dated = thiếu required heading / section `migrations.remove` còn sót
 - [ ] Conform → stamp; out-dated → tóm tắt đúng dấu hiệu (thiếu required heading gì / section deprecated nào còn sót). Lưu ý: presence-check KHÔNG bắt format-update (blind spot unversioned)

package/skills/artifact-migrate/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: artifact-migrate
-description: Migrate artifact trong .specs/ lên structure template mới nhất. Generic cho mọi type. Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 artifact (path); không có arg → quét toàn bộ, migrate từng cái có confirm + skip.
+description: Migrate MAIN artifact trong .specs/main/ lên structure template mới nhất (chỉ main artifacts — prd/domain/sad/frd/fdd/tsd/crd/cdd; integration artifacts ngoài scope). Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 main artifact (path); không có arg → quét mọi main artifact, migrate từng cái có confirm + skip.
 ---
 
 # artifact-migrate
 
 ## Overview
 
-Đưa một artifact (hoặc toàn bộ) **lỗi thời** lên đúng structure của template mới nhất, rồi cập nhật `template_version`. Đây là vế **fix** đối xứng với `/artifact-audit` (vế **detect**).
+Đưa một main artifact (hoặc toàn bộ main artifacts) **lỗi thời** lên đúng structure của template mới nhất, rồi cập nhật `template_version`. Đây là vế **fix** đối xứng với `/artifact-audit` (vế **detect**).
+
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `tsd`, `crd`, `cdd` — đều dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — ephemeral + immutable sau `done`, không migrate theo version.
 
 Cơ chế (xem `conventions.md` §7 Template Versioning):
 - **Required section hiện tại** = body `##` headings của template (deterministic theo level; `###` = instance).
@@ -30,11 +32,11 @@ Cơ chế (xem `conventions.md` §7 Template Versioning):
 
 ## Type → template map
 
-Resolve type theo **filename** (giống `/artifact-audit` — integration artifact không có field `type`). Mỗi type map tới đúng một template tại `.claude/templates/...`:
+Resolve type của main artifact theo **filename** (giống `/artifact-audit`). Mỗi type map tới đúng một template tại `.claude/templates/...`:
 
-`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `tsd.md`→`main/feature/tsd-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md` · `spec.md`→`integrations/spec-template.md` · `tech.md`→`integrations/tech-template.md` · `test.md`→`integrations/test-template.md` · `plan.md`→`integrations/plan-template.md` · `todo.md`→`integrations/todo-template.md` · `techdebt.md`→`integrations/techdebt-template.md`
+`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `tsd.md`→`main/feature/tsd-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md`
 
-File không khớp map → bỏ qua.
+**Chỉ main artifacts.** Integration artifacts (`spec`/`tech`/`test`/`plan`/`todo`/`techdebt`) ngoài scope → bỏ qua. File không khớp map → cũng bỏ qua.
 
 ---
 
@@ -42,8 +44,8 @@ File không khớp map → bỏ qua.
 
 ### Bước 0: Resolve scope
 
-- **ARGUMENT là path tới 1 artifact** → migrate riêng nó. Nếu artifact thuộc integration folder đã `done` (spec.md `status: done`) hoặc nằm trong `.specs/archive`/`.specs/removed` → **DỪNG**, báo "artifact đóng băng (immutable record) — không migrate".
-- **Không có ARGUMENT** → quét `.specs/main/**` + `.specs/integrations/**`, áp **đúng skip list của `/artifact-audit`** (bỏ archive/removed, `*.bak.*`, và **integration folder có spec.md `status: done`**).
+- **ARGUMENT là path tới 1 main artifact** → migrate riêng nó. Nếu path là integration artifact (`.specs/integrations/...`) → **DỪNG**, báo "integration artifact ngoài scope — chỉ migrate main artifacts". Nếu nằm trong `.specs/archive`/`.specs/removed` → **DỪNG**, báo "artifact đóng băng (immutable record) — không migrate".
+- **Không có ARGUMENT** → quét **chỉ** `.specs/main/**`, áp **đúng skip list của `/artifact-audit`** (bỏ toàn bộ `.specs/integrations/`, archive/removed, `*.bak.*`).
 
 ### Bước 1: Pre-flight — working tree clean
 
@@ -94,7 +96,7 @@ User confirm (toàn bộ / từng item / skip artifact). **Section nội dung m
 - Áp UPDATE format: thay nội dung section bằng bản chuyển format đã confirm (giữ section + ngữ nghĩa).
 - **Giữ nguyên** mọi sub-section / content tác giả **không nằm trong `remove`/`update`** (superset rule).
 - Set frontmatter `template_version` = current.
-- Nếu template có `## Change History` (main artifact) → append entry, operation = `manual`:
+- Main artifact có `## Change History` ở cuối → append entry, operation = `manual`:
   ```markdown
   ### {YYYY-MM-DD} — manual — migrate
 
@@ -138,12 +140,13 @@ SKIPPED / up-to-date ({n})
 - Xóa section không nằm trong `migrations.remove` (vi phạm superset).
 - Tự remap ID / đụng tới artifact khác (migrate là single-artifact, không cascade).
 - Chạy khi working tree dirty (mất đường rollback).
-- Migrate artifact đóng băng: integration folder đã `done`, `.specs/archive`, `.specs/removed` (immutable record — phải skip).
+- Migrate artifact ngoài scope: bất kỳ file nào trong `.specs/integrations/` (integration artifacts ngoài scope), `.specs/archive`, `.specs/removed` (phải skip / DỪNG).
 - Migrate artifact đã up-to-date (phải no-op sớm).
 - Tự cài lại logic detect thay vì dùng audit classify-only.
 
 ## Verification
 
+- [ ] Scope = **chỉ main artifacts** (`.specs/main/**`); arg là integration artifact → DỪNG, no-arg chỉ quét `.specs/main/**`
 - [ ] Pre-flight: working tree clean (hoặc user confirm khi không phải git repo)
 - [ ] Detect bằng `/artifact-audit` classify-only, scoped theo target; version `==` → up-to-date → no-op sớm; `!=` → migrate
 - [ ] Required `##` thiếu → ADD (skeleton từ body template); section `migrations.remove` còn sót → REMOVE (confirm)

package/skills/plan/SKILL.md

@@ -118,7 +118,7 @@ Invoke `planning-and-task-breakdown` với context đã load. Skill đó sẽ th
 
 ### plan.md
 
-Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền nội dung từ breakdown vào từng section. Frontmatter lấy `template_version` từ template (xem `conventions.md` §7).
+Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền nội dung từ breakdown vào từng section. Frontmatter copy từ template (plan.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, xem `conventions.md` §7).
 
 **Lưu ý format:**
 - Task ID dùng `·` (middle dot), không dùng `—`
@@ -128,7 +128,7 @@ Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền n
 
 ### todo.md
 
-Dùng `.claude/templates/integrations/todo-template.md` làm skeleton, điền nội dung từ breakdown vào từng section. Frontmatter lấy `template_version` từ template.
+Dùng `.claude/templates/integrations/todo-template.md` làm skeleton, điền nội dung từ breakdown vào từng section. Frontmatter copy từ template (todo.md là integration artifact — không mang `template_version`).
 
 ---
 
@@ -146,4 +146,4 @@ Nếu trong quá trình breakdown phát hiện delta cần cập nhật `sad.md`
 - [ ] plan.md có section **Dependency Graph**
 - [ ] Mỗi task có đủ: Mục tiêu / depends / Các bước / Verification
 - [ ] Không viết code trong suốt quá trình
-- [ ] plan.md + todo.md có `template_version` copy từ template tương ứng
+- [ ] plan.md + todo.md (integration) KHÔNG mang `template_version` (versioning chỉ cho main artifacts)

package/skills/spec-frd/SKILL.md

@@ -43,6 +43,31 @@ Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (
 
 ## Process
 
+### Pre-flight: chuẩn bị nhánh Git (chạy TRƯỚC Bước 0)
+
+Mục tiêu: không bao giờ author frd ngay trên nhánh hiện tại của user (có thể là một nhánh đang làm dở) — luôn bắt đầu từ **nhánh chính mới nhất** rồi tách một **nhánh làm việc riêng**.
+
+**Trước tiên, thông báo cho user toàn bộ việc Git skill sẽ làm** (để user biết trước, đúng tinh thần "agent làm các việc này"):
+
+> Trước khi author frd, mình sẽ:
+> 1. Pull code mới nhất từ nhánh chính (`{main}`).
+> 2. Tạo & checkout một nhánh mới tách từ `{main}` để làm việc.
+>
+> (Bạn đang ở nhánh `{current}`.)
+
+**1. Xác định nhánh chính (`{main}`).**
+- Không phải git repo → bỏ qua toàn bộ pre-flight, note cho user rồi tiếp Bước 0.
+- Có nhánh `develop` → mặc định `{main}` = `develop`. Không có `develop` nhưng có `main`/`master` → dùng nó.
+- Mơ hồ (tồn tại cả `develop` lẫn `main`, hoặc remote default khác) → **hỏi user** nhánh nào là nhánh chính. KHÔNG đoán.
+
+**2. Kiểm tra working tree sạch.** `git status` còn thay đổi chưa commit → **DỪNG**, báo user commit/stash trước. KHÔNG tự ý stash/discard.
+
+**3. Checkout + pull nhánh chính:** `git checkout {main}` rồi `git pull`. Pull fail (conflict, không có upstream…) → **DỪNG**, surface lỗi cụ thể, để user xử lý.
+
+**4. Tạo nhánh làm việc mới off `{main}`.** Cần slug để đặt tên → thực hiện **ngay sau khi xác định feature mục tiêu ở Bước 1c** (xem nhắc ở đó): đề xuất `git checkout -b spec/{F-XXX}-{slug}`, cho user sửa tên rồi tạo. Mọi việc author/cascade từ Bước 2 trở đi diễn ra trên nhánh này.
+
+---
+
 ### 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):
@@ -106,7 +131,7 @@ Chọn feature để author frd:
 
 Kiểm tra `.specs/main/feature/{F-XXX}-*/frd.md`.
 
-- **Chưa tồn tại** → tiếp Bước 2 (author mới).
+- **Chưa tồn tại** → **tạo nhánh làm việc** (Pre-flight bước 4): `git checkout -b spec/{F-XXX}-{slug}` off `{main}` (đề xuất tên, cho user sửa), rồ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>`).
@@ -355,6 +380,7 @@ Bước tiếp theo:
 
 ## Verification
 
+- [ ] **Pre-flight Git**: đã thông báo plan cho user; xác định đúng nhánh chính (hỏi nếu mơ hồ); working tree sạch; đã `checkout {main}` + `pull`; tạo nhánh làm việc mới off `{main}` trước khi author
 - [ ] `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`

package/skills/spec-new/SKILL.md

@@ -27,6 +27,31 @@ Tạo `spec.md` cho một integration mới trong `.specs/integrations/{NNN}-{sl
 
 ## Process
 
+### Bước 0 · Pre-flight: chuẩn bị nhánh Git (chạy TRƯỚC Bước 1)
+
+Mục tiêu: không bao giờ tạo spec/cascade ngay trên nhánh hiện tại của user (có thể là một nhánh đang làm dở) — luôn bắt đầu từ **nhánh chính mới nhất** rồi tách một **nhánh làm việc riêng** cho integration.
+
+**Trước tiên, thông báo cho user toàn bộ việc Git skill sẽ làm** (để user biết trước, đúng tinh thần "agent làm các việc này"):
+
+> Trước khi tạo spec, mình sẽ:
+> 1. Pull code mới nhất từ nhánh chính (`{main}`).
+> 2. Tạo & checkout một nhánh mới tách từ `{main}` để làm integration này.
+>
+> (Bạn đang ở nhánh `{current}`.)
+
+**1. Xác định nhánh chính (`{main}`).**
+- Không phải git repo → bỏ qua toàn bộ pre-flight, note cho user rồi tiếp Bước 1.
+- Có nhánh `develop` → mặc định `{main}` = `develop`. Không có `develop` nhưng có `main`/`master` → dùng nó.
+- Mơ hồ (tồn tại cả `develop` lẫn `main`, hoặc remote default khác) → **hỏi user** nhánh nào là nhánh chính. KHÔNG đoán.
+
+**2. Kiểm tra working tree sạch.** `git status` còn thay đổi chưa commit → **DỪNG**, báo user commit/stash trước. KHÔNG tự ý stash/discard.
+
+**3. Checkout + pull nhánh chính:** `git checkout {main}` rồi `git pull`. Pull fail (conflict, không có upstream…) → **DỪNG**, surface lỗi cụ thể, để user xử lý.
+
+**4. Tạo nhánh làm việc mới off `{main}`.** Cần `{NNN}-{slug}` để đặt tên → thực hiện **ngay sau khi xác định slug + số thứ tự ở Bước 4** (xem nhắc ở đó): đề xuất `git checkout -b feat/{NNN}-{slug}`, cho user sửa tên rồi tạo. Mọi việc ghi spec + auto-cascade từ Bước 5/7 diễn ra trên nhánh này.
+
+---
+
 ### Bước 1: Xác định input
 
 **Nếu có ARGUMENT** → đây là raw requirement, chuyển sang Bước 2.
@@ -156,6 +181,8 @@ Xác định số thứ tự (`NNN`):
 
 Output path: `.specs/integrations/{NNN}-{slug}/spec.md`
 
+**Tạo nhánh làm việc** (Pre-flight bước 4) — giờ đã có `{NNN}-{slug}`: `git checkout -b feat/{NNN}-{slug}` off `{main}` (đề xuất tên, cho user sửa). Bỏ qua nếu không phải git repo (pre-flight đã note).
+
 ---
 
 ### Bước 5: Write — sinh draft
@@ -343,7 +370,7 @@ Chỉ tiến hành Bước 7 sau khi user confirm. Nếu user yêu cầu chỉnh
 
 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; `template_version` lấy từ `spec-template.md` (xem `conventions.md` §7).
+**[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. (spec.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, xem `conventions.md` §7.)
 
 **[7.2] Auto-apply mỗi Changes block** vào main artifact tương ứng. Thứ tự apply (để tránh forward reference): `prd.md` → `domain.md` → `sad.md` → `component/*/crd.md` → `feature/*/frd.md`.
 
@@ -429,6 +456,7 @@ Bước tiếp theo:
 
 Trước khi user confirm (Bước 6), kiểm tra:
 
+- [ ] **Pre-flight Git**: đã thông báo plan cho user; xác định đúng nhánh chính (hỏi nếu mơ hồ); working tree sạch; đã `checkout {main}` + `pull`; tạo nhánh làm việc mới off `{main}` trước khi cascade
 - [ ] Problem Statement từ góc nhìn user/business, không mention tech
 - [ ] Mỗi Acceptance Criterion dùng cú pháp GIVEN / WHEN / THEN, có thể test được
 - [ ] Out of Scope có ít nhất 1 item
@@ -443,4 +471,4 @@ Sau khi user confirm (Bước 7):
 - [ ] Auto-apply chạy theo thứ tự prd → domain → sad → crd → frd
 - [ ] Mỗi artifact bị touched có entry mới được append vào `## Change History` (xem `conventions.md` §5.5)
 - [ ] Fail-safe: nếu apply fail thì không ghi spec.md (rollback luôn Change History entries)
-- [ ] Artifact create (spec.md + frd/crd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ
+- [ ] Main artifact create (frd/crd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ. spec.md (integration) KHÔNG mang `template_version`

package/skills/spec-tech/SKILL.md

@@ -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`; `template_version` lấy từ `tech-template.md` (xem `conventions.md` §7).
+**[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`. (tech.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, xem `conventions.md` §7.)
 
 **[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`.
 
@@ -315,4 +315,4 @@ Sau khi user confirm (Bước 6):
 - [ ] Auto-apply chạy theo thứ tự sad → domain → cdd → fdd
 - [ ] Mỗi artifact bị touched có entry mới được append vào `## Change History` (conventions §5.5)
 - [ ] Fail-safe: nếu apply fail thì không ghi tech.md (rollback luôn Change History entries)
-- [ ] Artifact create (tech.md + cdd/fdd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ
+- [ ] Main artifact create (cdd/fdd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ. tech.md (integration) KHÔNG mang `template_version`

package/skills/spec-test/SKILL.md

@@ -284,7 +284,7 @@ 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`; `template_version` lấy từ `test-template.md` (xem `conventions.md` §7).
+**[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`. (test.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, xem `conventions.md` §7.)
 
 **[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.
 
@@ -381,4 +381,4 @@ Sau khi QC confirm (Bước 6):
 - [ ] Mỗi tsd.md bị touched có entry mới trong `## Change History` (conventions §5.5)
 - [ ] Fail-safe: nếu apply fail thì không ghi integration test.md (rollback luôn Change History entries)
 - [ ] Mỗi feature tsd.md mới có status `draft` (separate lifecycle)
-- [ ] test.md + tsd.md create có `template_version` copy từ template; tsd.md update giữ nguyên version cũ
+- [ ] Main artifact tsd.md create có `template_version` copy từ template; tsd.md update giữ nguyên version cũ. test.md (integration) KHÔNG mang `template_version`

package/skills-overview.md

@@ -220,26 +220,26 @@ Nhóm skill dọn dẹp / migrate artifacts hiện có sau khi template được
 
 | Command | Reads | Writes |
 | --- | --- | --- |
-| `/artifact-audit [type]` | `.specs/**` artifacts, `.claude/templates/*-template.md` | *(báo cáo; + stamp `template_version` cho artifact legacy conform)* |
-| `/artifact-migrate [path]` | `.specs/**` artifacts, `.claude/templates/*-template.md` (block `migrations`) | artifact được migrate (structure + `template_version`) |
+| `/artifact-audit [type]` | `.specs/main/**` artifacts, `.claude/templates/main/*-template.md` | *(báo cáo; + stamp `template_version` cho main artifact legacy conform)* |
+| `/artifact-migrate [path]` | `.specs/main/**` artifacts, `.claude/templates/main/*-template.md` (block `migrations`) | main artifact được migrate (structure + `template_version`) |
 
 ### `/artifact-audit [type]`
 
-Phát hiện artifact lỗi thời so với template (xem `conventions.md` §7 Template Versioning). So `template_version` của artifact với `template_version` đọc thẳng từ template tại `.claude/templates/` — không manifest, không cache.
+Phát hiện **main artifact** lỗi thời so với template (xem `conventions.md` §7 Template Versioning). So `template_version` của artifact với `template_version` đọc thẳng từ template tại `.claude/templates/main/` — không manifest, không cache. **Chỉ main artifacts** (`prd`/`domain`/`sad`/`frd`/`fdd`/`tsd`/`crd`/`cdd`); integration artifacts ngoài scope.
 
-**Scope:** argument là 1 type (`/artifact-audit frd`) hoặc list (`frd,spec`); không có arg → audit mọi type. Type resolve theo **filename** (integration artifact không có field `type`).
+**Scope:** argument là 1 main type (`/artifact-audit frd`) hoặc list (`frd,crd`); không có arg → audit mọi main type. Type resolve theo **filename**.
 
 **Phân loại mỗi artifact:**
 - Có `template_version` → `==`: **up-to-date**; `!=`: **out-dated** `(vX → vY)` → migrate.
 - Thiếu version (legacy) → presence-check (đủ required `##` + không còn section `migrations.remove`): conform → **stamp** `template_version` (có confirm); lệch → **out-dated** + tóm tắt phần thiếu.
 
-**Ranh giới:** chỉ phát hiện + stamp legacy conform. **KHÔNG migrate** — đổi structure là việc của `/artifact-migrate`. Bỏ qua `.specs/archive/` và `.specs/removed/`.
+**Ranh giới:** chỉ phát hiện + stamp legacy conform. **KHÔNG migrate** — đổi structure là việc của `/artifact-migrate`. Bỏ qua toàn bộ `.specs/integrations/`, `.specs/archive/`, `.specs/removed/`.
 
 ### `/artifact-migrate [path]`
 
-Migrate artifact lỗi thời lên structure template mới nhất, generic cho mọi type (vế **fix** đối xứng với `/artifact-audit` vế **detect**).
+Migrate **main artifact** lỗi thời lên structure template mới nhất, cho mọi main type (vế **fix** đối xứng với `/artifact-audit` vế **detect**). Integration artifacts ngoài scope.
 
-**Scope:** arg = 1 artifact (path) → migrate riêng nó; không arg → quét toàn bộ, migrate từng cái có confirm + skip.
+**Scope:** arg = 1 main artifact (path) → migrate riêng nó; không arg → quét mọi main artifact trong `.specs/main/`, migrate từng cái có confirm + skip.
 
 **Quy trình:** pre-flight git clean → **tự chạy `/artifact-audit` classify-only (scoped)** để phát hiện out-dated (up-to-date → no-op sớm) → đọc block `migrations` của template lấy delta `add`/`remove`/`update` → dry-run + confirm → apply (set `template_version` = current; main artifact thêm Change History `manual`/migrate).
 

package/templates/integrations/plan-template.md

@@ -6,10 +6,6 @@ features: []
 components: []
 status: draft
 created: {YYYY-MM-DD}
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.5 plan.md > Cấu trúc
   - skills/plan/SKILL.md > Output Format > plan.md

package/templates/integrations/spec-template.md

@@ -6,10 +6,6 @@ features: []
 components: []
 status: draft
 created: {YYYY-MM-DD}
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.3 spec.md > Cấu trúc
   - skills/spec-new/SKILL.md > Process > Bước 5: Write — sinh draft

package/templates/integrations/tech-template.md

@@ -6,10 +6,6 @@ features: []
 components: []
 status: draft
 created: {YYYY-MM-DD}
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.4 tech.md > Cấu trúc
   - skills/spec-tech/SKILL.md > Process > Bước 4: Write — sinh draft

package/templates/integrations/techdebt-template.md

@@ -1,10 +1,6 @@
 ---
 slug: "{slug}"
 created: {YYYY-MM-DD}
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
 referenced_by:
   - skills/review-integration/SKILL.md > Bước 2 — Luôn ghi findings vào techdebt.md
 ---

package/templates/integrations/test-template.md

@@ -5,10 +5,6 @@ title: "{title}"
 features: []
 status: draft
 created: {YYYY-MM-DD}
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.7 test.md > Cấu trúc
   - skills/spec-test/SKILL.md > Process > Bước 4: Write — sinh draft

package/templates/integrations/todo-template.md

@@ -5,10 +5,6 @@ title: "{title}"
 features: []
 components: []
 created: {YYYY-MM-DD}
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.6 todo.md > Cấu trúc
   - skills/plan/SKILL.md > Output Format > todo.md