@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.1

package/skills/design-spec/SKILL.md

@@ -1,161 +1,161 @@
 ---
-description: Generates a Design Specification document for FE or App platforms from a Business PRD. Trigger when: "/generate-design-spec", "tạo design spec", "generate design spec", "viết design spec", "tạo tài liệu thiết kế UI", "generate UI spec", "cần design spec cho", "tôi muốn spec UI", "tài liệu cho FE", "tài liệu cho app".
+description: Sinh tài liệu Design Specification cho platform FE hoặc App từ một Business PRD. Trigger when: "/generate-design-spec", "tạo design spec", "generate design spec", "viết design spec", "tạo tài liệu thiết kế UI", "generate UI spec", "cần design spec cho", "tôi muốn spec UI", "tài liệu cho FE", "tài liệu cho app".
 ---
 
 # /generate-design-spec — Generate Design Specification (FE / App)
 
-This skill generates a platform-specific Design Spec from a Business PRD.
-Design Spec captures screen-level UI requirements, component inventory, platform interactions,
-and design-level AC-UI for PO + Designer sign-off — separate from the business-level PRD.
+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ụ.
 
-**Supported platforms:** web (react / nextjs / vue / angular), app (flutter / react-native / ios-swiftui / android-compose)
-**Not supported:** backend services — API contracts belong in the Business PRD.
+**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.
 
 ---
 
 ## Gate
 
 <!-- Directory: specs/*/*/prd.md -->
-# Gate — Universal Entry Procedure
+# Gate — Quy trình vào chuẩn cho mọi lệnh
 
-Every command must execute this gate before proceeding with its specific logic.
+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ó.
 
-## Step 0 — Sub-Agent Mode Check
+## Bước 0 — Kiểm tra chế độ Sub-Agent
 
-Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
 
-1. Attempt to parse `$ARGUMENTS` as JSON.
-2. If it parses successfully **and** contains `"_agent_mode": true`:
-   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
-   - Set target file = `payload.target_file`
-   - Set loaded context = `payload.context` (do NOT run context-loader.md)
-   - Set UC scope = `payload.uc_id` (process only this UC)
-   - Set line range = `payload.uc_section` (read only that PRD section)
-   - Proceed directly to the command-specific logic.
-3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+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)
+   - Đ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).
 
-## Step 0-B — Model Check
+## Bước 0-B — Kiểm tra Model
 
-*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
 
-Complex generation and review commands require strong reasoning.
-Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+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.
 
-Display and wait for response:
+Hiển thị và chờ phản hồi:
 
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (or latest Opus model)
-  Why needed   : Spec analysis, architecture review, code generation
-                 require deep reasoning. Smaller models miss edge cases.
+  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.
 
-  To switch in Claude Code:
-    • Settings → Model → select "claude-opus"
-    • or: /model → choose claude-opus
+  Cách đổi trong Claude Code:
+    • Settings → Model → chọn "claude-opus"
+    • hoặc: /model → chọn claude-opus
 
-  Running on claude-opus?
-    Y — yes, on claude-opus → proceed
-    S — skip check (I accept lower quality risk with current model)
+  Đ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" → proceed to Step 1.
-- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
-- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+- "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."
 
-## Step 1 — Resolve Target File
+## Bước 1 — Xác định Target File
 
-1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
-2. If `$ARGUMENTS` is a **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
-   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
-   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
-   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
-   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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`.
 
-   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
-3. If `$ARGUMENTS` is empty or no match found:
-   - List files in the relevant directory for this command (e.g., `specs/*/*/prd.md` for PRD commands, `specs/*/*/bdd/**/*.feature` for BDD commands).
-   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
-   - Wait for user selection before continuing.
+   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/*/*/prd.md` 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.
 
-## Step 2 — Execute Context Loader
+## Bước 2 — Chạy Context Loader
 
-Load all project context by following the procedure in `steps/context-loader.md`.
-Store all loaded context in memory for use throughout this command session.
+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.
 
-## Step 3 — CHECKPOINT
+## Bước 3 — CHECKPOINT
 
-After completing Steps 1 and 2, display a summary and wait for confirmation:
+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 from project-context.yaml}
+Project    : {project.name từ project-context.yaml}
 Tech stack : {language} / {framework}
-Module     : {module if set, else "not configured"}
-Domains    : {comma-separated domain list}
+Module     : {module nếu có, else "not configured"}
+Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
 
-Proceed? (Y/N)
+Tiếp tục? (Y/N)
 ```
 
-Wait for explicit "Y" or "N" from the user before continuing.
-- "Y" → proceed to the command-specific steps below.
-- "N" → stop and ask what the user wants to change.
+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 — Load All Project Context
+# Context Loader — Nạp toàn bộ context dự án
 
-Execute these steps in order. Store everything in memory for the duration of the command session.
+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.
 
-**Priority guide (anti-lost-in-middle):**
-- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
-- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
-- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
-- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
-- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+**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.
 
 ---
 
-## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+## Bước 1 — [PROJECT-CONFIG] Nạp project-context.yaml
 
-Read `.agent/project-context.yaml`. Extract and store:
+Đọc `.agent/project-context.yaml`. Trích xuất và lưu:
 
 **Tech Stack:**
-- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
-- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
-- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
-- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
-- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
-- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+- `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` → how to compile/build
-- `conventions.test_command` → how to run tests
-- `conventions.service_run` → how to start the service
-- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+- `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` → list of active business domains
-
-**Paths (if present):**
-- `paths.specs_dir` → spec artifacts root — PRD, BDD, tech-docs, design-spec. Structure: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
-- `paths.refinement_dir` → findings/review output dir
-- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
-- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
-- `paths.product_definitions_dir` → product definitions root
-- `paths.domain_knowledge_dir` → domain knowledge root
-- `paths.business_dictionary` → path to business-dictionary.md
-- `paths.core_entities` → path to core-entities.md
-- `paths.tech_docs_dir` → technical documentation root (merged with specs_dir in feature-package layout — tech-docs live under `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
-- `paths.trace_dir` → trace state directory; structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
-
-If `paths` section is absent, use these defaults:
+- `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}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `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`
@@ -167,184 +167,184 @@ If `paths` section is absent, use these defaults:
 - `tech_docs_dir` = `specs`
 - `trace_dir` = `.trace`
 
-Note: In the feature-package layout, `specs_dir` is the unified root. All spec artifact types (PRD, BDD, tech-docs, design-spec) live under `{specs_dir}/{domain}/{prd-slug}/`. The `prd-slug` is the feature-package folder name, not a separate config variable.
+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.
 
-**How to extract `prd_slug` (works for ANY target file, regardless of nesting depth):** given a target path of the form `{specs_dir}/{domain}/{prd-slug}/...`, take the **first path segment after `{specs_dir}/{domain}/`** — i.e. the `{prd-slug}` position. Do NOT use the file's immediate parent folder, because BDD/tech-docs/design-spec artifacts are nested one or two levels deeper inside the package. Examples:
+**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/prd.md` → `prd_slug = create-invoice`
-- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `system`)*
-- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `web`)*
-- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(NOT `tech-docs`)*
+- `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`
 
-All sibling artifacts of one feature (PRD, every platform's BDD, the BE + FE tech-docs, the design-spec, and the trace TSV) therefore resolve to the **same `prd_slug`** — so a synthesized **system** BDD or **system/BE** tech-doc lands in the same `{specs_dir}/{domain}/{prd-slug}/` package as the web/app artifacts it was derived from.
+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ừ đó.
 
-If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+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.
 
 ---
 
-## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+## Bước 1.5 — [SERVICE ROUTING] Phân giải path service (chế độ umbrella)
 
-*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+*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.*
 
-If `services` section is present:
+Nếu có section `services`:
 
-**1. Detect active domain** (in priority order):
-- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
-- Extract from target file path: `domain` = the first segment after the `specs_dir` base path; `prd_slug` = the next segment (the feature-package folder). This holds for any target depth — see the `prd_slug` extraction rule in Step 1.  
-  *(e.g., `specs/user/create-account/prd.md` **and** `specs/user/create-account/bdd/system/UC1.feature` both → domain = `user`, prd_slug = `create-account`)*
-- If `$ARGUMENTS` contains a path, extract the domain segment after `specs_dir`
+**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/prd.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 to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
-- Store `active_service` = `services.{domain}.path`
-- Store `active_service_module` = `services.{domain}.module`
-- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+**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** — if domain not detected or no matching service key:
-- Keep default paths from Step 1
-- Set `active_service = unresolved`
+**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. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
-- Override `paths.specs_dir` → `{spec_source}/specs` — **always when `spec_source` is set.** All spec artifacts (PRD, BDD, tech-docs, design-spec) live under the unified spec root in the shared spec repo using the feature-package layout: `{spec_source}/specs/{domain}/{prd-slug}/`. Every umbrella (FE/App/BE) reads from here. *(Per-service `specs/` only when there is no `spec_source`.)*
-- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). Tech-docs live at `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
+**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` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Internal structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace/{domain}/{prd-slug}/`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
+- 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`.)*
 
-> **Why under `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** using the feature-package layout so every umbrella (FE/App/BE) and the PM read one source via `/sync`. In the feature-package layout, a single `specs/{domain}/{prd-slug}/` folder groups all artifact types for one PRD, making the spec repo self-contained and navigable by feature. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo. In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
+> **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.
 
 ---
 
-## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
 
-When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
-**1. Locate service config** — try in priority order:
+**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. If found, override with service-specific values:**
+**2. Nếu tìm thấy, override bằng giá trị riêng của service:**
 
-| Variable | Source |
+| Biến | Nguồn |
 |----------|--------|
-| `conventions.test_command` | service's `conventions.test_command` |
-| `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
-| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs`); ignore any service-level `specs_dir`** (all spec artifacts are cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
+| `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. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
+**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. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+**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).
 
 ---
 
-## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện)
 
-If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
-Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
-If the file does not exist → skip silently.
+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.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
+## Bước 3 — [CRITICAL] Nạp CLAUDE.md (phân tầng: root + service overlay)
 
-*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+*Đâ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 is loaded in **two layers** so umbrella-wide rules and service-specific
-architecture/coding standards compose correctly. The agent always sits at the umbrella
-root, but the implementation code lives in a service submodule with its OWN stack,
-architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+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.
 
-**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
-Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
-whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
-single-service mode) the project's only architecture + coding standards.
+**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.
 
-**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
-*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
-Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
-the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
-Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
-coding standards, and error handling. Layer-1 values that the service does not redefine
-(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+**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.
 
-From the **merged** result, extract and store:
+Từ kết quả **đã merge**, trích xuất và lưu:
 
-- **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
-- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
+- **§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*
 
-**Resolution rules:**
-- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
-- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
-- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
-- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
+**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.
 
 ---
 
-## Step 4 — [SAFETY] Load Data Protection Rules
+## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu
 
-Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework).
 
-Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+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.
 
-If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+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*`.
 
 ---
 
-## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện)
 
-Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+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).
 
-If it exists, read it and extract:
-- **Canonical Terms** → complete list of approved terms and their definitions
-- **Banned Terms** → complete list of banned terms and their canonical replacements
-- **Status / Enum Registry** → allowed enum values per entity
+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
 
-Store the banned terms list for **active enforcement** throughout the command session:
-- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
-- Replace banned terms with their canonical equivalents automatically
+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
 
-If the file does not exist → skip silently. Do not warn or block.
+Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn.
 
 ---
 
-## Step 6 — [DOMAIN] Load Core Entities (conditional)
+## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện)
 
-Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
-Default path: `specs/domain-knowledge/core-entities.md`.
+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`.
 
-If it exists, read it and store:
-- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
-- **Field name registry** → canonical field names to use in generated code and documents
-- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+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.)
 
-**How to use this catalog:**
-- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
-- When generating PRD/BDD: reference entity names from this catalog for consistency
-- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+**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
 
-If the file does not exist → skip silently.
+Nếu file không tồn tại → bỏ qua âm thầm.
 
 ---
 
-## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type
 
-Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+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   (e.g. "java-spring", "react", "flutter")
+active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
 ```
 
 | `platform_type` | Modules |
@@ -353,161 +353,161 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 | `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
 | `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
 
-If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+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.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
+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).
 
 ---
 
-## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện)
 
-*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
-or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+*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`.*
 
-Resolve the lessons file path:
-- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
-- Else default `specs/domain-knowledge/lessons-learned.md`
-- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+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`
 
-If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
-- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
-- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
-- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+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.
 
-If the file does not exist → skip silently (no lessons captured yet).
+Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
 
 ---
 
-## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle)
 
-After loading all context, synthesize and output a compact summary block.
-This recap ensures the most critical facts are stated at the END of context loading
-(recency effect — freshest in working memory when the task begins).
+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).
 
-Output exactly this block:
+Xuất đúng khối này:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
-CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
+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 | none yet}
+Lessons   : {loaded — N guardrails | chưa có}
 Service   : {active_service} ({active_service_module}) | single-service
-Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
-Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
+Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
-If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+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.
 
 ---
 
-## Context Load Complete
+## Hoàn tất nạp Context
 
-After completing all steps, you have loaded:
-- Project identity, tech stack, module conventions
-- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
-- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
-- Data protection rules (sensitive file patterns to never access)
-- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
-- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
-- All configured paths
+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
 
-Proceed to the next step of the calling command.
+Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
-*Read the target PRD. Extract: TICKET-ID, domain, feature name, Service, Module from metadata, User Flow (Section 4a), Wireframe screen names (Section 4b).*
+*Đọ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 is only for FE/App. BE API contracts go in the Business PRD."
+- `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"` (or `"app-ios"` / `"app-android"` for native)
-- `platform_type = "unknown"` → ask user to select platform
+- `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
 
-Ask: "Do you have a Figma link? (paste URL or Enter to skip)"
+Hỏi: "Bạn có link Figma không? (dán URL hoặc Enter để skip)"
 
-Store as `figma_url` or set to `"TBD"` with AI Assumption noted.
+Lưu thành `figma_url` hoặc set `"TBD"` kèm AI Assumption.
 
 ---
 
 ## Screen Discovery
 
-Extract screen names from PRD Section 4. Present list for PO to confirm/add before generating.
+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
 
-Write `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`.
+Ghi `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`.
 
-Structure:
-1. **Metadata** — Spec ID, platform, module, service, Business PRD link, Figma link
-2. **Screen Inventory** — table of all screens with entry points and Figma frame links
-3. **Screen Specs** (per screen):
-   - Layout (grid, spacing, design tokens)
+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 (triggers → results)
-4. **Interaction Patterns** (platform-adaptive):
-   - Web: responsive breakpoints table, hover/focus/keyboard table
-   - App: gesture table, navigation stack diagram, iOS vs Android conventions table
-5. **Platform Considerations** (platform-adaptive):
-   - Web: accessibility checklist (WCAG, keyboard, ARIA)
-   - App: safe area, touch targets, deep links, permissions, offline, dark mode
-6. **AC-UI** — design acceptance criteria table (Verified by: Designer / PO / QA)
-7. **Appendix** — Figma summary, design tokens, references, AI assumptions, changelog
-
-Component mapping rules:
-- Check `figma-components/{active_module}.md` (loaded in context) for every component
-- ✅ Found → use exact Code Component + Import Path
-- ⚠️ TODO → mark `[TODO — implementation pending]`
-- ❌ Not found → mark `[NEW — confirm with designer]`
+   - 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 — Standard Command Output Format
+# Report Footer — Định dạng output chuẩn cho mọi lệnh
 
-Every command report must end with this standard footer section.
+Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
 
 ## Status Badge
 
-Choose one based on outcome:
-- `✅ Complete` — all steps succeeded, no issues found
-- `❌ Failed` — command could not complete due to a blocking error
-- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+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
 
-List every file created or modified by this command:
+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} ({brief description})
-  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({mô tả ngắn})
+  {created|updated} {file-path} ({mô tả ngắn})
 ```
 
-If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+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
 
-Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
-so the user always sees where this command sits in the end-to-end flow:
+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
 ```
 
-Find the current command in this phase legend and mark **its** phase in the map above:
+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 |
 |-------|----------|
@@ -521,69 +521,69 @@ Find the current command in this phase legend and mark **its** phase in the map
 | QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
 | Trace Audit | `/validate-traces` |
 
-For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+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`.
 
-**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
-**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+**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ơ đồ).
 
-## Next Command Suggestion
+## Gợi ý lệnh tiếp theo
 
-Suggest the logical next command based on workflow phase:
+Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 
-| Current command         | Suggest next                                  |
+| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
 |-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` to start your first feature |
+| /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}` then `/review-context {prd-file}` |
-| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
-| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /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)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /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}` (test-case review)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
-| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /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}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /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}` or `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
-| /dev-smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
-| /fix-bug                | Create PR and link to ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
-| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
-| /learn                  | Continue working — lesson applies on next command |
-| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
-
-Format the footer as:
+| /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}
-{Output Artifacts block}
+{khối Output Artifacts}
 Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {suggested command with example arguments}
+           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {lệnh gợi ý kèm ví dụ tham số}
 ```
-*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
 ```
-/generate-design-spec Complete — {TICKET-ID} [{active_platform}]
+/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   : Share with Designer → add Figma links → PO + Designer sign-off
+Next   : Chia sẻ với Designer → thêm link Figma → PO + Designer sign-off
          → /generate-bdd {prd-file}
 ```