@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.8

package/core/skills/design-spec/SKILL.md

@@ -4,587 +4,8 @@ description: Sinh tài liệu Design Specification cho platform FE hoặc App t
 
 # /generate-design-spec — Generate Design Specification (FE / App)
 
-Skill này sinh một Design Spec riêng theo platform từ một Business PRD.
-Design Spec nắm bắt yêu cầu UI mức màn hình, component inventory, tương tác platform,
-và AC-UI mức design để PO + Designer sign off — tách khỏi PRD mức nghiệp vụ.
+Skill này xử lý `/generate-design-spec`. Để **không lệch gate/schema**, skill KHÔNG nhân bản — thực thi **y hệt** command.
 
-**Platform hỗ trợ:** web (react / nextjs / vue / angular), app (flutter / react-native / ios-swiftui / android-compose)
-**Không hỗ trợ:** service backend — API contract thuộc về Business PRD.
+→ **Đọc và tuân theo `commands/generate-design-spec.md`** với cùng `$ARGUMENTS`.
 
----
-
-## Gate
-
-<!-- Directory: specs/*/*/*.md (file PRD ở gốc feature folder) -->
-# Gate — Quy trình vào chuẩn cho mọi lệnh
-
-Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
-
-## Bước 0 — Kiểm tra chế độ Sub-Agent
-
-Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
-
-1. Thử parse `$ARGUMENTS` dưới dạng JSON.
-2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
-   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
-   - Đặt target file = `payload.target_file`
-   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
-   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
-   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
-   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
-   - Đi thẳng tới phần logic riêng của lệnh.
-3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
-
-## Bước 0-B — Kiểm tra Model
-
-*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
-
-Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh.
-Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
-
-Hiển thị và chờ phản hồi:
-
-```
-⚙️  MODEL CHECK
-──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
-  Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
-
-  Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
-
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
-    S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
-──────────────────────────────────────────────────────────────────
-```
-
-- "Y" → tiếp tục sang Bước 1.
-- "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
-
-## Bước 1 — Xác định Target File
-
-1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
-2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
-   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
-   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
-   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
-
-   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
-3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
-   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
-   - Chờ người dùng chọn rồi mới tiếp tục.
-
-## Bước 2 — Chạy Context Loader
-
-Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
-Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
-
-## Bước 3 — CHECKPOINT
-
-Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận:
-
-```
-CHECKPOINT
------------
-Target     : {resolved file path}
-Project    : {project.name từ project-context.yaml}
-Tech stack : {language} / {framework}
-Module     : {module nếu có, else "not configured"}
-Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
-
-Tiếp tục? (Y/N)
-```
-
-Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục.
-- "Y" → tiếp tục sang các bước riêng của lệnh bên dưới.
-- "N" → dừng lại và hỏi người dùng muốn thay đổi gì.
-
-
----
-
-## Context
-
-# Context Loader — Nạp toàn bộ context dự án
-
-Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nhớ trong suốt phiên làm việc của lệnh.
-
-**Hướng dẫn ưu tiên (chống lost-in-middle):**
-- Bước 1–2 là PROJECT-CONFIG — nạp trước, phân giải mọi path và metadata.
-- Bước 3 là CRITICAL — kiến trúc + coding standards, là các sự thật ưu tiên cao nhất khi sinh nội dung.
-- Bước 4 là SAFETY — quy tắc bảo vệ dữ liệu, thực thi ngầm suốt cả phiên.
-- Bước 5–6 là DOMAIN KNOWLEDGE — thuật ngữ và định nghĩa entity.
-- Bước 7 là WORKING MEMORY RECAP — chốt các sự thật quan trọng lên đầu bộ nhớ làm việc.
-
----
-
-## Bước 1 — [PROJECT-CONFIG] Nạp project-context.yaml
-
-Đọc `.agent/project-context.yaml`. Trích xuất và lưu:
-
-**Tech Stack:**
-- `tech_stack.language` → ngôn ngữ đang dùng (vd: Java 17, TypeScript, C#, Go)
-- `tech_stack.framework` → framework đang dùng (vd: Spring Boot 3.2, Angular 17, .NET 8)
-- `tech_stack.build_tool` → build tool (vd: Maven, npm, dotnet, go)
-- `tech_stack.test_framework` → test framework (vd: JUnit 5 + Mockito, Jest, xUnit)
-- `tech_stack.database` → database (vd: PostgreSQL, MySQL, MongoDB)
-- `tech_stack.module` → module profile đang dùng (vd: java-spring, angular, dotnet, golang, context-engineering)
-
-**Conventions:**
-- `conventions.build_command` → cách compile/build
-- `conventions.test_command` → cách chạy test
-- `conventions.service_run` → cách khởi động service
-- `conventions.ticket_prefix` → tiền tố ticket ID (vd: PROJ, FEAT, UC)
-
-**Domains:**
-- `domains` → danh sách các business domain đang hoạt động
-
-**Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
-- `paths.refinement_dir` → thư mục output cho findings/review
-- `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
-- `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
-- `paths.product_definitions_dir` → gốc product definition
-- `paths.domain_knowledge_dir` → gốc domain knowledge
-- `paths.business_dictionary` → path tới business-dictionary.md
-- `paths.core_entities` → path tới core-entities.md
-- `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
-- `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
-
-Nếu không có section `paths`, dùng các giá trị mặc định:
-- `specs_dir` = `specs`
-- `refinement_dir` = `.agent/review`
-- `qc_dir` = `docs`
-- `qc_skills_dir` = `.agent/skills/qc`
-- `product_definitions_dir` = `specs/product-definition`
-- `domain_knowledge_dir` = `specs/domain-knowledge`
-- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
-- `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `specs`
-- `trace_dir` = `.trace`
-
-Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng.
-
-**Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
-- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
-- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
-- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
-- `specs/payment/create-invoice/design-spec/PAY-design-spec-web.md` → `prd_slug = create-invoice`
-
-Mọi artifact cùng cấp của một feature (PRD, BDD của từng platform, tech-docs BE + FE, design-spec, và trace TSV) đều phân giải về **cùng một `prd_slug`** — nên một BDD **system** hay tech-doc **system/BE** được tổng hợp sẽ nằm chung package `{specs_dir}/{domain}/{prd-slug}/` với các artifact web/app mà nó được suy ra từ đó.
-
-Nếu `tech_stack.module` được đặt, đồng thời nạp `.agent/modules/{module}/stack-profile.yaml` nếu file tồn tại.
-
----
-
-## Bước 1.5 — [SERVICE ROUTING] Phân giải path service (chế độ umbrella)
-
-*Bỏ qua hoàn toàn bước này nếu `setup.mode` không phải `"umbrella"` và không có section `services` trong project-context.yaml.*
-
-Nếu có section `services`:
-
-**1. Phát hiện active domain** (theo thứ tự ưu tiên):
-- Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
-- Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
-- Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
-
-**2. Route tới service** — nếu active domain khớp với một key trong `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
-- Lưu `active_service` = `services.{domain}.path`
-- Lưu `active_service_module` = `services.{domain}.module`
-- Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`)
-
-**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
-- Giữ path mặc định từ Bước 1
-- Đặt `active_service = unresolved`
-
-**4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
-- Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
-- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt** (bước 2 không còn pin tech-docs theo service trong trường hợp này). Tech-docs nằm tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. Tech-design CHÍNH LÀ API contract liên team: BE viết ở đây, FE/App đọc nó từ cùng spec submodule tại `/generate-code --phase=integration`. *(tech-docs theo service chỉ xảy ra khi không có `spec_source` — repo BE thuần đa-service không có spec module dùng chung.)*
-- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
-- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
-- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
-- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
-- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
-- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
-- Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `spec_source`.)*
-
-> **Vì sao đặt dưới `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, feedback của tester, **và trạng thái coverage `.trace/`** đều là **artifact liên team** — chúng nằm trong **spec repo dùng chung** theo bố cục feature-package để mọi umbrella (FE/App/BE) và PM đọc từ một nguồn qua `/sync`. Trong bố cục feature-package, một folder `specs/{domain}/{prd-slug}/` gom tất cả loại artifact của một PRD, giúp spec repo tự đủ và dễ điều hướng theo feature. Service submodule chỉ chứa **code** (+ tooling build/test). `.trace/` và `feedback/` là khu vực **ghi** của dev/QC trong spec repo. Ở chế độ single-service (không có `spec_source`), mọi thứ mặc định dưới gốc repo — vẫn là một repo.
-
----
-
-## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
-
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
-
-Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
-
-**1. Định vị config của service** — thử theo thứ tự ưu tiên:
-- `{active_service}/.agent/project-context.yaml`
-- `{active_service}/project-context.yaml`
-
-**2. Nếu tìm thấy, override bằng giá trị riêng của service:**
-
-| Biến | Nguồn |
-|----------|--------|
-| `conventions.test_command` | `conventions.test_command` của service |
-| `conventions.build_command` | `conventions.build_command` của service |
-| `paths.trace_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.trace`); bỏ qua mọi `trace_dir` cấp service.** Chỉ khi không có `spec_source`: `{active_service}/{service paths.trace_dir}` (mặc định `{active_service}/.trace`). |
-| `paths.specs_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/specs`); bỏ qua mọi `specs_dir` cấp service** (mọi spec artifact đều liên team, không bao giờ theo service ở chế độ này). Chỉ khi không có `spec_source`: `{active_service}/{service paths.specs_dir}` nếu được set, else dùng override ở Bước 1.5. |
-
-**3. Lưu** `service_root = {active_service}` làm mốc thư mục làm việc cho mọi lệnh phía sau:
-- Các lệnh shell (`/dev-run-test`, `/dev-gen-test`) chạy **bên trong** `service_root`
-- **File source/test** được ghi tương đối với `service_root`; **trace TSV** được ghi vào `{paths.trace_dir}` (là spec repo khi `spec_source` được đặt — một thao tác ghi liên-repo, commit/push vào spec submodule giống như `feedback/`).
-
-**4. Nếu không tìm thấy config của service** — giữ mặc định umbrella, vẫn set `service_root = {active_service}` (luôn cần mốc path kể cả khi không có config override).
-
----
-
-## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện)
-
-Nếu `tech_stack.module` được đặt, đọc `.agent/modules/{module}/stack-profile.yaml`.
-Merge các convention riêng của framework (layer pattern, test pattern, quy tắc đặt tên) vào context đã nạp.
-Nếu file không tồn tại → bỏ qua âm thầm.
-
----
-
-## Bước 3 — [CRITICAL] Nạp CLAUDE.md (phân tầng: root + service overlay)
-
-*Đây là context ưu tiên cao nhất — nó định nghĩa CÁCH viết code và tài liệu cho dự án này.*
-
-CLAUDE.md được nạp theo **hai tầng** để các quy tắc toàn-umbrella và kiến trúc/coding standards
-riêng của service kết hợp đúng cách. Agent luôn đứng ở gốc umbrella, nhưng code triển khai nằm
-trong một service submodule với stack, kiến trúc, và convention RIÊNG của nó — nên CLAUDE.md của
-service phải thắng khi sinh code.
-
-**Tầng 1 — [BASE] Root CLAUDE.md (toàn umbrella).**
-Đọc `CLAUDE.md` ở gốc repo. Coi nội dung của nó là **nền tảng dùng chung** cho cả umbrella —
-git convention, tư thế bảo vệ dữ liệu, quy tắc xuyên suốt, và (ở chế độ single-service) là
-kiến trúc + coding standards duy nhất của dự án.
-
-**Tầng 2 — [OVERLAY] Service CLAUDE.md (chỉ chế độ umbrella).**
-*Chỉ chạy nếu `service_root` đã được set ở Bước 1.6 (tức đã route tới một service thật).*
-Đọc `{service_root}/CLAUDE.md`. File này định nghĩa kiến trúc + coding standards của **stack
-thực sự đang được triển khai** (vd: `user-service` = java-spring, `web` = nextjs).
-Overlay nó lên trên Tầng 1: **khi có xung đột, giá trị của service THẮNG** cho kiến trúc,
-coding standards, và error handling. Các giá trị Tầng 1 mà service không định nghĩa lại
-(vd: git convention, banned pattern dùng chung toàn tổ chức) vẫn có hiệu lực.
-
-Từ kết quả **đã merge**, trích xuất và lưu:
-
-- **§1 Project Overview** → tên dự án, ngôn ngữ, framework, lệnh build/test, domains
-- **§2 Architecture** → thứ tự layer (vd: Controller → Facade → Service → Repository), quy tắc kiến trúc — *service overlay thắng*
-- **§3 Coding Standards** → quy tắc đặt tên (class, method), kiểu response wrapper, pattern bị cấm — *service overlay thắng*
-- **§5 Error Handling** → kiểu exception, mapping HTTP status code, tên class not-found exception — *service overlay thắng*
-- **§7 Git Conventions** → pattern đặt tên branch, format commit message — *lấy theo root trừ khi service định nghĩa lại*
-
-**Quy tắc phân giải:**
-- Nếu cả hai tầng tồn tại → merge như trên; ghi `claude_md_source = root + {service_root}`.
-- Nếu chỉ có service overlay (không có root CLAUDE.md) → dùng file service một mình; `claude_md_source = {service_root}`.
-- Nếu `service_root` được set nhưng `{service_root}/CLAUDE.md` **thiếu** → fallback về root CLAUDE.md và gắn cờ ⚠️ trong recap Bước 7 (service không có định nghĩa kiến trúc/coding-standards — việc sinh code sẽ dùng mặc định umbrella, có thể sai stack).
-- Nếu cả hai đều không tồn tại → ghi nhận CLAUDE.md thiếu và tiếp tục chỉ với dữ liệu từ project-context.yaml.
-
----
-
-## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu
-
-Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework).
-
-Lưu các pattern file nhạy cảm — bạn **tuyệt đối không** đọc, ghi, hiển thị, hay tham chiếu nội dung từ các file khớp những pattern đó trong suốt cả phiên.
-
-Nếu cả hai file đều không tồn tại → áp dụng mặc định built-in: không bao giờ truy cập `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
-
----
-
-## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện)
-
-Kiểm tra file business dictionary có tồn tại không (dùng `paths.business_dictionary` đã phân giải ở Bước 1).
-
-Nếu tồn tại, đọc và trích xuất:
-- **Canonical Terms** → danh sách đầy đủ các thuật ngữ chuẩn và định nghĩa
-- **Banned Terms** → danh sách đầy đủ các thuật ngữ bị cấm và bản thay thế chuẩn
-- **Status / Enum Registry** → các giá trị enum được phép theo từng entity
-
-Lưu danh sách banned term để **thực thi chủ động** suốt phiên làm việc của lệnh:
-- Khi sinh bất kỳ văn bản nào (PRD, BDD, comment code, tech docs), kiểm tra không có banned term nào xuất hiện
-- Tự động thay banned term bằng bản chuẩn tương đương
-
-Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn.
-
----
-
-## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện)
-
-Kiểm tra file core entities có tồn tại tại `paths.core_entities` không (đã phân giải ở Bước 1).
-Path mặc định: `specs/domain-knowledge/core-entities.md`.
-
-Nếu tồn tại, đọc và lưu:
-- **Entity catalog** → với mỗi entity: tên, mục đích, service sở hữu, các field chính (tên + kiểu), business invariant, và quan hệ
-- **Field name registry** → tên field chuẩn dùng trong code và tài liệu được sinh ra
-- **Relationship map** → cách các entity liên hệ với nhau (1:N, N:N, embedded, v.v.)
-
-**Cách dùng catalog này:**
-- Khi sinh code: dùng tên field, kiểu, và quan hệ định nghĩa ở đây — KHÔNG suy đoán từ code có sẵn
-- Khi sinh PRD/BDD: tham chiếu tên entity từ catalog này để nhất quán
-- Khi sinh tech-docs: dùng catalog này làm nguồn chân lý cho định nghĩa entity
-
-Nếu file không tồn tại → bỏ qua âm thầm.
-
----
-
-## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type
-
-Dùng `tech_stack.module` đã nạp ở Bước 1, suy ra và lưu hai biến để mọi lệnh phía sau dùng:
-
-```
-active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
-```
-
-| `platform_type` | Modules |
-|---|---|
-| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
-| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
-| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
-
-Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
-
-Hai biến này (`active_module`, `platform_type`) là nguồn chuẩn cho mọi logic rẽ nhánh trong các lệnh cần hành vi riêng theo platform (dev-gen-test, debug, fix-bug, dev-smoke-test).
-
----
-
-## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện)
-
-*Các lỗi tích luỹ mà AI không được lặp lại trong dự án này. Chúng được bổ sung dần qua `/learn`
-hoặc được chấp nhận trong `/review-code`, `/fix-bug`, `/debug`.*
-
-Phân giải path file lessons:
-- Dùng `paths.lessons_file` nếu được set (có thể bị service override ở chế độ umbrella, Bước 1.6)
-- Else mặc định `specs/domain-knowledge/lessons-learned.md`
-- Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{service_root}/.agent/project-lessons.md`
-
-Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
-- Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3).
-- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file).
-- Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng.
-
-Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
-
----
-
-## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle)
-
-Sau khi nạp toàn bộ context, tổng hợp và xuất một khối tóm tắt gọn.
-Recap này đảm bảo các sự thật quan trọng nhất được nêu ở CUỐI quá trình nạp context
-(hiệu ứng recency — tươi mới nhất trong bộ nhớ làm việc khi bắt đầu task).
-
-Xuất đúng khối này:
-```
-[CTX LOADED]
-Stack     : {language} / {framework} / {database}
-Platform  : {active_module} ({platform_type})
-Layers    : {thứ tự layer từ CLAUDE.md §2 đã merge, vd: Controller → Facade → Service → Repository}
-CLAUDE.md : {root + {service_root} | chỉ {service_root} | chỉ root | ⚠️ service overlay THIẾU — dùng root | missing}
-Ticket    : {ticket_prefix}-
-Dict      : {loaded — N canonical terms, M banned terms | missing}
-Entities  : {loaded — EntityA, EntityB, EntityC | missing}
-Lessons   : {loaded — N guardrails | chưa có}
-Service   : {active_service} ({active_service_module}) | single-service
-Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
-Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}
-```
-
-Nếu bất kỳ file CRITICAL nào thiếu (CLAUDE.md), gắn cờ rõ ràng để người dùng quyết định có tiếp tục hay không.
-
----
-
-## Hoàn tất nạp Context
-
-Sau khi hoàn thành tất cả các bước, bạn đã nạp:
-- Định danh dự án, tech stack, convention module
-- Quy tắc kiến trúc và thứ tự layer  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
-- Coding standards và quy tắc đặt tên  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
-- Quy tắc bảo vệ dữ liệu (pattern file nhạy cảm không bao giờ truy cập)
-- Quy tắc thuật ngữ kèm danh sách banned term  ← **[DOMAIN — áp dụng cho mọi từ được sinh ra]**
-- Entity catalog (tên field, kiểu, invariant)  ← **[DOMAIN — dùng khi sinh code]**
-- Toàn bộ path đã cấu hình
-
-Tiếp tục sang bước kế tiếp của lệnh đang gọi.
-
-
-*Đọc PRD target. Trích: TICKET-ID, domain, tên feature, Service, Module từ metadata, User Flow (Section 4a), tên màn hình Wireframe (Section 4b).*
-
----
-
-## Platform Check
-
-- `platform_type = "backend"` → **STOP**: "Design Spec chỉ dành cho FE/App. API contract BE đi vào Business PRD."
-- `platform_type = "web-frontend"` → `active_platform = "web"`
-- `platform_type = "mobile"` → `active_platform = "app"` (hoặc `"app-ios"` / `"app-android"` cho native)
-- `platform_type = "unknown"` → hỏi user chọn platform
-
----
-
-## Figma Check
-
-Hỏi: "Bạn có link Figma không? (dán URL hoặc Enter để skip)"
-
-Lưu thành `figma_url` hoặc set `"TBD"` kèm AI Assumption.
-
----
-
-## Screen Discovery
-
-Trích tên màn hình từ Section 4 của PRD. Trình bày danh sách để PO confirm/thêm trước khi sinh.
-
----
-
-## Generate
-
-Ghi `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`.
-
-Cấu trúc:
-1. **Metadata** — Spec ID, platform, module, service, link Business PRD, link Figma
-2. **Screen Inventory** — bảng mọi màn hình với entry point và link Figma frame
-3. **Screen Specs** (theo từng màn):
-   - Layout (grid, spacing, design token)
-   - Component Inventory (Figma → code component, import path, states)
-   - Screen States (default / loading / error / empty / success)
-   - Actions & Navigation (trigger → kết quả)
-4. **Interaction Patterns** (thích ứng theo platform):
-   - Web: bảng responsive breakpoint, bảng hover/focus/keyboard
-   - App: bảng gesture, sơ đồ navigation stack, bảng convention iOS vs Android
-5. **Platform Considerations** (thích ứng theo platform):
-   - Web: checklist accessibility (WCAG, keyboard, ARIA)
-   - App: safe area, touch target, deep link, permission, offline, dark mode
-6. **AC-UI** — bảng design acceptance criteria (Verified by: Designer / PO / QA)
-7. **Appendix** — tóm tắt Figma, design token, references, AI assumptions, changelog
-
-Quy tắc component mapping:
-- Kiểm tra `figma-components/{active_module}.md` (nạp trong context) cho mọi component
-- ✅ Found → dùng đúng Code Component + Import Path
-- ⚠️ TODO → đánh dấu `[TODO — implementation pending]`
-- ❌ Not found → đánh dấu `[NEW — confirm with designer]`
-
----
-
-## Output
-
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
-
-
-```
-/generate-design-spec Hoàn tất — {TICKET-ID} [{active_platform}]
----
-Status : ✅ Complete
-Output Artifacts:
-  created specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
-Next   : Chia sẻ với Designer → thêm link Figma → PO + Designer sign-off
-         → /generate-bdd {prd-file}
-```
+Command lo: guard PRD approved (mềm) · ghi `Built from PRD` + Version Check drift · Figma per-screen node-level link (`?node-id=`) fetch qua MCP, màn thiếu link → ❌ Missing → Status giữ `draft` · Screen Inventory/Specs/States · Interaction Patterns + Platform Considerations theo platform · AC-UI (Verified by) · **Self-Review Gate** trước khi ghi · chỉ FE/App (BE bị từ chối).