@educa-corp/sdd-framework 0.2.3 → 0.2.5

package/docs/06-commands/explain-generate-spec-manifest.md

@@ -1,20 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /generate-spec-manifest
-
-# `/generate-spec-manifest` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Quét toàn bộ file spec và ghi một **sổ mục lục** `spec-manifest.yaml` — cho **agent bên ngoài** (vd agent của tester) biết feature nào có PRD/BDD/tech-doc ở đâu. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/generate-spec-manifest` như **lập danh mục kho tài liệu**: đi một vòng, ghi lại "feature X có PRD ở đây, BDD ở kia, tech-doc chỗ nọ, trạng thái/version bao nhiêu" thành một file index để công cụ/agent khác tra nhanh mà không phải mò.
-
----
-
-## Cách chạy
-
-- Xác định gốc quét (umbrella: spec submodule; single: project).
-- **Quét PRD** (mỗi feature) → lấy TICKET-ID, domain, status, version.
-- **Khớp** file product-definition, BDD, tech-doc theo từng TICKET-ID (theo glob + `@trace.prd`).
-- **Ghi** `spec-manifest.yaml` (index gọn theo feature) và đảm bảo nó nằm trong `.gitignore` (file sinh ra, không commit).
-
-Report còn cảnh báo PRD nào chưa có BDD/tech-doc khớp.
-
-> **Một câu chốt:** `/generate-spec-manifest` lập sổ mục lục toàn bộ spec (feature → PRD/BDD/tech-doc/version) cho agent ngoài tra cứu — file sinh ra, gitignored, chạy lại bất cứ lúc nào.

package/docs/06-commands/explain-generate-tech-docs.md

@@ -1,56 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /generate-tech-docs
-
-# `/generate-tech-docs` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Từ **BDD đã duyệt** của một PRD, sinh **một** bản thiết kế kỹ thuật **full-stack** — chỗ chi tiết kỹ thuật mà PRD cố tình không chứa. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/generate-tech-docs` như một **bản vẽ thi công**: PRD/BDD nói "cần làm gì", còn bản vẽ này nói "làm bằng gì" (API, data model, luồng service, component, state, xử lý lỗi…). Đây là nơi chi tiết kỹ thuật được phép sống.
-
----
-
-## Một PRD → một bản vẽ (merged, full-stack)
-
-- **1 tech-doc / 1 PRD**, KHÔNG phải 1 doc / 1 UC. File gộp **cả backend lẫn client** trong cùng một tài liệu: §1–§4.4 + §6–§8 là phần BE (API contract, data model, DB); §4.5 là phần client (component, state, Figma mapping, test-id) cho mỗi platform; **§5 sequence diagram** nối xuyên tầng (component → service → API → external → DB). Một dev đọc một file là hiểu và code được cả tính năng.
-- **Input = file BDD tech lead trỏ vào** — 1 file, hoặc một batch nhỏ (vd `system/` + `web/` + `app/` của cùng 1 UC). Lệnh nạp **chỉ** các file đó (giữ context nhỏ), **KHÔNG** tự gom hết BDD của PRD. Cảnh báo mềm nếu > 5 file/lần (không chặn).
-- **Output:** `.../{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (không hậu tố UC/platform).
-
----
-
-## Sinh mới vs bổ sung (append)
-
-- Doc **chưa tồn tại** → **Fresh:** sinh đầy đủ cho mọi UC hiện có.
-- Doc **đã tồn tại** → **Append:** đọc **§10 UC Coverage** + Changelog để biết UC nào đã có; chỉ **thêm** section/sequence-diagram cho UC mới, cập nhật ma trận coverage + Changelog, **giữ nguyên** phần cũ (tôn trọng chỉnh tay + chữ ký reviewer). Không có UC mới và BDD không đổi version → báo "đã đầy đủ", không ghi đè.
-
-Nhờ vậy, mỗi lần PRD có thêm BDD (thêm UC, thêm platform), bản vẽ **lớn dần lên** thay vì đẻ ra nhiều file rời.
-
----
-
-## Trước khi vẽ, kiểm cửa
-
-- **BDD sạch chưa?** Quét review-BDD findings của **mọi** feature trong PRD. Còn lỗi critical chưa xử → **dừng** (bắt `/review-context --fix/--resume`). BDD chưa duyệt → cảnh báo mềm.
-- **(Client) có design-spec chưa?** Nếu PRD có `web/`·`app/` BDD, §4.5 lấy fidelity từ design-spec (Figma/component/token). Thiếu → **cảnh báo mềm**, §4.5 vẽ text-only từ BDD và đánh dấu `[DRAFT — no design-spec]` (không chặn cứng — phần BE vẫn đầy đủ giá trị).
-- **Brownfield?** API đã tồn tại (`API Source: existing`) → chế độ **reverse-document**: mô tả lại contract as-is, ghi chú chỗ vênh, không thiết kế mới.
-
-Rồi hiện **plan** (mode fresh/append, platform, danh sách UC, các section sẽ vẽ) và chờ Y.
-
----
-
-## Sau khi vẽ
-
-- Ra **một** file `{TICKET-ID}-tech-design.md` cho cả PRD.
-- Nếu tech-doc sống trong spec repo dùng chung → **publish** (commit + push) để cả team `/sync` đọc được.
-- Trạng thái ban đầu là **draft** — phải qua `/review-tech-docs` duyệt mới cho sinh code.
-
-§4.5 client có **Test Selectors** — quy ước test-id ổn định cho từng element có action, làm *hợp đồng* để QC định vị phần tử mà không phải dò runtime (cùng một id value dùng chung web ↔ app, chỉ khác attribute).
-
----
-
-## Vị trí trong dây chuyền
-
-```
-BDD duyệt (web+app+system của 1 PRD)
-     → [ generate-tech-docs ◀ bạn ở đây ] → review-tech-docs (duyệt) → generate-code
-       (1 bản vẽ full-stack / PRD, append khi có UC mới)
-```
-
-> **Một câu chốt:** `/generate-tech-docs` gom mọi BDD của một PRD thành **một** bản vẽ full-stack (BE + client + sequence xuyên tầng), sinh mới hoặc **bổ sung** khi có UC mới; ra draft, phải review mới cho code.

package/docs/06-commands/explain-learn.md

@@ -1,21 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /learn
-
-# `/learn` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Ghi một **bài học của dự án** (guardrail) để AI **không lặp lại một lỗi**. Bài học được nạp vào context ở đầu mỗi lệnh. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/learn` như **dán một tờ nhắc lên tường xưởng**: "lần trước AI hay làm sai X → từ nay phải làm Y". Mỗi lần chạy lệnh, AI đọc lại tấm bảng nhắc này nên không mắc lại.
-
-> Đây là **bộ nhớ dự án**, không phải huấn luyện lại model — nó thành guardrail nhờ được inject vào context mỗi lần.
-
----
-
-## Cách chạy
-
-- Bạn gõ `/learn {mô tả tự do}` — lý tưởng kiểu *"AI làm X, nên làm Y"*.
-- Nó tách thành **lỗi** (AI làm sai gì) + **quy tắc** (câu sửa mệnh lệnh "Luôn…/Không bao giờ…"), suy ra `category` (code-gen / bdd / tech-docs / tests / prd / general) và `scope` (domain / file glob / all).
-- Hiện lại cho bạn xác nhận → ghi vào file lessons của dự án.
-
-Guardrail có hiệu lực ngay từ lệnh kế. Nhiều lệnh khác (`/review-code`, `/debug`, `/fix-bug`) cũng **tự đề nghị** ghi lesson khi thấy một lỗi AI hay lặp.
-
-> **Một câu chốt:** `/learn` dán tờ nhắc lên tường xưởng — biến một lỗi hay lặp thành quy tắc, được nạp vào context mỗi lần chạy để AI không mắc lại; commit file lessons để cả team dùng chung.

package/docs/06-commands/explain-map-testids.md

@@ -1,28 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /map-testids
-
-# `/map-testids` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Gán/backfill **test-id ổn định** lên các element FE **tái dùng hoặc đã có sẵn** — để QC định vị phần tử bằng id thay vì dò runtime. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/map-testids` như **dán nhãn tên cố định** lên các nút/ô nhập trên giao diện. QC cần một cái "tay cầm" ổn định để tìm đúng element mà test; lệnh này lo phần khó: các component **dùng chung** (nhãn phải sống ở nơi sử dụng, và component phải *chuyển tiếp* được nhãn) và các màn **cũ/brownfield** đã code mà chưa có nhãn.
-
-> `/generate-tech-docs` (FE) và `/generate-code` đã gán id cho code **mới**. Lệnh này lo phần **tái dùng + đã có sẵn**.
-
----
-
-## Cách chạy (chỉ FE/App)
-
-1. **Guard:** system/BE → dừng (không có UI test-id).
-2. **Thu element có action** từ các step `When` của BDD + màn Design Spec (nút, ô nhập, link, chọn, toggle…), phân loại: *reused* (trong catalog dùng chung) / *existing* (đã code, brownfield) / *new* (để `/generate-code` lo).
-3. **Gán id ổn định** theo quy ước `{uc}-{screen}-{element}-{type}` (vd `ft001-login-submit-btn`) — không nhúng số scenario; element đã có id thì dùng lại. Cùng element trên web & app dùng **cùng id value**.
-4. **Đảm bảo component dùng chung chuyển-tiếp được id:** nếu chưa, patch component **một lần** để nhận + forward nhãn, rồi ghi vào figma-components catalog.
-5. **Patch nơi sử dụng** (chỉ thêm nhãn, không refactor).
-6. **Ghi map §4.5.6** vào tech-doc gộp (tạo file tối thiểu nếu chưa có).
-
-## Vị trí trong dây chuyền
-
-```
-generate-tech-docs(FE) / generate-code → [ map-testids ◀ backfill id ] → review-tech-docs → qc-design-test
-```
-
-> **Một câu chốt:** `/map-testids` dán nhãn tên cố định cho element FE tái dùng/đã-có, đảm bảo component dùng chung chuyển-tiếp được nhãn, và ghi map §4.5.6 — để QC định vị bằng id thay vì dò runtime.

package/docs/06-commands/explain-propose-scenario.md

@@ -1,24 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /propose-scenario
-
-# `/propose-scenario` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Cho **tester & QC** đề xuất một **kịch bản BDD mới** cho edge case chưa được phủ — dạng phiếu đề xuất để PO/Dev duyệt. Không đụng `.feature` chính thức. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/propose-scenario` như **bỏ phiếu đề xuất vào hòm góp ý**: tester thấy một tình huống chưa có test, viết draft kịch bản Gherkin và gửi đề xuất — PO/Dev là người quyết đưa nó vào BDD thật.
-
-> **Không sửa BDD chính thức.** BDD do PO/Dev sở hữu; lệnh này chỉ ghi proposal.
-
----
-
-## Cách chạy
-
-1. **Phân giải UC + platform** (để khớp vocabulary + tag trace, tránh đề xuất trùng).
-2. **Quyết định coverage (mấu chốt):**
-   - **Case A — behavior NẰM TRONG một AC có sẵn** (chỉ thiếu scenario) → draft Gherkin, map tới AC đó, tag `@proposed @from-test`.
-   - **Case B — behavior KHÔNG nằm trong AC nào** (yêu cầu mới) → **không** draft BDD (không có gì để trace); thay vào đó ghi **PRD change request** để PO thêm/mở rộng AC.
-3. **Ghi proposal** vào `feedback/bdd-proposals/` với `Status: proposed`.
-4. **Handoff:** commit + push lên spec repo → PO/Dev thấy khi `/sync`.
-
-Vòng đời: `proposed → accepted/rejected` (PO/Dev duyệt) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi `incorporated`.
-
-> **Một câu chốt:** `/propose-scenario` là hòm góp ý test — draft kịch bản cho gap coverage (Case A) hoặc chuyển thành PRD change request nếu là yêu cầu mới (Case B); PO/Dev duyệt mới vào BDD.

package/docs/06-commands/explain-qc-analyze.md

@@ -1,22 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /qc-analyze
-
-# `/qc-analyze` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Trạm 1** của dây chuyền QC tự động (`qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report`). Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung dây chuyền QC như một **xưởng kiểm thử 6 trạm**. Trạm đầu — `/qc-analyze` — đóng vai **QC Analyst**: đọc spec chính thức (PRD + BDD + Design Spec) và **phân rã thành yêu cầu có cấu trúc** để các trạm sau dựa vào.
-
----
-
-## Cách chạy
-
-- **Guard:** BDD chưa duyệt → cảnh báo mềm.
-- Phân rã spec thành: chức năng → **business rule** (`BR-xx`) → data flow → **acceptance criteria** (`AC-xx`); mỗi BR/AC **map tới scenario** `{UC-ID}-SC{N}` sở hữu nó.
-- **Ghi DOC_GAPS:** mọi chỗ mơ hồ/thiếu/mâu thuẫn thành `GAP-xx` (không bao giờ tự bịa câu trả lời). Gap 🔴 Blocker → UC chưa sẵn sàng.
-- **Đẩy defect thật lên PO:** blocker là lỗi trong spec chính thức → file qua `/report-bug` (hoặc `/propose-scenario` nếu thiếu coverage), không chỉ nằm local.
-
-Ranh giới vai: `/qc-analyze` trả lời *"yêu cầu là gì?"*; trạm sau `/qc-plan` trả lời *"rủi ro ở đâu, hỏi dev gì?"*.
-
-Ra 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md` (đặt ở `docs/{UC-ID}/` — folder QC nhìn thấy được, không phải spec repo của PO).
-
-> **Một câu chốt:** `/qc-analyze` là QC Analyst — biến spec chính thức thành yêu cầu có cấu trúc (BR/AC map tới scenario) + danh sách gap, đẩy defect thật lên PO; nó *phân tích*, không viết test case.

package/docs/06-commands/explain-qc-design-test.md

@@ -1,20 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /qc-design-test
-
-# `/qc-design-test` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Trạm 3** của dây chuyền QC tự động. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Trạm 3 đóng vai **QC Designer**: viết ra các **test case** bằng Markdown (`.Test.md`) từ phân tích + kế hoạch. **Chưa** viết Python (đó là Trạm 5).
-
----
-
-## Cách chạy
-
-- Chọn **tầng test** (một màn / feature đa-màn / API / integration / e2e / non-functional / exploratory) và nạp đúng skill.
-- Viết TC: mã `TC_<FEATURE>_<NNN>`, tách happy/negative, mỗi TC một mối quan tâm, **giá trị expected cụ thể**, priority P0/P1/P2, tags, status.
-- **Tham chiếu test-id, không tả hình ảnh:** mỗi step GUI trỏ tới test-id ổn định trong §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") — để Trạm 5 dựng locator từ contract, không dò runtime.
-- **Trace:** mỗi TC ghi `@trace.verifies={UC-ID}-SC{N}` (join key để Trạm 5 ghi `qc_status` theo scenario). TC bị chặn bởi gap vẫn viết + đánh dấu `🚫 Block: GAP-xx`.
-
-Ra các file `.Test.md` trong `docs/{UC-ID}/test-cases/`.
-
-> **Một câu chốt:** `/qc-design-test` là QC Designer — viết test case Markdown bám scenario, trỏ test-id thay vì tả hình ảnh; Python đến sau ở Trạm 5.

package/docs/06-commands/explain-qc-plan.md

@@ -1,21 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /qc-plan
-
-# `/qc-plan` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Trạm 2** của dây chuyền QC tự động. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Trạm 2 đóng vai **QC Planner**: từ bản phân tích của Trạm 1, lập **kế hoạch test** — soi *rủi ro nằm ở đâu* và *phải hỏi dev/PO điều gì*.
-
----
-
-## Cách chạy
-
-- Đọc output của `/qc-analyze` (`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`).
-- Lập `TEST_PLAN.md`: **ma trận rủi ro**, kịch bản **what-if**, phạm vi & chiến lược test theo từng tầng (functional / integration / e2e / non-functional), điều kiện vào/ra.
-- Suy ra **questions-for-dev** từ mỗi gap còn mở/blocker — để gửi PO/Dev làm rõ trước khi thiết kế test.
-
-Ranh giới vai: `/qc-plan` trả lời *"rủi ro ở đâu, hỏi gì?"* — **không** thiết kế test case cụ thể (đó là Trạm 3).
-
-Giới hạn plan trong các scenario của UC để Trạm 3 thiết kế case theo từng scenario.
-
-> **Một câu chốt:** `/qc-plan` là QC Planner — biến phân tích thành kế hoạch test (rủi ro · what-if · phạm vi từng tầng · câu hỏi cho dev), chưa viết case chi tiết.

package/docs/06-commands/explain-qc-report.md

@@ -1,23 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /qc-report
-
-# `/qc-report` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Trạm 6 (cuối)** của dây chuyền QC tự động. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Trạm cuối đóng vai **QC Report**: biến lần chạy gần nhất thành **báo cáo + bằng chứng** chia sẻ được, và chuyển các lỗi sản phẩm về cho PO/Dev.
-
----
-
-## Cách chạy
-
-- Định vị artifact lần chạy gần nhất, sinh `report.html` (pytest-html self-contained) + **Playwright Trace** (`trace.zip`, xem bằng `playwright show-trace`), đính screenshot/evidence cho mỗi FAIL/SKIP.
-- Tóm tắt TOTAL / PASS / FAIL / SKIP; mỗi FAIL ghi lệnh xem trace + phân loại script-bug hay product-gap.
-- **Bàn giao product-gap về spec (có nhắc):** với mỗi FAIL là *product-gap* (impl ≠ spec), in sẵn lệnh `/report-bug {UC-ID} {expected-vs-actual}` để QC file vào spec repo — để PO/Dev thấy trên `/sync`. **script-bug KHÔNG file** (QC tự sửa). Không bao giờ fake-pass.
-
-## Vị trí trong dây chuyền
-
-```
-qc-run-test → [ qc-report ◀ trạm cuối ] → (product-gap) /report-bug → validate-traces → PR
-```
-
-> **Một câu chốt:** `/qc-report` là trạm cuối — gói report + trace/evidence, và đẩy product-gap về PO/Dev qua `/report-bug`; script-bug thì QC tự lo, product-gap thì giữ nguyên FAIL cho tới khi fix.

package/docs/06-commands/explain-qc-review.md

@@ -1,24 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /qc-review
-
-# `/qc-review` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Trạm 4** của dây chuyền QC tự động — một **cổng review chạy hai lần**. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Trạm 4 đóng vai **QC Reviewer**: một **cổng kiểm** đặt ở hai chỗ trong dây chuyền, soi trước khi cho đi tiếp.
-
----
-
-## Chạy hai lần, hai mode
-
-1. **Sau Trạm 3 (design)** → review **test case** `.Test.md`: đã phủ mọi scenario chưa, có đủ happy + negative + boundary, expected có cụ thể, trace đầy đủ, không có TC "mồ côi".
-2. **Sau Trạm 5 (run)** → review **script Python / Page Object**: khớp `.Test.md` 1-1 chưa, Page Object gọn 3 lớp, dùng `expect()` không phải assert trần, không hardcode URL/cred/timeout, không `time.sleep`, selector theo đúng thứ tự ưu tiên (test-id trước).
-
-Nó tự **phát hiện mode** theo artifact target (`.Test.md` hay file Python). Ra findings + phán quyết **APPROVED** / **NEEDS_FIX**.
-
-## Vị trí trong dây chuyền
-
-```
-qc-design-test → [ qc-review · lần 1: test case ] → qc-run-test → [ qc-review · lần 2: script ] → qc-report
-```
-
-> **Một câu chốt:** `/qc-review` là cổng kiểm hai chiều — lần 1 soi test case (sau thiết kế), lần 2 soi script (sau khi chạy) — phán APPROVED/NEEDS_FIX trước khi cho qua trạm kế.

package/docs/06-commands/explain-qc-run-test.md

@@ -1,27 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /qc-run-test
-
-# `/qc-run-test` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Trạm 5** của dây chuyền QC tự động — nơi ghi **kết quả QC CHÍNH THỨC** (`qc_status`). Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Trạm 5 đóng vai **QC Runner**: biến test case Markdown (đã review) thành **script Python thật** (pytest-playwright + Page Object), chạy chúng, và ghi kết quả pass/fail *chính thức* vào trace.
-
----
-
-## Cách chạy
-
-- **Markdown-first:** không sinh Python khi chưa có `.Test.md` đã review.
-- Dùng stack riêng **qc-playwright** (độc lập với module code của dev). Page Object gọn 3 lớp (locator / action / assertion), dùng `expect()`, không hardcode, không `time.sleep`.
-- **Locator từ contract test-id** (§4.5.6), không dò runtime; fallback role/text chỉ khi element thiếu id.
-- Mỗi test gắn `@trace.verifies={UC-ID}-SC{N}`, phủ 100% TC (mỗi cái kết Pass/Fail/Skip).
-- **Phân loại mỗi FAIL:** *script-bug* (QC tự sửa selector/logic) vs *product-gap* (defect thật — **giữ FAIL**, không bao giờ fake-pass).
-
-## Nét quan trọng nhất: ghi `qc_status` chính thức
-
-Đây là trạm **duy nhất** ghi `qc_status` vào trace `.tsv` — tín hiệu QC authoritative (khác hẳn `dev_selftest` của dev). Kèm theo:
-- `qc_owner` — SC đang chờ ai: `dev` (product-gap) / `po` (bị chặn bởi spec gap) / `—` (pass).
-- `qc_blocked_by` — `GAP-{id}` / `BUG-{id}` liên kết.
-
-**Không bao giờ** đụng `dev_selftest` — hai tín hiệu tách biệt.
-
-> **Một câu chốt:** `/qc-run-test` là QC Runner — sinh & chạy script Playwright từ test case đã review (locator theo test-id), rồi ghi `qc_status` **chính thức** + ai đang chờ; product-gap giữ FAIL, không fake-pass.

package/docs/06-commands/explain-refine-prd.md

@@ -1,51 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /refine-prd
-
-# `/refine-prd` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Soi PRD để **làm nội dung tốt hơn** trước khi qua cổng chất lượng cuối. Đọc read-only, ghi biên bản lỗi, con người quyết. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/refine-prd` như một **tổ soi bài** ngồi đọc PRD của bạn qua nhiều "cặp kính" khác nhau, tìm chỗ mô tả thiếu/mơ hồ/mâu thuẫn, rồi **ghi ra một danh sách góp ý** (findings). Nó **không tự sửa bài** — bạn duyệt từng góp ý rồi mới áp.
-
-Nó là "anh em" với [`/review-context`](explain-review-context.md): dùng **chung một bộ máy soi** (fan-out nhiều lăng kính + người canh độ đầy đủ), nhưng `refine-prd` chạy **sớm hơn** — lo *cải thiện nội dung*; còn `review-context` là *cổng gác cuối*.
-
----
-
-## Ba "cặp kính" (lăng kính)
-
-Tổ soi bài gồm 3 vai, mỗi vai một góc nhìn:
-
-- **DEV** — đọc như một dev sắp build: luồng đã đủ rõ để triển khai chưa, hay còn phải đoán?
-- **SA** — đọc như một architect: các thực thể/luồng nghiệp vụ có thông suốt, nhất quán không?
-- **PO** — đọc như chủ sản phẩm: mục tiêu, phạm vi, tiêu chí thành công có rõ không?
-
-> **Quan trọng:** DEV và SA **đọc bằng mắt kỹ thuật nhưng VIẾT bằng lời nghiệp vụ** — chỉ ra chỗ nghiệp vụ mô tả thiếu để sau này xử lý được về kỹ thuật, chứ **không** kê giải pháp/cơ chế kỹ thuật vào PRD.
->
-> *(Từng có lăng kính QA nhưng đang tạm tắt — vẫn giữ trong file dưới dạng block DISABLED kèm hướng dẫn bật lại.)*
-
----
-
-## Cách soi cho kỹ (giống review-context)
-
-- **Chia nhỏ:** mỗi lăng kính soi trên từng Use Case → nhiều "người soi đầu óc tươi", ít sót.
-- **Người canh "đã đủ chưa?":** sau khi soi, đọc lại toàn bộ hỏi "còn sót gì không", lặp tới khi hai vòng liền không ra gì mới → **một lần chạy là đủ**.
-- **Gộp & xử mâu thuẫn:** khử trùng lặp, hai góp ý chọi nhau thì nêu cả hai cho người chọn.
-
-Kết quả là một file `…-findings.yaml`: mỗi góp ý ghi rõ ở đâu, trích nguyên văn, vấn đề gì, đề xuất sửa sao. Có xếp mức độ (critical/major/minor) và khuyến nghị (BLOCKED / NEEDS_REVISION / APPROVED).
-
----
-
-## Sau khi có biên bản
-
-Mở **Review Board**, duyệt từng góp ý (✓Nhận / ✎Sửa / ✗Bỏ) → chạy `--resume` để **áp những cái đã nhận**. Áp xong tự tăng version PRD + hạ về draft (phải duyệt lại).
-
-Khi áp, nó **giữ đúng tầng**: cơ chế → BR/BL, AC chỉ giữ outcome + ref (không nhồi vào AC).
-
----
-
-## Vị trí trong dây chuyền
-
-```
-generate-prd → [ refine-prd ◀ bạn ở đây ] → review-context (cổng cuối) → PO duyệt → generate-bdd
-```
-
-> **Một câu chốt:** `/refine-prd` là tổ soi bài 3 lăng kính (DEV/SA/PO) — đọc bằng mắt kỹ thuật, góp ý bằng lời nghiệp vụ — chạy sớm để *nâng chất nội dung PRD*; ghi biên bản, con người quyết, không tự sửa bài.

package/docs/06-commands/explain-report-bug.md

@@ -1,24 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /report-bug
-
-# `/report-bug` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Cho **tester & QC** lập một **phiếu bug có hồ sơ spec** — gắn ngữ cảnh (PRD/BDD/AC), đoán layer khả nghi, đẩy về team dev. Read-only trên spec/code. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/report-bug` như **lập phiếu sự cố có truy vết**: không chỉ ghi "lỗi ở đâu", mà còn móc thẳng vào spec (AC nào bị vi phạm) và **đoán nguyên nhân nằm ở tầng nào** để định tuyến đúng người xử lý.
-
-> **Chỉ ghi phiếu — không bao giờ sửa PRD/BDD/tech-docs/code.** Fix là việc `/fix-bug` (dev); viết scenario là `/propose-scenario`.
-
----
-
-## Cách chạy
-
-1. **Phân giải ngữ cảnh spec:** tìm PRD/BDD/tech-doc của UC (ưu tiên `spec-manifest.yaml`), lấy scenario fail, version PRD. Không có scenario nào khớp → đánh dấu *coverage gap*.
-2. **Thu chi tiết:** xảy ra ở đâu, tái hiện sao, expected (theo spec) vs actual, log, env.
-3. **Xác định AC bị vi phạm:** trích nguyên văn AC. Không AC nào phủ → có thể là PRD gap.
-4. **Phân loại layer khả nghi (BUG_FLOW):** Code bug → `/fix-bug`; BDD bug → Dev/PO; PRD mơ hồ → PO; coverage gap → `/propose-scenario`; Design Spec bug → Dev/Designer; Env → DevOps.
-5. **Ghi phiếu** `BUG-{ngày}-{NN}` vào `feedback/bug-reports/`, **backfill trace** (`qc_blocked_by`, `qc_owner`) để view "đang chờ ai" của PM trỏ đúng.
-6. **Handoff:** commit + push lên spec repo — để PO/Dev thấy khi `/sync`.
-
-Vòng đời: `Open → Fixed` (bởi `/fix-bug`) `→ Closed` (khi `/qc-run-test` verify pass).
-
-> **Một câu chốt:** `/report-bug` là phiếu sự cố có hồ sơ spec — móc vào AC, đoán tầng nguyên nhân, đẩy lên spec repo để đúng người xử lý; chỉ ghi phiếu, không sửa gì.

package/docs/06-commands/explain-review-code.md

@@ -1,45 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /review-code
-
-# `/review-code` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Soi **code** theo 4 mặt trước khi cho đi test. Read-only — chỉ report, không sửa. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/review-code` như một **giám sát công trình** đi soi phần code vừa thi công: đúng bản vẽ chưa, đúng chuẩn chưa, có bỏ sót kịch bản nào không. Nó **không tự sửa** — chỉ ra báo cáo và phán "đạt" hay "cần sửa".
-
----
-
-## Bốn mặt soi
-
-| Mặt | Soi gì |
-|---|---|
-| **1. Traceability** | Mỗi endpoint có nhãn `@trace.implements` chưa; nhãn có đặt đúng layer không; trace `.tsv` có cập nhật không. |
-| **2. Layer Architecture** | Mỗi class đúng layer chưa, phụ thuộc đi đúng chiều, không bypass layer (theo CLAUDE.md §2). |
-| **3. Coding Standards** | Naming, response wrapper, exception không bị nuốt, không magic number, không log dữ liệu nhạy cảm, transaction đúng (CLAUDE.md §3). |
-| **4. Spec Compliance** | Mỗi scenario BDD có code phủ; không có endpoint "lậu" (code không có spec đỡ lưng). |
-
-Trước khi soi, nó liệt kê **scope** (file nào gắn `@trace.implements={UC-ID}`, bao nhiêu scenario) và chờ Y.
-
----
-
-## Kết quả
-
-Một báo cáo phân theo mức Critical / Major / Minor (file · dòng · vấn đề · gợi ý sửa), và **phán quyết**:
-
-- **APPROVED ✅** → đi tiếp `/dev-gen-test`.
-- **NEEDS_FIX ❌** → sửa nhỏ inline rồi review lại / lỗi logic-kiến trúc → `/fix-bug` / code lệch spec → `/generate-code` lại.
-
-**Không tạo artifact** (read-only thuần).
-
----
-
-## Học từ lỗi lặp
-
-Nếu một finding Critical/Major trông như **lỗi AI hay lặp** khi sinh code, nó hỏi bạn có muốn ghi thành **project lesson** để `/generate-code` lần sau không lặp lại — một vòng phản hồi giúp framework tự khá lên.
-
-## Vị trí trong dây chuyền
-
-```
-generate-code → [ review-code ◀ bạn ở đây ] → (APPROVED) → dev-gen-test → dev-run-test
-```
-
-> **Một câu chốt:** `/review-code` là giám sát công trình soi code 4 mặt (truy vết · kiến trúc · chuẩn · bám spec), chỉ báo cáo không sửa, phán APPROVED/NEEDS_FIX, và có thể ghi lại lỗi lặp thành bài học cho lần sinh code sau.

package/docs/06-commands/explain-review-context.md

@@ -1,68 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /review-context
-
-# `/review-context` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Mô tả cách `/review-context` chạy bằng lời dễ hiểu + ví von đời thường. Bổ sung cho đặc tả chính thức ở [Reference › Commands](../05-reference/commands.md) và [command-cheatsheet](../05-reference/command-cheatsheet.md) — trang này ưu tiên *trực giác*, không phải đặc tả.
-
-Hình dung `/review-context` như một **cửa kiểm định chất lượng cuối** trước khi tài liệu được "cho qua" sang bước sau. Nó **không sửa bài của bạn** — chỉ soi và ghi ra một danh sách lỗi để bạn tự quyết.
-
----
-
-## Ví von: một tổ thanh tra trước cổng
-
-Bạn đưa một tài liệu tới cổng (PRD hoặc BDD). Ở cổng có một **tổ thanh tra**. Quy trình như sau:
-
-### 1. Bảo vệ nhìn tài liệu, biết ngay nó là loại gì
-- Đuôi `.md` (ở gốc thư mục feature) → đây là **PRD** → dùng bộ tiêu chí **P** (P1–P5).
-- Đuôi `.feature` → đây là **BDD** → dùng bộ tiêu chí **B** (B1–B6).
-
-Hai loại giấy tờ, hai bảng kiểm khác nhau, nhưng **cùng một cái cổng**.
-
-### 2. Chia nhỏ việc soi cho nhiều thanh tra — mỗi người một "cặp kính", mỗi người một phần
-Thay vì một người ôm cả tài liệu soi mọi thứ cùng lúc (dễ sót), tổ trưởng **chia mỗi thanh tra soi đúng một khía cạnh, trên đúng một Use Case**. Người chỉ soi thuật ngữ, người chỉ soi câu mơ hồ, người chỉ soi cấu trúc… Ai cũng có "đầu óc tươi" nên soi kỹ hơn, ít sót hơn.
-
-### 3. Một người canh "đã đủ chưa?" — chống bắt-cóc-bỏ-dĩa
-Vấn đề muôn thuở: soi một lượt thì không bao giờ ra hết lỗi cùng lúc; chạy lại lần sau lại lòi lỗi mới (đập chuột chũi). Nên có một **người canh độ đầy đủ**: sau khi cả tổ soi xong, người này đọc lại **toàn bộ** tài liệu hỏi *"còn sót gì không?"*. Lặp tới khi **hai vòng liền không ra thêm gì mới** → mới chốt. Nhờ vậy **một lần chạy là đủ**, chạy lại sẽ ra 0 lỗi mới.
-
-### 4. Hai việc tổ trưởng tự làm (không giao ai)
-Có 2 kiểm tra cần nhìn ra ngoài tài liệu này nên tổ trưởng tự làm:
-- **Định tuyến (P0):** PRD có ghi đúng "Domain" để sau này BDD/code chảy về đúng service không (chỉ ở chế độ umbrella).
-- **Xung đột với PRD khác (P3):** feature này có mâu thuẫn luật với một PRD anh em nào không.
-
-### 5. Soi hết → viết ra một tờ "biên bản lỗi", KHÔNG sửa bài
-Kết quả là một file `…-findings.yaml`: mỗi lỗi ghi rõ *ở đâu, trích nguyên văn câu lỗi, vấn đề gì, đề xuất sửa thế nào, có tự sửa được không*. **Tài liệu gốc không bị đụng.** An toàn chạy bất cứ lúc nào.
-
----
-
-## Sau khi có biên bản, bạn làm gì với nó?
-
-Đây là chỗ **con người quyết**, có 2 đường:
-
-- **Đường nhanh — `--fix`:** "cứ mấy lỗi máy tự sửa an toàn được (đổi thuật ngữ cấm, thêm khung section thiếu…) thì sửa ngay đi." Mấy lỗi cần đầu người vẫn để đó chờ.
-- **Đường cẩn thận — Review Board + `--resume`:** bạn mở biên bản, duyệt **từng lỗi**: ✓Nhận / ✎Sửa lại đề xuất / ✗Bỏ. Xong bấm `--resume` để **áp những cái đã nhận**.
-
-Áp xong, nó **tự tăng version** và **hạ trạng thái về `draft`** — vì tài liệu vừa đổi thì con dấu "đã duyệt" cũ hết hiệu lực, phải duyệt lại.
-
----
-
-## Một mẹo tiết kiệm: lần đầu soi hết, lần sau chỉ soi chỗ đổi
-
-- **Lần đầu** (chưa có biên bản cũ) → soi **toàn bộ** (full).
-- **Lần sau** → chỉ soi những Use Case **đã thay đổi** (delta) cho nhanh. NHƯNG người-canh-đầy-đủ **vẫn đọc cả tài liệu** như lưới an toàn — phòng khi sửa chỗ này làm lộ lỗi chỗ kia.
-- Nếu phát hiện tài liệu bị **người/lệnh khác** sửa ngoài tầm theo dõi → tự động quay lại soi **toàn bộ** cho chắc.
-
----
-
-## Nó đứng ở đâu trong dây chuyền?
-
-```
-generate-prd → refine-prd → [ review-context: cổng chất lượng cuối ] → PO duyệt → generate-bdd
-```
-
-Với BDD thì nó là cổng trước `generate-tech-docs`.
-
-> **Một câu chốt:** `refine-prd` lo *làm nội dung tốt hơn*; `review-context` là *cửa gác cuối* — soi thật kỹ, ghi biên bản, để con người quyết sửa gì; bản thân nó **không bao giờ tự ý sửa bài**.
-
----
-
-*Muốn giải thích dễ hiểu cho một lệnh khác → thêm một trang `explain-{command}.md` trong thư mục này.*

package/docs/06-commands/explain-review-tech-docs.md

@@ -1,45 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /review-tech-docs
-
-# `/review-tech-docs` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Soi **bản thiết kế kỹ thuật** trước khi cho sinh code. Read-only, ghi biên bản, con người quyết. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/review-tech-docs` như một **hội đồng nghiệm thu bản vẽ**: soi bản vẽ kỹ thuật đúng chuẩn kiến trúc chưa, có khớp entity/BDD không, có đụng bản vẽ khác không — và với hợp đồng API liên team thì còn **thu đủ chữ ký** trước khi đóng dấu.
-
-Giống các lệnh review khác: **không sửa bài**, chỉ ghi `…-tech-review-findings.yaml`; bạn duyệt ở Review Board rồi `--resume` để áp.
-
----
-
-## Bảy mặt soi (T1–T7)
-
-| Mặt | Soi gì |
-|---|---|
-| **T1 Architecture** | Có đúng thứ tự layer trong CLAUDE.md không (Controller không gọi thẳng Repository, logic không nằm ở Controller/DTO…). Vi phạm = **critical**, không auto-fix. |
-| **T2 Entity** | Tên entity/field có khớp core-entities không. |
-| **T3 BDD Traceability** | Thiết kế có bám scenario BDD không, có mâu thuẫn scenario không. |
-| **T4 Domain Conflict** | Có đụng bản vẽ khác cùng domain không (trùng endpoint khác shape, trùng trách nhiệm…). |
-| **T5 Internal Consistency** | Trong nội bộ doc có tự mâu thuẫn không (sơ đồ ≠ mô tả, return type ≠ code sketch…). |
-| **T6 Completeness** | Đủ các section chuẩn chưa (thiếu = auto-fix thêm skeleton). |
-| **T7 Cross-Team Sign-off** | *(chỉ hợp đồng API system, không phải brownfield)* thu chữ ký BE/FE/App/SA và đối chiếu contract với `Then` của web+app BDD. |
-
----
-
-## Cổng chữ ký (chỉ hợp đồng API liên team)
-
-Đây là nét riêng: một hợp đồng API mới **không được đóng dấu approved** cho tới khi **cả BE, FE, App (nếu có) và SA/Tech Lead đều ký "done"**. Còn ai `pending` → trạng thái giữ `in-review` → `/generate-code` bị chặn. Cơ chế này ép cả liên team đồng thuận contract *trước khi* ai đó bắt đầu code.
-
-*(Nếu là brownfield — API đã tồn tại — thì bỏ qua T7: contract đã do PO chốt trong PRD, không có gì để đàm phán.)*
-
----
-
-## Áp fix & đóng dấu
-
-`--resume` áp các finding đã nhận (theo critical → major → minor), tăng `@trace.revision`, và đặt trạng thái: đủ chữ ký → **approved**; chưa đủ → **in-review**. Đồng thời cập nhật cột revision trong trace `.tsv`.
-
-## Vị trí trong dây chuyền
-
-```
-generate-tech-docs → [ review-tech-docs ◀ bạn ở đây ] → (approved) → generate-code
-```
-
-> **Một câu chốt:** `/review-tech-docs` là hội đồng nghiệm thu bản vẽ kỹ thuật (7 mặt soi) — và với hợp đồng API liên team, nó còn là **cổng chữ ký**: chưa đủ BE/FE/App/SA ký thì chưa approved, chưa cho sinh code.

package/docs/06-commands/explain-setup-ai-first.md

@@ -1,25 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /setup-ai-first
-
-# `/setup-ai-first` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Khởi tạo **một-lần** framework trong dự án: tạo thư mục, `CLAUDE.md`, config, từ điển, rồi verify. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/setup-ai-first` như **dựng khung một xưởng mới**: đặt sẵn các phòng (thư mục), bảng nội quy (`CLAUDE.md`), sổ cấu hình (`project-context.yaml`), và từ điển thuật ngữ — để mọi lệnh sau có chỗ mà chạy.
-
----
-
-## Cách chạy
-
-1. **Kiểm đã setup chưa** (an toàn chạy lại — mỗi bước đề nghị merge/skip).
-2. **Hỏi loại dự án:**
-   - **Single-service** — một codebase (setup chuẩn đầy đủ).
-   - **Umbrella** — repo chứa nhiều service submodule (chỉ tạo `.trace/` + `.agent/review/`; spec sống trong spec submodule).
-   - **PO Spec repo** — chỉ docs, không code (tạo `specs/`, `feedback/`; `CLAUDE.md` tối thiểu).
-3. **Tạo cấu trúc** thư mục theo loại (folder từng-feature thì tạo **on demand** bởi các lệnh generate, không tạo trước).
-4. **Tạo file nền:** `CLAUDE.md` (nội quy: layer, coding standards, git), `project-context.yaml` (đường dẫn, tech stack), `business-dictionary.md`, `core-entities.md`.
-5. **Gợi ý cài extension** VS Code (Review Board + Living Docs).
-6. **Verify** checklist theo loại dự án.
-
-Điểm nhấn: mọi PRD phải có row **Domain** đúng — team dev route BDD/code theo domain đó.
-
-> **Một câu chốt:** `/setup-ai-first` dựng khung xưởng một-lần — thư mục + nội quy + config + từ điển theo 3 loại dự án (single / umbrella / PO spec) — để cả pipeline có nền mà chạy.

package/docs/06-commands/explain-sync.md

@@ -1,24 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /sync
-
-# `/sync` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Một lệnh **đồng bộ dự án** umbrella: git pull + xử lý submodule + nổi feedback tester + bootstrap config service + làm mới Living Docs. Chạy hằng ngày. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/sync` như **nghi thức đầu ngày**: kéo về cái mới nhất, dọn dẹp, và báo cho bạn "có gì mới cần để mắt" — nhưng **cẩn thận không đụng vào chỗ bạn đang làm dở**.
-
-> Khác `/update-framework`: `/sync` lo **nội dung dự án** (code/specs submodule + Living Docs); `/update-framework` lo **nâng cấp bản thân framework**.
-
----
-
-## Cách chạy
-
-1. **Pre-flight:** kiểm là git repo, đọc config (spec_source, services), quét trạng thái submodule (conflict → dừng).
-2. **Pull umbrella** + init submodule chưa clone.
-3. **Xử lý từng submodule theo trạng thái** — điểm tinh tế nhất: **không bao giờ ép branch**. Submodule bạn đang đứng trên một branch (active) → chỉ fetch, để nguyên; detached sạch (passive) → align về pointer; đang sửa dở (dirty) → cảnh báo, skip. Riêng **spec submodule** thì cố ý advance tới branch mới nhất (PO push liên tục).
-4. **Nổi feedback tester/QC** vừa pull về (bug report *Open*, scenario proposal, PRD change request) — để PO/Dev được thông báo qua routine bình thường.
-5. **Bootstrap config service** (tự tạo `.agent/project-context.yaml` cho service thiếu, đoán module từ `pom.xml`/`go.mod`/`package.json`…).
-6. **Làm mới Living Docs** + spec-manifest.
-
-Báo cáo cuối gom mọi thứ: git, từng submodule, feedback mới, config service, Living Docs.
-
-> **Một câu chốt:** `/sync` là nghi thức đầu ngày cho umbrella — pull + đồng bộ submodule (tôn trọng branch đang làm), nổi feedback tester, tự tạo config service, làm mới dashboard; an toàn chạy lại.

package/docs/06-commands/explain-update-framework.md

@@ -1,22 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /update-framework
-
-# `/update-framework` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Nâng cấp **bản thân bộ đồ nghề framework** (command, steps, modules, templates, skills) lên version mới trên npm. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/update-framework` như **thay bộ đồ nghề mới**: các slash command và khung template là "dụng cụ"; lệnh này lấy bản mới nhất về, thay dụng cụ cũ — nhưng **giữ nguyên đồ của bạn** (config, CLAUDE.md, từ điển, trace).
-
-> Khác `/sync`: `/sync` lo **nội dung dự án** (chạy hằng ngày); `/update-framework` lo **nâng cấp dụng cụ** (chạy thỉnh thoảng, khi có bản mới).
-
----
-
-## Cách chạy
-
-1. **Phát hiện trạng thái:** đọc `FRAMEWORK_VERSION`, mode, các module đã cài (phải truyền lại khi nâng để chúng cũng update).
-2. **Kiểm bản mới nhất** trên npm; đã mới nhất → dừng; có bản mới → hỏi Y.
-3. **(umbrella)** nhắc: bộ đồ nghề chỉ sống ở umbrella root, service submodule không cần update riêng.
-4. **Pre-flight git:** có thay đổi chưa commit trong `.agent/` → khuyên commit/stash trước (để review diff sạch).
-5. **Chạy nâng cấp** (`npx @latest --init`) — **ghi đè** file framework (`.agent/commands`, `steps`, `templates`, `skills`…) nhưng **KHÔNG đụng** `project-context.yaml`, `CLAUDE.md`, `domain-knowledge/`, `.trace/`.
-6. **Review changes:** `git diff --stat`, nêu command mới/đổi/bị bỏ, rồi bạn commit.
-
-> **Một câu chốt:** `/update-framework` thay bộ đồ nghề (command/steps/templates) lên bản npm mới nhất, giữ nguyên nội dung của bạn; chạy thỉnh thoảng, khác với `/sync` chạy hằng ngày.